Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## cnrg.itx.ds
Class DirectoryService

    java.lang.Object
      |
      +--cnrg.itx.ds.DirectoryService

public class DirectoryService
extends java.lang.Object

This class provides clients an interface to communicate with the directory server.

A typical itx application has one directory service object, one signaling component object, and one data exchange object.
An application can be in one of the following type:
- custom per-user application (the user is whoever is logged on using the application)
- gateway (the user is Gatewaysrv only)
- PBX (the user is PBXsrv only)
- voice mail server (the user is Vmailsrv only)
- conference server (the user is Conferencesrv only)
NOTE: user refers to userID, who needs to be pre-registered into the directory server database.

Scenario of how to use interface with directory service:
When a registered user (e.g. bergmark@cs.cornell.edu, Adm, Gatewaysrv, PBXsrv, Vmailsrv, Conferencesrv) starts up an application using the directory service, the following things NEED to happen:
1. The desktop signaling component object associated with the application needs to call DirectoryService.declareIdentity (with his/her userID and password as arguments) on the directory service object to authenticate and verify his/her identity before being allowed to use the directory serivice object.
2. The desktop signaling component then calls Directory.Service.registerLocation to register the application's location associated with the user.
(NOTE: For an itx application which may not support data exchange object, registerLocation does not need to be called.)
3. At this point, the application can use directory service object.
4. When application exits, the desktop signaling component is responsible to remove this location associated with the user.
(NOTE: If application exit adnormally, Adm needs to manually clean up the database in the directory server.)

Field Summary
`static int` | `ADM_ACCESS_LEVEL`
`private static java.lang.String` | `CONFIG_FILE`
`private DirectoryStub` | `m_DSstub`
`static int` | `MAX_EXTENSION_SIZE`
`static int` | `MIN_EXTENSION_SIZE`
`static int` | `NULL_ACCESS_LEVEL`
`static int` | `SERVER_ACCESS_LEVEL`
`static int` | `USER_ACCESS_LEVEL`

Constructor Summary
`DirectoryService()` Default constructor NOTE: It also sets up where to find the config file.
`DirectoryService(DSComm newDSComm)` Constructor for a given DSComm-derived object.
`DirectoryService(java.lang.String configFilePath)` Constructor for a given config file path to locate the config file.
`DirectoryService(java.lang.String configFilePath, DSComm newDSComm)` Constructor for a given config file path to locate the config file and a given DSComm-derived object.

Method Summary
`void` | `addCustomLocation(CustomLocation newCustomLocation)` Adds the custom location list of the user authenticated with this directory service
`void` | `addUser(UserID id, Digits newExtension, Password newPin, int accessLevel, java.lang.String customMsg)` Adds a new user into the directory database based on an input extension number.
`Digits` | `addUser(UserID id, int numberOfDigitForExtension, Password newPin, int accessLevel, java.lang.String customMsg)` Adds a new user into the directory database.
`void` | `declareIdentity(UserID id, Password pin)` Authenticate this directory service with the ID and corresponding PIN of the client BEFORE calling any methods. Client only needs to call this method once.
`void` | `deleteCustomLocation(java.lang.String customLocationID)` Deletes the custom location of the user authenticated with this directory service
`java.util.Vector` | `dumpAllUsers()` Dump all users' records from the directory database to the terminal output.
`int` | `getAccessLevel()` Get the access level of the user authenticated with this directory service
`java.util.Vector` | `getCustomLocationByExtension(Digits extension)` Gets all custom locations of the user authenticated with this directory service
`java.lang.String` | `getCustomMessage()` Get the custom message of the user authenticated with this directory service
`java.lang.String` | `getCustomMessageByID(UserID uid)` Get the custom message of the specified userID
`java.util.Vector` | `getDefaultLocationByExtension(Digits extension)` Gets all default locations of the user authenticated with this directory service
`Digits` | `getExtension()` Get the Extension of the user authenticated with this directory service
`Digits` | `getExtension(UserID id)` Get the extension from a given UserID
`UserID` | `getID()` Get the ID of the user authenticated with this directory service
`UserID` | `getID(Digits extension)` Get the UserID from a given extension
`LocationList` | `getLocationListByExtension(Digits extension)` Get the location list from a given extension
`LocationList` | `getLocationListByID(UserID id)` Get the location list from a given UserID.
`void` | `registerLocation(int locationType, Location newLocation)` Register the location of the user (authenticated with this directory service) when he/she starts up an application.
`void` | `removeUser(Digits extension)` Removes a user from the directory database.
`void` | `setCleanUp(boolean bCleanup)` Turn off or turn on the cleanup thread.
`void` | `setCustomMessage(java.lang.String newCustomMsg)` Set the custom message of the user authenticated with this directory service
`void` | `setDefaultLocation(java.lang.String newLocation)` Set the default location of the user authenticated with this directory service
`void` | `setPIN(UserID id, Password newPin)` Change the PIN of a registered user by the directory service administrator NOTE: Only the administrator has privilege to use this method; otherwise, AccessDeniedException will throw.
`void` | `setPIN(UserID id, Password currentPin, Password newPin)` Change the PIN of the user authenticated with this directory service.
`void` | `unregisterLocation(int locationType, Location newLocation)` Unregister the location of the user (authenticated with this directory service) when he/she exits from an application

