com.nitido.nimx.nuggets.pab.real
Class PABNuggetImpl

java.lang.Object
  com.nitido.nim.Nugget
      com.nitido.nim.CachableNugget
          com.nitido.nimx.nuggets.pab.PABNugget
              com.nitido.nimx.nuggets.pab.real.PABNuggetImpl

All Implemented Interfaces:

java.io.Serializable

public class PABNuggetImpl
extends PABNugget

Personal Address Book Nugget provides services for accessing and modifying a user's address book. It assume that the backend is LDAP directory type of data storage.

This nugget encapsulate the information of the address group and personal information with PABGroup and PABNugget classes. You should refer to the JavaDoc of these two classes for a detail list of infromation supported by them.

This nugget utilizes the com.nitido.nimx.services.dirpool.mozilla.DirPoolServiceImpl to obtain the Directory object from a connection pool.

PABNuggetImpl Settings
This nugget requires the following settings:

Name	Constant	Type	Description
readpool	KEY_READ_POOL	String	A pool name that has been configured for the DirPoolService. This connection pool will be used to obtain the read-only access to the backend directory server.
writepool	KEY_WRITE_POOL	String	A pool name that has been configured for the DirPoolService. This connection pool will be used to obtain the write access to the backend directory server.
base	KEY_BASE	String	The base DN of the PAB entry. For example, if the pab entry has the DN in the format of "uid=myUid,o=pab,dc=nitido,dc=com", the base DN for this nugget will be "o=pab,dc=nitido,dc=com".
dm.userid	KEY_DM_USERID	String	The Directory Manager's login DN. e.g. "cn=Directory Manager"
dm.password	KEY_DM_PASSWORD	String	The Directory Manager's login password.
oc.pabperson	KEY_OC_PABPERSON	String	The LDAP objectclass for PAB Person entries. This is an optional configuration. If it is not specified, the default value "pabperson" will be used.
oc.pabgroup	KEY_OC_PABGROUP	String	The LDAP objectclass for PAB Group entries. This is an optional configuration. If it is not specified, the default value "pabgroup" will be used.

See Also:

Serialized Form

Field Summary

protected java.lang.String	_addrBookUN The UN of the address book.
protected java.lang.String	_base The parent base of all user PAB subtree.
protected java.lang.String	_dmPwd The DirectoryManager password.
protected java.lang.String	_dmUid The DirectoryManager user id.
protected java.lang.String	_ocPABGroup The object class of the PAB group
protected java.lang.String	_ocPABPerson The object class of the PAB person
protected java.lang.String	_pabBase The user's PAB subtree.
protected java.lang.String	_readPoolName The read pool name.
protected java.lang.String	_userid The user's own ID.
protected java.lang.String	_writePoolName The write pool name.
protected static java.lang.String	AT_EMAIL
protected static java.lang.String	AT_GROUP_MEM
protected static java.lang.String	AT_OBJ_CLASS
protected static java.lang.String	AT_PAB
protected static java.lang.String	DEFAULT_OC_PABGROUP
protected static java.lang.String	DEFAULT_OC_PABPERSON
static java.lang.String	KEY_BASE Constant String of the setting key "base".
static java.lang.String	KEY_DM_PASSWORD Constant String of the setting key "dm.password".
static java.lang.String	KEY_DM_USERID Constant String of the setting key "dm.userid".
static java.lang.String	KEY_OC_PABGROUP Constant String of the setting key "oc.pabgroup".
static java.lang.String	KEY_OC_PABPERSON Constant String of the setting key "oc.pabperson".
static java.lang.String	KEY_READ_POOL Constant String of the setting key "readpool".
static java.lang.String	KEY_WRITE_POOL Constant String of the setting key "writepool".

Fields inherited from class com.nitido.nim.Nugget

_entity, _nim, _nuggetName, _settings

Constructor Summary

PABNuggetImpl(NuggetVisa visa)

Method Summary

