com.nitido.nimx.nuggets.helpdesk
Class HelpDeskNugget

java.lang.Object
  com.nitido.nim.Nugget
      com.nitido.nim.NonCachableNugget
          com.nitido.nimx.nuggets.iplanetset.IPlanetSettingsNugget
              com.nitido.nimx.nuggets.helpdesk.HelpDeskNugget

All Implemented Interfaces:

CredentialConstants, java.io.Serializable

Direct Known Subclasses:

HelpDeskNuggetImpl, HelpDeskNuggetImpl

public abstract class HelpDeskNugget
extends IPlanetSettingsNugget

HelpDeskNugget is responsible for accessing and modifying personal preference settings for the customer. This Nugget is supposed to be invoked by users who has administrative privileges, such as the customer representatatives. However, the Nugget itself does not manage the access control. The administrator should set up the correct Access Control List on the directory server.

This Nugget inherits most of the implementation from IPlanetSettingsNugget. The only major difference is on the login binding. In IPlanetSettingsNugget, all the attribute access are bound to the login user's entry. However, the bounded base of the entry can be switched on the fly.

Settings The settings used by HelpDeskNugget are:

Name	Constant	Type	Description
host	KEY_HOST	String	The host string can be an IP address or a host name. It must be provided when the nugget is created.
port	KEY_PORT	int String	A string that specifies the port number. It must be provided when the nugget is created.
adminbase	KEY_ADMINBASE	String	The base DN for the HelpDesk representatives to login with. i.e. this is the base DN of the administrator.
userbase	KEY_USERBASE	String	The base DN for the user profiles to be administrated. i.e. this is the base DN of the regular users.
dm.userid	KEY_DM_USERID	String	The login user id of the Directory Manager. (i.e. the DN)
dm.password	KEY_DM_PASSWORD	String	The login password of the Directory Manager.
directory.factory	KEY_DIRECTORY_FACTORY	String	The class name of the factory class of Nitido Directory library. If no value has been specified for this setting, this nugget will use the class "com.nitido.directory.jndi.DirectoryFactoryImpl" (i.e. the constant DEFAULT_DIRECTORY_FACTORY).

General Programming Model When you get a request to display or modified the settings for an user, you should first chose that user by selectUser( uid ). If you are using this Nugget within a web application, you must call selectUser( uid ) for every request. It is because the Nugget itself is stateless and does not cache the infromation about the user. For example, the code should be

 // assume you have got the instance of the nugget already.
 helpDeskNugget.selectUser( "some_user" );
 ....
 String commonName = helpDeskNugget.getCommonName(); 
 ....
 

The following comment is copied from IPlanetSettingsNugget.

This implementation has many methods for iPlanet Messaging Server (iMS). Most of these settings are all stored in a LDAP directory server that the iMS uses and they are impossible to be changed through the standard JavaMail API.

Replication Issue with Master-Slave Cluster LDAP Servers
iPlanet Messaging Server stores a number of "extension" settings in the same attribute of the user's entry on the LDAP server. Modifying this type of setting will require you to read all existing values of the attribute, to modify your specific setting and then to store the attribute.

If you are using a master-slave LDAP server cluster, this approach will become a problem. For example, let's say you need to modify two setting (A and B) in a row and both settings are "extension" settings. Assume you have modify the setting A successfully. When you modify the setting B and read the existing values from the slave, the replication of the cluster may not have been completed. As a result, you may read the old value for A. In other words, modifying setting B will overwrite the changes you made to A.

To solve this problem, you invoke startTransaction() before your settings modification calls and then invoke commitTransaction() after the calls. Here is an example:

 settingNugget.startTransaction();
 settingNugget.setSignature( "My new signature" );
 settingNugget.setReplyTo( "test-dummy@nitido.com" );
 settingNugget.commitTransaction();
 

The follwoing is a list of methods that acts on the iPlanet Messaging server "extended" settings:

