Chapter 4   Cluster Management


This chapter discusses the Java classes used for performing cluster administration tasks. This chapter has the following sections:

• Introduction

• IPMClusterManager

• IPMCluster

• IPMClusterProperty

• PMClusterPropertyFactory

• Code Samples

Note: You can find all the necessary classes in the pm60classes.jar file. If you have installed the Process Manager Builder, you can find this jar file in the directory builder-root\support\sdk. You may also be able to find it on the CD.

Introduction

---

A Process Manager cluster contains the following components:

• a corporate user LDAP directory service

• a configuration LDAP directory service that stores the application definitions

• a relational database for user data

• one or more application servers

• an iPlanet Web Server

• a mail server for notifications

When deploying an application from Process Builder, application developers must identify the cluster on which to deploy it. All applications in a cluster share the same common database and directories. They access the same Directory Server for their process definitions and they use the same set of cross-application tables in the database, as well as the same corporate users and groups directory.

Using the Process Administrator interface, you can interactively modify a cluster.

You can build Java applications that programmatically perform Process Manager cluster administration tasks. Process Manager has one cluster manager bean, IPMClusterManager. For each separate cluster, there is an IPMCluster bean.

You can use the cluster manager bean to perform administrative tasks such as creating, deleting, joining and unjoining clusters. You can also use the cluster manager bean to get handles to individual clusters beans.

You can use the cluster bean to change properties of the cluster, to access and write to cluster logs, and to retrieve information about the cluster such as getting installed applications, getting path information, getting the finder and getting the deployment manager.

Given an individual cluster bean, you can get individual application beans. Given an application bean, you can access any process instance or work item so long as you have the key, such as the process instance ID.

For details of IPMClusterManager and IPMCluster beans see:

• IPMClusterManager

• IPMCluster

In Process Manager 6.0, there is only one cluster, but in future releases there may be multiple clusters.

Clusters have properties. These are represented as IPMClusterProperty objects. Many of the methods for working with clusters take IPMClusterProperty objects as arguments. To create cluster property objects, you use IPMClusterPropertyFactory . For details see:

• IPMClusterProperty

• PMClusterPropertyFactory

At the end of this chapter, there is a coded example of creating a cluster.

• Code Samples

IPMClusterManager

---

The IPMClusterManager bean can be thought as a manager of all the cluster beans in the application server instance. In Process Manager 6.0, there is just one cluster, which is the default cluster. The IPMClusterManager manages the default cluster bean. But in the future, when Process Manager supports multiple clusters, the IPMClusterManager bean will manage all the different clusters for that application server instance.

The following code shows how to access the cluster manager:

// Get the cluster manager IPMClusterManager myClusterManager = null; try {    javax.naming.Context cxt = new javax.naming.InitialContext();    IPMClusterManagerHome clManagerHome = (IPMClusterManagerHome)          cxt.lookup(IPMClusterManager.JNDI_ROOT);     myClusterManager = clManagerHome.create();    } catch( Exception e )    {     System.out.println("Cluster manager creation failed" + e);    }

The IPMClusterManager bean is a stateless session bean that has methods for creating, joining, accessing, unjoining and deleting clusters, and checking LDAP and database connections.

IPMCluster

---

IPMCluster objects represent individual clusters. For operations such as creating, deleting, joining and unjoining clusters, you call methods on the cluster manager class, IPMClusterManager, rather than calling methods on the cluster itself.

To get access to an IPMCluster method, call the getCluster() method on the IPMClusterManager as illustrated in the following code sample:

// Get the cluster manager IPMClusterManager myClusterManager = null; try {    javax.naming.Context cxt = new javax.naming.InitialContext();    IPMClusterManagerHome clManagerHome = (IPMClusterManagerHome)          cxt.lookup(IPMClusterManager.JNDI_ROOT);     myClusterManager = clManagerHome.create();    } catch( Exception e )    {     System.out.println("Cluster manager creation failed" + e);    } // Get the default cluster IPMCluster myCluster = myClusterManager.getCluster(    IPMCluster.DEFAULT);

The IPMCluster bean has methods for changing cluster properties, accessing logs and retrieving information about the cluster.

For details for the IPMCluster bean methods, see the javadocs, which can be found in the support\sdk\docs directory of the Process Manager Builder installation.

IPMClusterProperty

---

The IPMClusterProperty interface is used in various cluster bean APIs. It is used to set and get cluster properties.

When creating an IPMCluster, you first need to create an IPMClusterProperty and then use the setValue() method to set the cluster properties. Table 4-1 lists the cluster properties that must be set when creating a cluster. Table 4-2 lists cluster properties that specify URLs for accessing various Process Manager components.

To create an IPMClusterProperty, use the create() method on IPMClusterPropertyFactory as follows:

IPMClusterProperty prop1 = PMClusterPropertyFactory.create ( ) ;

To get the existing IPMClusterProperty for a cluster, call getClusterProperty() on the cluster, as follows:

IPMClusterProperty myProp = myCluster.getClusterProperty();

Table 4-1    Cluster properties

