IBM WebSphere® DataPower® XC10 Appliance
Release 1.0 Client API Specification

com.ibm.websphere.objectgrid.management
Interface PlacementServiceMBean

All Superinterfaces:
com.ibm.websphere.objectgrid.management.CoreGroupServiceMBean

public interface PlacementServiceMBean
extends com.ibm.websphere.objectgrid.management.CoreGroupServiceMBean

This MBean interface allows a client process to perform operations on and get status from the PlacementService running in a dynamic environment. The object name pattern for this MBean is:

 com.ibm.websphere.objectgrid:type=PlacementService
 
If ObjectGrid is running in a WebSphere Application Server process, more key=value pairs may be added to the object name.

Since:
WAS XD 6.1 FIX3, XC10

Field Summary
static int ALL
          Constant representing a all shard types
static int ASYNCHRONOUS_REPLICA
          Constant representing an asynchronous replica shard type.
static int PRIMARY
          Constant representing a primary shard type.
static int SYNCHRONOUS_REPLICA
          Constant representing a synchronous replica shard type.
 
Fields inherited from interface com.ibm.websphere.objectgrid.management.CoreGroupServiceMBean
HEARTBEAT_FREQUENCY_LEVEL_AGGRESSIVE, HEARTBEAT_FREQUENCY_LEVEL_RELAXED, HEARTBEAT_FREQUENCY_LEVEL_TYPICAL, STATUS_QUORUM_DISABLED, STATUS_QUORUM_ENABLED_NORMAL, STATUS_QUORUM_ENABLED_WAITING, STATUS_QUORUM_INCONSISTENT, STATUS_QUORUM_OVERRIDE
 
Method Summary
 java.lang.String collectContainerStatus(java.lang.String objectGridName, java.lang.String mapSetName)
          Retrieves the container status for all containers in the domain.
 java.lang.String getCoreGroups()
          Gets the coregroup status.
 java.lang.String getObjectGridNames()
          Gets the names of all ObjectGrids and their mapsets in the domain.
 java.lang.String listCoreGroupMembers(java.lang.String coreGroupName)
          List the coregroup members for a given coregroup.
 java.lang.String listObjectGridPlacement(java.lang.String objectGridName, java.lang.String mapSetName)
          List the placement of shards for each container in the domain.
 java.lang.String listObjectGridPlacementStatus(java.lang.String objectGridName, java.lang.String mapSetName)
          List the current placement status.
 java.lang.String listPartition(java.lang.String objectGridName, java.lang.String mapSetName, java.lang.String partitionId)
          List the partition placement status in the domain.
 java.lang.String listShards(java.lang.String objectGridName, java.lang.String mapSetName, java.lang.String containerName, int mask)
          List the shard placement status.
 java.lang.String listVerifiedRoutingTable(java.lang.String objectGridName)
          Calling this method will return an XML string of the current known routing table.
 java.lang.String replaceLostShards(java.lang.String objectGridName, java.lang.String mapSetName)
          Lost shards are placed onto the UNREPAIRED container when autoReplaceLostShards is disabled.
 java.util.List retrieveAllServersJMXAddresses()
          Retrieves a List of JMX addresses for all servers that have registered with the placement service.
 java.lang.String retrieveMapSetName(java.lang.String gridName, java.lang.String mapName)
          Retrieves the name of the MapSet in which the specified map is defined.
 java.util.List retrieveServerJMXAddress(java.lang.String hostName, java.lang.String serverName)
          Retrieves a List of JMX address strings for a specific host and server name that has registered with the placement service.
 java.lang.String tearDownServers(java.lang.String[] servers)
          Each of the container servers that are passed into this method will be stopped.
 java.lang.String triggerPlacement(java.lang.String objectGridName, java.lang.String mapSetName)
          Placement normally occurs implicitly after an event such as an ObjectGrid container starting or stopping.
 
Methods inherited from interface com.ibm.websphere.objectgrid.management.CoreGroupServiceMBean
getHeartBeatFrequencyLevel, getQuorumActivationStatus, overrideQuorum, setHeartBeatFrequencyLevel
 

Field Detail

PRIMARY

static final int PRIMARY
Constant representing a primary shard type.

See Also:
Constant Field Values

SYNCHRONOUS_REPLICA

static final int SYNCHRONOUS_REPLICA
Constant representing a synchronous replica shard type.

See Also:
Constant Field Values

ASYNCHRONOUS_REPLICA

static final int ASYNCHRONOUS_REPLICA
Constant representing an asynchronous replica shard type.

See Also:
Constant Field Values

ALL

static final int ALL
Constant representing a all shard types

See Also:
Constant Field Values
Method Detail

retrieveServerJMXAddress

java.util.List retrieveServerJMXAddress(java.lang.String hostName,
                                        java.lang.String serverName)
Retrieves a List of JMX address strings for a specific host and server name that has registered with the placement service.

Parameters:
hostName - The name of the host to retrieve the JMX addresses.
serverName - The name of the server to retrieve the JMX addresses.
Returns:
the List of all JMX address strings for the specified host and server name.

