Package 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 Details

    • 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

    • 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 appData = (JeBackendCfgClient) config.getRootConfiguration().getBackend("appData");
      appData.setBaseDN(Arrays.asList(Dn.valueOf("dc=example,dc=com")));
      appData.setDBCachePercent(70);
      // changes must be committed to be effective
      appData.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

    • getLdapClientSocket

      public LdapClientSocket getLdapClientSocket() throws EmbeddedDirectoryServerException
      Returns a LDAP client socket connected 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 socket
      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

    • isRunning

      public boolean isRunning()
      Indicates whether this server is currently running.
      Returns:
      true if the server is currently running, or false if not.

    • initializeConfiguration

      public Setup 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().

      By default, the embedded server is configured to secure peer-to-peer communications with SSL key-pair generated from a the deployment ID provided in ConfigParameters.deploymentId(DeploymentId). Use Setup.useExistingCertificatesForTls(KeyStoreModel, TrustStoreModel) on the object returned by this method in order to specify your own SSL key-pair and CAs.

      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