Methods inherited from class java.lang.Object
`, clone, equals, finalize, getClass, hashCode, notify, notifyAll, registerNatives, toString, wait, wait, wait`

Field Detail

### NULL_ACCESS_LEVEL

    public static final int NULL_ACCESS_LEVEL

### USER_ACCESS_LEVEL

    public static final int USER_ACCESS_LEVEL

### SERVER_ACCESS_LEVEL

    public static final int SERVER_ACCESS_LEVEL

### ADM_ACCESS_LEVEL

    public static final int ADM_ACCESS_LEVEL

### MIN_EXTENSION_SIZE

    public static final int MIN_EXTENSION_SIZE

### MAX_EXTENSION_SIZE

    public static final int MAX_EXTENSION_SIZE

### CONFIG_FILE

    private static final java.lang.String CONFIG_FILE

### m_DSstub

    private DirectoryStub m_DSstub

Constructor Detail

### DirectoryService

    public DirectoryService()
                     throws DirectoryServiceException

  Default constructor
  NOTE: It also sets up where to find the config file. Config file is used to locate the Directory Server.
  The default location of the config file is in the same directory as DSComm.dll resides.

### DirectoryService

    public DirectoryService(java.lang.String configFilePath)
                     throws DirectoryServiceException

  Constructor for a given config file path to locate the config file. Config file is used to locate the Directory Server.
  NOTE: If default constructor is used instead, the config file (called resolv.conf) is assumed to be resided in the same directory as DSComm.dll resides.
  Parameters:
    `configFilePath` - a full file path to locate the config file.

### DirectoryService

    public DirectoryService(DSComm newDSComm)
                     throws DirectoryServiceException

  Constructor for a given DSComm-derived object.
  NOTE: It also sets up where to find the config file. Config file is used to locate the Directory Server.
  The default location of the config file is in the same directory as DSComm.dll resides.
  Parameters:
    `newDSComm` - a DSComm-derived object to provide customized interface communicating to user-defined directory database server.

### DirectoryService

    public DirectoryService(java.lang.String configFilePath,
                            DSComm newDSComm)
                     throws DirectoryServiceException

  Constructor for a given config file path to locate the config file and a given DSComm-derived object.
  Parameters:
    `configFilePath` - a full file path to locate the config file.
    `newDSComm` - a DSComm-derived object to provide customized interface communicating to user-defined directory database server.

Method Detail

### setCleanUp

    public void setCleanUp(boolean bCleanup)

  Turn off or turn on the cleanup thread. The default is ON, which means when a user call declareIdentity, the cleanup thread starts automatically.
  Parameters:
    `bCleanup` - false to turn off the cleanup thread; true to turn it on

### declareIdentity

    public void declareIdentity(UserID id,
                                Password pin)
                         throws AuthenticationException

  Authenticate this directory service with the ID and corresponding PIN of the client BEFORE calling any methods.
  Client only needs to call this method once.
  New user needs to register his/her ID and PIN via the administrator of the directory server.
  Parameters:
    `id` - user's ID
    `pin` - user's PIN

### getAccessLevel

    public int getAccessLevel()
                       throws AuthenticationException

  Get the access level of the user authenticated with this directory service
  Returns:
    the access level of the user (e.g. DirectoryService.USER_ACCESS_LEVEL, DirectoryService.SERVER_ACCESS_LEVEL, DirectoryService.ADM_ACCESS_LEVEL, DirectoryService.NULL_ACCESS_LEVEL)