All properties are public static int
Cluster and configuration properties
CLUSTER_DN	the distinguished name (DN) of the cluster entry
CONFIGURATION_DIRECTORY_SERVER	the host name where the configuration directory resides
CONFIGURATION_DIRECTORY_PORT	the port number for the configuration directory
CONFIGURATION_DIRECTORY_BIND_ DN	the Bind DN of the configuration directory
CONFIGURATION_DIRECTORY_BIND_ DN_ PASSWORD	the Bind DN password of the configuration directory
Corporate directory properties
CORPORATE_DIRECTORY_SERVER	the host name where the corporate directory resides
CORPORATE_DIRECTORY_PORT	the corporate directory port number
CORPORATE_DIRECTORY_BASE	the corporate directory base, for example: ou=People, o=mcom.com
CORPORATE_DIRECTORY_BIND_DN	the corporate directory BIND DN, for example: cn=Directory Manager This property is optional when creating a cluster.
CORPORATE_DIRECTORY_BIND_DN_ PASSWORD	the corporate directory BIND DN Password. This property is optional when creating a cluster.
Database properties
DATABASE_TYPE	the Database Type. The value can be: IPMClusterProperty.ORACLE IPMClusterProperty.SYBASE
DATABASE_IDENTIFIER	the database identifier
DATABASE_NAME	the database name (optional if the database type is ORACLE)
DATABASE_USER_NAME	the database user name
DATABASE_PASSWORD	the database password
General properties
DESCRIPTION	the description of the cluster
PRETTY_NAME	the pretty name of the cluster that appears in the Builder. This property is optional when creating a cluster.
SMTP_SERVER	the SMTP server host name. This property is optional when creating a cluster.
SMTP_PORT	the SMTP port number . This property is optional when creating a cluster.
SMTP_REPLY_TO	the SMTP reply to. This property is optional when creating a cluster.

Table 4-2    URL Properties

All properties are public static int
DEPLOY_URL	The URL where Process Manager applications are deployed.
EXPRESS_URL	The URL for the Process Manager Express
ADMINISTRATOR_URL	The URL for the Process Administration interface
BUSINESS_URL	The URL for the Process Business Manager's interface
APPLICATION_URL

Table 4-3    Event Properties

All properties are public static int
EVENT_USER	The cluster uses the EVENT_USER ID when it makes asynchronous requests into the Process Manager Engine, such as when the timer agent checks for expired work items. This user and password combination should be a valid combination inside the corporate directory.
EVENT_USER_PASSWORD	Password for the EVENT_USER.

Other pre-defined variables are listed in Table 4-4.

Table 4-4    Other static int variables

ORACLE SYBASE	These are used as the values of the DATABASE_TYPE variable.
LOG_INFORMATION LOG_SECURITY LOG_ERROR	These are used as an argument to the getLog() method on IPMCluster to specify what kind of log to retrieve.

Getting and Setting Property Values

To retrieve or set properties, use the methods:

• getValue

• setValue

• getProperties

For on the property value settings, see the javadocs, which can be found in the support\sdk\docs directory of the Process Manager Builder installation.

PMClusterPropertyFactory

---

The purpose of this class is to create new IPMClusterProperty objects, which contain the properties for a cluster.

// Create a PMClusterProperty object IPMClusterProperty prop1 = PMClusterPropertyFactory.create ( ) ;

IPMClusterProperty prop = PMClusterPropertyFactory.create ( ); // Set the various properties of the interface .... .... ... // look up in JNDI name space to get a handle on the // IPMClusterManager bean interface ... .... // maybe, then create a cluster IPMClusterManager.createCluster ( prop ) ;

Code Samples

---

This section presents the following code samples:

• Mount the Cluster Manager and Get the Default Cluster

• Create a Cluster

• Get and Set Cluster Properties

Mount the Cluster Manager and Get the Default Cluster

This code sample gets the cluster manager and the default cluster.

// Get the cluster manager IPMClusterManager myClusterManager = null; try {    javax.naming.Context cxt = new javax.naming.InitialContext();    IPMClusterManagerHome clManagerHome = (IPMClusterManagerHome)          cxt.lookup(IPMClusterManager.JNDI_ROOT);     myClusterManager = clManagerHome.create();    } catch( Exception e )    {     System.out.println("Cluster manager creation failed" + e);    } // Get the default cluster IPMCluster myCluster = myClusterManager.getCluster(    IPMCluster.DEFAULT);

Create a Cluster

This code sample creates a new cluster, which overwrites the existing one in Process Manager 6.0, since only one cluster is supported at a time.

// Create a PMClusterProperty object IPMClusterProperty prop1 = PMClusterPropertyFactory.create ( ) ; // Populate the properties in the PMClusterProperty object prop1.setValue(IPMClusterProperty.CONFIGURATION_DIRECTORY_SERVER , "westminster"); prop1.setValue(IPMClusterProperty.CONFIGURATION_DIRECTORY_PORT, "4141"); // Continue setting properties ... // Now create the cluster IPMCluster cluster1 = myClusterManager.createCluster( prop1 );

Get and Set Cluster Properties

This code sample gets and sets cluster properties.

// myCluster is the default cluster // Get some properties IPMClusterProperty myProp = myCluster.getClusterProperty(); String description = myProp.getValue(IPMClusterProperty.DESCRIPTION); // Change some property values IPMClusterProperty myProp = myCluster.getClusterProperty(); myProp.setValue(IPMClusterProperty.DESCRIPTION,    "New cluster description"); myProp.setValue(IPMClusterProperty.SMTP_REPLY_TO ,    "pmadministrator@netscape.com"); // Save the changes to the cluster myProp.changeCluster(myprop);