Overview  Package   Class  Tree  Deprecated  Index  Help 
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES
SUMMARY:  INNER | FIELD | CONSTR | METHOD DETAIL:  FIELD | CONSTR | METHOD

com.netscape.pm.model
Interface IPMApplication

All Superinterfaces:
javax.ejb.EJBObject, java.rmi.Remote
public interface IPMApplication
extends javax.ejb.EJBObject, java.rmi.Remote

Provides an access point for updatable process instances and work items. The methods off the application bean allow the user to initiate and edit process instances associated with the application. Additionally, this interface also provides methods to retrieve the application's definition and deployment parameters.

Process instances and work items may be retrieved via the IFinder interface, however only for read-only. The application bean interface is the only means of retrieving a process instance for update. 

 javax.naming.Context cxt = new javax.naming.InitialContext();
 String jndiName = "java:comp/env/" + IPMClusterManager.JNDI_ROOT;
 IPMClusterManagerHome home = (IPMClusterManagerHome) cxt.lookup( jndiName );
 IPMClusterManager clusterManager = home.create();
 IPMCluster cluster = clusterManager.getCluster( IPMCluster.DEFAULT );
 IPMApplication app = cluster.getApplication( "myApp" );

 IProcessDefinition pd = app.getProcessDefinition();
 INodeElement entryNode = pd.getProcessMap()
                            .getNodeElement( "EntryPoint1" );
 ITransition conclusion = entryNode.getTransition( "Action1" );

 IWorkItem wi = app.initiateProcessInstance( entryNode );
 IProcessInstance pi = wi.getProcessInstance();

 IPMRequest req = PMRequestFactory.create( httpServletRequest );
 IFormElement entryForm = pd.getFormDictionary()
                            .getFormElement( "EntryForm" );
 for( Enumeration e = entryForm.editables(); e.hasMoreElements(); )
 {
     IPresentationElement ipe = (IPresentationElement) e.nextElement();
     ipe.update( pi, req );
 }

 wi.setConclusion( conclusion );
 app.execute( wi );
 wi.release( true );

See Also:
IPMCluster, IPMApplicationHome, IProcessDefinition, IProcessInstance, IProcessInstancePK, IWorkItem, IWorkItemPK, EJBObject, Remote

Field Summary
static java.lang.String DEFAULT_JNDI_ROOT
          The application bean prefix to use when constructing the JNDI name to use for looking up the application bean home.
static int LOG_ERROR
          Log type value for an error log message.
static int LOG_INFORMATION
          Log type value for an informational log message.
static int LOG_SECURITY
          Log type value for an security log message.
 
Method Summary
 java.util.Enumeration execute(IWorkItem wi)
          Executes a series of actions required for the specified workitem.
 boolean existsImage()
          Returns true if the application has been deployed with a copy of its process map image.
 IProcessInstance findProcessInstance(IProcessInstancePK pk)
          Returns the process instance matching the given key parameters.
 IWorkItem findWorkItem(IWorkItemPK pk)
          Returns the work item matching the given key parameters.
 IPMCluster getCluster()
          Returns the cluster bean associated with this application.
 java.lang.String getClusterName()
          Returns the name of the cluster to which this application belongs to.
 java.sql.Connection getConnection()
          Returns a connection to the Process Manager database.
 IDeploymentDescriptor getDeploymentDescriptor()
          Returns the deployment descriptor associated with this application.
 java.lang.String getHomePath()
          Returns the absolute path name for the application's installation directory.
 java.lang.String getImageFileName()
          Returns the name of the application's process map image file.
 java.util.Vector getLog(int logType, int size)
          Returns the contents of an application log file.
 java.lang.String getPageDataModel()
          Returns a string (in the format of a JavaScript hashtable definition) of the properties of the application.
 IProcessDefinition getProcessDefinition()
          Returns the process definition associated with this application.
 IWorkItem initiateProcessInstance(INodeElement entryNode)
          Initiates a new process instance at a particular entry point node.
 void log(java.lang.Exception e)
          Logs an exception to the error log of the application.
 void log(int logType, java.lang.String msg, java.util.Hashtable context)
          Logs a message to an application log file.
 java.util.Enumeration moveTo(IWorkItem wi, INodeElement targetNode)
          Moves the work item to the specified node.
 
Methods inherited from interface javax.ejb.EJBObject
getEJBHome, getHandle, getPrimaryKey, isIdentical, remove
 

