Embedding the Liberty server in your applications

You can use the System Programming Interfaces (SPIs) that are provided by Liberty to configure, control, and monitor a Liberty server in your applications.

About this task

Liberty provides the following SPIs to start or stop a Liberty server:

com.ibm.wsspi.kernel.embeddable.Server
com.ibm.wsspi.kernel.embeddable.ServerBuilder

Use a Future object to store the result of a start or stop operation. The return codes that are used by embedded operations are the same as the return codes used by the server command. For more information about return codes, JVM options used by the server script, and the process environment used by the server script, see Server command options.

Additionally, you can receive asynchronous notifications when the server is starting, has started, or has stopped by creating your own class that implements the com.ibm.wsspi.kernel.embeddable.ServerEventListener interface.

Note: To create an instance of an embedded server within your application, you must carry out the following steps:

Include the ws-server.jar file on the class path. The ws-server.jar file is in the ${wlp.install.dir}/bin/tools directory of the Liberty installation.
Specify the name of the target server. The target server must exist.
Optional: Configure the ws-javaagent.jar file with the -javaagent JVM option. The ws-javaagent.jar file is in the ${wlp.install.dir}/bin/tools directory of the Liberty installation. You are advised to configure the ws-javaagent.jar file, but it is not mandatory unless you use capabilities of the server that require it, such as monitoring or trace. If you contact IBM® support, you might need to provide trace, and if so, you must start the server with the ws-javaagent.jar file, even if you do not normally use it.

Note: In an embedded environment:

Environment variables are not checked, and the jvm.options and server.env files are not read.
Management of the JVM and environment is assumed to be managed by the caller.

Procedure

Import the SPIs into your caller class and define the arguments that are required to operate the Liberty server.
```
import com.ibm.wsspi.kernel.embeddable.Server;
import com.ibm.wsspi.kernel.embeddable.ServerBuilder;

public class MyEmbeddedServer {
    String serverName="defaultServer";
    File userDir = new File("usr");
    File outputDir = new File("usr/servers/");
    ...
}
```
Where
- The serverName is required, and must match the name of a previously created server.
- The userDir is optional and used to set the path of the user directory. By default, the user directory is ${wlp.user.dir}.
- The outputDir is optional and used to set the path of the output directory. By default, the output directory is ${wlp.user.dir}/servers.

Initialize the server by using the ServerBuilder class.

    ServerBuilder sb = new ServerBuilder();
    Server libertyServer = sb.setName(serverName)
                             .setUserDir(userDir)
                             .setOutputDir(outputDir)
                             .build();

Call the Server.start() method to start the server. Call get() on the future to block until the start operation completes.
Use one of the following to determine whether the server started successfully:
- Check the returned result code.
- Use the successful() method.
- If the server is started, the server.isRunning() method returns true.
```
    Future<Server.Result> startReturnCode = libertyServer.start();
    Server.Result result = startReturnCode.get(); // block until operation complete, if necessary
    System.out.println("Start returned: success=" + result.successful() + ", rc=" + result.getReturnCode() + ", ex=" + result.getException());
```
Call the Server.stop() method to stop the server. Call get() on the future to block until the stop operation completes.
Use one of the following to determine whether the server stopped successfully:
- Check the returned result code.
- Use the successful() method.
- If the server is stopped, the server.isRunning() method returns false.
```
    Future<Server.Result> stopReturnCode = libertyServer.stop();
    Server.Result result = stopReturnCode.get(); // block until operation complete, if necessary
    System.out.println("Stop returned: success=" + result.successful() + ", rc=" + result.getReturnCode() + ", ex=" + result.getException());
```

Implement the ServerEventListener interface. If you implement the ServerEventListener interface, you can receive notifications when the server is started or stopped.

// update the class declaration to indicate that it implements ServerEventListener
public class MyEmbeddedServer implements ServerEventListener {
    ...
    MyEmbeddedServer() throws ServerException {
        // set the listener via the server builder
        ServerBuilder sb = new ServerBuilder();
        Server libertyServer = sb.setName(serverName)
                                 .setServerEventListener(this)
                                 .build();
    }

    ...
    @Override
    public void serverEvent(ServerEvent event) {
        // provide an implementation of the serverEvent method
        System.out.println("serverEvent: " + event);
    }
}