com.sonicsw.mf.mgmtapi.runtime
Interface IDirectoryServiceProxy

public interface IDirectoryServiceProxy

Remote interface to a runtime instance of a DirectoryService.

Management attributes and operations are documented in this interface.

An implementation of this interface can be created using the MFProxyFactory class. Each implementation instance is valid for the life of the provided JMS/JMX Connector and MBean ObjectName. The implementation is built using remote JMX MBeanServer calls.

For each JMX MBean attribute, this interface provides an associated get method (for readable attributes) and/or a set method (for writable attributes).

For each JMX MBean operation, this interface provides an associated method with a signature as described by the MBean's operation meta-data. Each JMX MBean operation has an associated impact:

• ACTION - Indicates that the operation is a write-like, and would modify the MBean in some way, typically by writing some value or changing a configuration.
• INFO - Indicates that the operation is read-like, it basically returns information.
• ACTION/INFO - Indicates that the operation is both read-like and write-like.
• UNKNOWN - Indicates that the operation has an "unknown" nature.

All exceptions emitted by implementations are wrapped as a ProxyRuntimeException.

See Also:

DirectoryService Notifications,

Field Summary

static java.lang.String	CONFIGURATION_STORAGE_CHANGE_NOTIFICATION_ID Notification type constant for the notification configuration.storage.Change.
static java.lang.String	GLOBAL_ID The well known global component identity for this singleton component.
static java.lang.String	SYSTEM_SECURITY_CONFIGUREPERMISSIONDENIED_NOTIFICATION_ID Notification type constant for the notification system.security.ConfigurePermissionDenied.
static java.lang.String	SYSTEM_STATE_FAILOVER_NOTIFICATION_ID Notification type constant for the notification system.state.Failover.
static java.lang.String	SYSTEM_STATE_OFFLINE_NOTIFICATION_ID Notification type constant for the notification system.state.Offline.
static java.lang.String	SYSTEM_STATE_ONLINE_NOTIFICATION_ID Notification type constant for the notification system.state.Online.

Method Summary

void	addNotificationListener(NotificationListener listener, NotificationFilter filter, java.lang.Object handback) Adds a notification listener.
void	clearError() Invokes the clearError operation.
java.lang.Boolean	getAllowFailover() Gets the value of the AllowFailover attribute.
AttributeList	getAttributes(java.lang.String[] attributeNames) Gets the values of several attributes of a DirectoryService component.
IBackupStatus	getBackupStatus() Invokes the getBackupStatus operation.
java.lang.String	getClassname() Gets the value of the Classname attribute.
java.lang.String	getClasspath() Gets the value of the Classpath attribute.
java.lang.String	getConfigID() Gets the value of the ConfigID attribute.
java.lang.Integer	getDirectoryServiceVersion() Invokes the getDirectoryServiceVersion operation.
java.lang.String	getDomain() Invokes the getDomain operation.
java.lang.String	getFaultToleranceRole() Gets the value of the FaultToleranceRole attribute.
java.lang.Short	getFaultTolerantState() Gets the value of the FaultTolerantState attribute.
java.lang.String	getFaultTolerantStateString() Gets the value of the FaultTolerantStateString attribute.
java.lang.String	getLastError() Gets the value of the LastError attribute.
java.lang.Integer	getLastErrorLevel() Gets the value of the LastErrorLevel attribute.
java.lang.String	getLastErrorLevelString() Gets the value of the LastErrorLevelString attribute.
java.lang.String	getReleaseVersion() Gets the value of the ReleaseVersion attribute.
java.lang.Short	getState() Gets the value of the State attribute.
java.lang.String	getStateString() Gets the value of the StateString attribute.
java.lang.Integer	getTraceMask() Gets the value of the TraceMask attribute.
java.lang.String	getTraceMaskValues() Gets the value of the TraceMaskValues attribute.
java.lang.Long	getUptime() Gets the value of the Uptime attribute.
java.lang.Boolean	leaseLock(java.lang.String lockName, java.lang.String key, java.lang.Integer leaseDuration) Invokes the leaseLock operation.
java.lang.String[]	listExternalDomainWithManagementSPI() Invokes the listExternalDomainWithManagementSPI operation.
void	releaseLock(java.lang.String lockName, java.lang.String key) Invokes the releaseLock operation.
java.lang.Boolean	reloadExternalAuthenticationDomain(java.lang.String mfDomainDescriptor) Invokes the reloadExternalAuthenticationDomain operation.
void	removeNotificationListener(NotificationListener listener) Removes a notification listener.
void	setAllowFailover(java.lang.Boolean value) Sets the value of the AllowFailover attribute.
AttributeList	setAttributes(AttributeList attributes) Sets the values of several attributes of a DirectoryService component.
void	setTraceMask(java.lang.Integer value) Sets the value of the TraceMask attribute.
void	start() Invokes the start operation.
void	startBackup(java.lang.String backupDir, java.lang.Boolean overwrite) Invokes the startBackup operation.
void	stop() Invokes the stop operation.

