Interface ServerManager

All Superinterfaces:
AutoCloseable
All Known Implementing Classes:
DomainManager, StandaloneManager
public interface ServerManager extends AutoCloseable
A simple manager for various interactions with a potentially running server.

When the server manager is closed, the underlying client is also closed.

Author:
James R. Perkins

  • Field Details

    • TIMEOUT

      static final long TIMEOUT
      A 60-second default timeout which can be overridden with the org.wildfly.plugin.tools.server.timeout system property.

  • Method Details

    • builder

      static ServerManager.Builder builder()
      Creates a builder to build a server manager.
      Returns:
      a new builder

    • builder

      static ServerManager.Builder builder(Configuration<?> configuration)
      Creates a builder to build a server manager based on the configuration.
      Parameters:
      configuration - the server configuration
      Returns:
      a new builder
      Since:
      2.0.0

    • findProcess

      static Optional<ProcessHandle> findProcess()
      Attempts to find the controlling process. For a domain server this, returns the process handle for the process controller. For a standalone server, this returns the standalone process handle.

      Please note this method does not work on Windows. The ProcessHandle.Info.arguments() is limited by the operating systems privileges.

      Returns:
      the process handle if one was found running

    • isValidHomeDirectory

      static boolean isValidHomeDirectory(Path path)
      Checks whether the directory is a valid home directory for a server.

      This validates the path is not null, exists, is a directory and contains a jboss-modules.jar.

      Parameters:
      path - the path to validate
      Returns:
      true if the path is valid otherwise false

    • isValidHomeDirectory

      static boolean isValidHomeDirectory(String path)
      Checks whether the directory is a valid home directory for a server.

      This validates the path is not null, exists, is a directory and contains a jboss-modules.jar.

      Parameters:
      path - the path to validate
      Returns:
      true if the path is valid otherwise false

    • isRunning

      static boolean isRunning(org.jboss.as.controller.client.ModelControllerClient client)
      Checks if a server is running regardless if it is a standalone or domain server.
      Parameters:
      client - the client used to check the server state
      Returns:
      true if a server is running, otherwise false

    • launchType

      static Optional<String> launchType(org.jboss.as.controller.client.ModelControllerClient client)
      Returns the "launch-type" attribute of a server.
      Parameters:
      client - the client used to check the launch-type attribute
      Returns:
      the servers launch-type

    • start

      static StandaloneManager start(StandaloneConfiguration configuration) throws ServerManagerException
      Starts a standalone server based on the command builder. 
      final ServerManager serverManager = ServerManager.start(StandaloneCommandBuilder.of(jbossHome));
if (!serverManager.waitFor(10L, TimeUnit.SECONDS)) {
    serverManager.kill();
    throw new RuntimeException("Failed to start server");
}
      Parameters:
      configuration - the configuration used for starting and managing the server
      Returns:
      the server manager
      Throws:
      ServerManagerException - if an error occurs starting the server
      Since:
      1.2

    • start

      static DomainManager start(DomainConfiguration configuration) throws ServerManagerException
      Starts a domain server based on the command builder and waits until the server is started. 
      final ServerManager serverManager = ServerManager.start(DomainCommandBuilder.of(jbossHome));
