com.unboundid.directory.sdk.common.types
Interface ServerContext

All Known Subinterfaces:

DirectoryServerContext, HTTPServerContext, ProxyServerContext, SyncServerContext

@NotExtensible
@ThreadSafety(level=INTERFACE_THREADSAFE)
public interface ServerContext

This interface may be used to obtain information about the server in which an extension is running.

Method Summary

java.lang.Thread	createThread(ServerThread serverThread, java.lang.String name) Creates a new thread to run within the server.
void	debugCaught(java.lang.Throwable t) Writes a debug message indicating that the provided exception has been caught.
boolean	debugEnabled() Indicates whether debugging is enabled in the server.
void	debugError(java.lang.String message) Writes a debug message with an error severity.
void	debugInfo(java.lang.String message) Writes a debug message with an informational severity.
void	debugThrown(java.lang.Throwable t) Writes a debug message indicating that the provided exception will be thrown.
void	debugVerbose(java.lang.String message) Writes a debug message with a verbose severity.
void	debugWarning(java.lang.String message) Writes a debug message with a warning severity.
void	deregisterAllMonitorProviders() Deregisters all the monitor providers that were registered with the server by this instance of ServerContext.
void	deregisterChangeListener(RegisteredChangeListener listener) Deregisters the provided change listener with the server.
void	deregisterDiskSpaceConsumer(RegisteredDiskSpaceConsumer consumer) Deregisters the provided disk space consumer with the server.
void	deregisterMonitorProvider(RegisteredMonitorProvider provider) Deregisters the given monitor provider with the server.
void	deregisterShutdownListener(RegisteredServerShutdownListener listener) Deregisters the provided server shutdown listener with the server.
void	deregisterSupportedControlOID(java.lang.String oid) Deregisters the provided OID with the server so that it will no longer appear in the supportedControl attribute of the server's root DSE.
java.lang.String	getCompactProductName() Retrieves the compact name of the server.
java.lang.String	getFullProductName() Retrieves the full name of the server.
java.lang.String	getFullVendorName() Retrieves the full name of the server vendor.
java.lang.String	getInstanceName() Retrieves the instance name that has been assigned to the server.
InternalConnection	getInternalConnection(java.lang.String dn) Retrieves an internal connection that is authenticated as the specified user.
InternalConnection	getInternalRootConnection() Retrieves an internal connection that is authenticated as a root user that is not subject to access control.
int	getMajorVersionNumber() Retrieves the major version number for the server.
int	getMinorVersionNumber() Retrieves the minor version number for the server.
int	getPatchVersionNumber() Retrieves the patch version number for the server.
int	getPointVersionNumber() Retrieves the point version number for the server.
Schema	getSchema() Retrieves a reference to the server schema.
java.io.File	getServerRoot() Retrieves the path to the server root directory.
java.lang.String	getShortVendorName() Retrieves the compact name of the server vendor.
java.lang.String	getSourceRevision() Retrieves a value which identifies the source revision (in the version control system used to hold the server source code) from which the server was built.
long	getStartTime() Retrieves the time that the server was started.
java.lang.String	getStartupID() Retrieves a compact ID that was generated at the time the server was started.
java.util.UUID	getStartupUUID() Retrieves a unique identifier that was generated at the time the server was started.
java.lang.String	getVersionQualifier() Retrieves the version qualifier string for the server.
boolean	isDirectoryFunctionalityAvailable() Indicates whether the extension is running in a server that has Directory Server functionality available.
boolean	isDirectoryProxyFunctionalityAvailable() Indicates whether the extension is running in a server that has Directory Proxy Server functionality available.
boolean	isRunning() Indicates whether the server is currently running.
boolean	isShuttingDown() Indicates whether the server is in the process of shutting down.
boolean	isStarting() Indicates whether the server is in the process of starting up.
boolean	isSyncFunctionalityAvailable() Indicates whether the extension is running in a server that has Synchronization Server functionality available.
void	logMessage(LogSeverity severity, java.lang.String message) Writes a message to the server error log.
RegisteredChangeListener	registerChangeListener(ChangeListener listener, java.util.Set<ChangeType> changeTypes, java.util.List<java.lang.String> baseDNs, Filter filter) Registers the provided change listener with the server so that it may be notified of any changes matching the provided criteria.
RegisteredDiskSpaceConsumer	registerDiskSpaceConsumer(DiskSpaceConsumer consumer) Registers the provided disk space consumer with the server.
RegisteredMonitorProvider	registerMonitorProvider(MonitorProvider provider, GenericConfig config) Registers the given monitor provider with the server.
RegisteredServerShutdownListener	registerShutdownListener(ServerShutdownListener listener) Registers the provided listener to be notified when the server shutdown process has begun.
void	registerSupportedControlOID(java.lang.String oid) Registers the provided OID with the server so that it will appear in the supportedControl attribute of the server's root DSE.
void	sendAlert(AlertSeverity severity, java.lang.String message) Generates an administrative alert notification.
void	sendAlert(java.lang.String alertTypeName, AlertSeverity severity, java.lang.String alertTypeOID, java.lang.String message) Generates an administrative alert notification.