Field Detail

CONFIGURATION_STORAGE_CHANGE_NOTIFICATION_ID

static final java.lang.String CONFIGURATION_STORAGE_CHANGE_NOTIFICATION_ID

Notification type constant for the notification configuration.storage.Change.

Description: Configuration change(s) propagated by the Directory Services.

See Also:

configuration.storage.Change

See Also:

Constant Field Values

GLOBAL_ID

static final java.lang.String GLOBAL_ID

The well known global component identity for this singleton component.

See Also:

Constant Field Values

SYSTEM_SECURITY_CONFIGUREPERMISSIONDENIED_NOTIFICATION_ID

static final java.lang.String SYSTEM_SECURITY_CONFIGUREPERMISSIONDENIED_NOTIFICATION_ID

Notification type constant for the notification system.security.ConfigurePermissionDenied.

Description: Standby container has failed over to become the active container.

See Also:

system.security.ConfigurePermissionDenied

See Also:

Constant Field Values

SYSTEM_STATE_FAILOVER_NOTIFICATION_ID

static final java.lang.String SYSTEM_STATE_FAILOVER_NOTIFICATION_ID

Notification type constant for the notification system.state.Failover.

Description: Standby service has failed over to become the active service.

See Also:

system.state.Failover

See Also:

Constant Field Values

SYSTEM_STATE_OFFLINE_NOTIFICATION_ID

static final java.lang.String SYSTEM_STATE_OFFLINE_NOTIFICATION_ID

Notification type constant for the notification system.state.Offline.

Description: Component stop complete.

See Also:

system.state.Offline

See Also:

Constant Field Values

SYSTEM_STATE_ONLINE_NOTIFICATION_ID

static final java.lang.String SYSTEM_STATE_ONLINE_NOTIFICATION_ID

Notification type constant for the notification system.state.Online.

Description: Component start complete.

See Also:

system.state.Online

See Also:

Constant Field Values

Method Detail

addNotificationListener

void addNotificationListener(NotificationListener listener,
                             NotificationFilter filter,
                             java.lang.Object handback)

Adds a notification listener.

A DirectoryService component publishes the following notifications:

• configuration.storage.Change
• system.security.ConfigurePermissionDenied
• system.state.Failover
• system.state.Offline
• system.state.Online

Parameters:

listener - The listener object which will handle the notifications emitted component.

filter - The filter object. If filter is null, no filtering will be performed before handling notifications.

handback - The context to be sent to the listener when a notification is emitted.

See Also:

removeNotificationListener(javax.management.NotificationListener)

clearError

void clearError()

Invokes the clearError operation.

Clear existing error condition.

Impact: ACTION

See Also:

getLastErrorLevel()

getAllowFailover

java.lang.Boolean getAllowFailover()

Gets the value of the AllowFailover attribute.

Returns:

When this Directory Service is in a standby state and this attribute is set to 'false', fault tolerant failover to active will not occur.

See Also:

setAllowFailover(java.lang.Boolean)

getAttributes

AttributeList getAttributes(java.lang.String[] attributeNames)