• get/setSignature
• get/setSignatureEnabled
• get/setVCard
• get/setVCardEnabled
• get/setReplyTo
• get/setCopySend
• get/setReplyInclude
• get/setComposeWidth
• get/setPaginationSize
• get/setComposeTextSize

Flexible Attribute Access
For the sake of future extendability, the HelpDeskNugget provides a number of methods that allows the developer to specify the attributes to access. The methods are

• getSingleValue
• setSingleValue
• getMultiValues
• setMultiValues
• getExtendedPref
• setExtendedPref
• getExtendedMailPref
• setExtendedMailPref
• getExtendedCalendarPref
• setExtendedCalendarPref

Please not that all these methods are also facing the same "replication" issue mentioned above. If you need to set multiple attributes in a roll, you must invoke startTransaction() before the calls and commitTransaction() after the calls.

See Also:

Serialized Form

Field Summary

static java.lang.String	DEFAULT_DIRECTORY_FACTORY
static java.lang.String	KEY_ADMINBASE
static java.lang.String	KEY_DIRECTORY_FACTORY
static java.lang.String	KEY_DM_PASSWORD
static java.lang.String	KEY_DM_USERID
static java.lang.String	KEY_HOST
static java.lang.String	KEY_PORT
static java.lang.String	KEY_USERBASE

Fields inherited from class com.nitido.nim.Nugget

_entity, _nim, _nuggetName, _settings

Fields inherited from interface com.nitido.nim.CredentialConstants

CRED_ADMIN, CRED_CONTAINER, CRED_HELPDESK, CRED_SYSTEM, CRED_USER, KEY_PASSWORD

Constructor Summary

HelpDeskNugget(NuggetVisa visa)
Default Nugget constructor.

Method Summary

abstract java.util.Vector	search(java.lang.String filter) Search for an entry and retrieve ALL attributes associated to the matched entry.
abstract java.util.Vector	search(java.lang.String filter, java.lang.String[] attributes) Search for an entry and retrieve the specified attributes of the matched entry.
abstract void	selectUser(java.lang.String uid) Select the user id for the search.

Methods inherited from class com.nitido.nimx.nuggets.iplanetset.IPlanetSettingsNugget

abortTransaction, activate, addFilter, arrayToVector, checkInt, checkNonNull, commitTransaction, containsValue, createUniqueArray, deactivate, getCommonName, getComposeTextSize, getComposeWidth, getCopyForward, getCopyForwardEnabled, getCopySend, getDescriptor, getExtendedCalendarPref, getExtendedMailPref, getExtendedPref, getExternalMailSetting, getFilters, getMultiValues, getNotificationEmailAddress, getNotificationFrom, getNotificationListOption, getNotificationOption, getNotificationPhoneFrom, getNotificationPhoneListOption, getNotificationPhoneNumber, getNotificationPhoneOption, getNotificationPhoneUrgentOption, getNotificationUrgentOption, getPaginationSize, getReplyInclude, getReplyTo, getSignature, getSignatureEnabled, getSingleValue, getVacationMessageEnabled, getVacationMessageEndDate, getVacationMessageExternal, getVacationMessageInternal, getVacationMessageRepeatDays, getVacationMessageStartDate, getVacationMessageSubject, getVCard, getVCardEnabled, isExtendedMailPrefTrue, isLegalNotificationOption, removeExtendedPref, removeMultiValues, removeStringFromArray, replaceStringInArray, setBooleanExtendedMailPref, setCommonName, setComposeTextSize, setComposeWidth, setCopyForward, setCopyForwardEnabled, setCopySend, setExtendedCalendarPref, setExtendedMailPref, setExtendedPref, setExternalMailSetting, setFilters, setMultiValues, setNotificationEmailAddress, setNotificationFrom, setNotificationListOption, setNotificationOption, setNotificationPhoneFrom, setNotificationPhoneListOption, setNotificationPhoneOption, setNotificationPhoneUrgentOption, setNotificationUrgentOption, setPaginationSize, setReplyInclude, setReplyTo, setSignature, setSignatureEnabled, setSingleValue, setVacationMessageEnabled, setVacationMessageExternal, setVacationMessageInternal, setVacationMessageRepeatDays, setVacationMessageSubject, setVCard, setVCardEnabled, startTransaction, vectorToArray

