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.
- 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.
- 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 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();
}
- 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();
}
- 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);
}