Gets the values of several attributes of a DirectoryService component.

Getting multiple attribute values at once is typically more efficient than getting individual attribute values.

Readable attributes (and their datatypes) exposed by a DirectoryService are:

• AllowFailover (java.lang.Boolean)
• Classname (java.lang.String)
• Classpath (java.lang.String)
• ConfigID (java.lang.String)
• FaultToleranceRole (java.lang.String)
• FaultTolerantState (java.lang.Short)
• FaultTolerantStateString (java.lang.String)
• LastError (java.lang.String)
• LastErrorLevel (java.lang.Integer)
• LastErrorLevelString (java.lang.String)
• ReleaseVersion (java.lang.String)
• State (java.lang.Short)
• StateString (java.lang.String)
• TraceMask (java.lang.Integer)
• TraceMaskValues (java.lang.String)
• Uptime (java.lang.Long)

Parameters:

attributeNames - A list of the attribute names of attributes to be retrieved.

Returns:

The list of the retrieved attributes.

See Also:

setAttributes(javax.management.AttributeList)

getBackupStatus

IBackupStatus getBackupStatus()

Invokes the getBackupStatus operation.

Return a BackupStatus object with information about the last backup

Impact: INFO

getClassname

java.lang.String getClassname()

Gets the value of the Classname attribute.

Returns:

Component classname.

getClasspath

java.lang.String getClasspath()

Gets the value of the Classpath attribute.

Returns:

Component classpath.

getConfigID

java.lang.String getConfigID()

Gets the value of the ConfigID attribute.

Returns:

Configuration identity.

getDirectoryServiceVersion

java.lang.Integer getDirectoryServiceVersion()

Invokes the getDirectoryServiceVersion operation.

Gets the Directory Service version.

Impact: INFO

getDomain

java.lang.String getDomain()

Invokes the getDomain operation.

Gets the domain name for the configuration domain the Directory Service maintains.

Impact: INFO

getFaultToleranceRole

java.lang.String getFaultToleranceRole()

Gets the value of the FaultToleranceRole attribute.

Returns:

The fault tolerant role of the DS (primary or backup) or null if not fault tolerant.

getFaultTolerantState

java.lang.Short getFaultTolerantState()

Gets the value of the FaultTolerantState attribute.

Returns:

The current fault tolerant state of this Directory Service.

getFaultTolerantStateString

java.lang.String getFaultTolerantStateString()

Gets the value of the FaultTolerantStateString attribute.

Returns:

The description of the current fault tolerant state of this Directory Service.

getLastError

java.lang.String getLastError()

Gets the value of the LastError attribute.

Returns:

Last (uncleared) error condition.

getLastErrorLevel

java.lang.Integer getLastErrorLevel()

Gets the value of the LastErrorLevel attribute.

Returns:

Last (uncleared) error severity.

getLastErrorLevelString

java.lang.String getLastErrorLevelString()

Gets the value of the LastErrorLevelString attribute.

Returns:

Last (uncleared) error severity description.

getReleaseVersion

java.lang.String getReleaseVersion()

Gets the value of the ReleaseVersion attribute.

Returns:

Component release version.

getState

java.lang.Short getState()

Gets the value of the State attribute.

Returns:

Execution state of the component.

See Also:

getStateString(), IComponentState

getStateString

java.lang.String getStateString()

Gets the value of the StateString attribute.

Returns:

Description of the execution state of the component.

See Also:

getState(), IComponentState.STATE_TEXT

getTraceMask

java.lang.Integer getTraceMask()

Gets the value of the TraceMask attribute. The trace mask is a bit mask composed from the following possible values:

• 1 - verbose
• 2 - set attributes
• 4 - operation invoked
• 8 - notification sent
• 16 - startup
• 32 - updates
• 64 - pass
• 128 - container access
• 256 - configuration notifications
• 512 - validation triggers
• 1024 - all directory service access
• 2048 - fault detection

Returns:

Debug bit mask.

See Also:

setTraceMask(java.lang.Integer), getTraceMaskValues()

getTraceMaskValues