void	activate() Used by NiM Nugget mechanism.
PABBatchResult	addEntries(PABEntry[] pabEntries) Add a large number of entries in one batch.
java.lang.String	addEntry(PABEntry pabEntry) Add a new PAB entry.
protected void	addEntryToDir(Directory writeDir, java.lang.String un, PABEntry pabEntry) A method that provides the potential customized logic for adding a PAB entry to the LDAP server.
protected Directory	connectRead()
protected Directory	connectWrite()
void	deactivate() Used by NiM Nugget mechanism.
protected void	dirAttrToPABAttr(Entry entry, PABEntry pab)
protected PABGroup	dirEntryToPABGroup(Entry entry) Method that converts a directory entry into a PABGroup object.
protected PABPerson	dirEntryToPABPerson(Entry entry) Method that converts a directory entry into a PABPerson object.
protected boolean	dirToPabExcluded(java.lang.String key)
protected void	disconnectRead(Directory readDir)
protected void	disconnectWrite(Directory writeDir)
java.util.Vector	getEmailAddresses(java.lang.String entryUN) Resolve the specified unique name into a vector of email addresses.
java.util.Enumeration	getEntries() An enumeration of PABEntries.
java.util.Enumeration	getEntries(java.lang.String filter) An enumeration of PABEntries based on the search filter.
PABEntry	getEntry(java.lang.String un) Fetch PABEntry based on the unique name.
protected PABEntry	getEntryByFilter(java.lang.String filter)
PABGroup	getGroup(java.lang.String un) Fetch the PABGroup based on the unique name.
java.util.Enumeration	getGroupMembers(java.lang.String groupUN) Get the Unique Name of members belong to the group
java.lang.String	getGroupObjectClass() Get the "objectclass" string that will be used by a PAB group LDAP entry.
PABPerson	getPerson(java.lang.String un) Fetch the PABPerson based on the unique name.
java.lang.String	getPersonObjectClass() Get the "objectclass" string that will be used by a PAB person LDAP entry.
protected void	handleObjectClassChange(Directory writeDir, java.lang.String dn, PABEntry oldEntry, PABEntry newEntry) A method that provides the potential logic for object class changes.
protected void	initImpl() Used by NiM Nugget mechanism.
protected java.util.Enumeration	internalGetEntries(java.lang.String filter)
protected PABEntry	internalGetEntry(Directory readDir, java.lang.String un)
protected PABEntry	internalGetEntryByFilter(Directory readDir, java.lang.String filter)
void	modifyEntry(PABEntry pabEntry) Replace an existing PAB entry with the new one.
protected void	pabAttrToDirAttr(PABEntry pab, Entry entry)
protected Entry	pabEntryToDirEntry(java.lang.String dn, PABEntry pab)
protected boolean	pabToDirExcluded(java.lang.String key)
void	removeEntry(PABEntry dyingEntry) Remove an existing PAB entry.
void	removeFromGroup(java.lang.String groupUN, java.lang.String personUN) Remove the specified PABEntry from the group.
protected void	setGroupFixedAttributes(PABEntry entry) Method that set the "fixed" (always present) attributes of a PAB group entry.
void	setGroupMembers(java.lang.String groupUN, java.util.Vector personUNs) Set the group member of a group.
void	setGroups(java.util.Vector groupUNs, java.lang.String personUN) Set the groups that the specified entryDN belongs to.
protected void	setPersonFixedAttributes(PABEntry entry) Method that set the "fixed" (always present) attributes of a PAB person entry.
protected void	setupDirectory()

Methods inherited from class com.nitido.nimx.nuggets.pab.PABNugget

generateNewCN, generateNewUN, getDescriptor

Methods inherited from class com.nitido.nim.CachableNugget

isCachable

Methods inherited from class com.nitido.nim.Nugget

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

Methods inherited from class java.lang.Object

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

Field Detail

KEY_READ_POOL

public static final java.lang.String KEY_READ_POOL

Constant String of the setting key "readpool".

See Also:

Constant Field Values

KEY_WRITE_POOL

public static final java.lang.String KEY_WRITE_POOL

Constant String of the setting key "writepool".

See Also:

Constant Field Values

KEY_BASE

public static final java.lang.String KEY_BASE

Constant String of the setting key "base".

See Also:

Constant Field Values

KEY_DM_USERID

public static final java.lang.String KEY_DM_USERID

Constant String of the setting key "dm.userid".

See Also:

Constant Field Values

KEY_DM_PASSWORD

public static final java.lang.String KEY_DM_PASSWORD

Constant String of the setting key "dm.password".

See Also:

Constant Field Values

KEY_OC_PABPERSON

public static final java.lang.String KEY_OC_PABPERSON

Constant String of the setting key "oc.pabperson".

See Also:

Constant Field Values

KEY_OC_PABGROUP

public static final java.lang.String KEY_OC_PABGROUP

Constant String of the setting key "oc.pabgroup".

See Also:

Constant Field Values

DEFAULT_OC_PABPERSON