Field Detail

DEFAULT_JNDI_ROOT

public static final java.lang.String DEFAULT_JNDI_ROOT
The application bean prefix to use when constructing the JNDI name to use for looking up the application bean home. 

 // The localName is the name of the application, "myApp" for instance.
 //
 javax.naming.Context cxt = new javax.naming.InitialContext();
 String jndiName = "java:comp/env/" + IPMApplication.DEFAULT_JNDI_ROOT
                 + "/" + localName;
 IPMApplicationHome home = (IPMApplicationHome) cxt.lookup( jndiName );
 IPMApplication app = home.create();
Since:
PAE 4.0

LOG_INFORMATION

public static final int LOG_INFORMATION
Log type value for an informational log message. Log messages of this type are written out to the application information log.
See Also:
log( int, String, Hashtable )
Since:
PM 6.0

LOG_ERROR

public static final int LOG_ERROR
Log type value for an error log message. Log messages of this type are written out to the application error log.
See Also:
log( int, String, Hashtable )
Since:
PM 6.0

LOG_SECURITY

public static final int LOG_SECURITY
Log type value for an security log message. Log messages of this type are written out to the application security log.
See Also:
log( int, String, Hashtable )
Since:
PM 6.0
Method Detail

findWorkItem

public IWorkItem findWorkItem(IWorkItemPK pk)
                       throws PMException,
                              java.rmi.RemoteException
Returns the work item matching the given key parameters. The work item can be fetched either for update or read-only, depending on the editable state of the primary key. Not all users may fetch the work item for update, however; access to the work item is governed by the following rules:

assigneeadmin?
for update OK OK NO
view only OK OK OK

If the current principal is neither the assignee nor an administrator (as specified by the cluster) then the only permitted access is read-only.

Parameters:
pk - a work item primary key
Returns:
an IWorkItem object
Throws:
PMException - if the work item cannot be found or there is a problem loading the work item from the back-end database.
java.rmi.RemoteException - if there is an RMI-related problem.
Since:
PAE 4.0
See Also:
IWorkItem, IWorkItemPK.setEditable(boolean)

findProcessInstance

public IProcessInstance findProcessInstance(IProcessInstancePK pk)
                                     throws PMException,
                                            java.rmi.RemoteException
Returns the process instance matching the given key parameters. The process instance can be fetched either for update or read-only, depending on the editable state of the primary key. Not all users may fetch the process instance for update, however; access to the process instance is governed by the following rules:

admin?
for update OK NO
view only OK OK

If the current principal is not an administrator (as specified by the cluster) then the only permitted access is read-only. If the user wants to edit the process instance, a handle must be retrieved via the getProcessInstance method from the work item.

Parameters:
pk - a process instance primary key
Returns:
an IProcessInstance object
Throws:
PMException - if the process instance cannot be found or there is a problem loading the process instance from the back-end database.
java.rmi.RemoteException - if there is an RMI-related problem.
Since:
PAE 4.0
See Also:
IProcessInstance, IProcessInstancePK

initiateProcessInstance

public IWorkItem initiateProcessInstance(INodeElement entryNode)
                                  throws PMException,
                                         java.rmi.RemoteException
Initiates a new process instance at a particular entry point node. Not all users may initiate a process instance for update, however; access will be granted iff the user has access to the specified entry node, based upon the form/role resolution specified from the builder's access control manager.
Parameters:
en - an entry point node
Returns:
an IWorkItem object positioned at the entry point node.
Throws:
PMException - if the process instance cannot be initiated at the given entry point node.
java.rmi.RemoteException - if there is an RMI-related problem.
Since:
PAE 4.0
See Also:
INodeElement, IWorkItem

execute

public java.util.Enumeration execute(IWorkItem wi)
                              throws PMException,
                                     java.rmi.RemoteException
Executes a series of actions required for the specified workitem. This method is a only means of asking the Process Manager engine to complete a work item and advance the process instance to a new set of work items. If the intention of the user is only to save a work item and not to advance it to the next node, the save method should be called on the work item object.

This method will return an enumeration of IWorkItemPKs for the next set of work items generated as a result of completing the given work item.

