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