Embedding the Liberty profile server in the applications

We can use the SPIs provided by the Liberty profile to configure, control, and monitor a Liberty profile server in the applications.

The Liberty profile provides the following SPIs to start or stop a Liberty profile 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, we can receive asynchronous notifications when the server is starting, has started, or has stopped by creating our own class that implements the com.ibm.wsspi.kernel.embeddable.ServerEventListener interface.

To create an instance of an embedded server within the application, we 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 profile installation.

• 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 profile installation. You are advised to configure the ws-javaagent.jar file, but it is not mandatory unless we use capabilities of the server that require it, such as monitoring or trace. If you contact IBM support, we might need to provide trace, and if so, we must start the server with the ws-javaagent.jar file, even if we do not normally use it.

In an embedded environment:

• Environment variables are not checked, and the jvm.options and server.envfiles are not read.

• Management of the JVM and environment is assumed to be managed by the caller.

1. Import the SPIs into the caller class and define the arguments required to operate the Liberty profile 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.

2. Initialize the server using the ServerBuilder class.

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

3. 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<Result> startReturnCode = libertyServer.start();
       Result result = startReturnCode.get(); // block until operation complete, if necessary
       System.out.println("Start returned: success=" + result.successful() + ", rc=" + result.getReturnCode() + ", ex=" + result.getException());

4. 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<Result> stopReturnCode = libertyServer.stop();
       Result result = stopReturnCode.get(); // block until operation complete, if necessary
       System.out.println("Stop returned: success=" + result.successful() + ", rc=" + result.getReturnCode() + ", ex=" + result.getException());

5. Implement the ServerEventListener interface. If you implement the ServerEventListener interface, we 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);
       }
   }

Parent topic: Extending the Liberty profile

Reference:

server command options