Method Detail

getShortVendorName

java.lang.String getShortVendorName()

Retrieves the compact name of the server vendor. The returned name will not have any spaces.

Returns:

The compact name of the server vendor.

getFullVendorName

java.lang.String getFullVendorName()

Retrieves the full name of the server vendor. The returned name may contain spaces.

Returns:

The full name of the server vendor.

getCompactProductName

java.lang.String getCompactProductName()

Retrieves the compact name of the server. The returned name will not have any spaces.

Returns:

The compact name of the server.

getFullProductName

java.lang.String getFullProductName()

Retrieves the full name of the server. The returned name may contain spaces.

Returns:

The full name of the server.

getMajorVersionNumber

int getMajorVersionNumber()

Retrieves the major version number for the server. The major version number is the first number which appears in the full version string (e.g., for a version string of "1.2.3.4-beta5", the major version number is 1).

Returns:

The major version number for the server.

getMinorVersionNumber

int getMinorVersionNumber()

Retrieves the minor version number for the server. The minor version number is the second number which appears in the full version string (e.g., for a version string of "1.2.3.4-beta5", the minor version number is 2).

Returns:

The minor version number for the server.

getPointVersionNumber

int getPointVersionNumber()

Retrieves the point version number for the server. The point version number is the third number which appears in the full version string (e.g., for a version string of "1.2.3.4-beta5", the point version number is 3).

Returns:

The point version number for the server.

getPatchVersionNumber

int getPatchVersionNumber()

Retrieves the patch version number for the server. The patch version number is the fourth number which appears in the full version string (e.g., for a version string of "1.2.3.4-beta5", the patch version number is 4).

Returns:

The point version number for the server.

getVersionQualifier

java.lang.String getVersionQualifier()

Retrieves the version qualifier string for the server. The version qualifier is an optional string which may provide additional information about the server version. If a version qualifier is present, then it will immediately follow the patch version number (e.g., for a version string of "1.2.3.4-beta5", the version qualifier is "-beta5").

Returns:

The version qualifier for the server, or an empty string if no version qualifier is defined.

getSourceRevision

java.lang.String getSourceRevision()

Retrieves a value which identifies the source revision (in the version control system used to hold the server source code) from which the server was built.

Returns:

The source revision identifier for the server.

isStarting

boolean isStarting()

Indicates whether the server is in the process of starting up.

Returns:

true if the server is in the process of starting up, or false if not.

isRunning

boolean isRunning()

Indicates whether the server is currently running.

Returns:

true if the server is running, or false if not.

isShuttingDown

boolean isShuttingDown()

Indicates whether the server is in the process of shutting down.

Returns:

true if the server is in the process of shutting down, or false if not.

getStartTime

long getStartTime()

Retrieves the time that the server was started. The value returned will be an offset in milliseconds since 12:00 a.m. on January 1, 1970.

Returns:

The time that the server was started.

getStartupID

java.lang.String getStartupID()

Retrieves a compact ID that was generated at the time the server was started. It is not guaranteed to be unique among all instances of the server, but is guaranteed to be unique across all invocations of a single server installation. This is suitable for inclusion in log messages and can help differentiate operations with the same connection ID and operation ID across server restarts.

