See the WebSphere eXtreme Scale Wiki for links to eXtreme Scale Version 7.0 documentation.
If you log in
with your developerWorks ID, you can leave comments and feedback for the development team.
The ObjectGrid is managed using JMX management beans (MBeans). When run in a WebSphere Application Server process, MBeans can be accessed using the wsadmin administration utility. When ObjectGrid is run outside of WebSphere Application Server, a third party console, like MC4J or jconsole, is required to access the MBeans using a graphical user interface. The JMX API can also be used to programmatically interact with the ObjectGrid administration MBeans.
The ObjectGrid MBean server may be disabled through the enableMBeans flag at startup. It may be desirable to disable the ObjectGrid administration MBeans if increased security or performance is required.
See the ObjectGrid systems management API documentation for a description of all of the MBean interfaces and methods.
ObjectGrid Server MBeans
Every ObjectGrid server JVM hosts the server MBean.
ObjectGridServer MBean
This MBean is a singleton that holds process scoped information like trace settings and allows for stopping the ObjectGrid Server.
Catalog Service MBeans
Currently the only MBean specific to the Catalog Service is the PlacementService MBean.
PlacementService MBean
This MBean allows access to the placement activities of the Catalog Service.
retrieveServerJMXAddress
This important method gives access to the Container MBeans by returning the connection address to use when establishing a connection to the server hosting an ObjectGrid Container. There is also a retrieveAllServerJMXAddresses method to return all known server addresses in a list.
listObjectGridPlacement
One very useful operation is the listObjectGridPlacement operation on the PlacementService Mbean. This method returns an XML formatted string listing the placement of all shards for a given ObjectGrid and MapSet. Each container will be listed along with the shards that are currently allocated to it. Note that there are special containers that act as a staging area for shards that are yet to be assigned.
package com.ibm.ws.objectgrid.test.catalogserver;
import java.util.Set;
import javax.management.MBeanServerConnection;
import javax.management.ObjectName;
import javax.management.remote.JMXConnector;
import javax.management.remote.JMXConnectorFactory;
import javax.management.remote.JMXServiceURL;
/**
* Collects the placement information from the Catalog Server for a given ObjectGrid.
*/
public final class CollectPlacementPlan {
private static String hostName = "localhost";
private static int port = 1099;
private static String objectGridName = "library";
private static String mapSetName = "ms1";
/**
* Connects to the ObjectGrid Catalog Service to retrieve placement information and prints it out.
*
* @param args
* @throws Exception
* If there is a problem connecting to the catalog service MBean server.
*/
public static void main(String[] args) throws Exception {
String serviceURL = "service:jmx:rmi: + hostName + ":" + port + "/objectgrid/MBeanServer";
JMXServiceURL jmxUrl = new JMXServiceURL(serviceURL);
JMXConnector jmxCon = JMXConnectorFactory.connect(jmxUrl);
MBeanServerConnection catalogServerConnection = jmxCon.getMBeanServerConnection();
Set placementSet = catalogServerConnection.queryNames(new ObjectName("com.ibm.websphere.objectgrid"
+ ":*,type=PlacementService"), null);
if (placementSet.size() != 1) {
throw new IllegalStateException("There should not be more than one placement service MBean.\n"
+ placementSet);
}
ObjectName placementService = (ObjectName) placementSet.iterator().next();
Object placementXML = catalogServerConnection.invoke(placementService, "listObjectGridPlacement", new Object[] {
objectGridName, mapSetName }, new String[] { String.class.getName(), String.class.getName() });
System.out.println(placementXML);
}
}
A few notes regarding the sample program
- The JMXServiceURL for the catalog service is always of the form service:jmx:rmi:///jndi/rmi://<host>:<port>/objectgrid/MBeanServer, where <host> is the host on which the catalog service is running and <port> is the JMX service port provided via the -JMXServicePort option when starting the catalog service. If no port is specified, the default is 1099.
- In order for the ObjectGrid or map statistics to be enabled, you need to specify the following property in the server properties file when starting an ObjectGrid container: statsSpec=all=enabled.
- In order to disable the MBeans running in the ObjectGrid containers, specify the following property in the server properties file: enableMBeans=false.
In the following example output one can see that there are two containers active. Container-0 hosts 4 Primary shards and Container-1 hosts a Synchronous Replica for each of them. Note that in this configuration there are 2 Synchronous Replicas and 1 Asynchronous Replica so the Unassigned Container is left with them. If two more containers were started the Unassigned Container will no longer be shown.
<objectGrid name="library" mapSetName="ms1">
<container name="Container-1" zoneName="DefaultZone"
hostName="descartes.rchland.ibm.com" serverName="ogserver">
<shard type="SynchronousReplica" partitionName="0"/>
<shard type="SynchronousReplica" partitionName="1"/>
<shard type="SynchronousReplica" partitionName="2"/>
<shard type="SynchronousReplica" partitionName="3"/>
</container>
<container name="Container-0" zoneName="DefaultZone"
hostName="descartes.rchland.ibm.com" serverName="ogserver">
<shard type="Primary" partitionName="0"/>
<shard type="Primary" partitionName="1"/>
<shard type="Primary" partitionName="2"/>
<shard type="Primary" partitionName="3"/>
</container>
<container name="library:ms1:_UnassignedContainer_" zoneName="_ibm_SYSTEM"
hostName="UNASSIGNED" serverName="UNNAMED">
<shard type="SynchronousReplica" partitionName="0"/>
<shard type="SynchronousReplica" partitionName="1"/>
<shard type="SynchronousReplica" partitionName="2"/>
<shard type="SynchronousReplica" partitionName="3"/>
<shard type="AsynchronousReplica" partitionName="0"/>
<shard type="AsynchronousReplica" partitionName="1"/>
<shard type="AsynchronousReplica" partitionName="2"/>
<shard type="AsynchronousReplica" partitionName="3"/>
</container>
</objectGrid>
The ObjectGridNames attribute on the PlacementService MBean is a handy way to get a list of all the ObjectGrids that are actively maintained by the PlacementService.
ObjectGrid Container MBeans
The ObjectGrid Container hosts a number of MBeans like those for the individual maps and ObjectGrid instances running within the container.
ObjectGridContainer MBean
This MBean has attributes for information about how many shards are currently active on the container as well as how many have been activated and how many have been deactivated over the lifetime of the container.
teardown
The teardown method can be used to migrate shards off of the container smoothly. This method will not fully shutdown the container but will render it empty over time.
retrieveStatus
Much like the listObjectGridPlacement method on the PlacementService, this method returns the currently allocations scoped to the container where the request is run. One important difference is that this method returns the actual real-time active shards list which does not take shards that are in the process of activating into account.
Here is an example program that prints out the status of each container hosted by the catalog server with the JMX address at "localhost:1099".
package com.ibm.ws.objectgrid.test.catalogserver;
import java.util.List;
import java.util.Set;
import javax.management.MBeanServerConnection;
import javax.management.ObjectInstance;
import javax.management.ObjectName;
import javax.management.remote.JMXConnector;
import javax.management.remote.JMXConnectorFactory;
import javax.management.remote.JMXServiceURL;
/**
* Collects placement status from each of the available containers directly.
*/
public final class CollectContainerStatus {
private static String hostName = "localhost";
private static int port = 1099;
/**
* @param args
*/
public static void main(String[] args) throws Exception {
String serviceURL = "service:jmx:rmi: + hostName + ":" + port + "/objectgrid/MBeanServer";
JMXServiceURL jmxUrl = new JMXServiceURL(serviceURL);
JMXConnector jmxCon = JMXConnectorFactory.connect(jmxUrl);
MBeanServerConnection catalogServerConnection = jmxCon.getMBeanServerConnection();
Set placementSet = catalogServerConnection.queryNames(new ObjectName("com.ibm.websphere.objectgrid"
+ ":*,type=PlacementService"), null);
if (placementSet.size() != 1) {
throw new IllegalStateException("There should not be more than one placement service MBean.\n"
+ placementSet);
}
ObjectName placementService = (ObjectName) placementSet.iterator().next();
List<String> containerJMXAddresses = (List<String>) catalogServerConnection.invoke(placementService,
"retrieveAllServersJMXAddresses", new Object[0], new String[0]);
for (String address : containerJMXAddresses) {
JMXServiceURL containerJMXURL = new JMXServiceURL(address);
JMXConnector containerConnector = JMXConnectorFactory.connect(containerJMXURL);
MBeanServerConnection containerConnection = containerConnector.getMBeanServerConnection();
Set<ObjectInstance> containers = containerConnection.queryMBeans(
new ObjectName("*:*,type=ObjectGridContainer"), null);
for (ObjectInstance container : containers) {
System.out.println(containerConnection.getAttribute(container.getObjectName(), "Status"));
}
}
}
}
The above program will print out the container status for each container.
<container name="Container-0" zoneName="DefaultZone" hostName="descartes.rchland.ibm.com" serverName="ogserver">
<shard type="Primary" partitionName="1"/>
<shard type="Primary" partitionName="0"/>
<shard type="Primary" partitionName="3"/>
<shard type="Primary" partitionName="2"/>
</container>
quiesceContainer
Prepare the container for a potential shutdown by moving replica shards, verifying that primaries have required sync replicas and preventing the placement of new shards. Returns the number of replicas moved off of the ObjectGrid container
Shard MBean
This MBean currently only has a number of attributes used primarily as metrics. The number of active, forwarded, processed, and total requests serviced by the shard is kept here.
Access ObjectGrid MBeans in a WebSphere Application Server environment
The method in which ObjectGrid MBeans are accessed when running in WebSphere is slightly different than in a non-WebSphere Application Server ObjectGrid environment. There are two options for accessing the MBeans in WebSphere: programmatically and using the wsadmin command-line tool.
Access ObjectGrid MBeans programmatically with JMX
Here is the CollectPlacementPlan.java from earlier, modified to access the ObjectGrid MBeans in WebSphere:
package com.ibm.ws.objectgrid.test.catalogserver;
import java.util.Set;
import javax.management.MBeanServerConnection;
import javax.management.ObjectName;
import javax.management.remote.JMXConnector;
import javax.management.remote.JMXConnectorFactory;
import javax.management.remote.JMXServiceURL;
/**
* Collects the placement information from the Catalog Server running in a deployment manager for a given ObjectGrid.
*/
public final class CollectPlacementPlan {
private static String hostName = "localhost";
private static int port = 9809;
private static String objectGridName = "library";
private static String mapSetName = "ms1";
/**
* Connects to the ObjectGrid Catalog Service to retrieve placement information and prints it out.
*
* @param args
* @throws Exception
* If there is a problem connecting to the catalog service MBean server.
*/
public static void main(String[] args) throws Exception {
String serviceURL = "service:jmx:iiop: + hostName + ":" + port + "/jndi/JMXConnector";
JMXServiceURL jmxUrl = new JMXServiceURL(serviceURL);
JMXConnector jmxCon = JMXConnectorFactory.connect(jmxUrl);
MBeanServerConnection catalogServerConnection = jmxCon.getMBeanServerConnection();
Set placementSet = catalogServerConnection.queryNames(new ObjectName("com.ibm.websphere.objectgrid"
+ ":*,type=PlacementService"), null);
if (placementSet.size() != 1) {
throw new IllegalStateException("There should not be more than one placement service MBean.\n"
+ placementSet);
}
ObjectName placementService = (ObjectName) placementSet.iterator().next();
Object placementXML = catalogServerConnection.invoke(placementService, "listObjectGridPlacement", new Object[] {
objectGridName, mapSetName }, new String[] { String.class.getName(), String.class.getName() });
System.out.println(placementXML);
}
}
In order to run this code, it will need to be compiled, then execute the following command:
"$JAVA_HOME/bin/java" "$WAS_LOGGING" -Djava.security.auth.login.config="$app_server_root/properties/wsjaas_client.conf" \
-Djava.ext.dirs="$JAVA_HOME/jre/lib/ext:$WAS_EXT_DIRS:$WAS_HOME/plugins:$WAS_HOME/lib/WMQ/java/lib" \
-Djava.naming.provider.url=<an_IIOP_URL_or_a_corbaloc_URL_to_your_application_server_machine_name> \
-Djava.naming.factory.initial=com.ibm.websphere.naming.WsnInitialContextFactory \
-Dserver.root="$WAS_HOME" "$CLIENTSAS" "$CLIENTSSL" $USER_INSTALL_PROP \
-classpath "$WAS_CLASSPATH":<list_of_your_application_jars_and_classes> \
<fully_qualified_class_name_to_run> <your_application_parameters>
This command assumes the $WAS_HOME/bin/setupCmdLine.sh script has been run to set the variables properly. An example of the format of the java.naming.provider.url property value is "corbaloc:iiop:1.0@<host>:<port>/NameService"
Example accessing ObjectGrid MBeans using the wsadmin tool
To retrieve a view of the current shard placement in a dynamic ObjectGrid, run the following wsadmin jython commands from the WebSphere bin directory (use wsadmin.bat for Windows platforms):
$ wsadmin.sh -lang jython
wsadmin>placementService = AdminControl.queryNames("com.ibm.websphere.objectgrid:*,type=PlacementService")
wsadmin>print AdminControl.invoke(placementService,"listObjectGridPlacement","library ms1")
<objectGrid name="library" mapSetName="ms1">
<container name="container-0" zoneName="DefaultDomain" hostName="host1.company.org" serverName="server1">
<shard type="Primary" partitionName="0"/>
<shard type="SynchronousReplica" partitionName="1"/>
</container>
<container name="container-1" zoneName="DefaultDomain" hostName="host2.company.org" serverName="server2">
<shard type="SynchronousReplica" partitionName="0"/>
<shard type="Primary" partitionName="1"/>
</container>
<container name="UNASSIGNED" zoneName="_ibm_SYSTEM" hostName="UNASSIGNED" serverName="UNNAMED">
<shard type="SynchronousReplica" partitionName="0"/>
<shard type="AsynchronousReplica" partitionName="0"/>
</container>
</objectGrid>
Additional information
© Copyright IBM Corporation 2007,2009. All Rights Reserved.
