Package org.forgerock.opendj.server.embedded

Class EmbeddedDirectoryServer

  • public final class EmbeddedDirectoryServer
extends Object
    Represents an embedded directory server on which high-level operations are available (setup, upgrade, start, stop, ...).

    • 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

      • 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

      • 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.

      • 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.

      • 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.