Returns:

A compact ID that was generated at the time the server was started.

getStartupUUID

java.util.UUID getStartupUUID()

Retrieves a unique identifier that was generated at the time the server was started. It will be unique across all server instances and all invocations of the same instance.

Returns:

A unique identifier that was generated at the time the server was started.

getInstanceName

java.lang.String getInstanceName()

Retrieves the instance name that has been assigned to the server.

Returns:

The instance name that has been assigned to the server.

getServerRoot

java.io.File getServerRoot()

Retrieves the path to the server root directory.

Returns:

The path to the server root directory.

isDirectoryFunctionalityAvailable

boolean isDirectoryFunctionalityAvailable()

Indicates whether the extension is running in a server that has Directory Server functionality available.

Returns:

true if Directory Server functionality is available, or false if not.

isDirectoryProxyFunctionalityAvailable

boolean isDirectoryProxyFunctionalityAvailable()

Indicates whether the extension is running in a server that has Directory Proxy Server functionality available.

Returns:

true if Directory Proxy Server functionality is available, or false if not.

isSyncFunctionalityAvailable

boolean isSyncFunctionalityAvailable()

Indicates whether the extension is running in a server that has Synchronization Server functionality available.

Returns:

true if Synchronization Server functionality is available, or false if not.

getInternalRootConnection

InternalConnection getInternalRootConnection()

Retrieves an internal connection that is authenticated as a root user that is not subject to access control.

Note that the returned connection will use the client connection policy defined as the default policy for internal operations. If you have access to a ClientContext and wish to use the client connection policy associated with that connection, use the ClientContext.getInternalRootConnection(boolean) method.

Returns:

An internal connection that is authenticated as a root user.

getInternalConnection

InternalConnection getInternalConnection(java.lang.String dn)
                                         throws LDAPException

Retrieves an internal connection that is authenticated as the specified user. Operations on the connection may be subject to access control based on the privileges associated with the specified user.

Note that the returned connection will use the client connection policy defined as the default policy for internal operations. If you have access to a ClientContext and wish to use the client connection policy associated with that connection, use the ClientContext.getInternalConnection(String,boolean) method.

Parameters:

dn - The DN of the user as whom the connection should be authenticated. It may be null or empty if the connection should be unauthenticated.

Returns:

An internal connection that is authenticated as the specified user.

Throws:

LDAPException - If a problem occurs while attempting to authenticate as the specified user.

getSchema

Schema getSchema()

Retrieves a reference to the server schema.

Returns:

A reference to the server schema.

registerSupportedControlOID

void registerSupportedControlOID(java.lang.String oid)

Registers the provided OID with the server so that it will appear in the supportedControl attribute of the server's root DSE. This method should only be used by extensions which implement some level of support for that control (e.g., a pre-parse plugin which performs all necessary processing from the control and removes it from the request so that it will not be seen and potentially rejected by the core server).

Parameters:

oid - The OID to be registered.

deregisterSupportedControlOID

void deregisterSupportedControlOID(java.lang.String oid)

Deregisters the provided OID with the server so that it will no longer appear in the supportedControl attribute of the server's root DSE.

Parameters:

oid - The OID to be deregistered.

registerChangeListener

RegisteredChangeListener registerChangeListener(ChangeListener listener,
                                                java.util.Set<ChangeType> changeTypes,
                                                java.util.List<java.lang.String> baseDNs,
                                                Filter filter)
                                                throws LDAPException

Registers the provided change listener with the server so that it may be notified of any changes matching the provided criteria.

Parameters:

listener - The change listener to be registered with the server. It must not be null.

changeTypes - The types of changes for which the listener should be registered. It may be null or empty to indicate that the listener should be registered for all types of changes.

baseDNs - The set of base DNs for which the listener should be registered. It may be null or empty to indicate that the listener should be registered for changes processed anywhere in the server.

filter - A filter which may be used to restrict the set of changes for which the listener is notified. If a filter is provided, then only changes in which the target entry matches the given filter (either before or after the change was processed) will be notified. It may be null to indicate that the contents of the entry should not be considered.

Returns:

