org.forgerock.opendj.server.embedded

Class EmbeddedDirectoryServer

java.lang.Object

org.forgerock.opendj.server.embedded.EmbeddedDirectoryServer

public final class EmbeddedDirectoryServer
extends Object

Represents an embedded directory server on which high-level operations are available (setup, upgrade, start, stop, ...).

Method Summary

Modifier and Type	Method and Description
void	configureReplication(ReplicationParameters parameters) Configures replication between this directory server (first server) and another server (second server).
EmbeddedDirectoryServer	extractArchiveForSetup(File openDJZipFile) Extracts the provided archive to the appropriate root directory of the server.
ManagementContext	getConfiguration() Returns the configuration of this server, which can be read or updated.
String	getConfigVersion() Returns the configuration version of the instance of the directory server as a String.
Connection	getConnection() Returns a connection to the embedded server that will be authenticated automatically with the bind DN defined for this server.
Connection	getConnection(Dn userDn) Returns a connection to the embedded server that will be authenticated as the specified user.
String	getDataVersion() Returns the data version of the instance of the directory server as a String.
void	importLDIF(ImportParameters parameters) Imports LDIF data to the directory server, overwriting existing data.
DirectoryServerSetup	initializeConfiguration() Creates a directory server setup object pre-initialized with configuration and connection parameters provided while creating this embedded directory server and returns the setup object to allow further configuration actions such as backend creation or profile setup.
void	initializeReplication(ReplicationParameters parameters) Initializes replication between this server and another server.
boolean	isReplicationRunning() Indicates whether replication is currently running for the embedded server.
boolean	isRunning() Indicates whether this server is currently running.
static EmbeddedDirectoryServer	manageEmbeddedDirectoryServer(ConfigParameters configParams, ConnectionParameters connParams, OutputStream out, OutputStream err) Creates an instance of an embedded directory server for any operation.
static EmbeddedDirectoryServer	manageEmbeddedDirectoryServerForRestrictedOps(ConfigParameters configParams) Creates an instance of an embedded directory server to perform a restricted set of operations that do not need connection parameters.
static EmbeddedDirectoryServer	manageEmbeddedDirectoryServerForRestrictedOps(ConfigParameters configParams, OutputStream out, OutputStream err) Creates an instance of an embedded directory server to perform a restricted set of operations that do not need connection parameters.
void	rebuildIndex(RebuildIndexParameters parameters) Rebuilds all the indexes of this server.
void	restart(String className, LocalizableMessage reason) Restarts the directory server.
void	setup(SetupParameters parameters) Deprecated. since 6.5.0 and OPENDJ-5507, initializeConfiguration() should be use instead
void	start() Starts this server.
void	stop(String className, LocalizableMessage reason) Stops this server.
void	upgrade(UpgradeParameters parameters) Upgrades this server.

Methods inherited from class java.lang.Object

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

Method Detail

manageEmbeddedDirectoryServer

public static EmbeddedDirectoryServer manageEmbeddedDirectoryServer(ConfigParameters configParams,
                                                                    ConnectionParameters connParams,
                                                                    OutputStream out,
                                                                    OutputStream err)

Creates an instance of an embedded directory server for any operation.

Parameters:

configParams - The basic configuration parameters for the server.

connParams - The connection parameters for the server.

out - Output stream used for feedback during operations on server

err - Error stream used for feedback during operations on server

Returns:

the embedded directory server

manageEmbeddedDirectoryServerForRestrictedOps

public static EmbeddedDirectoryServer manageEmbeddedDirectoryServerForRestrictedOps(ConfigParameters configParams,
                                                                                    OutputStream out,
                                                                                    OutputStream err)

Creates an instance of an embedded directory server to perform a restricted set of operations that do not need connection parameters.

The following operations won't be allowed because they require the connection parameters: setup, configureReplication, initializeReplication, isReplicationRunning, importLDIF and getInternalConnection without argument (getInternalConnection(DN) method is allowed).

To be able to perform any operation on the server, use the alternative manageEmbeddedDirectoryServer() method.