retrieveAllServersJMXAddresses

java.util.List retrieveAllServersJMXAddresses()
Retrieves a List of JMX addresses for all servers that have registered with the placement service.

Returns:
the List of all servers' JMX addresses

collectContainerStatus

java.lang.String collectContainerStatus(java.lang.String objectGridName,
                                        java.lang.String mapSetName)
Retrieves the container status for all containers in the domain.

The results are returned in the following format:

 <container name="<container>" zoneName="<zone>" hostName="<host>" serverName="<server>">
   <shard type="<type>" partitionName="<partition>"/>
 </container>
 

Parameters:
objectGridName - The name of the ObjectGrid for which to get container status.
mapSetName - The name of the mapset for which to get the container status.
Returns:
The String status object for all containers in XML form.

listObjectGridPlacement

java.lang.String listObjectGridPlacement(java.lang.String objectGridName,
                                         java.lang.String mapSetName)
List the placement of shards for each container in the domain.

The results are returned in the following format:

 <objectGrid name="<objectgrid>" mapSetName="<mapset">
   <container name="<container>" zoneName="<zone>" hostName="<host>" serverName="<server>">
      <shard type="<type>" partitionName="<partition>" reserved="<true>"/>
   /container>
 </objectGrid>
  
NOTE: The default value for the "reserved" is false.

Parameters:
objectGridName - The name of the ObjectGrid for which to get placement status.
mapSetName - The name of the mapset for which to get the placement status.
Returns:
The placement status in XML form.

listObjectGridPlacementStatus

java.lang.String listObjectGridPlacementStatus(java.lang.String objectGridName,
                                               java.lang.String mapSetName)
List the current placement status.

The results are returned in the following format:

 <objectGrid name="<objectgrid>" mapSetName="<mapset>">
   <configuration>
     <attribute name="<placementStrategy>" value="<strategy>"/>
     <attribute name="<numInitialContainers>" value="<num>"/>
     <attribute name="<minSyncReplicas>" value="<min>"/>
     <attribute name="<developmentMode>" value="<mode>"/>
   </configuration>
   <runtime>
     <attribute name="<numContainers>" value="<num>"/>
     <attribute name="<numMachines>" value="<num>"/>
     <attribute name="<numOutstandingWorkItems>" value="<num>"/>
     <attribute name="<numActiveZones>" value="<num>"/>
   </runtime>
 </objectGrid>
 

Parameters:
objectGridName - The name of the ObjectGrid for which to get placement status.
mapSetName - The name of the mapset for which to get the placement status.
Returns:
The placement status in XML form.

getCoreGroups

java.lang.String getCoreGroups()
Gets the coregroup status.

The results are returned in the following format:

 <coreGroup name="<coregroup>">
   <coreGroupLeader hostName="<host>" serverName="<server>"/>
   <coreGroupMember hostName="<host>" serverName="<server>"/>
 </coreGroup>
 

Returns:
the coregroup status in XML form.

listCoreGroupMembers

java.lang.String listCoreGroupMembers(java.lang.String coreGroupName)
List the coregroup members for a given coregroup.

The results are returned in the following format:

 <coreGroup name="<coregroup>">
   <coreGroupMember hostName="<host>" serverName="<server>"/>
 </coreGroup>
 

Parameters:
coreGroupName - The name of the coregroup for which to get the members.
Returns:
The coregroup members in XML form.

listPartition

java.lang.String listPartition(java.lang.String objectGridName,
                               java.lang.String mapSetName,
                               java.lang.String partitionId)
List the partition placement status in the domain. The results are returned in the following format:
 <partition name="<partition>">
   <shard type="<type>" containerName="<container>" hostName="<host>" serverName="<server>"/>
 </partition>
 

Parameters:
objectGridName - The name of the ObjectGrid for which to get placement status.
mapSetName - The name of the mapset for which to get the placement status.
partitionId - The name of the partition for which to get the placement status.
Returns:
The partition placement status in the XML form.

listShards

java.lang.String listShards(java.lang.String objectGridName,
                            java.lang.String mapSetName,
                            java.lang.String containerName,
                            int mask)
List the shard placement status.

The results are returned in the following format:

 <objectGrid name="<objectgrid>" mapSetName="<mapset>">
   <container name="<container>" zoneName="<zone>" hostName="<host>" serverName="<server>">
     <shard type="<type>" partitionName="<partition>"/>
   </container>
 </objectGrid>
 

Parameters:
objectGridName - The name of the ObjectGrid for which to get placement status.
mapSetName - The name of the mapset for which to get the placement status.
containerName - The name of the container for which to get the placement status. If empty string ( "" ), get shard placement for all containers.
mask - The Integer mask to determine for which shard types to get status.
Returns:
The shard placement status in XML form.
See Also:
ALL, PRIMARY, SYNCHRONOUS_REPLICA, ASYNCHRONOUS_REPLICA

getObjectGridNames

java.lang.String getObjectGridNames()
Gets the names of all ObjectGrids and their mapsets in the domain.

