With WebSphere® eXtreme Scale,
you can use a programmatic API for managing the life cycle of embedded
servers and containers. You can programmatically configure the server
with any of the options that you can also configure with the command
line options or file-based server properties. You can configure the
embedded server to be a container server, a catalog service, or both.
Before you begin
- You must have a method for running code from within an already
existing Java™ virtual machine. The eXtreme Scale classes must be available
through the class loader tree.
- If your container servers are
using IBM® eXtremeMemory,
you must first configure the native libraries. For more information,
see Configuring IBM eXtremeMemory.
About this task
You can run many administration tasks with the Administration
API. One common use of the API is as an internal server for storing
Web application state. The Web server can start an embedded WebSphere eXtreme Scale server, report the
container server to the catalog service, and the server is then added
as a member of a larger distributed grid. This usage can provide
scalability and high availability to an otherwise volatile data store.
You
can programmatically control the complete life cycle of an embedded eXtreme Scale server. The examples
are as generic as possible and only show direct code examples for
the outlined steps.
Procedure
- Obtain the ServerProperties object
from the ServerFactory class and configure any
necessary options.
For more information
about the ServerProperties interface, see ServerProperties interface.Every
eXtreme Scale server has a set
of configurable properties. When a server starts from the command
line, those properties are set to defaults, but you can override several
properties by providing an external source or file. In the embedded
scope, you can directly set the properties with a ServerProperties
object. You must set these properties before you obtain a server
instance from the
ServerFactory class. The following
example snippet obtains a
ServerProperties object,
sets the CatalogServiceBootStrap field, and initializes several optional
server settings. See the API documentation for a list of the configurable
settings.
ServerProperties props = ServerFactory.getServerProperties();
props.setCatalogServiceBootstrap("host:port"); // required to connect to specific catalog service
props.setServerName("ServerOne"); // name server
props.setTraceSpecification("com.ibm.ws.objectgrid=all=enabled"); // Sets trace spec
- If you want the server to be a catalog
service, obtain
the CatalogServerProperties object.
For more information about the CatalogServerProperties
interface, see CatalogServerProperties interface.
Every
embedded server can be a catalog service, a container server, or both
a container server and a catalog service. The following example obtains
the
CatalogServerProperties object, enables the
catalog service option, and configures various catalog service settings.
CatalogServerProperties catalogProps = ServerFactory.getCatalogProperties();
catalogProps.setCatalogServer(true); // false by default, it is required to set as a catalog service
catalogProps.setQuorum(true); // enables / disables quorum
- Obtain a Server instance
from the ServerFactory class.
The Server instance is a process-scoped singleton
that is responsible for managing the membership in the grid. After
this instance has been instantiated, this process is connected and
is highly available with the other servers in the grid.
For more information about the Server interface,
see Server interface. For more information abut the ServerFactory class,
see ServerFactory class.
The following example
shows how to create the
Server instance:
Server server = ServerFactory.getInstance();
Reviewing
the previous example, the
ServerFactory class provides
a static method that returns a
Server instance.
The
ServerFactory class is intended to be the only
interface for obtaining a
Server instance. Therefore,
the class ensures that the instance is a singleton, or one instance
for each JVM or isolated classloader. The
getInstance method
initializes the
Server instance. You must configure
all the server properties before you initialize the instance. The
Server class
is responsible for creating new
Container instances.
You can use both the ServerFactory and Server classes for managing
the life cycle of the embedded Server instance.
For
more information about the Container interface,
see Container interface.
- Start a Container instance using the
Server instance.
Before shards can be placed on an embedded
server, you must create a container on the server. The
Server interface
has a
createContainer method that takes a
DeploymentPolicy argument.
The following example uses the server instance that you obtained to
create a container using a created DeploymentPolicy file. Note that
Containers require a classloader that has the application binaries
available to it for serialization. You can make these binaries available
by calling the
createContainer method with the
Thread context classloader set to the classloader that you want to
use.
DeploymentPolicy policy = DeploymentPolicyFactory.createDeploymentPolicy(new
URL("file://urltodeployment.xml"),
new URL("file://urltoobjectgrid.xml"));
Container container = server.createContainer(policy);
- Remove and clean up a container server.
You
can remove and clean up a container server by using the running the teardown method
on the obtained Container instance. Running the teardown method
on a container properly cleans up the container and removes the container
from the embedded server.
The process of cleaning up the container
includes the movement and tearing down of all the shards that are
placed within that container. Each server can contain many containers
and shards. Cleaning up a container does not affect the life cycle
of the parent
Server instance. The following example
demonstrates how to run the
teardown method on
a server. The
teardown method is made available
through the
ContainerMBean interface. By using
the
ContainerMBean interface, if you no longer
have programmatic access to this container, you can still remove and
clean up the container with its MBean. A
terminate method
also exists on the
Container interface, do not
use this method unless it is absolutely needed. This method is more
forceful and does not coordinate appropriate shard movement and clean
up.
container.teardown();
-
Stop the embedded server.
When you stop an
embedded server, you also stop any containers and shards that are
running on the server. When you stop an embedded server, you must
clean up all open connections and move or tear down all the shards.
The following example demonstrates how to stop a server and using
the
waitFor method on the Server interface to ensure
that the Server instance shuts down completely. Similarly to the
container example, the
stopServer method is made
available through the
ServerMBean interface. With
this interface, you can stop a server with the corresponding Managed
Bean (MBean).
ServerFactory.stopServer(); // Uses the factory to kill the Server singleton
// or
server.stopServer(); // Uses the Server instance directly
server.waitFor(); // Returns when the server has properly completed its shutdown procedures
Full
code example:
import java.net.MalformedURLException;
import java.net.URL;
import com.ibm.websphere.objectgrid.ObjectGridException;
import com.ibm.websphere.objectgrid.deployment.DeploymentPolicy;
import com.ibm.websphere.objectgrid.deployment.DeploymentPolicyFactory;
import com.ibm.websphere.objectgrid.server.Container;
import com.ibm.websphere.objectgrid.server.Server;
import com.ibm.websphere.objectgrid.server.ServerFactory;
import com.ibm.websphere.objectgrid.server.ServerProperties;
public class ServerFactoryTest {
public static void main(String[] args) {
try {
ServerProperties props = ServerFactory.getServerProperties();
props.setCatalogServiceBootstrap("catalogservice-hostname:catalogservice-port");
props.setServerName("ServerOne"); // name server
props.setTraceSpecification("com.ibm.ws.objectgrid=all=enabled"); // TraceSpec
/*
* In most cases, the server will serve as a container server only
* and will connect to an external catalog service. This is a more
* highly available way of doing things. The commented code excerpt
* below will enable this Server to be a catalog service.
*
*
* CatalogServerProperties catalogProps =
* ServerFactory.getCatalogProperties();
* catalogProps.setCatalogServer(true); // enable catalog service
* catalogProps.setQuorum(true); // enable quorum
*/
Server server = ServerFactory.getInstance();
DeploymentPolicy policy = DeploymentPolicyFactory.createDeploymentPolicy
(new URL("url to deployment xml"), new URL("url to objectgrid xml file"));
Container container = server.createContainer(policy);
/*
* Shard will now be placed on this container if the deployment requirements are met.
* This encompasses embedded server and container creation.
*
* The lines below will simply demonstrate calling the cleanup methods
*/
container.teardown();
server.stopServer();
int success = server.waitFor();
} catch (ObjectGridException e) {
// Container failed to initialize
} catch (MalformedURLException e2) {
// invalid url to xml file(s)
}
}
}