Program guide > Programming for administrative tasks

Use the embedded server API to start and stop servers

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.

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

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

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

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

4. Start a Container instance using the Server instance.

   Before shards can be placed on an embedded server, 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 to use.

   DeploymentPolicy policy = DeploymentPolicyFactory.createDeploymentPolicy(new 
         URL("file://urltodeployment.xml"), 
       new URL("file://urltoobjectgrid.xml"));
   Container container = server.createContainer(policy);
   

5. Remove and clean up a container.

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

6. 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, 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)
           }
   
       }
   
   }
   

Parent topic:

Program for administrative tasks

Related concepts

Embedded server API

Related tasks

Monitor with the statistics API

Monitor with WAS PMI

+

Search Tips   |   Advanced Search