protected static final java.lang.String DEFAULT_OC_PABPERSON

See Also:

Constant Field Values

DEFAULT_OC_PABGROUP

protected static final java.lang.String DEFAULT_OC_PABGROUP

See Also:

Constant Field Values

AT_OBJ_CLASS

protected static final java.lang.String AT_OBJ_CLASS

See Also:

Constant Field Values

AT_PAB

protected static final java.lang.String AT_PAB

See Also:

Constant Field Values

AT_GROUP_MEM

protected static final java.lang.String AT_GROUP_MEM

See Also:

Constant Field Values

AT_EMAIL

protected static final java.lang.String AT_EMAIL

See Also:

Constant Field Values

_ocPABPerson

protected java.lang.String _ocPABPerson

The object class of the PAB person

_ocPABGroup

protected java.lang.String _ocPABGroup

The object class of the PAB group

_readPoolName

protected java.lang.String _readPoolName

The read pool name.

_writePoolName

protected java.lang.String _writePoolName

The write pool name.

_addrBookUN

protected java.lang.String _addrBookUN

The UN of the address book. (All of its member should have memberOfPAB attribute pointing to this UN.)

_base

protected java.lang.String _base

The parent base of all user PAB subtree. (e.g. ou=People, o=nitido.com, o=isp, o=pab)

_dmUid

protected java.lang.String _dmUid

The DirectoryManager user id. (i.e. the DN).

_dmPwd

protected java.lang.String _dmPwd

The DirectoryManager password.

_pabBase

protected java.lang.String _pabBase

The user's PAB subtree. In other words, it is the base of all PAB entries of the user. (e.g. ou=MyUserId, ou=People, o=nitido.com, o=isp, o=pab)

_userid

protected java.lang.String _userid

The user's own ID.

Constructor Detail

PABNuggetImpl

public PABNuggetImpl(NuggetVisa visa)

Method Detail

activate

public void activate()
              throws ActivationException

Description copied from class: PABNugget

Used by NiM Nugget mechanism. An application developer should never invoke this.

Overrides:

activate in class PABNugget

Throws:

ActivationException - If unable to activate the Nugget

deactivate

public void deactivate()
                throws ActivationException

Description copied from class: PABNugget

Used by NiM Nugget mechanism. An application developer should never invoke this.

Overrides:

deactivate in class PABNugget

Throws:

ActivationException - If unable to deactivate the Nugget

initImpl

protected void initImpl()
                 throws InitializationFailedException,
                        InvalidSettingException

Description copied from class: PABNugget

Used by NiM Nugget mechanism. An application developer should never invoke this.

Specified by:

initImpl in class PABNugget

Throws:

InitializationFailedException - If unable to initialize the nugget with the given parameters.

InvalidSettingException - If any of the expected initialization settings are null.

connectRead

protected Directory connectRead()
                         throws InitializationFailedException

Throws:

InitializationFailedException

connectWrite

protected Directory connectWrite()
                          throws InitializationFailedException

Throws:

InitializationFailedException

disconnectRead

protected void disconnectRead(Directory readDir)

disconnectWrite

protected void disconnectWrite(Directory writeDir)

setupDirectory

protected void setupDirectory()
                       throws DirectoryException,
                              InitializationFailedException

Throws:

DirectoryException

InitializationFailedException

getPerson

public PABPerson getPerson(java.lang.String un)
                    throws PABException

Description copied from class: PABNugget

Fetch the PABPerson based on the unique name.

Specified by:

getPerson in class PABNugget

Parameters:

un - The unique name of the PABPerson.

Throws:

PABException

getGroup

public PABGroup getGroup(java.lang.String un)
                  throws PABException

Description copied from class: PABNugget

Fetch the PABGroup based on the unique name.

Specified by:

getGroup in class PABNugget

Parameters:

un - The unique name of the PABGroup.

Throws:

PABException

getEntry

public PABEntry getEntry(java.lang.String un)
                  throws PABException

Description copied from class: PABNugget

Fetch PABEntry based on the unique name. In other words, the result can be either a PABGroup or a PABPerson.

Specified by:

getEntry in class PABNugget

Parameters:

un - The unique name of the PABEntry.

Throws:

PABException

internalGetEntry

protected PABEntry internalGetEntry(Directory readDir,
                                    java.lang.String un)
                             throws PABException

Throws:

PABException

internalGetEntryByFilter