if (!serverManager.waitFor(10L, TimeUnit.SECONDS)) {
    serverManager.kill();
    throw new RuntimeException("Failed to start server");
}
      Parameters:
      configuration - the configuration used for starting and managing the server
      Returns:
      the server manager
      Throws:
      ServerManagerException - if an error occurs starting the server
      Since:
      1.2

    • of

      static StandaloneManager of(StandaloneConfiguration configuration)
      Creates a standalone server manager.
      Parameters:
      configuration - the configuration for the server
      Returns:
      a new standalone server manager

    • of

      static DomainManager of(DomainConfiguration configuration)
      Creates a domain server manager.
      Parameters:
      configuration - the configuration for the server
      Returns:
      a new domain server manager

    • of

      static ServerManager of(Configuration<?> configuration)
      Creates a new server manager based on configuration.
      Parameters:
      configuration - the configuration for the server
      Returns:
      a new server manager

    • client

      org.jboss.as.controller.client.ModelControllerClient client()
      Returns the client associated with this server manager.
      Returns:
      a client to communicate with the server

    • serverState

      String serverState()
      Gets the "server-state" for standalone servers or the "host-state" for domain servers.
      Returns:
      the server-state or "failed" if an error occurred

    • launchType

      String launchType()
      Determines the servers "launch-type".
      Returns:
      the servers launch-type or "unknown" if it could not be determined

    • takeSnapshot

      String takeSnapshot() throws IOException
      Takes a snapshot of the current servers configuration and returns the relative file name of the snapshot.

      This simply executes the take-snapshot operation with no arguments.

      Returns:
      the file name of the snapshot configuration file
      Throws:
      IOException - if an error occurs executing the operation

    • containerDescription

      ContainerDescription containerDescription() throws IOException
      Returns the container description for the running server.
      Returns:
      the container description for the running server
      Throws:
      IOException - if an error occurs communicating with the server

    • deploymentManager

      DeploymentManager deploymentManager()
      Returns the deployment manager for the server.
      Returns:
      the deployment manager

    • isRunning

      boolean isRunning()
      Checks to see if a server is running.
      Returns:
      true if the server is running, otherwise false

    • kill

      default CompletableFuture<ServerManager> kill()
      If a process is available and alive, the process is attempted to be killed. Note in cases where the process is not associated with this server manager, this method does nothing.

      The returned ServerManager is the same instance of this server manager. You can use the CompletableFuture.get() to wait until the process, if available, to exit.

      Returns:
      a completable future that on a CompletableFuture.get() will wait for the process, if available, exits
      Since:
      1.2

    • waitFor

      default boolean waitFor(long startupTimeout) throws InterruptedException
      Waits the given amount of time in seconds for a server to start.

      If the process is not null and a timeout occurs the process will be destroyed.

      Parameters:
      startupTimeout - the time, in seconds, to wait for the server start
      Returns:
      true if the server is up and running, false if a timeout occurred waiting for the server to be in a running state
      Throws:
      InterruptedException - if interrupted while waiting for the server to start

    • waitFor

      boolean waitFor(long startupTimeout, TimeUnit unit) throws InterruptedException
      Waits the given amount of time for a server to start.

      If the process is not null and a timeout occurs the process will be destroyed.

      Parameters:
      startupTimeout - the time, to wait for the server start
      unit - the time unit for the startupTimeout argument
      Returns:
      true if the server is up and running, false if a timeout occurred waiting for the server to be in a running state
      Throws:
      InterruptedException - if interrupted while waiting for the server to start

    • addServerManagerListener

      ServerManager addServerManagerListener(ServerManagerListener listener)
      Adds a ServerManagerListener to be notified of server manager events.

      Listeners are invoked in the order they are added (FIFO) for all events except beforeShutdown, which uses reverse order (LIFO) to allow proper cleanup of resources.

      Event Ordering:

      Thread Safety: This method is thread-safe. Listeners are stored in a concurrent collection and can be added at any time, even while the server is running.

      Parameters:
      listener - the listener to add (must not be null)
      Returns:
      this server manager instance for method chaining
      Throws:
      UnsupportedOperationException - if this server manager does not support listeners (e.g., managed servers)
      Since:
      2.0.0

    • removeServerManagerListener

      boolean removeServerManagerListener(ServerManagerListener listener)
      Removes a previously added ServerManagerListener from this server manager.

      Once removed, the listener will no longer receive notifications for any subsequent server manager events. If the listener is currently being invoked when this method is called, it will complete its current invocation but will not be called for future events.

      Thread Safety: This method is thread-safe and can be called at any time, even while the server is running or events are being processed.

      Parameters:
      listener - the listener to remove
      Returns:
      true if the listener was found and removed, false if the listener was not registered
      Since:
      2.0.0

    • start

      default ServerManager start() throws ServerManagerException
      Starts a server and waits for 60 seconds for the server to start.
      Returns:
      the started server
      Throws:
      ServerManagerException - if the server is already started or an error occurs while starting the server
      Since:
      2.0.0
      See Also:

    • start

      ServerManager start(long timeout, TimeUnit unit) throws ServerManagerException
      Starts a server and waits for it to reach a running state.

      This method can be used to start a server that was created using of(Configuration) or to restart a server that was previously shutdown.

      Thread Safety: This method is thread-safe and uses internal locking to ensure only one server instance can be started at a time. If multiple threads attempt to start the server concurrently, only one will succeed and the others will receive a ServerManagerException.

      Lifecycle:

      • If the server is already running, throws a ServerManagerException
      • On successful start, the server manager becomes operational and ready for use
      • On failure or timeout, the server process is cleaned up and the error state is restored

      Relationship with other methods:

      • shutdown() must be called before calling start() again to restart a server
      • close() may shutdown the server if configured with shutdownOnClose
      Parameters:
      timeout - the maximum time to wait for the server to start
      unit - the time unit for the timeout parameter
      Returns:
      this server manager instance
      Throws:
      ServerManagerException - if the server is already running, fails to start, or doesn't start within the specified timeout
      Since:
      2.0.0

    • startAsync

      default CompletionStage<ServerManager> startAsync()
      Asynchronously starts a server and waits for 60 seconds for the server to start.
      Returns:
      a completion stage with the started server if the server starts within 60 seconds
      Since:
      2.0.0
      See Also:

    • startAsync

      CompletionStage<ServerManager> startAsync(long timeout, TimeUnit unit)
      Asynchronously starts a server and waits the amount of time defined by the timeout and the time unit.
      Parameters:
      timeout - the timeout
      unit - the unit for the timeout
      Returns:
      a completion stage with the started server if the server starts within timeout constraints
      Since:
      2.0.0
      See Also:

    • shutdown

      default void shutdown() throws IOException
      Shuts down the server without a graceful shutdown timeout and wait for the server to be shutdown. This is a shortcut for @link #shutdown(long) shutdown(0)}.
      Throws:
      IOException - if an error occurs communicating with the server
      See Also:

    • shutdown

      void shutdown(long timeout) throws IOException
      Shuts down the server and wait for the servers to be shutdown.
      Parameters:
      timeout - the graceful shutdown timeout, a value of -1 will wait indefinitely and a value of 0 will not attempt a graceful shutdown
      Throws:
      IOException - if an error occurs communicating with the server

    • shutdownAsync

      default CompletableFuture<ServerManager> shutdownAsync()
      Shuts down the server without a graceful shutdown timeout. This is a shortcut for shutdown(0).

      The returned ServerManager is the same instance of this server manager. You can use the CompletableFuture.get() to wait until the process, if available, to exit.

      Returns:
      a completable future that on a CompletableFuture.get() will wait for the process, if available, exits
      Since:
      1.2
      See Also:

    • shutdownAsync

      default CompletableFuture<ServerManager> shutdownAsync(long timeout)
      Shuts down the server.

      The returned ServerManager is the same instance of this server manager. You can use the CompletableFuture.get() to wait until the process, if available, to exit.

      Note for implementations. The default method should likely not be used. Care must be taken to ensure a TimeoutException on a CompletableFuture.get() stops the shutdown from continuing to run in the background.

      Parameters:
      timeout - the graceful shutdown timeout, a value of -1 will wait indefinitely and a value of 0 will not attempt a graceful shutdown
      Returns:
      a completable future that on a CompletableFuture.get() will wait for the process, if available, exits
      Since:
      1.2

    • executeReload

      void executeReload() throws IOException
      Reloads the server and returns immediately.
      Throws:
      IOException - if an error occurs communicating with the server

    • executeReload

      void executeReload(org.jboss.dmr.ModelNode reloadOp) throws IOException
      Reloads the server and returns immediately.
      Parameters:
      reloadOp - the reload operation to execute
      Throws:
      IOException - if an error occurs communicating with the server

    • reloadIfRequired

      default void reloadIfRequired() throws IOException
      Checks if the container status is "reload-required" and if it's the case, executes reload and waits for completion with a 60-second timeout. The timeout can be globally changed with the org.wildfly.plugin.tools.server.timeout system property.
      Throws:
      IOException - if an error occurs communicating with the server
      See Also:

    • reloadIfRequired

      void reloadIfRequired(long timeout, TimeUnit unit) throws IOException
      Checks if the container status is "reload-required" and if it's the case, executes reload and waits for completion.
      Parameters:
      timeout - the time to wait for the server to reload
      unit - the time unit for the timeout argument
      Throws:
      IOException - if an error occurs communicating with the server

    • executeOperation

      default org.jboss.dmr.ModelNode executeOperation(org.jboss.dmr.ModelNode op) throws IOException, OperationExecutionException
      Executes the operation with the client() returning the result or throwing an OperationExecutionException if the operation failed.
      Parameters:
      op - the operation to execute
      Returns:
      the result of the operation
      Throws:
      IOException - if an error occurs communicating with the server
      OperationExecutionException - if the operation failed
      Since:
      1.2

    • executeOperation

      default org.jboss.dmr.ModelNode executeOperation(org.jboss.as.controller.client.Operation op) throws IOException, OperationExecutionException
      Executes the operation with the client() returning the result or throwing an OperationExecutionException if the operation failed.
      Parameters:
      op - the operation to execute
      Returns:
      the result of the operation
      Throws:
      IOException - if an error occurs communicating with the server
      OperationExecutionException - if the operation failed
      Since:
      1.2

    • isClosed

      default boolean isClosed()
      Checks if this server manager has been closed. The server manager may be closed if the underlying client was closed.
      Returns:
      true if the server manager was closed, otherwise false
      Since:
      1.2

    • close

      default void close()
      Specified by:
      close in interface AutoCloseable
      Since:
      1.2

    • asManaged

      default ServerManager asManaged()
      Returns an instance of this server manager which does not allow the shutting down the server. A shutdown operation is not allowed and throws an UnsupportedOperationException. The shutdown(), shutdown(long) and kill() operations also throw an UnsupportedOperationException.

      The use-case for this is for cases when you do not want to allow a caller to be able to shutdown a server that has been started.

      Server Manager Listeners: The managed wrapper does not support adding listeners via addServerManagerListener(ServerManagerListener). If you need event notifications, add listeners to this ServerManager instance before calling asManaged(). Listeners added to the original instance will continue to receive events for operations (such as deploy(Deployment) or undeploy(DeploymentDescription)) performed through the managed wrapper.

      Returns:
      a managed server manager
      Since:
      1.2

    • deploy

      ServerManager deploy(Deployment deployment)
      Deploys content to the server. This will fire ServerManagerListener.beforeDeploy(ServerManager, Deployment) before the deployment and ServerManagerListener.afterDeploy(ServerManager, Deployment) after a successful deployment. If the deployment fails, ServerManagerListener.deployFailed(ServerManager, Deployment, Throwable) will be invoked to allow listeners to clean up any resources.
      Parameters:
      deployment - the deployment to deploy to the server
      Returns:
      this server manager
      Throws:
      ServerManagerException - if the deployment fails, the server is not running, or a listener throws an exception
      Since:
      2.0.0

    • undeploy

      ServerManager undeploy(DeploymentDescription deployment)
      Undeploys content from the server. This will fire ServerManagerListener.beforeUndeploy(ServerManager, DeploymentDescription) before undeploying and ServerManagerListener.afterUndeploy(ServerManager, DeploymentDescription) after a successful undeployment. If the undeployment fails, ServerManagerListener.undeployFailed(ServerManager, DeploymentDescription, Throwable) will be invoked.
      Parameters:
      deployment - the deployment description for the deployment to undeploy
      Returns:
      this server manager
      Throws:
      ServerManagerException - if the undeployment fails, the server is not running, or a listener throws an exception
      Since:
      2.0.0