Methods inherited from class com.nitido.nim.NonCachableNugget

isCachable

Methods inherited from class com.nitido.nim.Nugget

destroy, destroyImpl, getEntity, getNuggetName, getSetting, getSettings, init, initImpl, requestBegin, requestEnd

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

KEY_HOST

public static final java.lang.String KEY_HOST

See Also:

Constant Field Values

KEY_PORT

public static final java.lang.String KEY_PORT

See Also:

Constant Field Values

KEY_ADMINBASE

public static final java.lang.String KEY_ADMINBASE

See Also:

Constant Field Values

KEY_USERBASE

public static final java.lang.String KEY_USERBASE

See Also:

Constant Field Values

KEY_DM_USERID

public static final java.lang.String KEY_DM_USERID

See Also:

Constant Field Values

KEY_DM_PASSWORD

public static final java.lang.String KEY_DM_PASSWORD

See Also:

Constant Field Values

KEY_DIRECTORY_FACTORY

public static final java.lang.String KEY_DIRECTORY_FACTORY

See Also:

Constant Field Values

DEFAULT_DIRECTORY_FACTORY

public static final java.lang.String DEFAULT_DIRECTORY_FACTORY

See Also:

Constant Field Values

Constructor Detail

HelpDeskNugget

public HelpDeskNugget(NuggetVisa visa)

Default Nugget constructor.

Method Detail

selectUser

public abstract void selectUser(java.lang.String uid)

Select the user id for the search. After this method has been invoked, all following methods will access the ldap entry with DN "uid=uid, base dn specified by configuration property helpdesk.userbase" This behaviour will be stop when another user id has been selected. In other words,

This method is used to select the user to perform the action on. The user that create this Nugget must have been given the access privilege to the specified entries by the LDAP administrator. This Nugget will not attempt to manage the access privilege.

The default ldap configuration of iplanet allow the data to be readable by all valid user. Therefore, you will have no problem to access the user's information. You will only encounter the insufficient access rights problem when you tries to update it.

Due to performance concern, this method does not need to check if the LDAP server actually contains the specified user. This means that you can't guarantee the existence of uid until you access the attributes.

Parameters:

uid - The user id for the user to be selected.

search

public abstract java.util.Vector search(java.lang.String filter,
                                        java.lang.String[] attributes)
                                 throws IPlanetServerException

Search for an entry and retrieve the specified attributes of the matched entry.

This method will return a single value for each attribute. If the attribute contains more than one value, this method will return the first one that it encounters

The search is performed against the base specified by helpdesk.userbase in the configuration setting.

Parameters:

filter - the standard LDAP filter

attributes - a String array that contains the name of the attribute you want to fetch from the server. If this paramter is null or set to a 0-size array, this method will assume it's the String array {"uid"}.

Returns:

a vector of String[] with the values of the attributes specified.

Throws:

IPlanetServerException

search

public abstract java.util.Vector search(java.lang.String filter)
                                 throws IPlanetServerException

Search for an entry and retrieve ALL attributes associated to the matched entry.

This method will return a single value for each attribute. If the attribute contains more than one value, this method will return the first one that it encounters

The search is performed against the base specified by helpdesk.userbase in the configuration setting.

Parameters:

filter - the standard LDAP filter

Returns:

a vector of Hashtable objects that contains the attributes of the matched entry. Each attribute name in the hashtable are mapped to only one value. These hashtables may contain different set of names, as what would happened in the actual LDAP directory.

Throws:

IPlanetServerException