Package org.wildfly.plugin.tools.server

## 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

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Interface | Description
    --- | --- | ---
    `static class` | `ServerManager.Builder` | A builder used to build a `ServerManager`.

  - ### Method Summary

    All Methods Static Methods Instance Methods Abstract Methods Default Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `default ServerManager` | `asManaged()` | Returns an instance of this server manager which does not allow the shutting down the server.
    `static ServerManager.Builder` | `builder()` | Creates a builder to build a server manager.
    `org.jboss.as.controller.client.ModelControllerClient` | `client()` | Returns the client associated with this server manager.
    `default void` | `close()`
    `ContainerDescription` | `containerDescription()` | Returns the container description for the running server.
    `DeploymentManager` | `deploymentManager()` | Returns the deployment manager for the server.
    `default org.jboss.dmr.ModelNode` | `executeOperation​(org.jboss.as.controller.client.Operation op)` | Executes the operation with the `client()` returning the result or throwing an `OperationExecutionException` if the operation failed.
    `default org.jboss.dmr.ModelNode` | `executeOperation​(org.jboss.dmr.ModelNode op)` | Executes the operation with the `client()` returning the result or throwing an `OperationExecutionException` if the operation failed.
    `void` | `executeReload()` | Reloads the server and returns immediately.
    `void` | `executeReload​(org.jboss.dmr.ModelNode reloadOp)` | Reloads the server and returns immediately.
    `static Optional<ProcessHandle>` | `findProcess()` | Attempts to find the controlling process.
    `default boolean` | `isClosed()` | Checks if this server manager has been closed.
    `boolean` | `isRunning()` | Checks to see if a server is running.
    `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.
    `static boolean` | `isValidHomeDirectory​(String path)` | Checks whether the directory is a valid home directory for a server.
    `static boolean` | `isValidHomeDirectory​(Path path)` | Checks whether the directory is a valid home directory for a server.
    `default CompletableFuture<ServerManager>` | `kill()` | If a process is available and alive, the process is attempted to be killed.
    `String` | `launchType()` | Determines the servers "launch-type".
    `static Optional<String>` | `launchType​(org.jboss.as.controller.client.ModelControllerClient client)` | Returns the "launch-type" attribute of a server.
    `void` | `reloadIfRequired()` | Checks if the container status is "reload-required" and if it's the case, executes reload and waits for completion with a 10 second timeout.
    `void` | `reloadIfRequired​(long timeout, TimeUnit unit)` | Checks if the container status is "reload-required" and if it's the case, executes reload and waits for completion.
    `String` | `serverState()` | Gets the "server-state" for standalone servers or the "host-state" for domain servers.
    `default void` | `shutdown()` | Shuts down the server without a graceful shutdown timeout and wait for the server to be shutdown.
    `void` | `shutdown​(long timeout)` | Shuts down the server and wait for the servers to be shutdown.
    `default CompletableFuture<ServerManager>` | `shutdownAsync()` | Shuts down the server without a graceful shutdown timeout.
    `default CompletableFuture<ServerManager>` | `shutdownAsync​(long timeout)` | Shuts down the server.
    `static DomainManager` | `start​(DomainConfiguration configuration)` | Starts a domain server based on the `command builder` and waits until the server is started.
    `static StandaloneManager` | `start​(StandaloneConfiguration configuration)` | Starts a standalone server based on the `command builder`.
    `String` | `takeSnapshot()` | Takes a snapshot of the current servers configuration and returns the relative file name of the snapshot.
    `default boolean` | `waitFor​(long startupTimeout)` | Waits the given amount of time in seconds for a server to start.
    `boolean` | `waitFor​(long startupTimeout, TimeUnit unit)` | Waits the given amount of time for a server to start.

- - ### Method Detail

    - #### builder

          static ServerManager.Builder builder()

      Creates a builder to build a server manager.
      Returns:
        a new builder

    - #### 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

    - #### 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

    - #### 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(long)`

    - #### 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(long)`

    - #### 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

          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 10 second timeout.
      Throws:
        `IOException` - if an error occurs communicating with the server
      See Also:
        `reloadIfRequired(long, TimeUnit)`

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

      Returns:
        a managed server manager
      Since:
        1.2