com.nitido.nimx.nuggets.pab
Class PABNugget

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

All Implemented Interfaces:

java.io.Serializable

Direct Known Subclasses:

PABNuggetImpl, PABNuggetStub

public abstract class PABNugget
extends CachableNugget

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 information supported by them.

See Also:

Serialized Form

Field Summary

Fields inherited from class com.nitido.nim.Nugget

_entity, _nim, _nuggetName, _settings

Constructor Summary

PABNugget(NuggetVisa visa)
Default Nugget constructor.

Method Summary

void	activate() Used by NiM Nugget mechanism.
abstract PABBatchResult	addEntries(PABEntry[] entries) Add a large number of entries in one batch.
abstract java.lang.String	addEntry(PABEntry entry) Add a new PAB entry.
void	deactivate() Used by NiM Nugget mechanism.
protected java.lang.String	generateNewCN(java.lang.String firstName, java.lang.String lastName)
protected java.lang.String	generateNewUN(java.lang.String cn)
java.lang.String	getDescriptor() Used by NiM Nugget mechanism.
abstract java.util.Vector	getEmailAddresses(java.lang.String entryUN) Resolve the specified unique name into a vector of email addresses.
abstract java.util.Enumeration	getEntries() An enumeration of PABEntries.
abstract java.util.Enumeration	getEntries(java.lang.String filter) An enumeration of PABEntries based on the search filter.
abstract PABEntry	getEntry(java.lang.String un) Fetch PABEntry based on the unique name.
abstract PABGroup	getGroup(java.lang.String un) Fetch the PABGroup based on the unique name.
abstract java.util.Enumeration	getGroupMembers(java.lang.String groupUN) Get the Unique Name of members belong to the group
abstract java.lang.String	getGroupObjectClass() Get the "objectclass" string that will be used by a PAB group LDAP entry.
abstract PABPerson	getPerson(java.lang.String un) Fetch the PABPerson based on the unique name.
abstract java.lang.String	getPersonObjectClass() Get the "objectclass" string that will be used by a PAB person LDAP entry.
protected abstract void	initImpl() Used by NiM Nugget mechanism.
abstract void	modifyEntry(PABEntry entry) Replace an existing PAB entry with the new one.
abstract void	removeEntry(PABEntry entry) Remove an existing PAB entry.
abstract void	removeFromGroup(java.lang.String groupUN, java.lang.String entryUN) Remove the specified PABEntry from the group.
abstract void	setGroupMembers(java.lang.String groupUN, java.util.Vector personUNs) Set the group member of a group.
abstract void	setGroups(java.util.Vector groupUNs, java.lang.String entryUN) Set the groups that the specified entryDN belongs to.

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

Constructor Detail

PABNugget

public PABNugget(NuggetVisa visa)

Default Nugget constructor.

Method Detail

initImpl

protected abstract void initImpl()
                          throws InitializationFailedException,
                                 InvalidSettingException

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

Specified by:

initImpl in class Nugget

Throws:

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

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

activate

public void activate()
              throws ActivationException

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

Overrides:

activate in class Nugget

Throws:

ActivationException - If unable to activate the Nugget

deactivate

public void deactivate()
                throws ActivationException

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

Overrides:

deactivate in class Nugget

Throws:

ActivationException - If unable to deactivate the Nugget

getDescriptor

public java.lang.String getDescriptor()

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

Specified by:

getDescriptor in class Nugget

Returns:

The string with the description of the Nugget.

getPerson

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

Fetch the PABPerson based on the unique name.

Parameters:

un - The unique name of the PABPerson.

Throws:

PABException

getGroup

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

Fetch the PABGroup based on the unique name.

Parameters:

un - The unique name of the PABGroup.

Throws:

PABException

getEntry

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

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

Parameters:

un - The unique name of the PABEntry.

Throws:

PABException

getEntries

public abstract java.util.Enumeration getEntries()
                                          throws PABException

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

Throws:

PABException

getEntries

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

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 );
 ....
 

Parameters:

filter - The filter string.

Throws:

PABException

addEntry

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

Add a new PAB entry.

Parameters:

entry - 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 abstract PABBatchResult addEntries(PABEntry[] entries)
                                   throws PABException

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

Parameters:

entries - 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 abstract void modifyEntry(PABEntry entry)
                          throws PABException,
                                 InvalidEntryException

Replace an existing PAB entry with the new one.

Parameters:

entry - The entry to be replaced.

Throws:

InvalidEntryException - If the specified entry does not exist.

PABException

removeEntry

public abstract void removeEntry(PABEntry entry)
                          throws PABException,
                                 InvalidEntryException

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.

Parameters:

entry - The entry to be removed.

Throws:

InvalidEntryException - If the specified entry does not exist.

PABException

setGroups

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

Set the groups that the specified entryDN belongs to.

Parameters:

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

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

Throws:

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

PABException

setGroupMembers

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

Set the group member of a group.

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

InvalidEntryException

removeFromGroup

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

Remove the specified PABEntry from the group.

Parameters:

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

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

Throws:

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

PABException

getGroupMembers

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

Get the Unique Name of members belong to the group

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 abstract java.util.Vector getEmailAddresses(java.lang.String entryUN)
                                            throws PABException

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.

Parameters:

entryUN -

Returns:

A vector of String with the emails in the format:

"Display Name" 

If no matches, an empty vector.

Throws:

PABException

getGroupObjectClass

public abstract 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 ).

Returns:

The LDAP "ObjectClass" string for PAB group.

getPersonObjectClass

public abstract 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 ).

Returns:

The LDAP "ObjectClass" string for PAB person.

generateNewUN

protected java.lang.String generateNewUN(java.lang.String cn)

generateNewCN

protected java.lang.String generateNewCN(java.lang.String firstName,
                                         java.lang.String lastName)