The results are returned in the following format:

 <objectGrid name="<objectgrid>" mapSetName="<mapset>"/>
 

Returns:
the names of all ObjectGrids and their mapsets in the domain in XML form.

replaceLostShards

java.lang.String replaceLostShards(java.lang.String objectGridName,
                                   java.lang.String mapSetName)
Lost shards are placed onto the UNREPAIRED container when autoReplaceLostShards is disabled. Shards on the UNREPAIRED will not be placed until this method is called.

Calling this method will move shards off the UNREPAIRED container onto the UNASSIGNED container.

Balance and placement operations will be queued up for the MapSet specified. These operations will execute when all outstanding placement work from previous events has completed.

The string returned is an XML representation of the shards that moved as a result of the call to this method.

 <objectGrid name="<objectgrid>" mapSetName="<mapset>">
   <shard type="<type>" partitionName="<partition>">
     <currentContainer name="<container>" zoneName="<zone>" hostName="<host>" serverName="<server>"/>
     <previousContainer name="<container>" zoneName="<zone>" hostName="<host>" serverName="<server>"/>
   </shard>
 </objectGrid>
 

The returned XML will look as follows when no shards have been moved:

 <objectGrid name="<objectgrid>" mapSetName="<mapset>">
   <!-- No shards were moved -->
 </objectGrid>
 

Parameters:
objectGridName - replace lost shards for this ObjectGrid
mapSetName - replace lost shards for this MapSet
Returns:
An XML String containing shards that have moved
Since:
WAS XD 6.1.0.5

triggerPlacement

java.lang.String triggerPlacement(java.lang.String objectGridName,
                                  java.lang.String mapSetName)
Placement normally occurs implicitly after an event such as an ObjectGrid container starting or stopping.

Calling this method will trigger a placement operation for the ObjectGrid and MapSet specified.

Under normal circumstances, the numInitialContainers attribute (in the deployment policy) must be met in order for placement to occur. However, when this method is called, the numInitialContainers value is ignored.

The string returned is an XML representation of the shards that moved as a result of the call to this method.

 <objectGrid name="<objectgrid>" mapSetName="<mapset>">
   <shard type="<type>" partitionName="<partition>">
     <currentContainer name="<container>" zoneName="<zone>" hostName="<host>" serverName="<server>"/>
     <previousContainer name="<container>" zoneName="<zone>" hostName="<host>" serverName="<server>"/>
   </shard>
 </objectGrid>
 

The returned XML will look as follows when no shards have been moved:

 <objectGrid name="<objectgrid>" mapSetName="<mapset>">
   <!-- No shards were moved -->
 </objectGrid>
 

Parameters:
objectGridName - trigger placement for this ObjectGrid
mapSetName - trigger placement for this MapSet
Returns:
An XML String containing shards that have moved
Since:
WAS XD 6.1.0.5
See Also:
ObjectGridDeployment.addMapSet(com.ibm.websphere.objectgrid.deployment.MapSet), MapSet.setNumInitialContainers(int)

tearDownServers

java.lang.String tearDownServers(java.lang.String[] servers)
Each of the container servers that are passed into this method will be stopped. If the server cannot be reached, all of the server's artifacts will be removed.

Use this method if servers are found to be in a corrupt state or bindings need to be cleared from the catalog server.

The string returned is an XML representation of the results of the attempt to tear down each of the servers.

 <domain name="<domain>">
   <server name="<server>" tearDownSuccessful="<boolean>"/>
   <server name="<server>" tearDownSuccessful="<boolean>"/>
 </domain>
 

Parameters:
servers - String array of servers to tear down.
Returns:
An XML String containing the results of tear down attempts.
Since:
WAS XD 6.1.0.5 FIX2

listVerifiedRoutingTable

java.lang.String listVerifiedRoutingTable(java.lang.String objectGridName)
Calling this method will return an XML string of the current known routing table. The Placement service will contact each shard and return state on whether it was able to verify that's shard's existence. All shards will be included in the XML doc, whether they were reachable or not. The user can use the reachable attribute below to filter valid or invalid shards.
 <objectGrid name="<objectgrid>" name="<name>">
   <primary zone="<zone>"> partition="<partition>"> state="<reachable>"> ipaddress="<ipaddress>">
     <replica zone="<zone>"> partition="<partition>"> state="<reachable>"> ipaddress="<ipaddress>">
   </primary>
 </objectGrid>
 

Parameters:
objectGridName - retrieve routing table for this ObjectGrid
Returns:
An XML String containing a pre-verified routing table
Since:
WAS XD 6.1.0.5 FIX2

retrieveMapSetName

java.lang.String retrieveMapSetName(java.lang.String gridName,
                                    java.lang.String mapName)
Retrieves the name of the MapSet in which the specified map is defined.

Parameters:
gridName - the name of the ObjectGrid
mapName - the name of the map
Returns:
the name of the MapSet in which the specified map is defined.
Since:
7.0

IBM WebSphere® DataPower® XC10 Appliance
Release 1.0 Client API Specification

© Copyright International Business Machines Corp 2005,2010. All rights reserved.