Parameters:

configParams - The basic configuration parameters for the server.

out - Output stream used for feedback during operations on server

err - Error stream used for feedback during operations on server

Returns:

the directory server

manageEmbeddedDirectoryServerForRestrictedOps

public static EmbeddedDirectoryServer manageEmbeddedDirectoryServerForRestrictedOps(ConfigParameters configParams)

Creates an instance of an embedded directory server to perform a restricted set of operations that do not need connection parameters.

The following operations won't be allowed because they require the connection parameters: setup, configureReplication, initializeReplication, isReplicationRunning, importLDIF and getInternalConnection without argument (getInternalConnection(DN) method is allowed).

To be able to perform any operation on the server, use the alternative manageEmbeddedDirectoryServer() method.

Standard out and error streams will be used for any output during operations on the embedded server.

Parameters:

configParams - The basic configuration parameters for the server.

Returns:

the directory server

configureReplication

public void configureReplication(ReplicationParameters parameters)
                          throws EmbeddedDirectoryServerException

Configures replication between this directory server (first server) and another server (second server).

This method updates the configuration of the servers to replicate the data under the base DN specified in the parameters.

Parameters:

parameters - The parameters for the replication.

Throws:

EmbeddedDirectoryServerException - If a problem occurs.

getConfigVersion

public String getConfigVersion()
                        throws EmbeddedDirectoryServerException

Returns the configuration version of the instance of the directory server as a String.

Returns:

the configuration version of the instance

Throws:

EmbeddedDirectoryServerException - If an error occurs while retrieving the version

getDataVersion

public String getDataVersion()
                      throws EmbeddedDirectoryServerException

Returns the data version of the instance of the directory server as a String.

Returns:

the data version of the instance

Throws:

EmbeddedDirectoryServerException - If an error occurs while retrieving the version

getConfiguration

public ManagementContext getConfiguration()
                                   throws EmbeddedDirectoryServerException

Returns the configuration of this server, which can be read or updated.

The returned object is an instance of ManagementContext class, which allow access to the root configuration object using its getRootConfiguration() method. Starting from the root configuration, it is possible to access any configuration object, in order to perform read or update operations.

Note that ManagementContext instance must be closed after usage. It is recommended to use it inside a try-with-resource statement.

Example reading configuration:

 
   try(ManagementContext config = server.getConfiguration()) {
      List<String> syncProviders = config.getRootConfiguration().listSynchronizationProviders();
      System.out.println("sync providers=" + syncProviders);
   }
 
 

Example updating configuration:

   try(ManagementContext config = server.getConfiguration()) {
      JEBackendCfgClient userRoot = (JEBackendCfgClient) config.getRootConfiguration().getBackend("userRoot");
      userRoot.setBaseDN(Arrays.asList(DN.valueOf("dc=example,dc=com")));
      userRoot.setDBCachePercent(70);
      // changes must be committed to be effective
      userRoot.commit();
   }
 

Returns:

the management context object which gives direct access to the root configuration of the server

Throws:

EmbeddedDirectoryServerException - If the retrieval of the configuration fails

getConnection

public Connection getConnection()
                         throws EmbeddedDirectoryServerException

Returns a connection to the embedded server that will be authenticated automatically with the bind DN defined for this server.

This method is available only if connection parameters are provided for the server. If the connection must be authenticated with another DN or if no connection parameters have been provided, use the alternate method getConnection(Dn).

Returns:

the connection

Throws:

EmbeddedDirectoryServerException - If the connection can't be returned

getConnection

public Connection getConnection(Dn userDn)
                         throws EmbeddedDirectoryServerException

Returns a connection to the embedded server that will be authenticated as the specified user.

Parameters:

userDn - The user to be used for authentication to the server

Returns:

the connection

Throws:

EmbeddedDirectoryServerException - If the connection can't be returned

importLDIF

public void importLDIF(ImportParameters parameters)
                throws EmbeddedDirectoryServerException