protected PABEntry internalGetEntryByFilter(Directory readDir,
                                            java.lang.String filter)
                                     throws DirectoryException

Throws:

DirectoryException

getEntryByFilter

protected PABEntry getEntryByFilter(java.lang.String filter)
                             throws PABException

Throws:

PABException

getEntries

public java.util.Enumeration getEntries()
                                 throws PABException

Description copied from class: PABNugget

An enumeration of PABEntries. This returns all the PAB Entries stored by the user.

Specified by:

getEntries in class PABNugget

Throws:

PABException

getEntries

public java.util.Enumeration getEntries(java.lang.String filter)
                                 throws PABException

Description copied from class: PABNugget

An enumeration of PABEntries based on the search filter.

The filter string follows the LDAP Search Filter standard (RFC 2254).

For example, if you want to get all person and folders with unique name starts with 'A', you may type in the following code:

 String filter = "( "+PABEntry.UNIQUE_NAME+"=A* )";

 Enumeration entries = getEntries( filter );
 ....
 

Specified by:

getEntries in class PABNugget

Parameters:

filter - The filter string.

Throws:

PABException

internalGetEntries

protected java.util.Enumeration internalGetEntries(java.lang.String filter)
                                            throws PABException

Throws:

PABException

addEntry

public java.lang.String addEntry(PABEntry pabEntry)
                          throws InvalidEntryException,
                                 PABException

Description copied from class: PABNugget

Add a new PAB entry.

Specified by:

addEntry in class PABNugget

Parameters:

pabEntry - The entry to be added. A new entry does not require the un specified (i.e. just pass "" to the un parameter when you construct the object).

Returns:

If successful, this method will return the "un" (UNIQUE_NAME) of the new entry.

Throws:

InvalidEntryException - Thrown when another entry with the same unique name already exists.

PABException

addEntries

public PABBatchResult addEntries(PABEntry[] pabEntries)
                          throws PABException

Description copied from class: PABNugget

Add a large number of entries in one batch. This method is mainly used for importing address book.

Specified by:

addEntries in class PABNugget

Parameters:

pabEntries - The list of PABEntry objects to be added.

Returns:

If successful, this method will return the "un" (UNIQUE_NAME) of the new entry.

Throws:

PABException - Major problem at the backend (such as major IO exception). For other entry specific errors, this method will only indicate those error codes in the PABBatchResult object instead of throwing an exception.

modifyEntry

public void modifyEntry(PABEntry pabEntry)
                 throws InvalidEntryException,
                        PABException

Description copied from class: PABNugget

Replace an existing PAB entry with the new one.

Specified by:

modifyEntry in class PABNugget

Parameters:

pabEntry - The entry to be replaced.

Throws:

InvalidEntryException - If the specified entry does not exist.

PABException

removeEntry

public void removeEntry(PABEntry dyingEntry)
                 throws InvalidEntryException,
                        PABException

Description copied from class: PABNugget

Remove an existing PAB entry.

If it is a PABGroup, this will remove the links to child PABEntry that it contains. However, it would not attempt to remove them from the system completely.

Specified by:

removeEntry in class PABNugget

Parameters:

dyingEntry - The entry to be removed.

Throws:

InvalidEntryException - If the specified entry does not exist.

PABException

setGroups

public void setGroups(java.util.Vector groupUNs,
                      java.lang.String personUN)
               throws InvalidEntryException,
                      PABException

Description copied from class: PABNugget

Set the groups that the specified entryDN belongs to.

Specified by:

setGroups in class PABNugget

Parameters:

groupUNs - The unique name of groups that the entry is going to be added to.

personUN - The unique name of the entry to be added.

Throws:

InvalidEntryException - If the entry or one of the specified groups does not exist.

PABException

removeFromGroup

public void removeFromGroup(java.lang.String groupUN,
                            java.lang.String personUN)
                     throws InvalidEntryException,
                            PABException

Description copied from class: PABNugget

Remove the specified PABEntry from the group.

Specified by:

removeFromGroup in class PABNugget

Parameters:

groupUN - The unique name of the group that the entry is going to be removed to.

personUN - The unique name of the entry to be added.

Throws:

InvalidEntryException - If the entry or the group does not exist.

PABException

setGroupMembers

public void setGroupMembers(java.lang.String groupUN,
                            java.util.Vector personUNs)
                     throws PABException

Description copied from class: PABNugget

Set the group member of a group.

Specified by:

setGroupMembers in class PABNugget

Parameters:

groupUN - The unique name of the target group

