Fix Pack 8550

Embedding the Liberty profile server in your applications

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

About this task

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 used by embedded operations are the same as those used by the server command. For more information about return codes, see Liberty profile: 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:
  • Include the ws-server.jar file on the class path. The ws-server.jar file is located in the ${wlp.install.dir}/bin/tools directory of the Liberty profile installation.
  • Specify the name of the target server. The target server must already exist.
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

  1. Import the SPIs into your caller class and define the arguments that are 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 by 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 or not the server has started successfully:
    • Check the returned result code.
    • Use the successful() method.
    • The server.isRunning() method returns true if the server is started.
    Future <Result> startReturnCode = libertyServer.start();
      try {
        Result result = startReturnCode.get(); // block until operation complete, if necessary
        System.out.println("Start returned: success=" + result.successful() + ", rc=" + result.getReturnCode() + ", ex=" + result.getException());
        } catch (InterruptedException e) {
         e.printStackTrace();
        } catch (ExecutionException e) {
         e.printStackTrace();
        }
  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 or not the server has stopped successfully:
    • Check the returned result code.
    • Use the successful() method.
    • The server.isRunning() method returns false if the server is stopped.
    Future<Result> stopReturnCode = libertyServer.stop();
      try {
        result = stopReturnCode.get(); // block until operation complete, if necessary
        System.out.println("Stop returned: success=" + result.successful() + ", rc=" + result.getReturnCode() + ", ex=" + result.getException());
        } catch (InterruptedException e) {
         e.printStackTrace();
        } catch (ExecutionException e) {
         e.printStackTrace();
        }
  5. ServerEventListener allows you to receive notifications when the server is started or stopped. To implement the ServerEventListener interface:
    // update the class declaration to indicate that it implements ServerEventListener
    public class MyEmbeddedServer implements ServerEventListener {
     ....
     MyEmbeddedServer() {
      try {
            // set the listener via the server builder
            ServerBuilder sb = new ServerBuilder(); 
      Server libertyServer = sb.setName(serverName)
                               .setServerEventListener(this) 
                               .build();
    	    } catch (ServerException e) {
    	    }
    }
    ...
    @Override
    public void serverEvent(ServerEvent event) { 
            // provide an implementation of the serverEvent method
            System.out.println("NEW SERVER EVENT " + event);
    }

Icon that indicates the type of topic Task topic

Terms and conditions for information centers | Feedback


Timestamp icon Last updated: Monday, 21 April 2014
http://www14.software.ibm.com/webapp/wsbroker/redirect?version=phil&product=was-nd-iseries&topic=twlp_extend_embed
File name: twlp_extend_embed.html