You must start the catalog service manually when you are using a distributed WebSphere® eXtreme Scale environment that is not running in WebSphere Application Server.
About this task
Start the catalog service with the startXsServer script. When you call
the start command, use the startXsServer.sh script on UNIX platforms or
startXsServer.bat on Windows. The
catalog service can run in a single process or can include multiple catalog servers to form a
catalog service domain. A catalog service domain is required in a production environment for high
availability. For more information, see High availability catalog service. You can also specify
additional parameters to the script to bind the transport to a specific host and port, specify the
domain, or enable security.
Procedure
- Start a single catalog server process.
To start a single catalog server, type the following commands from the command line:
- Navigate to the bin directory.
- Run the startXsServer command.
startXsServer.bat|sh catalogServer
For a list of all of the available command-line parameters, see
startXsServer script (XIO). Do not use a single
Java™ virtual machine
(
JVM) to run the catalog service in a production
environment. If the catalog service fails, no new clients are able to route to the deployed
eXtreme Scale, and no new ObjectGrid instances can be added to the
domain. For these reasons, you should start a set of
Java virtual machines
to run a catalog service domain.
- Start a catalog service domain that consists of multiple
endpoints.
To start a set of servers to run a catalog service, you must use the
-catalogServiceEndPoints option on the startXsServer
script. This argument accepts a list of catalog service endpoints in the format of
serverName:hostName:clientPort:peerPort.
The following example shows how to start the first of three
Java virtual machines to host a catalog service:
- Navigate to the bin directory.
- Run the startXsServer command.
startXsServer.bat|sh cs1 -catalogServiceEndPoints
cs1:MyServer1.company.com:6601:6602,cs2:MyServer2.company.com:6601:6602,cs3:MyServer3.company.com:6601:6602
In this example, the
cs1 server on the
MyServer1.company.com host is started. This server name is the first argument
that is passed to the script. During initialization of the
cs1 server, the
-catalogServiceEndpoints parameters are examined to determine which ports are
allocated for this process. The list is also used to allow the
cs1 server to
accept connections from other servers:
cs2 and
cs3.
- To start the remaining catalog servers in the list, pass the following arguments to
the startXsServer script. Starting the cs2 server on the
MyServer2.company.com host.
startXsServer.bat|sh cs2 -catalogServiceEndPoints
cs1:MyServer1.company.com:6601:6602,cs2:MyServer2.company.com:6601:6602,cs3:MyServer3.company.com:6601:6602
Starting
cs3 on
MyServer3.company.com:
startXsServer.bat|sh cs3 -catalogServiceEndPoints
cs3:MyServer3.company.com:6601:6602,cs1:MyServer1.company.com:6601:6602,cs2:MyServer2.company.com:6601:6602
The
order of the list for the
-catalogServiceEndpoints parameter can be different
for the various catalog servers, but the servers contained in the list must be the same. Do not put
any spaces in the list.
Important: Start at least two catalog servers in parallel.
You must start catalog servers that are in a data grid in parallel, because each server pauses to
wait for the other catalog servers to join the core group. A catalog server that is configured for a
data grid does not start until it identifies other members in the group. The catalog server
eventually times out if no other servers become available.
- Bind the transport to a specific host and port.
Aside from ports defined in the
catalogServiceEndpoints argument, each
catalog service also uses an Object Request Broker (ORB) to accept connections from clients and
containers. By default, the ORB listens on port
2809 of the localhost. If you
want to bind the ORB to a specific host and port on a catalog service JVM, use the
-listenerHost and
-listenerPort arguments. The following
example shows how to start a single JVM catalog server with its transport bound to port
7000 on
MyServer1.company.com:
startXsServer.sh catalogServer -listenerHost MyServer1.company.com
-listenerPort 7000
Each
eXtreme Scale container and client must be provided with
catalog service ORB endpoint data. Clients only need a subset of this data, but you should use at
least two endpoints for high availability.
- Optional: Name the catalog service domain
A catalog service domain name is not required when starting a catalog service. However, if
you are using multi-master replication or are using multiple catalog service domains within the same
set of processes, then you need to define a unique catalog service domain name. The default domain
name is
DefaultDomain. To give your domain a name, use the
-domain option. The following example demonstrates how to start a single
catalog service JVM with the domain name
myDomain.
startXsServer.sh catalogServer -domain myDomain
For
more information about configuring multi-master replication, see
Configuring multiple data center topologies.
- Start a secure catalog service.
- Start the catalog service programmatically.
Any JVM setting that is flagged by the
CatalogServerProperties.setCatalogServer method can host the catalog service for
eXtreme Scale. This method indicates to the
eXtreme Scale server run time to instantiate the catalog service when
the server is started. The following code shows how to instantiate the
eXtreme Scale catalog
server:
CatalogServerProperties catalogServerProperties =
ServerFactory.getCatalogProperties();
catalogServerProperties.setCatalogServer(true);
//The getInstance() method will start the catalog service.
Server server = ServerFactory.getInstance();
For more information about starting servers programmatically, see Using the embedded server API to start and stop servers.