com.ibm.websphere.objectgrid.management
Interface PlacementServiceMBean

All Superinterfaces:

CoreGroupServiceMBean

public interface PlacementServiceMBean
extends 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

Method Summary

String	balanceShardTypes(String objectGridName, String mapSetName) The placement service will examine the distribution of primaries and replicas for a given mapSet and attempt (if zone rules and other balancing constraints allow) to achieve a consistent primary to replica ratio across the set of containers.
String	balanceStatus(String objectGridName, String mapSetName) Check the balance status (suspended or resumed) for a specified MapSet.
String	collectContainerStatus(String objectGridName, String mapSetName) Retrieves the container status for all containers in the domain.
boolean	enableForPlacement(String containerName) Re-enables container which has been disabled because of the failure of shard placement operations.
String	getCoreGroups() Gets the coregroup status.
TabularData	getDisabledForPlacement() Retrieves TabularData of containers which have been disabled because of the failure of shard placement operations.
boolean	getInitialized() Returns whether this instance of the Placement Service finished initialization.
String	getObjectGridNames() Gets the names of all ObjectGrids and their mapsets in the domain.
String	listCoreGroupMembers(String coreGroupName) List the coregroup members for a given coregroup.
String	listObjectGridPlacement(String objectGridName, String mapSetName) List the placement of shards for each container in the domain.
String	listObjectGridPlacementStatus(String objectGridName, String mapSetName) List the current placement status.
String	listPartition(String objectGridName, String mapSetName, String partitionId) List the partition placement status in the domain.
String	listShards(String objectGridName, String mapSetName, String containerName, int mask) List the shard placement status.
String	listVerifiedRoutingTable(String objectGridName) Deprecated.
String	replaceLostShards(String objectGridName, String mapSetName) Lost shards are placed onto the UNREPAIRED container when autoReplaceLostShards is disabled.
String	resumeBalancing(String objectGridName, String mapSetName) Execute balancing operation at next opportunity and allow execution of future balancing attempts for the map set specified.
List	retrieveAllServersJMXAddresses() Retrieves a List of JMX addresses for all servers that have registered with the placement service.
String	retrieveMapSetName(String gridName, String mapName) Retrieves the name of the MapSet in which the specified map is defined.
List	retrieveServerJMXAddress(String hostName, String serverName) Retrieves a List of JMX address strings for a specific host and server name that has registered with the placement service.
TabularData	retrieveServerJMXAddressesWithInfo(String hostName, String serverName) Retrieves TabularData of JMX address strings for a specific host and server name that has registered with the placement service.
String	suspendBalancing(String objectGridName, String mapSetName) Prevent future balancing attempts for a specific map set.
String	tearDownServers(String[] servers) Each of the container servers that are passed into this method will be stopped.
String	triggerPlacement(String objectGridName, 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, 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

List retrieveServerJMXAddress(String hostName,
                              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.

retrieveServerJMXAddressesWithInfo

TabularData retrieveServerJMXAddressesWithInfo(String hostName,
                                               String serverName)

Retrieves TabularData of JMX address strings for a specific host and server name that has registered with the placement service. Null host or null server names can be used to retrieve several results. Using a null host and null server name will retrieve all of the servers. The TabularData contains CompositeData with the following items, where each CompositeData represents a server:

Item Name	Type	Description
JMXServiceURL	String	JMX Service URL
HostName	String	Host name
ServerName	String	Server Name

Parameters:

hostName - The name of the host for which to retrieve JMX addresses. Use null or an empty string to retrieve JMX addresses for any host.

serverName - The name of the server for which to retrieve JMX addresses. Use null or an empty string to retrieve JMX addresses for any server.

Returns:

the TabularData of all JMX address strings for the specified host and server name.

Since:

8.5

retrieveAllServersJMXAddresses

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

String collectContainerStatus(String objectGridName,
                              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

String listObjectGridPlacement(String objectGridName,
                               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" attribute 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

String listObjectGridPlacementStatus(String objectGridName,
                                     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

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

String listCoreGroupMembers(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

String listPartition(String objectGridName,
                     String mapSetName,
                     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

String listShards(String objectGridName,
                  String mapSetName,
                  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

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

String replaceLostShards(String objectGridName,
                         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

String triggerPlacement(String objectGridName,
                        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

String tearDownServers(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. If the command is successful, the XML will look as follows:

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

If the command is not successful, the string will look as follows (where the exception element is only present if an exception is part of the failure):

 <domain name="<domain>">
   <server name="<server>" tearDownSuccessful="false" reason="<String>">
       <exception type="<String>" message="<String>" stack="<String>"/>
   </server>
 </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

@Deprecated
String listVerifiedRoutingTable(String objectGridName)

Deprecated.

This method is deprecated. The com.ibm.websphere.objectgrid.client.RouteTableValidation utility replaces this method.

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

String retrieveMapSetName(String gridName,
                          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

getInitialized

boolean getInitialized()

Returns whether this instance of the Placement Service finished initialization.

Returns:

true if initialized, false if not initialized.

Since:

8.5

balanceShardTypes

String balanceShardTypes(String objectGridName,
                         String mapSetName)

The placement service will examine the distribution of primaries and replicas for a given mapSet and attempt (if zone rules and other balancing constraints allow) to achieve a consistent primary to replica ratio across the set of containers.

If the number of primaries or the number of replicas do not divide evenly across the containers, some tolerance must be allowed for the ratio to differ from container to container. However, the difference in the number of primaries from one container to the next will not be greater than 1. Similarly, the difference in the number of replicas from one container to the next will not be greater than 1.

Null arguments are not allowed as input to this method.

The results are returned in the following format:

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

If no shards were moved or a problem was encountered attempting to execute this method, no shard elements will appear in the XML output. A detail element will appear instead. The message attribute will have further information.

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

Parameters:

objectGridName - the grid

mapSetName - the map set within the grid

Returns:

An XML String containing the results of the attempt to redistribute shards for better primary/replica balance

Since:

7.1.1

suspendBalancing

String suspendBalancing(String objectGridName,
                        String mapSetName)

Prevent future balancing attempts for a specific map set. Balancing work that is in progress will be allowed to complete.

Other placement activities are allowed to execute while balancing is suspended.

• shard promotion due to container loss
• shard role swap
• shard reservation
• triggerPlacement
• replaceLostShards

Balancing will remain suspended until it is resumed by calling resumeBalancing(String, String).

Null arguments are not allowed as input to this method.

The results are returned in the following format:

 <objectGrid name="<objectgrid>" mapSetName="<mapset>">
   <suspendBalancing currentValue="<currentValue>" previousValue="<previousValue>"/>
 </objectGrid>
 

Additionally, an optional detail element may be contained within the suspendBalancing element. The detail element will include additional data regarding execution of this method. The XML result will be in the following format when a detail element is included:

 <objectGrid name="<objectgrid>" mapSetName="<mapset>">
   <suspendBalancing currentValue="<currentValue>" previousValue="<previousValue>">
     <detail message="<message>" />
   <suspendBalancing/>
 </objectGrid>
 

Parameters:

objectGridName - suspend balancing for the map set specified within this ObjectGrid

mapSetName - suspend balancing for this map set

Returns:

An XML String containing the results of the attempt to suspend balancing

Since:

7.1.0.3

See Also:

resumeBalancing(String, String)

resumeBalancing

String resumeBalancing(String objectGridName,
                       String mapSetName)

Execute balancing operation at next opportunity and allow execution of future balancing attempts for the map set specified. Balancing is executed in reaction to key placement events. Such events include containers starting and containers stopping.

By default, balancing work is executed unless suspendBalancing(String, String) has been called for the map set.

Null arguments are not allowed as input to this method.

The results are returned in the following format:

 <objectGrid name="<objectgrid>" mapSetName="<mapset>">
   <suspendBalancing currentValue="<currentValue>" previousValue="<previousValue>"/>
 </objectGrid>
 

Additionally, an optional detail element may be contained within the suspendBalancing element. The detail element will include additional data regarding execution of this method. The XML result will be in the following format when a detail element is included:

 <objectGrid name="<objectgrid>" mapSetName="<mapset>">
   <suspendBalancing currentValue="<currentValue>" previousValue="<previousValue>">
     <detail message="<message>" />
   <suspendBalancing/>
 </objectGrid>
 

Parameters:

objectGridName - resume balancing for the map set specified within this ObjectGrid

mapSetName - resume balancing for this map set

Returns:

An XML String containing the results of the attempt to resume balancing

Since:

7.1.0.3

See Also:

suspendBalancing(String, String)

balanceStatus

String balanceStatus(String objectGridName,
                     String mapSetName)

Check the balance status (suspended or resumed) for a specified MapSet.

Null arguments are not allowed as input to this method.

The string returned is an XML representation of the balance status. The XML will look as follows:

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

Additionally, an optional detail element may be contained within the balanceStatus element. When balancing has been pre-suspended, the message attribute of the detail element will contain the following message.

 <objectGrid name="<objectgrid>" mapSetName="<mapset>">
   <balanceStatus suspended="true" >
     <detail message="Balancing has been pre-suspended for this mapSet." />
   </balanceStatus>
 </objectGrid> 
  

Parameters:

objectGridName - check balance status for the map set specified within this ObjectGrid

mapSetName - check balance status for this map set

Returns:

An XML String containing the balance status

Since:

7.1.1

See Also:

suspendBalancing(String, String), resumeBalancing(String, String)

enableForPlacement

boolean enableForPlacement(String containerName)

Re-enables container which has been disabled because of the failure of shard placement operations.

Parameters:

containerName - The name of the container to re-enable.

Returns:

If container is removed fromo the penalty box, return true, else if not in the penalty box, return false.

Since:

8.6

getDisabledForPlacement

TabularData getDisabledForPlacement()

Retrieves TabularData of containers which have been disabled because of the failure of shard placement operations. The TabularData contains CompositeData with the following items, where each CompositeData represents a container:

Item Name	Type	Description
Container	String	A container that has been disabled for placement

Returns:

A TabularData of the names of disabled containers.

Since:

8.6