An object representing the change listener that has been registered with the server.

Throws:

LDAPException - If a problem is encountered while attempting to register the provided change listener (e.g., if any of the base DNs cannot be parsed as a valid DN).

deregisterChangeListener

void deregisterChangeListener(RegisteredChangeListener listener)

Deregisters the provided change listener with the server. This will have no effect if the provided listener is not registered.

Parameters:

listener - The change listener to be deregistered. It must not be null.

registerDiskSpaceConsumer

RegisteredDiskSpaceConsumer registerDiskSpaceConsumer(DiskSpaceConsumer consumer)

Registers the provided disk space consumer with the server.

Parameters:

consumer - The disk space consumer to be registered with the server. It must not be null.

Returns:

An object representing the disk space consumer that has been registered with the server.

deregisterDiskSpaceConsumer

void deregisterDiskSpaceConsumer(RegisteredDiskSpaceConsumer consumer)

Deregisters the provided disk space consumer with the server. This will no no effect if the provided consumer is not registered.

Parameters:

consumer - The disk space consumer to be deregistered with the server. It must not be null.

registerShutdownListener

RegisteredServerShutdownListener registerShutdownListener(ServerShutdownListener listener)

Registers the provided listener to be notified when the server shutdown process has begun.

Parameters:

listener - The server shutdown listener to be registered. It must not be null.

Returns:

An object representing the shutdown listener that has been registered with the server.

deregisterShutdownListener

void deregisterShutdownListener(RegisteredServerShutdownListener listener)

Deregisters the provided server shutdown listener with the server. This will have no effect if the provided listener is not registered.

Parameters:

listener - The server shutdown listener to be deregistered. It must not be null.

registerMonitorProvider

RegisteredMonitorProvider registerMonitorProvider(MonitorProvider provider,
                                                  GenericConfig config)

Registers the given monitor provider with the server. It is important that this monitor provider has a unique instance name across all monitor providers in the server. If there is already a monitor provider registered with the same instance name, an IllegalStateException will be thrown.

The generated monitor entry will have a DN in the following format: cn={monitor-instance-name} [from {extension-type}:{extension-name}], cn=monitor and it will contain three auto-generated attributes: ds-extension-monitor-name, ds-extension-type, and ds-extension-name. Note: the {extension-type} and {extension-name} are from the extension which owns this ServerContext instance, not from the given MonitorProvider object.

The specified monitor provider does not need any server-side configuration, and the configuration-related methods (initalizeMonitorProvider(), finalizeMonitorProvider(), defineConfigArguments(), isConfigurationAcceptable(), applyConfiguration()) do not need to be implemented because they will not be called.

When an extension is disabled, all of its registered monitor providers will automatically deregister themselves from the server. You can also manually deregister them using deregisterMonitorProvider(RegisteredMonitorProvider) or deregisterAllMonitorProviders().

Parameters:

provider - The monitor provider instance to be registered. It must not be null.

config - The configuration object from the extension that is registering the given monitor provider. This is required so that the monitor entry can be given a unique DN which includes the name of the extension that registered it.

Returns:

An object representing the monitor provider that has been registered with the server.

deregisterMonitorProvider

void deregisterMonitorProvider(RegisteredMonitorProvider provider)

Deregisters the given monitor provider with the server. This will have no effect if the given monitor provider is not registered.

Parameters:

provider - The monitor provider instance to be registered. It must not be null.

deregisterAllMonitorProviders

void deregisterAllMonitorProviders()

Deregisters all the monitor providers that were registered with the server by this instance of ServerContext. This can be useful during cleanup or if you want to clear out all the existing monitor data from a given extension and register new monitor providers.

This will be called automatically when your extension is unloaded or disabled.

createThread

java.lang.Thread createThread(ServerThread serverThread,
                              java.lang.String name)

Creates a new thread to run within the server. The thread will not be started.

Parameters:

name - The name to use for the thread. It must not be null or empty.

serverThread - The class providing the logic for the thread. It must not be null.

Returns:

The thread that has been created but not yet started.

logMessage

void logMessage(LogSeverity severity,
                java.lang.String message)

Writes a message to the server error log.

Parameters:

severity - The severity to use for the log message. It must not be null.

message - The message to be logged. It must not be null.

sendAlert

void sendAlert(AlertSeverity severity,
               java.lang.String message)

Generates an administrative alert notification.

Parameters:

severity - The severity to use for the alert notification. It must not be null.

message - The message to be used for the alert notification. It must not be null.

sendAlert

void sendAlert(java.lang.String alertTypeName,
               AlertSeverity severity,
               java.lang.String alertTypeOID,
               java.lang.String message)
               throws LDAPException

Generates an administrative alert notification.

Parameters:

alertTypeName - The name to use to identify the alert type. Each kind of alert must have a distinct name and all alerts with this alert type must always be used with the same severity and OID values. Alert type names must start with a lowercase ASCII letter and must contain only lowercase ASCII letters, numeric digits, and dashes.

severity - The severity to use for the alert notification. It must not be null.

alertTypeOID - The numeric OID for the alert type. It must not be null, and it must be a valid numeric OID. The same OID must always be used for the associated alert type, and each different alert type must have a unique OID.

message - The message to be used for the alert notification. It must not be null.

Throws:

LDAPException - If the provided information cannot be used to generate a valid alert (e.g., if the alert type name does not meet the naming constraints or has already been used with a different severity and/or OID, or if the OID has already been used with a different alert type).

debugEnabled

boolean debugEnabled()

Indicates whether debugging is enabled in the server.

Note that debug messages written by Server SDK extensions will be handled in the same way as debug messages generated in other areas of the server. However, the "Server SDK Extension Debug Logger" may be used to easily obtain only debug messages generated by Server SDK extensions, suppressing all messages generated in other areas of the server.

Returns:

true if debugging is enabled in the server, or false if not.

debugCaught

void debugCaught(java.lang.Throwable t)

Writes a debug message indicating that the provided exception has been caught.

Note that debug messages written by Server SDK extensions will be handled in the same way as debug messages generated in other areas of the server. However, the "Server SDK Extension Debug Logger" may be used to easily obtain only debug messages generated by Server SDK extensions, suppressing all messages generated in other areas of the server.

Parameters:

t - The exception that has been caught.

debugThrown

void debugThrown(java.lang.Throwable t)

Writes a debug message indicating that the provided exception will be thrown.

Note that debug messages written by Server SDK extensions will be handled in the same way as debug messages generated in other areas of the server. However, the "Server SDK Extension Debug Logger" may be used to easily obtain only debug messages generated by Server SDK extensions, suppressing all messages generated in other areas of the server.

Parameters:

t - The exception that will be thrown.

debugError

void debugError(java.lang.String message)

Writes a debug message with an error severity.

Note that debug messages written by Server SDK extensions will be handled in the same way as debug messages generated in other areas of the server. However, the "Server SDK Extension Debug Logger" may be used to easily obtain only debug messages generated by Server SDK extensions, suppressing all messages generated in other areas of the server.

Parameters:

message - The message to be debugged.

debugWarning

void debugWarning(java.lang.String message)

Writes a debug message with a warning severity.

Note that debug messages written by Server SDK extensions will be handled in the same way as debug messages generated in other areas of the server. However, the "Server SDK Extension Debug Logger" may be used to easily obtain only debug messages generated by Server SDK extensions, suppressing all messages generated in other areas of the server.

Parameters:

message - The message to be debugged.

debugInfo

void debugInfo(java.lang.String message)

Writes a debug message with an informational severity.

Note that debug messages written by Server SDK extensions will be handled in the same way as debug messages generated in other areas of the server. However, the "Server SDK Extension Debug Logger" may be used to easily obtain only debug messages generated by Server SDK extensions, suppressing all messages generated in other areas of the server.

Parameters:

message - The message to be debugged.

debugVerbose

void debugVerbose(java.lang.String message)

Writes a debug message with a verbose severity.

Note that debug messages written by Server SDK extensions will be handled in the same way as debug messages generated in other areas of the server. However, the "Server SDK Extension Debug Logger" may be used to easily obtain only debug messages generated by Server SDK extensions, suppressing all messages generated in other areas of the server.

Parameters:

message - The message to be debugged.