java.lang.String getTraceMaskValues()

Gets the value of the TraceMaskValues attribute.

Returns:

Possible TraceMask values.

See Also:

getTraceMask(), setTraceMask(java.lang.Integer)

getUptime

java.lang.Long getUptime()

Gets the value of the Uptime attribute.

Returns:

Execution time (milliseconds).

leaseLock

java.lang.Boolean leaseLock(java.lang.String lockName,
                            java.lang.String key,
                            java.lang.Integer leaseDuration)

Invokes the leaseLock operation.

Leases the named lock against the given key for the given period. Returns true if the the lock was successfully acquired, false if not.

Impact: ACTION

Parameters:

lockName - The name of the lock to be acquired.

key - The key under which the lock (if acquired) should be held.

leaseDuration - The duration the lock lease will remain in effect (cannot be (re)acquired using a different key). After the duration has expired the lock can be acquired under a different key.

listExternalDomainWithManagementSPI

java.lang.String[] listExternalDomainWithManagementSPI()

Invokes the listExternalDomainWithManagementSPI operation.

Return list of external domain descriptors that have been configured with Management SPI.

Impact: INFO

releaseLock

void releaseLock(java.lang.String lockName,
                 java.lang.String key)

Invokes the releaseLock operation.

Releases a previously acquired lock (if that lock is still held against the given key).

Impact: ACTION

Parameters:

lockName - The name of the acquired lock.

key - The key under which the lock was acquired.

reloadExternalAuthenticationDomain

java.lang.Boolean reloadExternalAuthenticationDomain(java.lang.String mfDomainDescriptor)

Invokes the reloadExternalAuthenticationDomain operation.

Reloads the external domain that matches the descriptor passed in.

Impact: ACTION

Parameters:

mfDomainDescriptor - The name of the external domain

removeNotificationListener

void removeNotificationListener(NotificationListener listener)

Removes a notification listener.

This method will remove all the information related to the given listener.

Parameters:

listener - The listener object which will handle the notifications emitted by the registered MBean.

See Also:

addNotificationListener(javax.management.NotificationListener, javax.management.NotificationFilter, Object)

setAllowFailover

void setAllowFailover(java.lang.Boolean value)

Sets the value of the AllowFailover attribute.

Parameters:

value - When this Directory Service is in a standby state and this attribute is set to 'false', fault tolerant failover to active will not occur.

See Also:

getAllowFailover()

setAttributes

AttributeList setAttributes(AttributeList attributes)

Sets the values of several attributes of a DirectoryService component.

Setting multiple attribute values at once is typically more efficient than setting individual attribute values.

Settable attributes (and their datatypes) exposed by a DirectoryService are:

• AllowFailover (java.lang.Boolean)
• TraceMask (java.lang.Integer)

Parameters:

attributes - A list of attributes: The identification of the attributes to be set and the values they are to be set to.

Returns:

The list of attributes that were set, with their new values.

See Also:

getAttributes(java.lang.String[])

setTraceMask

void setTraceMask(java.lang.Integer value)

Sets the value of the TraceMask attribute. The trace mask is a bit mask composed from the following possible values:

• 1 - verbose
• 2 - set attributes
• 4 - operation invoked
• 8 - notification sent
• 16 - startup
• 32 - updates
• 64 - pass
• 128 - container access
• 256 - configuration notifications
• 512 - validation triggers
• 1024 - all directory service access
• 2048 - fault detection

Parameters:

value - Debug bit mask.

See Also:

getTraceMask(), getTraceMaskValues()

start

void start()

Invokes the start operation.

Start providing service.

Impact: ACTION

See Also:

stop()

startBackup

void startBackup(java.lang.String backupDir,
                 java.lang.Boolean overwrite)

Invokes the startBackup operation.

Start the backup process asynchronously

Impact: ACTION

Parameters:

backupDir - The directory to use for the backup

overwrite - Overwrite the existing DS if there is one in the backup directory

stop

void stop()

Invokes the stop operation.

Stop providing service.

Impact: ACTION

See Also:

start()