Chapter 3
Cluster Management
This chapter discusses the Java classes used for performing cluster administration tasks. This chapter has the following sections:
Note: You can find all the necessary classes in the pm60classes.jar file in the api directory on the Process Manager 6.0 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 Enterprise 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:
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:
At the end of this chapter, there is a coded example of creating a cluster.
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 the following methods:
createCluster
This method creates a cluster. Use the IPMClusterProperty class to create the cluster properties needed when creating a new cluster.
Syntax.
IPMCluster createCluster (IPMClusterProperty prop)
throws PMException
Parameters.
|
|
This parameter is an IPMClusterProperty object that contains all the properties required to create the cluster. Use the IPMClusterPropertyFactory.create() method to create this. See Table 3-1 for a list of the optional and required properties for a cluster.
If any of the required properties for the cluster are not set when this method is called, this method throws a PMException.
|
Description.
This method does the following:
Process Manager 6.0 supports only one cluster at a time. If you create a new cluster when a cluster exists already, the new cluster overwrites the existing cluster.
Returns .
The interface to the cluster bean.
Example.
The following example creates a new cluster called cluster1 that overwrites the existing cluster.
|
// 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 );
|
|
getCluster
Syntax.
IPMCluster getCluster (String name) throws PMException
Parameters.
|
|
This is the JNDI name of the cluster bean that is being looked up.
|
Example.
The following example gets the default cluster:
|
// Get the default cluster
IPMCluster myCluster = myClusterManager.getCluster(
IPMCluster.DEFAULT);
|
|
joinCluster
Joins a new cluster to the original cluster.
Syntax.
IPMCluster joinCluster ( IPMCluster cluster )
Parameters.
|
|
This is the cluster to join. Use the getCluster method to get the cluster.
|
Description.
This method performs the following tasks:
creates a deployment descriptor for a new cluster bean
registers a cluster bean with the new deployment descriptor
joins the cluster to the original cluster
Example.
unjoinCluster
Unjoins a cluster bean from the Process Manager cluster that it currently belongs to.
Syntax.
void unjoinCluster ( IPMCluster cluster)
Parameters.
|
|
This is the cluster to unjoin. Use the getCluster method to get the cluster.
|
Description.
unjoins the cluster bean and unregisters the cluster bean from the JNDI name space.
deleteCluster
Deletes a cluster.
Syntax.
void deleteCluster ( IPMCluster cluster, boolean bDeleteTable )
Parameters.
|
|
This is the cluster to delete. Use the getCluster method to get the cluster.
|
|
|
If this parameter is set to true then the backend database tables are deleted otherwise not
|
Description.
deletes the cluster bean and unregisters it from the JNDI name space. If bDeleteTable is true, the backend database tables are deleted otherwise not.
checkLDAPConnection
Checks whether a user can connect to the configuration or corporate directory at the given host name and port number.
Syntax.
void checkLDAPConnection (String hostName, String portNumber,
String userName, String password )
throws LDAPException
Parameters.
|
|
hostName of the LDAP server
|
|
|
port number of the LDAP server
|
|
|
name of the user who is accessing the configuration or corporate directory
|
|
|
password of the user
|
Description.
Checks whether the cluster bean can connect to the configuration or corporate directory. The userName and password can be empty strings for the corporate directory connection (for anonymous lookups).
checkLDAPEntry
Checks whether a given LDAP entry can be read.
Syntax.
void checkLDAPEntry ( String entry, String hostName,
String portNumber, String userName, String password )
throws LDAPException
Parameters.
|
|
A string of the LDAP entry to be checked, for example "cn=myCluster, o=NetscapeRoot"
|
|
|
hostName of the LDAP server
|
|
|
port number of the LDAP server
|
|
|
name of the user who is accessing the configuration or corporate directory
|
|
|
password of the user
|
Description .
Checks whether the LDAP entry can be read.This method is typically used to verify whether the corporate directory base entry can be read.
checkDBConnection
Checks whether the given user can connect to the database with the given password.
Syntax.
void checkDBConnection ( String dbServerType, String dbServerName,
String dbServerIdentifier, String userName, String password )
throws SQLException
Parameters.
|
|
The type of database server. The valid values are:
|
|
|
The name of the database server. This an be an empty string if the database is ORACLE.
|
|
|
The database identifier.
|
|
|
The name of the user who is accessing the database.
|
|
|
The user's password.
|
Description.
checks whether the given user can connect to the database with the given password.
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 the following methods for changing cluster properties, accessing logs and retrieving information about the cluster:
getClusterProperty
Gets the properties of the cluster as an IPMClusterProperty object.
Syntax.
IPMClusterProperty getClusterProperty( ) throws PMException
Description.
Returns an IPMClusterProperty interface that contains all the properties of the cluster.
You can call the getValue() method on the returned IPMClusterProperty object to get a particular property, specifying one of the static ints described in Table 3-1 to identify the property.
Example.
|
// myCluster is an IPMCluster
// Get some properties
IPMClusterProperty myProp = myCluster.getClusterProperty();
String description =
myProp.getValue(IPMClusterProperty.DESCRIPTION);
|
|
changeCluster
This method changes the properties of a cluster.
Syntax.
void changeCluster ( IPMClusterProperty prop) throws PMException
Parameters.
|
|
The IPMClusterProperty object that contains the properties for the cluster.
|
Description.
This method changes the properties of the cluster.
To change the properties of a cluster, first get an IPMClusterProperty either by:
To change the properties of an IPMClusterProperty object, use its setValue() method. When you have finished setting properties on the IPMClusterProperty object, call changeCluster() on the IPMCluster object, specifying the IPMClusterProperty object that contains the changes.
Example.
|
// myCluster is the default cluster
// Change some property values
IPMClusterProperty myProp = myCluster.getClusterProperty();
myProp.setValue(IPMClusterProperty.DESCRIPTION,
"New cluster description");
myProp.setValue(IPMClusterProperty.SMTP_REPLY_TO ,
"pmadministrator@netscape.com");
// Change the cluster property object
myProp.changeCluster(myProp);
|
|
log
Logs exceptions to a cluster log.
Syntax.
void Log ( Exception e )
Parameters.
|
|
An exception to be logged. This can be any arbitrary exception including PMExceptions.
|
Description.
The log() method logs exceptions to the cluster log. The cluster maintains three different kinds of logs - error, information, and security.
This method takes any arbitrary exception including PMExceptions. If the exception is a PMException, this method introspects the exception object to determine what type ( error, information, or security) of an exception it is and logs the exception accordingly into the appropriate files.
If the exception is an ordinary Java exception, the exception is logged in the error file.
getLog
Accesses the logs.
Syntax.
public Vector getLog( int logType, int size ) throws PMException
Parameters.
|
|
Indicates the type of log to access. The value can be:
IPMClusterProperty.LOG_INFORMATION
IPMClusterProperty.LOG_ERROR
IPMClusterProperty.LOG_SECURITY
|
|
|
The number of entries you want to see in the log. To see the entire log specify IPMClusterProperty.MAX_LOG_SIZE.
|
Description.
This method accesses the logs and returns a vector of log objects. Each log object is essentially a single timestamped log entry. So if a particular log contains 1000 timestamped entries, the vector contains 1000 entries. The log entries are given in reverse chronological order.
getInstalledApplications
Returns a vector of the names of applications that are installed in the cluster currently.
Syntax.
Vector getInstalledApplications ( ) throws PMException
Description.
This returns a vector of the names of applications that are installed in the cluster currently. Given a vector of currently installed application names you could use the names to look up an application bean in the JNDI name space.
getVersion
returns the version of the cluster
Syntax.
String getVersion( ) throws RemoteException, PMException
isDefined
returns true if the cluster is defined or false if the cluster is not defined.
Syntax.
boolean isDefined( ) throws RemoteException, PMException
Description.
In Process Manager 6.0, the installer registers an empty bean as the default cluster bean. When you create a cluster (either interactively through the Administrator interface or programmatically by calling createCluster() on the cluster manager), this bean is filled with the relevant information for the cluster. Until then, the bean is empty - just a place holder. The isDefined() method determines if the cluster has been created or not.
Before calling methods onthe default cluster you can use isDefined() to test if it has been created. If it has not been created, you cannot call methods on it (that is, you get an exception if you try to call methods on it).
Example.
if (isDefined(IPMCluster.DEFAULT) )
{ // call methods on the default cluster bean }
getApplicationsPath
returns the full path of the Process Manager applications directory.
Syntax.
String getApplicationsPath( ) throws RemoteException, PMException
returns the full path of the Process Manager applications directory. It is typically $PM_HOME/applications.
getCorporateDirectory
returns the corporate directory object for the cluster.
Syntax.
CorporateDirectory getCorporateDirectory( ) throws PMException,
RemoteException
getFinder
returns the Finder object of the cluster.
Syntax.
IFinder getFinder( ) throws RemoteException, PMException
Description.
Returns the Finder object for a cluster. Given the Finder object, you can find work items and process instances in the cluster.
getDeploymentManager
returns the DeploymentManager object for the cluster.
Syntax.
IDeploymentManager getDeploymentManager( ) throws PMException,
RemoteException
Description.
Returns the Deployment Manager object for a cluster. Given the deployment manager, you can access the deployment descriptor for individual applications. Given a deployment descriptor, you can change the application's stage, status, mode and testing state. For details of the deployment manager, see Chapter 4 "Deployment Manager."
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 3-1 lists the cluster properties that must be set when creating a cluster. Table 3-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 3-1 Cluster properties
|
All properties are public static int
|
|
Cluster and configuration properties
|
|
|
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
|
|
|
the corporate directory port number
|
|
|
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
|
|
|
|
the Database Type. The value can be:
IPMClusterProperty.ORACLE
IPMClusterProperty.SYBASE
|
|
|
the database identifier
|
|
|
the database name (optional if the database type is ORACLE)
|
|
|
the database user name
|
|
|
the database password
|
|
General properties
|
|
|
|
the description of the cluster
|
|
|
the pretty name of the cluster that appears in the Builder.
This property is optional when creating a cluster.
|
|
|
the SMTP server host name.
This property is optional when creating a cluster.
|
|
|
the SMTP port number .
This property is optional when creating a cluster.
|
|
|
the SMTP reply to.
This property is optional when creating a cluster.
|
Table 3-2 URL Properties
|
All properties are public static int
|
|
|
The URL where Process Manager applications are deployed
|
|
|
The URL for the Process Manager Express
|
|
|
The URL for the Process Administration interface
|
|
|
The URL for the Process Administration interface
|
|
|
|
Other pre-defined variables are listed in Table 3-3.
Table 3-3 Other static int variables
|
|
|
|
|
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 following methods:
getValue
Gets the value of a particular property.
Syntax:.
String getValue ( int propName)
Parameters.
|
|
The property whose value is to be retrieved. The value must be one of the static variables listed in Table 3-1. For example:
IPMClusterProperty.DATABASE_USER_NAME
|
Example.
|
// myCluster is the default cluster
IPMClusterProperty myProp = myCluster.getClusterProperty();
String description =
myProp.getValue(IPMClusterProperty.DESCRIPTION);
|
|
setValue
Sets the value of a particular property.
Syntax.
void setValue ( int propName, String value)
Parameters.
|
|
The property to be set. The value must be one of the static variables listed in Table 3-1. For example:
IPMClusterProperty.DATABASE_USER_NAME
|
|
|
The value for the property.
|
Example.
|
// Create a PMClusterProperty object
IPMClusterProperty prop1 = PMClusterPropertyFactory.create ( ) ;
// Populate the properties in the PMClusterProperty object
prop1.setValue(IPMClusterProperty.CORPORATE_DIRECTORY_SERVER,
"westminster");
prop1.setValue(IPMClusterProperty.CORPORATE_DIRECTORY_PORT,
"4141");
|
|
getProperties
Returns a hashtable of all properties and their corresponding values. Clients can iterate through the properties and their corresponding values. The hashtable is indexed by property name.
Syntax.
Hashtable getProperties ( )
Example.
|
// Populate the properties in the PMClusterProperty object
Hashtable allprops = prop1.getProperties();
|
|
PMClusterPropertyFactory
The purpose of this class is to create new IPMClusterProperty objects, which contain the properties for a cluster.
create
Creates an IPMClusterProperty object.
Syntax.
IPMClusterProperty create();
Example.
|
// 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
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);
|
|