Imports LDIF data to the directory server, overwriting existing data.

Parameters:

parameters - The import parameters

Throws:

EmbeddedDirectoryServerException - If the import fails

initializeReplication

public void initializeReplication(ReplicationParameters parameters)
                           throws EmbeddedDirectoryServerException

Initializes replication between this server and another server.

Parameters:

parameters - The parameters for the replication.

Throws:

EmbeddedDirectoryServerException - If a problem occurs.

isReplicationRunning

public boolean isReplicationRunning()

Indicates whether replication is currently running for the embedded server.

Returns:

true if replication is running, false otherwise

isRunning

public boolean isRunning()

Indicates whether this server is currently running.

Returns:

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

setup

@Deprecated
public void setup(SetupParameters parameters)
                       throws EmbeddedDirectoryServerException

Deprecated. since 6.5.0 and OPENDJ-5507, initializeConfiguration() should be use instead

Set this server up from the root directory.

As a pre-requisite, the OpenDJ archive must have been previously extracted to some directory. To extract an archive for setup, see extractArchiveForSetup().

Parameters:

parameters - The setup parameters.

Throws:

EmbeddedDirectoryServerException - If the setup fails for any reason.

initializeConfiguration

public DirectoryServerSetup initializeConfiguration()
                                             throws EmbeddedDirectoryServerException

Creates a directory server setup object pre-initialized with configuration and connection parameters provided while creating this embedded directory server and returns the setup object to allow further configuration actions such as backend creation or profile setup.

As a pre-requisite, the OpenDJ archive must have been previously extracted to some directory. To extract an archive for setup, see extractArchiveForSetup(File).

Once further configuration actions have been performed on the setup object returned by this method, embedded server must be setup by a call to Setup.setup():

Embedded DS setup examples can be found in opendj-embedded-server-examples/src/main/java/org/forgerock/opendj/examples/SetupServer.java.

Returns:

A setup object already initialized with this embedded server configuration and connection parameters and which can be used to create local backend or configure server with setup profiles and then must be use to setup this embedded server

Throws:

EmbeddedDirectoryServerException - If the configuration initialization fails for any reason.

extractArchiveForSetup

public EmbeddedDirectoryServer extractArchiveForSetup(File openDJZipFile)
                                               throws EmbeddedDirectoryServerException

Extracts the provided archive to the appropriate root directory of the server.

As the DJ archive includes the "opendj" directory, it is mandatory to have the root directory named after it when using this method.

Parameters:

openDJZipFile - The OpenDJ server archive.

Returns:

This embedded directory server

Throws:

EmbeddedDirectoryServerException - If the extraction of the archive fails.

rebuildIndex

public void rebuildIndex(RebuildIndexParameters parameters)
                  throws EmbeddedDirectoryServerException

Rebuilds all the indexes of this server.

This operation is done offline, hence the server must be stopped when calling this method.

Parameters:

parameters - The parameters for rebuilding the indexes.

Throws:

EmbeddedDirectoryServerException - If an error occurs.

restart

public void restart(String className,
                    LocalizableMessage reason)

Restarts the directory server.

This will perform an in-core restart in which the existing server instance will be shut down, a new instance will be created, and it will be reinitialized and restarted.

Parameters:

className - The name of the class that initiated the restart.

reason - A message explaining the reason for the restart.

start

public void start()
           throws EmbeddedDirectoryServerException

Starts this server.

Throws:

EmbeddedDirectoryServerException - If the server is already running, or if an error occurs during server initialization or startup.

stop

public void stop(String className,
                 LocalizableMessage reason)

Stops this server.

Parameters:

className - The name of the class that initiated the shutdown.

reason - A message explaining the reason for the shutdown.

upgrade

public void upgrade(UpgradeParameters parameters)
             throws EmbeddedDirectoryServerException

Upgrades this server.

Upgrades the server configuration and application data so that it is compatible with the installed binaries.

Parameters:

parameters - The upgrade parameters.

Throws:

EmbeddedDirectoryServerException - If the upgrade fails