Program guide > (deprecated) Partitioning facility > Partitioning facility programming > Partitioning facility framework programming model

Deprecated feature: The partitioning facility (WPF) feature is deprecated. You can configure partitioning with WebSphere eXtreme Scale.

PartitionManager

PartitionManager

An instance of the PartitionManager can be obtained by the application from JNDI. An instance is bound into JNDI by the runtime. The following code segment shows how the partition stateless session bean (PSSB) can look up an instance and then cache it using an instance variable.

public void setSessionContext(javax.ejb.SessionContext ctx) {
    mySessionCtx = ctx;
    try
    {
        // cache various references.
        InitialContext ic = new InitialContext();
        bookHome = (PartitionManager)ic.lookup(PartitionManager.JNDI_NAME);
    }
    catch(Exception e)
    {
        throw new EJBException(e);
    }
}

See the sample programmers for more example usage.

PartitionManager#JNDI_NAME

The JNDI_NAME attribute can be used by an application to retrieve the PartitionManager service using JNDI.

PartitionManager#createPartitionDefinition

This method has three signatures, and each is used to create a PartitionDefinition instance representing an application partition. This method is overloaded and the appropriate method should be chosen depending on the desired behavior.

The first method signature is:

PartitionDefinition createPartitionDefinition(String partitionName) This is creates a PartitionDefinition with the default classification and cluster scope. The default classification string is the value of the PartitionDefinition#DEFAULT_CLASSIFICATION (_DFLT). This version cannot create a unique classification per partition, specify Node Scoped partitions or provide a map to better manage the partitions.

The second method signature is:

PartitionDefinition createPartitionDefinition(String partitionName,
String partitionClass,
PartitionScope scope)
This creates a PartitionDefinition with the specified partition classification (partitionClass) and a specific partition scope. This version does not provide a map of policy attributes to create the partition definition. Providing a map of extra policy attributes can offer better partition management options.

The method signature is:

PartitionDefinition createPartitionDefinition(String partitionName,
String partitionClass,
PartitionScope scope,
Map attributemap)
This creates a PartitionDefinition with the specified partition classification (partitionClass) and a specific partition scope. In addition, a set of attribute and value pairs can be added to the default list of HA manager group properties for this partition. The extra attributes can be used to control the HA manager policies more specifically. The map attributes are in use during the runtime. Therefore, minimizing the number of attributes and the actual data in use is important.

The first value inserted in the map put() API is the HA manager key, the second will be the HA manager value for that key pair.

An example when using the optional map parameter can be implemented something similar to the following:

public PartitionDefinition[] getPartitions()
{    
 String names = "ABCDEFGHIJKLMNOPQRSTUVWXYZ";
 PartitionDefinition[] rc = new PartitionDefinition[names.length()];
    for(int i = 0; i
< names.length(); ++i)
    {
      Map testMap = new HashMap();
        testMap.put(“custom-attrib", "samplevalue");            
        testMap.put("activateOn", Integer.toString(i%3)); // have 3 servers, 
balance at start
        rc[i] = ivRuntime.createPartitionDefinition(names.substring(i, i + 1),
                                    "MapExamle",
                                    PartitionScope.K_NODE, 
                        testMap);
            testMap = null;

        }
        logger.trace(RASITraceEvent.TYPE_LEVEL1, this, "getPartitions", 
"Returning partitions", rc);
        return rc;
    }

In this case, a map was created that had one HA manager key attribute set to the same value for all partitions (custom-attrib), and a second that is named activateOn and had a string value 0-2. This example was used in conjunction with the policy support to create a policy for each start value and request the preferred server policy be unique for every third partition. See the policy sections for more details on this approach.

createPartitionDefinition() Attribute Constraints

The attributes provided to the createPartitionDefinition() API must comply with the following rules, or during the create operation an HA manager failure exception HAMapException will be thrown and the partition will not be created correctly. Not only do these apply to the key and value pairs of the map attribute, but also the partition name and classification. In this case you provide the values for the partitioning facility (WPF) defaulted key values -pn and -pc respectively.

• The map cannot be null or empty. WPF guarantees against this case as WPF provides default map values which include the partition name, default classification and other attributes documented in the HA manager Policy section, so in general this rule should not be a concern.

• All keys in the map must be Strings.

• All values in the map must be Strings.

• No key is allowed to start with the underbar ('_') character.

• No key or value is allowed to contain the comma (',') character.

• No key or value is allowed to contain the equals ('=') character.

• No key or value is allowed to contain the vertical bar ('|') character.

PartitionManager#getPartitions

This method can be called to get a list of the known partitions for this cluster member. The method signature is:

String[] getPartitions()

PartitionManager#getApplicationName

This method can be called to get the application name determined by the administrator at deploy time. This string can be used in the name of the partition to ensure it is unique within the cluster (the deployed application name must be unique within a WebSphere cluster).

The method signature is:

String getApplicationName() If this is used when creating a partition, we suggest you deploy the partitioned J2EE application with a minimal name in terms of string length, as the name is used throughout the HA manager runtime.

One common use can be to use this to version partition references having the same partitioned J2EE application in the same cluster, simply installed with a different name, and each partition, e.g. PartitionA can instead be called Appv2r2.PartitionA. Thus, in the cluster, the user could have Appv2r1.PartitionA and Appv2r2.PartitionAh active concurrently. The application would simply address their request to the version they are compatible with. This is just one approach to this problem.

PartitionManager#addPartition

This method is called by an application to dynamically add a new partition. The method signature is:

void addPartition(PartitionDefinition name)

If a cluster member adds a partition then it is also asynchronously added to all current cluster members automatically. Using the default cluster scoped policy, the partition will typically be activated on the cluster member receiving the request, although this is not guaranteed behavior. In addition, activating a partition across a cluster is a distributed function, thus, a time delay is reasonable between the time the API returns and the actual activation of the partition occurs. Programmers should account for this.

This API is demonstrated in the WPFKeyBasedPartition example.

PartitionManager#removePartition

This method allows an application to remove a partition dynamically. If the partition is currently active on any cluster member then it is also deactivated. The partition is removed across all online cluster members.

The method signature is:

void removePartition(String name) Deactivating a partition across a cluster is a distributed function, thus, a time delay is reasonable between the time the API returns and the actual deactivation of the partition occurs. Programmers should account for this.

For scenarios where a temporary error is suspect rather than a permanent error, the programmer should consider using the disablePartition() API. In this case, the policy mechanism can be used to determine if the partition should actually not restart, or in fact could be restarted on another cluster member if the opportunity exists.

PartitionManager#disablePartition

This dynamically disables a partition. Calling this method disables the partition on the current cluster members. This can also be accomplished through the wpfadmin command.

The method signature is:

void removePartition(String name) When the method is invoked, the partition will either enter a deactivated state or activate immediately on another cluster member capable of hosting the partition. The partition would be deactivated depending on the current policy settings but by default activated on another cluster member if one is available. If the partition is not automatically reactivated, wpfadmin can be used to enable the member once the administrator can review the logs and determine any action that should be done prior to re-enabling the partition.

The partitionUnloadEvent(...) is not called as the application will call this method and can clean as much as possible prior to the invocation.

PartitionManager#reportPartitionFault

This method is called by the application to indicate a problem with an active partition. This causes the HA manager to react according to the value of the severity parameter. This method is reserved for future use, and not implemented at this time. See disablePartition() to take corrective action.

PartitionManager#reportTransactionComplete

This method is called by an application to report a transaction has just completed with a specific response time for a particular partition. This is normally used when the application is using an asynchronous method for receiving work requests as opposed to synchronous IIOP requests.

The method signature is:

void reportTransactionComplete(String partitionName, long responseTime_ms) This API result is stored and transferred to the WPF Performance Monitoring facility. The WPF Performance Monitoring facility will track the individual results across the entire cluster. This service is discussed in several parts of this document, and examples are also included in the Getting Started section.

This API is demonstrated in the WPFKeyBasedPartitionSample example.

PartitionManager#setHttpPartitionManager

This indicates to WPF that this application uses HTTP Partitioning. See the HTTP Partitioning section of this document. The method signature is:

void setHttpPartitionManager(HttpPartitionManagerInterface manager)

PartitionManager# reportTransactionComplete

WPF PMI contains one statistic, responseTime, which is used to measure the response time of transactions and transaction number executed on behalf of a specific partition. The response time is collected by users applications. User applications update the PMI statistics by calling the reportTransactionComplete method of the com.ibm.websphere.wpf.PartitionManager interface.

Following is the method signature in the PartitionManager interface:

    /**
     * This should be called to inform the runtime when a transaction/operation
     * completes on this partition. This is used for records how many
     * transactions per seconds are being executed per partition.
     * @param partitionName the name of the partition.
     * @param responseTime_ms the response time for the transaction.
     * @throws IllegalStateException If the calling application has no partition 
handler bean
     */    
   void reportTransactionComplete(String partitionName, long responseTime_ms)

You can call PartitionManager.reportTransactionComplete in the partition stateless session bean (PSSB). The best practice is that users calculate the transaction time of a transaction and then use this API to report the transaction time. Here is one example. Method buy is a method to simulate the transaction in the WPFKeyBasedPartition Bean in the WPFKeyBasedPartitionSample application.

/**
     * A buy method. This method does nothing now except report the transaction
     * completion. The transaction takes a random value ranging from 
   0 ms to 1000ms.
     * 
     * @param partitionName
     * @return the partition name
     */
    public String buy(String partitionName) {
    String serverName = AdminServiceFactory.getAdminService().getNodeName()
+"/"+AdminServiceFactory.getAdminService().getProcessName();
    
        ivManager.reportTransactionComplete(partitionName, (long) 
(1000 * Math.random()));

        logger.trace(
            RASITraceEvent.TYPE_LEVEL1,
            this,
            "buy",
            "The method called at " + serverName + "." + partitionName);

        return "partiton=" + partitionName + ",server=" + serverName;
    }

The first time the PartitionManager.reportTransactionComplete is called for a particular partition in one application server, a PMI module is created for this partition grouped by the application name and the session EJB name. For example, if the application name is app1, and the session EJB name is session1, the PMI module is grouped by app1#session1. We will describe this in more detail in the PMI path section.

The responseTime statistics is designed to calculate some statistics facts, for example, average response time, minimum response time, maximum response time, and sum of squares of the response times. Users can access these data by querying the PMI data using wpfadmin command, wsadmin command or MBean.

Parent topic:

Partitioning facility framework programming model

Related concepts

Partitioning facility framework programming model

+

Search Tips   |   Advanced Search