Note: users must call the release method on the work item object, not only to release any resources obtained throughout the servicing of the request but also to trigger the routing of any new work items created as a result of this call. 

 for( Enumeration nextWIs = app.execute( wi );
      nextWIs.hasMoreElements(); )
 {
     IWorkItemPK pk = (IWorkItemPK) nextWIs.nextElement();
     System.out.println( "Next workitem in line : " + pk );
 }
Parameters:
wi - the current work item
Returns:
a java.util.Enumeration of IWorkItemPK objects.
Throws:
PMException - if there is problem executing the work item during any execution stage.
java.rmi.RemoteException - if there is an RMI-related problem.
Since:
PM 6.0
See Also:
INodeElement.EXECUTION_STAGE_MANAGE, INodeElement.EXECUTION_STAGE_PERFORM, INodeElement.EXECUTION_STAGE_VERIFY, INodeElement.EXECUTION_STAGE_COMPLETE, IWorkItem

moveTo

public java.util.Enumeration moveTo(IWorkItem wi,
                                    INodeElement targetNode)
                             throws PMException,
                                    java.rmi.RemoteException
Moves the work item to the specified node. The work item can only be moved to a node that is connected to the node the work item is currently positioned at; that is, there must be a transition (either real or virtual) between the current node and the target node.

Additionally, if the work item is positioned at an exception node, the work item cannot be move to any other node. It is possible to move the work item to the same node it is currently positioned at however.

This method will return an enumeration of IWorkItemPKs for the next set of work items generated as a result of moving the given work item to the specified node.

Parameters:
wi - the current work item
targetNode - the node to move the work item to
Returns:
a java.util.Enumeration of IWorkItemPK objects.
Throws:
PMException - if the work item cannot be moved to the specified node.
java.rmi.RemoteException - if there is an RMI-related problem.
Since:
PM 6.0
See Also:
INodeElement, IWorkItem

getPageDataModel

public java.lang.String getPageDataModel()
                                  throws PMException,
                                         java.rmi.RemoteException
Returns a string (in the format of a JavaScript hashtable definition) of the properties of the application. This method is used by the engine's event handler UI to output a client-side description of the application. Users will probably not find this method of much use, and should just ignore it.
Returns:
a string containing the properties of the application.
Throws:
PMException - if there is a problem initializing the application.
java.rmi.RemoteException - if there is an RMI-related problem.
Since:
PAE 4.0

getConnection

public java.sql.Connection getConnection()
                                  throws PMException,
                                         java.rmi.RemoteException
Returns a connection to the Process Manager database. The connection is made using the username/password information given when deploying the application via the builder. Users should use this method sparingly - this method may be deprecated in future releases.
Returns:
a connection to the Process Manager database.
Throws:
PMException - if there is a problem initializing the application.
java.rmi.RemoteException - if there is an RMI-related problem.
Since:
PAE 4.0
See Also:
Connection

getProcessDefinition

public IProcessDefinition getProcessDefinition()
                                        throws PMException,
                                               java.rmi.RemoteException
Returns the process definition associated with this application.
Returns:
the process definition for the application.
Throws:
PMException - if there is a problem initializing the application.
java.rmi.RemoteException - if there is an RMI-related problem.
Since:
PAE 4.0
See Also:
IProcessDefinition

getCluster

public IPMCluster getCluster()
                      throws PMException,
                             java.rmi.RemoteException
Returns the cluster bean associated with this application.
Returns:
the cluster bean associated with this application bean.
Throws:
PMException - if there is a problem initializing the application.
java.rmi.RemoteException - if there is an RMI-related problem.
Since:
PAE 4.0
See Also:
IPMCluster

getClusterName

public java.lang.String getClusterName()
                                throws PMException,
                                       java.rmi.RemoteException
Returns the name of the cluster to which this application belongs to.
Returns:
the cluster name associated with this application bean.
Throws:
PMException - if there is a problem initializing the application.
java.rmi.RemoteException - if there is an RMI-related problem.
Since:
iPM 6.5
See Also:
IPMCluster

getDeploymentDescriptor

public IDeploymentDescriptor getDeploymentDescriptor()
                                              throws PMException,
                                                     java.rmi.RemoteException
Returns the deployment descriptor associated with this application. The deployment descriptor contains the deployment parameters for the application, such as its state and mode.
Returns:
the deployment descriptor associated with this application.
Throws:
PMException - if there is a problem initializing the application.
java.rmi.RemoteException - if there is an RMI-related problem.
Since:
PAE 4.0
See Also:
IPMCluster, IDeploymentDescriptor

