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