### getID

    public UserID getID()
                 throws AuthenticationException,
                        AccessDeniedException,
                        RecordNotFoundException

  Get the ID of the user authenticated with this directory service
  Returns:
    user's ID

### getExtension

    public Digits getExtension()
                        throws AuthenticationException,
                               AccessDeniedException,
                               RecordNotFoundException

  Get the Extension of the user authenticated with this directory service
  Returns:
    Digits object to store user's extension

### setPIN

    public void setPIN(UserID id,
                       Password newPin)
                throws AuthenticationException,
                       AccessDeniedException,
                       RecordNotFoundException

  Change the PIN of a registered user by the directory service administrator NOTE: Only the administrator has privilege to use this method; otherwise, AccessDeniedException will throw.
  Parameters:
    `id` - user's ID
    `newPin` - new user's PIN

### setPIN

    public void setPIN(UserID id,
                       Password currentPin,
                       Password newPin)
                throws AuthenticationException,
                       AccessDeniedException,
                       RecordNotFoundException

  Change the PIN of the user authenticated with this directory service.
  Parameters:
    `id` - user's ID
    `currentPin` - user's PIN
    `newPin` - new user's PIN

### getCustomMessage

    public java.lang.String getCustomMessage()
                                      throws AuthenticationException,
                                             AccessDeniedException,
                                             RecordNotFoundException

  Get the custom message of the user authenticated with this directory service
  Returns:
    message string

### getCustomMessageByID

    public java.lang.String getCustomMessageByID(UserID uid)
                                          throws AuthenticationException,
                                                 AccessDeniedException,
                                                 RecordNotFoundException

  Get the custom message of the specified userID
  Parameters:
    `uid` - the userID corresponding to the custom message
  Returns:
    message string

### setCustomMessage

    public void setCustomMessage(java.lang.String newCustomMsg)
                          throws AuthenticationException,
                                 AccessDeniedException,
                                 RecordNotFoundException

  Set the custom message of the user authenticated with this directory service
  Parameters:
    `newCustomMsg` - new custom message

### registerLocation

    public void registerLocation(int locationType,
                                 Location newLocation)
                          throws AuthenticationException,
                                 AccessDeniedException,
                                 RecordNotFoundException

  Register the location of the user (authenticated with this directory service) when he/she starts up an application.
  Dialable location is allowed to be added ONLY as ROAMING or DYNAMIC location. Non-Dialable location is allowed to be added ONLY as DEFAULT location. Otherwise, an AccessDeniedException is thrown.
  Parameters:
    `locationType` - (e.g. Location.ROAMING, Location.DEFAULT, Location.DYNAMIC)
    `newLocation` - a new location object to be registered

### unregisterLocation

    public void unregisterLocation(int locationType,
                                   Location newLocation)
                            throws AuthenticationException,
                                   AccessDeniedException,
                                   RecordNotFoundException

  Unregister the location of the user (authenticated with this directory service) when he/she exits from an application
  Parameters:
    `locationType` - (e.g. Location.ROAMING, Location.DEFAULT, Location.DYNAMIC)
    `newLocation` - a location object to be unregistered

### getDefaultLocationByExtension

    public java.util.Vector getDefaultLocationByExtension(Digits extension)
                                                   throws AuthenticationException,
                                                          AccessDeniedException,
                                                          RecordNotFoundException

  Gets all default locations of the user authenticated with this directory service
  Parameters:
    `extension` - user's extension
  Returns:
    vector of location objects

### setDefaultLocation

    public void setDefaultLocation(java.lang.String newLocation)
                            throws AuthenticationException,
                                   AccessDeniedException,
                                   RecordNotFoundException

  Set the default location of the user authenticated with this directory service
  Parameters:
    `newLocation` - is the description of the new Default Location

### getCustomLocationByExtension

    public java.util.Vector getCustomLocationByExtension(Digits extension)
                                                  throws AuthenticationException,
                                                         AccessDeniedException,
                                                         RecordNotFoundException

  Gets all custom locations of the user authenticated with this directory service
  Parameters:
    `extension` - user's extension
  Returns:
    vector of CustomLocationRecord objects

### addCustomLocation

    public void addCustomLocation(CustomLocation newCustomLocation)
                           throws AuthenticationException,
                                  AccessDeniedException,
                                  RecordNotFoundException

  Adds the custom location list of the user authenticated with this directory service
  Parameters:
    `newCustomLocation` - a new custom location object