getHomePath

public java.lang.String getHomePath()
                             throws java.rmi.RemoteException,
                                    PMException
Returns the absolute path name for the application's installation directory. The path points to the exact location of the deployed application as it exists on the server machine. For example, on an NT machine, if the Process Manager product has been installed on D:\netscape\server4\bpm, the application path for the application ClaimProcess would be D:\netscape\server4\bpm\applications\ClaimProcess.
Returns:
the absolute path name for the application
Throws:
PMException - if there is a problem initializing the application.
java.rmi.RemoteException - if there is an RMI-related problem.
Since:
PAE 4.0

log

public void log(java.lang.Exception e)
         throws PMException,
                java.rmi.RemoteException
Logs an exception to the error log of the application. This method will differ in its behavior depending on the type of exception being passed in:
Parameters:
e - a java.lang.Exception to log
Throws:
PMException - if there is a problem writing to the application log file.
java.rmi.RemoteException - if there is an RMI-related problem.
Since:
PAE 4.0
See Also:
#log( String, String, Hashtable )

log

public void log(int logType,
                java.lang.String msg,
                java.util.Hashtable context)
         throws PMException,
                java.rmi.RemoteException
Logs a message to an application log file. There are three types of log messages that can be logged:

The msg parameter specifies the message to be written to the log; the context is an optional object containing key/value pairs of additional contextual information associated with the log message that may be of use when viewing the entry.

The resulting log entry, when viewed from the Administrator UI, will resemble: 

 [Fri Oct 22 20:00:31 CDT 1999] PAGE_COUNT_TOO_LONG
 ------------ author : Ima Writer 
 ------------ docName :  PM Programmer's Guide 
 ------------ pageCount :  7450
Parameters:
logType - the type of the log message, can be one of:
  • LOG_INFORMATION
  • LOG_ERROR
  • LOG_SECURITY
msg - the message to be written to the log
context - contains additional contextual info
Throws:
PMException - if there is a problem writing to the application log file.
java.rmi.RemoteException - if there is an RMI-related problem.
Since:
PAE 4.0
See Also:
LOG_INFORMATION, LOG_ERROR, LOG_SECURITY, log( java.lang.Exception )

getLog

public java.util.Vector getLog(int logType,
                               int size)
                        throws PMException,
                               java.rmi.RemoteException
Returns the contents of an application log file. The entries in the log file are returned as elements of a java.util.Vector. Each entry will consist of an HTML formatted log entry. The total number of entries to return can be customized by using the size parameter.

The returned list will contain log entries in ascending chronological order, that is the most recent log entries will be found at the end of the java.util.Vector.

Parameters:
logType - the type of the log file to retrieve, can be one of:
  • LOG_INFORMATION
  • LOG_ERROR
  • LOG_SECURITY
size - the maximum number of entries to return
Returns:
the contents of a particular application log file.
Throws:
PMException - if there is a problem reading the application log file.
java.rmi.RemoteException - if there is an RMI-related problem.
Since:
PAE 4.0
See Also:
LOG_INFORMATION, LOG_ERROR, LOG_SECURITY, log( java.lang.Exception ), #log( String, String, java.util.Hashtable )

existsImage

public boolean existsImage()
                    throws PMException,
                           java.rmi.RemoteException
Returns true if the application has been deployed with a copy of its process map image. This image can be generated from the Process Manager builder by exporting the process map to a particular image format. If the application is then deployed, a copy of the exported process map image will be copied over to the application's installation on the server.
Returns:
true if the application has been deployed with a copy of its process map image; false otherwise.
Throws:
PMException - if there is a problem initializing the application.
java.rmi.RemoteException - if there is an RMI-related problem.
Since:
PAE 4.0

getImageFileName

public java.lang.String getImageFileName()
                                  throws PMException,
                                         java.rmi.RemoteException
Returns the name of the application's process map image file. If no process map image can be found, an exception is thrown.
Returns:
the name of the application's process map image file.
Throws:
PMException - if there is a problem initializing the application, or if there is no process map image found.
java.rmi.RemoteException - if there is an RMI-related problem.
Since:
PAE 4.0
Overview  Package   Class  Tree  Deprecated  Index  Help 
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES
SUMMARY:  INNER | FIELD | CONSTR | METHOD DETAIL:  FIELD | CONSTR | METHOD