personUNs - The UNs of the PAB persons to be added to the group.

Throws:

PABException - PB problem

getGroupMembers

public java.util.Enumeration getGroupMembers(java.lang.String groupUN)
                                      throws InvalidEntryException,
                                             PABException

Description copied from class: PABNugget

Get the Unique Name of members belong to the group

Specified by:

getGroupMembers in class PABNugget

Parameters:

groupUN - The unique name of the group

Returns:

An Enumeration of PABPerson objects that belongs to the group.

Throws:

InvalidEntryException - If the entry does not exist.

PABException

getEmailAddresses

public java.util.Vector getEmailAddresses(java.lang.String entryUN)
                                   throws PABException

Description copied from class: PABNugget

Resolve the specified unique name into a vector of email addresses.

If it is a person, it will return the email of the corresponding person (if it is specified).

If it is a group, it will return the email addresses of ALL members.

Specified by:

getEmailAddresses in class PABNugget

Returns:

A vector of String with the emails in the format:

"Display Name" 

If no matches, an empty vector.

Throws:

PABException

getGroupObjectClass

public java.lang.String getGroupObjectClass()

Get the "objectclass" string that will be used by a PAB group LDAP entry. This string is used to differentiate a PAB group entry from a PAB person entry in the LDAP server. It is usually used for constructing the LDAP search filter string for invoking the method getEntries( String filter ).

The default implementation always return "pabgroup". The specific implementation should overwrite it with their implementation specific object class name.

Specified by:

getGroupObjectClass in class PABNugget

Returns:

The LDAP "ObjectClass" string for PAB group.

getPersonObjectClass

public java.lang.String getPersonObjectClass()

Get the "objectclass" string that will be used by a PAB person LDAP entry. This string is used to differentiate a PAB person entry from a PAB group entry in the LDAP server. It is usually used for constructing the LDAP search filter string for invoking the method getEntries( String filter ).

The default implementation always return "pabperson". The specific implementation should overwrite it with their implementation specific object class name.

Specified by:

getPersonObjectClass in class PABNugget

Returns:

The LDAP "ObjectClass" string for PAB person.

dirAttrToPABAttr

protected void dirAttrToPABAttr(Entry entry,
                                PABEntry pab)

pabAttrToDirAttr

protected void pabAttrToDirAttr(PABEntry pab,
                                Entry entry)

pabEntryToDirEntry

protected Entry pabEntryToDirEntry(java.lang.String dn,
                                   PABEntry pab)
                            throws InvalidAttributeException

Throws:

InvalidAttributeException

dirToPabExcluded

protected boolean dirToPabExcluded(java.lang.String key)

pabToDirExcluded

protected boolean pabToDirExcluded(java.lang.String key)

setPersonFixedAttributes

protected void setPersonFixedAttributes(PABEntry entry)

Method that set the "fixed" (always present) attributes of a PAB person entry. It can be override by client specific logic. (e.g. Sprint waimea has its own object class definition)

setGroupFixedAttributes

protected void setGroupFixedAttributes(PABEntry entry)

Method that set the "fixed" (always present) attributes of a PAB group entry. It can be override by client specific logic. (e.g. Sprint waimea has its own object class definition)

dirEntryToPABPerson

protected PABPerson dirEntryToPABPerson(Entry entry)

Method that converts a directory entry into a PABPerson object. It can be override by client specific logic. (e.g. Sprint waimea has its own object class definition)

dirEntryToPABGroup

protected PABGroup dirEntryToPABGroup(Entry entry)

Method that converts a directory entry into a PABGroup object. It can be override by client specific logic. (e.g. Sprint waimea has its own object class definition)

handleObjectClassChange

protected void handleObjectClassChange(Directory writeDir,
                                       java.lang.String dn,
                                       PABEntry oldEntry,
                                       PABEntry newEntry)
                                throws DirectoryException

A method that provides the potential logic for object class changes. This is mainly a "place holder" for client specific customization. (e.g. Sprint waimea)

Throws:

DirectoryException

addEntryToDir

protected void addEntryToDir(Directory writeDir,
                             java.lang.String un,
                             PABEntry pabEntry)
                      throws DirectoryException,
                             InvalidAttributeException

A method that provides the potential customized logic for adding a PAB entry to the LDAP server. This is mainly a "place holder" for client specific customization. (e.g. Sprint waimea overwrite this method to add the sync flag.)

Throws:

DirectoryException

InvalidAttributeException