### deleteCustomLocation

    public void deleteCustomLocation(java.lang.String customLocationID)
                              throws AuthenticationException,
                                     AccessDeniedException,
                                     RecordNotFoundException

  Deletes the custom location of the user authenticated with this directory service
  Parameters:
    `customLocationID` - ID of the custom location to be deleted

### getExtension

    public Digits getExtension(UserID id)
                        throws AuthenticationException,
                               AccessDeniedException,
                               RecordNotFoundException

  Get the extension from a given UserID
  Parameters:
    `id` - user's ID
  Returns:
    user's extension represented by Digits object

### getID

    public UserID getID(Digits extension)
                 throws AuthenticationException,
                        AccessDeniedException,
                        RecordNotFoundException

  Get the UserID from a given extension
  Parameters:
    `extension` - user's extension
  Returns:
    user's ID

### getLocationListByID

    public LocationList getLocationListByID(UserID id)
                                     throws AuthenticationException,
                                            AccessDeniedException,
                                            RecordNotFoundException

  Get the location list from a given UserID. UserID can be one of the following:
  1. email (physical person registered in our directory database)
  2. server application (e.g. Gatewaysrv, PBXsrv, Vmailsrv, etc.)
  3. phone number
  Parameters:
    `id` - user's ID
  Returns:
    a list of location

### getLocationListByExtension

    public LocationList getLocationListByExtension(Digits extension)
                                            throws AuthenticationException,
                                                   AccessDeniedException,
                                                   RecordNotFoundException

  Get the location list from a given extension
  Parameters:
    `extension` - user's extension
  Returns:
    a list of location

### addUser

    public void addUser(UserID id,
                        Digits newExtension,
                        Password newPin,
                        int accessLevel,
                        java.lang.String customMsg)
                 throws AuthenticationException,
                        AccessDeniedException,
                        RecordAlreadyExistsException,
                        DirectoryServiceException

  Adds a new user into the directory database based on an input extension number.
  If the input extension number is already assigned, RecordAlreadyExistsException will be thrown.
  NOTE: Only the administrator has privilege to use this method; otherwise, AccessDeniedException will throw.
  Parameters:
    `id` - new user's id
    `newExtension` - new extension number to be assigned to the new user
    `newPin` - new user's password
    `accessLevel` - new user's access level (USER_ACCESS_LEVEL, SERVER_ACCESS_LEVEL, ADM_ACCESS_LEVEL)
    `customMsg` - custom message (can be empty)

### addUser

    public Digits addUser(UserID id,
                          int numberOfDigitForExtension,
                          Password newPin,
                          int accessLevel,
                          java.lang.String customMsg)
                   throws AuthenticationException,
                          AccessDeniedException,
                          RecordAlreadyExistsException,
                          DirectoryServiceException

  Adds a new user into the directory database. Returns a new extension associated with the new user.
  If user already exists in the database, RecordAlreadyExistsException will be thrown.
  If there is no available extension number, AccessDeniedException will be thrown.
  NOTE: Only the administrator has privilege to use this method; otherwise, AccessDeniedException will throw.
  Parameters:
    `id` - new user's id
    `numberOfDigitForExtension` - requested number of extension digits [DirectoryService.MIN_EXTENSION_SIZE...DirectoryService.MAX_EXTENSION_SIZE]
    `newPin` - new user's password
    `accessLevel` - new user's access level (USER_ACCESS_LEVEL, SERVER_ACCESS_LEVEL, ADM_ACCESS_LEVEL)
    `customMsg` - custom message (can be empty)
  Returns:
    extension of the new user

### removeUser

    public void removeUser(Digits extension)
                    throws AuthenticationException,
                           AccessDeniedException,
                           RecordNotFoundException,
                           DirectoryServiceException

  Removes a user from the directory database.
  NOTE: Only the administrator has privilege to use this method
  Parameters:
    `extension` - extension of the user to be removed

### dumpAllUsers

    public java.util.Vector dumpAllUsers()
                                  throws AuthenticationException,
                                         AccessDeniedException,
                                         RecordNotFoundException,
                                         DirectoryServiceException

  Dump all users' records from the directory database to the terminal output.
  Returns:
    a Vector of UserProperty objects

Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD