com.nitido.nimx.nuggets.iplanetset
Class IPlanetSettingsNugget

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

All Implemented Interfaces:

CredentialConstants, java.io.Serializable

Direct Known Subclasses:

HelpDeskNugget, IPlanetSettingsNuggetImpl, IPlanetSettingsNuggetImpl, IPlanetSettingsNuggetImpl, IPlanetSettingsNuggetImpl

public abstract class IPlanetSettingsNugget
extends NonCachableNugget
implements CredentialConstants

IPlanetSettingsNugget is responsible for accessing and modifying personal preference settings that may involve more than one iPlanet servers.

This Nugget provides the following additional features that the regular NiM Entity User Space did not provide:

1. Many SunONE servers combine a number of preferences together as a single multi-value LDAP attribute. For example, the iPlanet Messaging Server stores the preferenses as a single multi-value attribute "nswmExtendedUserPrefs". Each value of this attribute is a "key=value" concatenated string. This nugget provides method that searches the list of "nswmExtendedUserPrefs" values and modify the specified "key=value" concatenated string.
2. This nugget frees the developer from worrying about synchronizing on the user space. Once the startTransaction() method has been invoked, any operation performed on this nugget will not be stored to the backend until commitTransaction() is invoked. Therefore, the application developer no longer need to worry about synchronization as long as an instance of this nugget is accessible by only one thread.

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 IPlanetSettingsNugget 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

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

IPlanetSettingsNugget(NuggetVisa visa)
Default Nugget constructor.

Method Summary

abstract void	abortTransaction() Abort a batch of settings change.
void	activate() Used by NiM Nugget mechanism.
void	addFilter(Filter filter) To add a message filter for the user.
protected java.util.Vector	arrayToVector(java.lang.String[] array) Copies an array into a vector
protected void	checkInt(java.lang.String key)
protected void	checkNonNull(java.lang.String key)
abstract void	commitTransaction() Commits a batch of settings change.
boolean	containsValue(java.lang.String attribute, java.lang.String value) Returns true if the attribute contains the specified value.
protected java.lang.String[]	createUniqueArray(java.lang.String[] array) Constructs a new array based on the one passed in and makes sure that all values in the array are unique
void	deactivate() Used by NiM Nugget mechanism.
java.lang.String	getCommonName() To retrieve the common name of the mail user.
int	getComposeTextSize() To retrieve an int value of the compose message text font size.
int	getComposeWidth() To retrieve an int value of the compose window width.
java.lang.String[]	getCopyForward() To retrieve the copy forward list of the mail user.
boolean	getCopyForwardEnabled() To retrieve the copy forward enabled/disabled flag.
boolean	getCopySend() To retrieve an indicator for the copysend field.
java.lang.String	getDescriptor() Used by NiM Nugget mechanism.
java.lang.String	getExtendedCalendarPref(java.lang.String name) Returns a single value from a set of iPlanet icsExtendedUserPrefs attributes.
java.lang.String	getExtendedMailPref(java.lang.String name) Returns a single value from a set of iPlanet nswmExtendedUserPrefs attributes.
java.lang.String	getExtendedPref(java.lang.String extAttr, java.lang.String name) Returns a single value from a set of preferences in an extended attribute.
java.util.Vector	getExternalMailSetting() Get the External Mail Setting.
java.util.Vector	getFilters() To retrieve filters for this user.
abstract java.lang.String[]	getMultiValues(java.lang.String attribute) Returns all values of the attribute in the user's entry.
java.lang.String	getNotificationEmailAddress() Returns the E-mail address that notification messages are sent to.
java.lang.String[]	getNotificationFrom() Returns an array of String objects each containing an e-mail address that can trigger a notification when mail is received from that address.
boolean	getNotificationListOption() Gets the e-mail notifictaion list option.
java.lang.String	getNotificationOption() Returns the current e-mail notification option setting.
java.lang.String[]	getNotificationPhoneFrom() Returns an array of String objects each containing an e-mail address that triggers PCS phone based notification.
boolean	getNotificationPhoneListOption() Gets the phone notifictaion list option.
java.lang.String	getNotificationPhoneNumber() Returns the PCS phone number to send notification to.
java.lang.String	getNotificationPhoneOption() Returns the current phone notification option setting.
boolean	getNotificationPhoneUrgentOption() Returns whether the urgent option is set for phone notification.
boolean	getNotificationUrgentOption() Returns whether the urgent option is set for e-mail notification.
int	getPaginationSize() To retrieve an int value of the page size.
boolean	getReplyInclude() To retrieve an indicator for the reply included flag.
java.lang.String	getReplyTo() To retrieve the name of the reply to field.
java.lang.String	getSignature() To retrieve the signature of the mail user.
boolean	getSignatureEnabled() To retrieve the flag indicating whether the user signature is enabled or not.
java.lang.String	getSingleValue(java.lang.String attribute) Returns a single value of the attribute in the user's entry.
boolean	getVacationMessageEnabled() To retrieve an indicator whether the vacation message has been enabled.
java.lang.String	getVacationMessageEndDate() Retrieves the effective end date of the vacation message.
java.lang.String	getVacationMessageExternal() To retrieve the vacation message for external recipients.
java.lang.String	getVacationMessageInternal() To retrieve the vacation message for internal recipients.
int	getVacationMessageRepeatDays() Returns the number of days between sending a repeat of the vacation message to senders.
java.lang.String	getVacationMessageStartDate() Retrieves the effective start date of the vacation message.
java.lang.String	getVacationMessageSubject() To retrieve the vacation message subject line.
java.lang.String	getVCard() To retrieve the vCard of the mail user.
boolean	getVCardEnabled() To retrieve the vCard enabled flag of the mail user.
protected boolean	isExtendedMailPrefTrue(java.lang.String name) Returns true if the extended pref is set to "true"
protected boolean	isLegalNotificationOption(java.lang.String value)
protected void	removeExtendedPref(java.lang.String extAttr, java.lang.String name)
protected abstract void	removeMultiValues(java.lang.String attribute) Removes the specified attribute from the user's entry.
protected java.lang.String[]	removeStringFromArray(java.lang.String[] array, java.lang.String value) Constructs a new array based on the one passed in with the parameter value removed from it if it is there.
protected java.lang.String[]	replaceStringInArray(java.lang.String[] array, java.lang.String value) Constructs a new array based on the one passed in and an extra value.
protected void	setBooleanExtendedMailPref(java.lang.String name, boolean enable)
void	setCommonName(java.lang.String commonName) To set the common name of the mail user.
void	setComposeTextSize(int composeTextSize) To set the compose text font size.
void	setComposeWidth(int composeWidth) To set the width of the compose window.
void	setCopyForward(java.lang.String[] copyForwardList) To set the copy forward list for the mail user.
void	setCopyForwardEnabled(boolean enable) To set the copy forward enabled/disabled flag.
void	setCopySend(boolean copySend) To set the copy send flag.
void	setExtendedCalendarPref(java.lang.String prefName, java.lang.String prefValue) Sets an icsExtendedUserPrefs value.
void	setExtendedMailPref(java.lang.String name, java.lang.String value) Sets an nswmExtendedUserPrefs value.
void	setExtendedPref(java.lang.String extAttr, java.lang.String name, java.lang.String value) Sets a value within a set of preferences in an extended attribute.
void	setExternalMailSetting(java.util.Vector extMailSettings) Set the External Mail Setting.
void	setFilters(java.util.Vector filters) To set the message filters for the user.
abstract void	setMultiValues(java.lang.String attribute, java.lang.String[] values) Sets the attribute/value for the user's entry in the Directory.
void	setNotificationEmailAddress(java.lang.String address) Sets the E-mail address that notification messages are sent to.
void	setNotificationFrom(java.lang.String[] addresses) Sets an array of String objects each containing an e-mail address that can trigger a notification when mail is received from that address.
void	setNotificationListOption(boolean option) Sets the e-mail notifictaion list option.
void	setNotificationOption(java.lang.String option) Sets the current e-mail notification option setting.
void	setNotificationPhoneFrom(java.lang.String[] addresses) Sets an array of String objects each containing an e-mail address that triggers PCS phone based notification.
void	setNotificationPhoneListOption(boolean option) Sets the phone notifictaion list option.
void	setNotificationPhoneOption(java.lang.String option) Sets the current phone notification option setting.
void	setNotificationPhoneUrgentOption(boolean urgent) Sets whether the urgent option is set for phone notification.
void	setNotificationUrgentOption(boolean urgent) Sets whether the urgent option is set for e-mail notification.
void	setPaginationSize(int pageSize) To set the page size..
void	setReplyInclude(boolean replyInclude) To set the reply included flag.
void	setReplyTo(java.lang.String replyTo) To set the reply to field.
void	setSignature(java.lang.String signature) To set the signature of the mail user.
void	setSignatureEnabled(boolean enable) To set the signature enabled flag for the mail user.
abstract void	setSingleValue(java.lang.String attribute, java.lang.String value) Sets the attribute/value pair for the user's entry in the Directory.
void	setVacationMessageEnabled(boolean enable, java.lang.String startDate, java.lang.String endDate) To set the indicator to enable or disable vacation message.
void	setVacationMessageExternal(java.lang.String vacationMessage) To set the vacation message for external recipients.
void	setVacationMessageInternal(java.lang.String vacationMessage) To set the vacation message for internal recipients.
void	setVacationMessageRepeatDays(int days) Sets the number of days between sending a repeat of the vacation message to senders.
void	setVacationMessageSubject(java.lang.String vacationMessage) To set the vacation message subject.
void	setVCard(java.lang.String vcard) To set the vCard for the mail user.
void	setVCardEnabled(boolean enable) To set the vCard enable/disable flag for the mail user.
abstract void	startTransaction() Starts a batch of settings change.
protected java.lang.String[]	vectorToArray(java.util.Vector values) Returns an array of strings from a vector of Strings

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

Constructor Detail

IPlanetSettingsNugget

public IPlanetSettingsNugget(NuggetVisa visa)

Default Nugget constructor.

Method Detail

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.

getExternalMailSetting

public java.util.Vector getExternalMailSetting()
                                        throws IPlanetServerException

Get the External Mail Setting.

Returns:

a vector of ExternalMailSetting object.

Throws:

IPlanetServerException

setExternalMailSetting

public void setExternalMailSetting(java.util.Vector extMailSettings)
                            throws IPlanetServerException

Set the External Mail Setting.

Parameters:

extMailSettings - a vector of ExternalMailSetting object.

Throws:

IPlanetServerException

getVacationMessageSubject

public java.lang.String getVacationMessageSubject()
                                           throws IPlanetServerException

To retrieve the vacation message subject line.

Returns:

String value of the vacation message's subject.

Throws:

IPlanetServerException - error occurred when contacting the backend server.

setVacationMessageSubject

public void setVacationMessageSubject(java.lang.String vacationMessage)
                               throws IPlanetServerException

To set the vacation message subject.

Parameters:

vacationMessage - String value for the vacation message.

Throws:

IPlanetServerException - error occurred when contacting the backend server.

getVacationMessageInternal

public java.lang.String getVacationMessageInternal()
                                            throws IPlanetServerException

To retrieve the vacation message for internal recipients.

Returns:

String value of the vacation message.

Throws:

IPlanetServerException - error occurred when contacting the backend server.

setVacationMessageInternal

public void setVacationMessageInternal(java.lang.String vacationMessage)
                                throws IPlanetServerException

To set the vacation message for internal recipients.

Parameters:

vacationMessage - String value for the vacation message.

Throws:

IPlanetServerException - error occurred when contacting the backend server.

getVacationMessageExternal

public java.lang.String getVacationMessageExternal()
                                            throws IPlanetServerException

To retrieve the vacation message for external recipients.

Returns:

String value of the vacation message.

Throws:

IPlanetServerException - error occurred when contacting the backend server.

setVacationMessageExternal

public void setVacationMessageExternal(java.lang.String vacationMessage)
                                throws IPlanetServerException

To set the vacation message for external recipients.

Parameters:

vacationMessage - String value for the vacation message.

Throws:

IPlanetServerException - error occurred when contacting the backend server.

getVacationMessageRepeatDays

public int getVacationMessageRepeatDays()
                                 throws IPlanetServerException

Returns the number of days between sending a repeat of the vacation message to senders.

If the user has not set this setting before, it will return the default value, which is 0.

Throws:

IPlanetServerException - error occurred when contacting the backend server.

setVacationMessageRepeatDays

public void setVacationMessageRepeatDays(int days)
                                  throws IPlanetServerException

Sets the number of days between sending a repeat of the vacation message to senders.

Parameters:

days - The number of days

Throws:

IPlanetServerException - error occurred when contacting the backend server.

getVacationMessageEnabled

public boolean getVacationMessageEnabled()
                                  throws IPlanetServerException

To retrieve an indicator whether the vacation message has been enabled.

Returns:

boolean - (vacation message enabled/disabled)

Throws:

IPlanetServerException - error occurred when contacting the backend server.

getVacationMessageStartDate

public java.lang.String getVacationMessageStartDate()
                                             throws IPlanetServerException

Retrieves the effective start date of the vacation message.

Returns:

date String representation of a date in format YYYYMMDDhhmmssZ

Throws:

IPlanetServerException - error occurred when contacting the backend server.

getVacationMessageEndDate

public java.lang.String getVacationMessageEndDate()
                                           throws IPlanetServerException

Retrieves the effective end date of the vacation message.

Returns:

date String representation of a date in format YYYYMMDDhhmmssZ

Throws:

IPlanetServerException - error occurred when contacting the backend server.

setVacationMessageEnabled

public void setVacationMessageEnabled(boolean enable,
                                      java.lang.String startDate,
                                      java.lang.String endDate)
                               throws IPlanetServerException

To set the indicator to enable or disable vacation message.

Parameters:

enable - boolean value enable or disable the vacation message

startDate - The date that vacation settings begin to take effect. In format YYYYMMDDhhmmssZ.

endDate - The date that vacation settings cease to take effect. In format YYYYMMDDhhmmssZ.

Throws:

IPlanetServerException - error occurred when contacting the backend server.

getFilters

public java.util.Vector getFilters()
                            throws IPlanetServerException

To retrieve filters for this user.

Returns:

a vector of Filter objects. If no filter has been set, an empty vector will be returned.

Throws:

IPlanetServerException - error occurred when contacting the backend server.

setFilters

public void setFilters(java.util.Vector filters)
                throws IPlanetServerException

To set the message filters for the user.

Parameters:

filters - a vector of the Filter objects that represent the new filter settings.

Throws:

IPlanetServerException - error occurred when contacting the backend server.

addFilter

public void addFilter(Filter filter)
               throws IPlanetServerException

To add a message filter for the user.

Parameters:

filter - The filter to be added.

Throws:

IPlanetServerException - error occurred when contacting the backend server.

getSignature

public java.lang.String getSignature()
                              throws IPlanetServerException

To retrieve the signature of the mail user.

Returns:

String - value of the mail signature file.

Throws:

IPlanetServerException - error occurred when contacting the backend server.

setSignature

public void setSignature(java.lang.String signature)
                  throws IPlanetServerException

To set the signature of the mail user.

Parameters:

signature - String value of the signature file

Throws:

IPlanetServerException - error occurred when contacting the backend server.

getSignatureEnabled

public boolean getSignatureEnabled()
                            throws IPlanetServerException

To retrieve the flag indicating whether the user signature is enabled or not.

Returns:

boolean - signature enable/disable flag.

Throws:

IPlanetServerException - error occurred when contacting the backend server.

setSignatureEnabled

public void setSignatureEnabled(boolean enable)
                         throws IPlanetServerException

To set the signature enabled flag for the mail user.

Parameters:

enable - boolean value of the signature enabled flag.

Throws:

IPlanetServerException - error occurred when contacting the backend server.

getVCard

public java.lang.String getVCard()
                          throws IPlanetServerException

To retrieve the vCard of the mail user.

Returns:

String - value of the vCard.

Throws:

IPlanetServerException - error occurred when contacting the backend server.

setVCard

public void setVCard(java.lang.String vcard)
              throws IPlanetServerException

To set the vCard for the mail user.

Parameters:

vcard - String value of the vCard.

Throws:

IPlanetServerException - error occurred when contacting the backend server.

getVCardEnabled

public boolean getVCardEnabled()
                        throws IPlanetServerException

To retrieve the vCard enabled flag of the mail user.

Returns:

boolean - value of the vCard enable/disable flag

Throws:

IPlanetServerException - error occurred when contacting the backend server.

setVCardEnabled

public void setVCardEnabled(boolean enable)
                     throws IPlanetServerException

To set the vCard enable/disable flag for the mail user.

Parameters:

enable - boolean value of the vCard enable/disable flag.

Throws:

IPlanetServerException - error occurred when contacting the backend server.

getCopyForwardEnabled

public boolean getCopyForwardEnabled()
                              throws IPlanetServerException

To retrieve the copy forward enabled/disabled flag.

Returns:

boolean - value of the copy forward enable/disable flag

Throws:

IPlanetServerException - error occurred when contacting the backend server.

setCopyForwardEnabled

public void setCopyForwardEnabled(boolean enable)
                           throws IPlanetServerException

To set the copy forward enabled/disabled flag.

Parameters:

enable - boolean value of the copy forward enable/disable flag.

Throws:

IPlanetServerException - error occurred when contacting the backend server.

getCopyForward

public java.lang.String[] getCopyForward()
                                  throws IPlanetServerException

To retrieve the copy forward list of the mail user.

Returns:

String[] - array value of the copy forward list.

Throws:

IPlanetServerException - error occurred when contacting the backend server.

setCopyForward

public void setCopyForward(java.lang.String[] copyForwardList)
                    throws IPlanetServerException

To set the copy forward list for the mail user.

Parameters:

copyForwardList - String[] array value of the copy forward list.

Throws:

IPlanetServerException - error occurred when contacting the backend server.

getCommonName

public java.lang.String getCommonName()
                               throws IPlanetServerException

To retrieve the common name of the mail user.

Returns:

String - value of the user common name

Throws:

IPlanetServerException - error occurred when contacting the backend server.

setCommonName

public void setCommonName(java.lang.String commonName)
                   throws IPlanetServerException

To set the common name of the mail user.

Parameters:

commonName - String value of the user common name.

Throws:

IPlanetServerException - error occurred when contacting the backend server.

getReplyTo

public java.lang.String getReplyTo()
                            throws IPlanetServerException

To retrieve the name of the reply to field.

Returns:

String - value of the reply to field.

Throws:

IPlanetServerException - error occurred when contacting the backend server.

setReplyTo

public void setReplyTo(java.lang.String replyTo)
                throws IPlanetServerException

To set the reply to field.

Parameters:

replyTo - String value of the reply to field.

Throws:

IPlanetServerException - error occurred when contacting the backend server.

getCopySend

public boolean getCopySend()
                    throws IPlanetServerException

To retrieve an indicator for the copysend field.

Returns:

boolean - value of the copy send flag.

Throws:

IPlanetServerException - error occurred when contacting the backend server.

setCopySend

public void setCopySend(boolean copySend)
                 throws IPlanetServerException

To set the copy send flag.

Parameters:

copySend - boolean value of the copy send flag.

Throws:

IPlanetServerException - error occurred when contacting the backend server.

getReplyInclude

public boolean getReplyInclude()
                        throws IPlanetServerException

To retrieve an indicator for the reply included flag.

Returns:

boolean - value of the reply included flag.

Throws:

IPlanetServerException - error occurred when contacting the backend server.

setReplyInclude

public void setReplyInclude(boolean replyInclude)
                     throws IPlanetServerException

To set the reply included flag.

Parameters:

replyInclude - boolean value of the reply include flag

Throws:

IPlanetServerException - error occurred when contacting the backend server.

getComposeWidth

public int getComposeWidth()
                    throws IPlanetServerException

To retrieve an int value of the compose window width.

If the user has not set this setting before, it will return the default value, which is 80.

Returns:

int - width value of the compose window.

Throws:

IPlanetServerException - error occurred when contacting the backend server.

setComposeWidth

public void setComposeWidth(int composeWidth)
                     throws IPlanetServerException

To set the width of the compose window.

Parameters:

composeWidth - int value of the width of the compose window.

Throws:

IPlanetServerException - error occurred when contacting the backend server.

getPaginationSize

public int getPaginationSize()
                      throws IPlanetServerException

To retrieve an int value of the page size.

If the user has not set this setting before, it will return the default value, which is 10.

Returns:

int - size of the page.

Throws:

IPlanetServerException - error occurred when contacting the backend server.

setPaginationSize

public void setPaginationSize(int pageSize)
                       throws IPlanetServerException

To set the page size..

Parameters:

pageSize - int value of the page size.

Throws:

IPlanetServerException - error occurred when contacting the backend server.

getComposeTextSize

public int getComposeTextSize()
                       throws IPlanetServerException

To retrieve an int value of the compose message text font size.

If the user has not set this setting before, it will return the default value, which is 12.

Returns:

int - size of the compose message text font size

Throws:

IPlanetServerException - error occurred when contacting the backend server.

setComposeTextSize

public void setComposeTextSize(int composeTextSize)
                        throws IPlanetServerException

To set the compose text font size.

Parameters:

composeTextSize - int value of the compose message text font size.

Throws:

IPlanetServerException - error occurred when contacting the backend server.

getNotificationEmailAddress

public java.lang.String getNotificationEmailAddress()
                                             throws IPlanetServerException

Returns the E-mail address that notification messages are sent to.

Returns:

address The e-mail address to send notifications to.

Throws:

IPlanetServerException - error occurred when contacting the backend server.

setNotificationEmailAddress

public void setNotificationEmailAddress(java.lang.String address)
                                 throws IPlanetServerException

Sets the E-mail address that notification messages are sent to.

Throws:

IPlanetServerException - error occurred when contacting the backend server.

getNotificationFrom

public java.lang.String[] getNotificationFrom()
                                       throws IPlanetServerException

Returns an array of String objects each containing an e-mail address that can trigger a notification when mail is received from that address.

Returns:

addresses Returns an array of String objects each containing an e-mail address that can trigger a notification when mail is received from that address.

Throws:

IPlanetServerException - error occurred when contacting the backend server.

setNotificationFrom

public void setNotificationFrom(java.lang.String[] addresses)
                         throws IPlanetServerException

Sets an array of String objects each containing an e-mail address that can trigger a notification when mail is received from that address.

Throws:

IPlanetServerException - error occurred when contacting the backend server.

getNotificationOption

public java.lang.String getNotificationOption()
                                       throws IPlanetServerException

Returns the current e-mail notification option setting. One of: "Selected", "All", "None".

Returns:

option Current notification option setting

Throws:

IPlanetServerException - error occurred when contacting the backend server.

setNotificationOption

public void setNotificationOption(java.lang.String option)
                           throws IPlanetServerException,
                                  java.lang.IllegalArgumentException

Sets the current e-mail notification option setting. One of: "Selected", "All", "None".

Throws:

java.lang.IllegalArgumentException - If the option is not one of the permissable settings

IPlanetServerException - error occurred when contacting the backend server.

getNotificationUrgentOption

public boolean getNotificationUrgentOption()
                                    throws IPlanetServerException

Returns whether the urgent option is set for e-mail notification.

Returns:

urgent True if the urgent option is set

Throws:

IPlanetServerException - error occurred when contacting the backend server.

setNotificationUrgentOption

public void setNotificationUrgentOption(boolean urgent)
                                 throws IPlanetServerException

Sets whether the urgent option is set for e-mail notification.

Throws:

IPlanetServerException - error occurred when contacting the backend server.

getNotificationListOption

public boolean getNotificationListOption()
                                  throws IPlanetServerException

Gets the e-mail notifictaion list option.

Returns:

option True if the notification list option is set

Throws:

IPlanetServerException - error occurred when contacting the backend server.

setNotificationListOption

public void setNotificationListOption(boolean option)
                               throws IPlanetServerException

Sets the e-mail notifictaion list option.

Throws:

IPlanetServerException - error occurred when contacting the backend server.

getNotificationPhoneFrom

public java.lang.String[] getNotificationPhoneFrom()
                                            throws IPlanetServerException

Returns an array of String objects each containing an e-mail address that triggers PCS phone based notification.

Returns:

addresses Array of String objects containing e-mail addresses.

Throws:

IPlanetServerException - error occurred when contacting the backend server.

setNotificationPhoneFrom

public void setNotificationPhoneFrom(java.lang.String[] addresses)
                              throws IPlanetServerException

Sets an array of String objects each containing an e-mail address that triggers PCS phone based notification.

Throws:

IPlanetServerException - error occurred when contacting the backend server.

getNotificationPhoneNumber

public java.lang.String getNotificationPhoneNumber()
                                            throws IPlanetServerException

Returns the PCS phone number to send notification to.

Returns:

phone The PCS phone number to send notification to.

Throws:

IPlanetServerException - error occurred when contacting the backend server.

getNotificationPhoneOption

public java.lang.String getNotificationPhoneOption()
                                            throws IPlanetServerException

Returns the current phone notification option setting. One of: "Selected", "All", "None".

Returns:

option Current notification option setting

Throws:

IPlanetServerException - error occurred when contacting the backend server.

setNotificationPhoneOption

public void setNotificationPhoneOption(java.lang.String option)
                                throws IPlanetServerException,
                                       java.lang.IllegalArgumentException

Sets the current phone notification option setting. One of: "Selected", "All", "None".

Throws:

java.lang.IllegalArgumentException - If the option is not one of the permissable settings

IPlanetServerException - error occurred when contacting the backend server.

getNotificationPhoneUrgentOption

public boolean getNotificationPhoneUrgentOption()
                                         throws IPlanetServerException

Returns whether the urgent option is set for phone notification.

Returns:

urgent True if the urgent option is set

Throws:

IPlanetServerException - error occurred when contacting the backend server.

setNotificationPhoneUrgentOption

public void setNotificationPhoneUrgentOption(boolean urgent)
                                      throws IPlanetServerException

Sets whether the urgent option is set for phone notification.

Throws:

IPlanetServerException - error occurred when contacting the backend server.

getNotificationPhoneListOption

public boolean getNotificationPhoneListOption()
                                       throws IPlanetServerException

Gets the phone notifictaion list option.

Returns:

option True if the notification list option is set

Throws:

IPlanetServerException - error occurred when contacting the backend server.

setNotificationPhoneListOption

public void setNotificationPhoneListOption(boolean option)
                                    throws IPlanetServerException

Sets the phone notifictaion list option.

Throws:

IPlanetServerException - error occurred when contacting the backend server.

getExtendedMailPref

public java.lang.String getExtendedMailPref(java.lang.String name)
                                     throws IPlanetServerException

Returns a single value from a set of iPlanet nswmExtendedUserPrefs attributes.

The nswmExtendedUserPrefs is a multi-values attribute used by iPlanet messaging server to store customized user preference. Each attribute value is in the format of "prefName=prefValue". Each prefName has a maximum one prefValue associated.

If you need to get/set multiple settings in a roll, you MUST invoke startTranscation() before the calls and commitTransaction() after the calls. (Note, you can interlace other IPlanetSettingsNugget calls in between the start/commit invocation. The start/commit are designed for all IPlanetSettingsNugget methods.)

Example: If one of the value of the attribute "nswmExtendedUserPrefs" is "meInitialize=true", getExtendedMailPref("meInitialized") will return the String "true".

Parameters:

name - The name of an nswmExtendUserPrefs attribute preference that is going to be fetched.

Returns:

The String contents of the attribute or null if there is no match.

Throws:

IPlanetServerException - If there is a connection problem with the Directory object.

setExtendedMailPref

public void setExtendedMailPref(java.lang.String name,
                                java.lang.String value)
                         throws IPlanetServerException

Sets an nswmExtendedUserPrefs value. If the directory already contains a value for the specific extended user preference, the new value will replace the old one. You can remove an existing preference value by setting it to a null object or empty string.

The nswmExtendedUserPrefs is a multi-values attribute used by iPlanet messaging server to store customized user preference. Each attribute value is in the format of "prefName=prefValue". Each prefName has a maximum one prefValue associated.

If you need to get/set multiple settings in a roll, you MUST invoke startTranscation() before the calls and commitTransaction() after the calls. (Note, you can interlace other IPlanetSettingsNugget calls in between the start/commit invocation. The start/commit are designed for all IPlanetSettingsNugget methods.)

Example: setting "meInitialized" to "true" would result in the value "meInitialized=true" being added to the attribute "nswmExtendedUserPrefs". If the directory already contains another value starts with "meInitialized=", the old value will be removed before adding the new value.

Special Instruction for Creating Default Mail Folder If you are creating a new user for the messaging server via the directory, that use is not completely initialized for the iPlanet messaging server to use. That user does not has the default folders and the corresponding user preference attributes. Therefore, you may need to create the folders and set the attributes for a new user.

Once the default folders are created, you can set the required attributes with the following code:

 // assuming you have got the SprintUser object assigned to variable
 // "user".
 try {
     IPlanetSettingsNugget nugget = user.getNugget( "IPSetNugget" );
     nugget.startTransaction();  // You must invoke this first
     nugget.setExtendedMailPref( "meInitialized", "true" );
     nugget.setExtendedMailPref( "meDraftFolder", "Drafts" );
     nugget.setExtendedMailPref( "meSentFolder", "Sent" );
     nugget.setExtendedMailPref( "meTrashFolder", "Trash" );
     nugget.commitTransaction();  // You must invoke this after
 } catch( Exception e ) {
     // your error handling mechanism
 } // end catch
 

Parameters:

name - The name of an nswmExtendUserPrefs attribute preference that is going to be modified.

value - The String contents of the attribute or null if there is no match.

Throws:

IPlanetServerException - If there is a connection problem with the Directory object.

getExtendedCalendarPref

public java.lang.String getExtendedCalendarPref(java.lang.String name)
                                         throws IPlanetServerException

Returns a single value from a set of iPlanet icsExtendedUserPrefs attributes.

The icsExtendedUserPrefs is a multi-values attribute used by iPlanet Calendar Server to store customized user preference. Each attribute value is in the format of "prefName=prefValue". Each prefName has a maximum one prefValue associated.

If you need to get/set multiple settings in a roll, you MUST invoke startTranscation() before the calls and commitTransaction() after the calls. (Note, you can interlace other IPlanetSettingsNugget calls in between the start/commit invocation. The start/commit are designed for all IPlanetSettingsNugget methods.)

Example: If one of the value of the attribute "icsExtendedUserPrefs" is "ceDateOrder=MDY", getExtendedCalendarPref("ceDateOrder") will return the String "MDY".

Parameters:

name - The name of an icsExtendUserPrefs attribute preference that is going to be fetched.

Returns:

The String contents of the attribute or null if there is no match.

Throws:

IPlanetServerException - If there is a connection problem with the Directory object.

setExtendedCalendarPref

public void setExtendedCalendarPref(java.lang.String prefName,
                                    java.lang.String prefValue)
                             throws IPlanetServerException

Sets an icsExtendedUserPrefs value. If the directory already contains a value for the specific extended user preference, the new value will replace the old one. You can remove an existing preference value by setting it to a null object or empty string.

The icsExtendedUserPrefs is a multi-values attribute used by iPlanet Calendar server to store customized user preference. Each attribute value is in the format of "prefName=prefValue". Each prefName has a maximum one prefValue associated.

If you need to get/set multiple settings in a roll, you MUST invoke startTranscation() before the calls and commitTransaction() after the calls. (Note, you can interlace other IPlanetSettingsNugget calls in between the start/commit invocation. The start/commit are designed for all IPlanetSettingsNugget methods.)

Example: setting "ceDateOrder" to "MDY" would result in the value "ceDateOrder=MDY" being added to the attribute "icsExtendedUserPrefs". If the directory already contains another value starts with "ceDateOrder=", the old value will be removed before adding the new value.

Parameters:

prefName - The name of an icsExtendUserPrefs attribute preference that is going to be modified.

prefValue - The String contents of the attribute or null if there is no match.

Throws:

IPlanetServerException - If there is a connection problem with the Directory object.

getExtendedPref

public java.lang.String getExtendedPref(java.lang.String extAttr,
                                        java.lang.String name)
                                 throws IPlanetServerException

Returns a single value from a set of preferences in an extended attribute. An extended attribute is a multi-values attribute that stores "name-value" pairs instead of just the values.

This method is intended to be used by future extension. In most cases, you can use getExtendedMailPref() or getExtendedCalendarPref().

If you need to get/set multiple settings in a roll, you MUST invoke startTranscation() before the calls and commitTransaction() after the calls. (Note, you can interlace other IPlanetSettingsNugget calls in between the start/commit invocation. The start/commit are designed for all IPlanetSettingsNugget methods.)

Example: If one of the value of the attribute "nswmExtendedUserPrefs" is "meInitialize=true", the method call getExtendedPref("nswmExtendedUserPrefs", "meInitialized") will return the String "true".

Parameters:

extAttr - The name of the extended attribute

name - The name of "name-value" pair that is stored in the specified extended attribute.

Returns:

The String contents of the attribute or null if there is no match.

Throws:

IPlanetServerException - If there is a connection problem with the Directory object.

setExtendedPref

public void setExtendedPref(java.lang.String extAttr,
                            java.lang.String name,
                            java.lang.String value)
                     throws IPlanetServerException

Sets a value within a set of preferences in an extended attribute. An extended attribute is a multi-values attribute that stores "name-value" pairs instead of just the values.

This method is intended to be used by future extension. In most cases, you can use getExtendedMailPref() or getExtendedCalendarPref().

If the directory already contains a value for the specific extendedUserPref, the new value will replace the old one. You can remove an existing preference value by setting it to a null object or empty string.

If you need to get/set multiple settings in a roll, you MUST invoke startTranscation() before the calls and commitTransaction() after the calls. (Note, you can interlace other IPlanetSettingsNugget calls in between the start/commit invocation. The start/commit are designed for all IPlanetSettingsNugget methods.)

Example: setting attribute "nswExtendedUserPrefs"'s preference "meInitialized" to "true" would result in the value "meInitialized=true" being added to the attribute "nswmExtendedUserPrefs". If the attribute already contains another value starts with "meInitialized=", the old value will be removed before adding the new value.

Parameters:

extAttr - The name of the extended attribute

name - The name of "name-value" pair that is stored in the specified extended attribute.

value - The String contents of the attribute or null if there is no match.

Throws:

IPlanetServerException - If there is a connection problem with the Directory object.

removeExtendedPref

protected void removeExtendedPref(java.lang.String extAttr,
                                  java.lang.String name)
                           throws IPlanetServerException

Throws:

IPlanetServerException

getSingleValue

public java.lang.String getSingleValue(java.lang.String attribute)
                                throws IPlanetServerException

Returns a single value of the attribute in the user's entry. If the attribute has more than one value, this method will return the first value sent by the directory server.

Returns:

value The value associated with the attribute or null if there is none.

Throws:

IPlanetServerException - If there is a connection problem with the connection

setSingleValue

public abstract void setSingleValue(java.lang.String attribute,
                                    java.lang.String value)
                             throws IPlanetServerException

Sets the attribute/value pair for the user's entry in the Directory. Any existing values will be removed (i.e. this is a "replace" instead of "add".)

Parameters:

attribute - The attribute name

value - The new value.

Throws:

IPlanetServerException - If there is a connection problem with the Directory object.

containsValue

public boolean containsValue(java.lang.String attribute,
                             java.lang.String value)
                      throws IPlanetServerException

Returns true if the attribute contains the specified value.

This method is usually used to check the existence of some value within multi-values attributes. For example, looking for "pabperson" in objectclass and "autoreply" in mailDeliveryOption and

Returns:

True if the multi-values attribute contains the value specified.

Throws:

IPlanetServerException - If there is a connection problem with the Directory object.

getMultiValues

public abstract java.lang.String[] getMultiValues(java.lang.String attribute)
                                           throws IPlanetServerException

Returns all values of the attribute in the user's entry.

Note: if the attribute has only one value stored, it simply returns an array of size one no matter whether the underlying attribute is single-value or multi-values.

Returns:

values Array of values associated with attribute. If the attribute has no value, it will return a String array of size 0.

Throws:

IPlanetServerException - If there is a connection problem with the Directory object.

setMultiValues

public abstract void setMultiValues(java.lang.String attribute,
                                    java.lang.String[] values)
                             throws IPlanetServerException

Sets the attribute/value for the user's entry in the Directory. Any existing values will be removed (i.e. this is a "replace" instead of "add".)

Parameters:

attribute - The attribute name

values - The new values.

Throws:

IPlanetServerException - If there is a connection problem with the Directory object.

startTransaction

public abstract void startTransaction()
                               throws IPlanetServerException

Starts a batch of settings change. If you need to set/get a number of attributes in a row, you should invoke this method before the calls.

Please see the class description for more details on why and when to use these transaction methods.

Throws:

IPlanetServerException

commitTransaction

public abstract void commitTransaction()
                                throws IPlanetServerException

Commits a batch of settings change. If you need to set/get a number of attributes in a row, you should use this method after the calls.

Please see the class description for more details on why and when to use these transaction methods.

Throws:

IPlanetServerException

abortTransaction

public abstract void abortTransaction()
                               throws IPlanetServerException

Abort a batch of settings change. This method will drop the transaction and LDAP connection. All setXXX changes after the startTransaction() method call will be lost. This method is is usually called when the application encountered an exception and need to drop the transaction.

If no transaction was in process when this method is called, this method will not do anything and no exception will be thrown.

Please see the class description for more details on why and when to use these transaction methods.

Throws:

IPlanetServerException

isLegalNotificationOption

protected boolean isLegalNotificationOption(java.lang.String value)

createUniqueArray

protected java.lang.String[] createUniqueArray(java.lang.String[] array)

Constructs a new array based on the one passed in and makes sure that all values in the array are unique

replaceStringInArray

protected java.lang.String[] replaceStringInArray(java.lang.String[] array,
                                                  java.lang.String value)

Constructs a new array based on the one passed in and an extra value. If the extra value is already in the array it is not added (so there is only one copy of the value)

removeStringFromArray

protected java.lang.String[] removeStringFromArray(java.lang.String[] array,
                                                   java.lang.String value)

Constructs a new array based on the one passed in with the parameter value removed from it if it is there.

arrayToVector

protected java.util.Vector arrayToVector(java.lang.String[] array)

Copies an array into a vector

vectorToArray

protected java.lang.String[] vectorToArray(java.util.Vector values)

Returns an array of strings from a vector of Strings

isExtendedMailPrefTrue

protected boolean isExtendedMailPrefTrue(java.lang.String name)
                                  throws IPlanetServerException

Returns true if the extended pref is set to "true"

Returns:

value True if the extended pref is set to "true"

Throws:

IPlanetServerException - If there is a connection problem with the Directory object.

setBooleanExtendedMailPref

protected void setBooleanExtendedMailPref(java.lang.String name,
                                          boolean enable)
                                   throws IPlanetServerException

Throws:

IPlanetServerException

removeMultiValues

protected abstract void removeMultiValues(java.lang.String attribute)
                                   throws IPlanetServerException

Removes the specified attribute from the user's entry.

Throws:

IPlanetServerException - If there is a connection problem with the Directory object.

checkNonNull

protected void checkNonNull(java.lang.String key)
                     throws InvalidSettingException

Throws:

InvalidSettingException

checkInt

protected void checkInt(java.lang.String key)
                 throws InvalidSettingException

Throws:

InvalidSettingException