bea.com | products | dev2dev | support | askBEA

Download Docs | Site Map | Glossary
Search

Programming BPM Client Apps

Connecting to the Process Engine

This section explains how a to connect to the WebLogic Integration process engine and access the features of the business process management (BPM) framework. It includes the following topics:

- Accessing the API Session EJBs

- Using the Convenience Methods to Access EJBs

Accessing the API Session EJBs

As with any EJB, you must access the BPM API session EJBs using the home and remote interfaces. The following table lists the home and remote interfaces available for this purpose.

Table 3-1 API Session EJB Home and Remote Interfaces

EJB Name | Home Interface | Remote Interface
--- | --- | ---
com.bea.wlpi.server.admin.Admin | AdminHome | Admin
com.bea.wlpi.server.audit.Audit | AuditHome | Audit
com.bea.wlpi.server.catalog.EJBCatalog | EJBCatalogHome | EJBCatalog
com.bea.wlpi.server.permission. Permission | PermissionHome | Permission
com.bea.wlpi.server.plugin. PluginManager | PluginManagerHome | PluginManager
com.bea.wlpi.server.plugin. PluginManagerCfg | PluginManagerCfgHome | PluginManagerCfg
com.bea.wlpi.server.serverproperties. ServerProperties | ServerPropertiesHome | ServerProperties
com.bea.wlpi.server.principal. WLPIPrincipal | WLPIPrincipalHome | WLPIPrincipal
com.bea.wlpi.server.worklist.Worklist | WorklistHome | Worklist
com.bea.eci.repository.ejb. XMLRepository | XMLRespositoryHome | XMLRepository

To access BPM API session EJBs and their methods, you must perform the following steps:

1. Look up a session EJB home interface in JNDI.

2. Create a remote session object (EJBObject) using the home interface.

The following sections describe these steps in detail.

Step 1: Look Up a Session EJB Home Interface in JNDI

The BPM session EJBs are exposed to client applications as part of the WebLogic Server JNDI namespace.

You can look up a session EJB home interface by first establishing a JNDI context (java.naming.Context). The most common way of doing this is by instantiating a javax.naming.InitialContext object. For client applications that require a specific security context for authorization to access EJBs and their methods, you must also pass security credentials (user name and password, for example) to the InitialContext() constructor.

For example, the following method, excerpted from the JSP worklist example, creates an initial context, passing the specified URL, user ID, and password as the context environment.

>     public Context getInitialContext(
>       String user,
>       String password,
>       String url
>     ) throws NamingException
>     {
>          // Get an InitialContext
>          Properties h = new Properties();
>          h.put(Context.INITIAL_CONTEXT_FACTORY,"weblogic.jndi.WLInitialContextFactory");
>          h.put(Context.PROVIDER_URL, url);
>          if (user != null) {
>              h.put(Context.SECURITY_PRINCIPAL, user);
>              if (password == null)
>                password = "";
>          }
>              h.put(Context.SECURITY_CREDENTIALS, password);

>          return new InitialContext(h);
>     }

For more information, see the javax.naming.InitialContext() Javadoc. For more information about the JSP worklist, see JSP Worklist Example.

Once the JNDI context is defined, you can use the JNDI context lookup() method to access the session EJB home interface.

For example, to look up the Worklist session EJB home interface, and store the object reference to the worklistHome variable, execute the following statements:

>     Context context = getInitialContext(url, userId, password);
>     Object result = context.lookup("com.bea.wlpi.Worklist");
>     WorklistHome worklistHome =(WorklistHome)
>       PortableRemoteObject.narrow(result, WorklistHome.class);

Similarly, to look up the WLPIPrincipal session EJB home interface and store the object reference to the principalHome variable, execute the following statements:

>     Context context = getInitialContext(url, userId, password);
>     object result = context.lookup("com.bea.wlpi.WLPIPrincipal");
>     PrincipalHome prinicipalHome=(PrincipalHome)
>       PortableRemoteObject.narrow(result,
>       WLPIPrinicipalHome.class);

Note: The PortableRemoteObject.narrow() method used in the previous examples ensures that the remote object is cast to the desired type. Use of this method is required if the system is configured to use RMI-IIOP; otherwise, its usage is optional (but recommended). For more information, see the javax.rmi.PortableRemoteObject class Javadoc.

Step 2: Create a Remote Session Object Using the Home Interface

Once you have a reference to a home interface, you can use the home interface object create() method to access a remote session object (EJBObject).

For example, to create an EJBObject for the Worklist session EJB and store the object reference to the worklist variable, execute the following statement:

>     Worklist worklist = worklistHome.create();

Similarly, to create an EJBObject for the WLPIPrincipal session EJB and store the object reference to the principal variable, execute the following statement:

>     WLPIPrincipal wlpiprincipal = principalHome.create();

Using the Convenience Methods to Access EJBs

The com.bea.wlpi.client.common.WLPI class provides a set of convenience methods for accessing session EJBs. The following table summarizes these methods.

Table 3-2 Convenience Methods for Accessing EJBs

Method | Description
--- | ---
public com.bea.wlpi.server.admin.Admin getAdmin( ) throws java.lang.IllegalStateException, com.bea.wlpi.common.WorkflowException | Returns Admin EJB object.
public com.bea.wlpi.server.catalog.EJBCatalog getCatalog( ) throws java.lang.IllegalStateException, com.bea.wlpi.common.WorkflowException | Returns EJBCatalog EJB object.
public com.bea.wlpi.server.permission.Permission getPermission( ) throws java.lang.IllegalStateException, com.bea.wlpi.common.WorkflowException | Returns Permission EJB object.
public com.bea.wlpi.server.plugin.PluginManager getPluginManager( ) throws java.lang.IllegalStateException | Returns PluginManager EJB object.
public com.bea.wlpi.server.serverproperties.ServerProperties getServerProperties( ) throws IllegalStateException, WorkflowException | Returns ServerProperties EJB object.
public com.bea.wlpi.server.principal.WLPIPrincipal getPrincipal( ) throws java.lang.IllegalStateException | Returns WLPIPrincipal EJB object.
public com.bea.wlpi.server.worklist.Worklist getWorklist( ) throws java.lang.IllegalStateException, com.bea.wlpi.common.WorkflowException | Returns Worklist EJB object.
public com.bea.eci.repository.ejb.XMLRepository getRepository( ) throws java.lang.IllegalStateException, com.bea.wlpi.common.WorkflowException | Returns XMLRepository EJB object.
public boolean connect( java.awt.Frame owner java.lang.String url, java.lang.String userId, java.lang.String password ) throws java.lang.IllegalStateException public boolean connect( java.awt.Frame owner java.lang.String url, java.lang.String userId, java.lang.String password, int maxRetries, boolean autoLogon, boolean graphical ) throws java.lang.IllegalStateException | Connects to the process engine by performing the following tasks: Accesses the WLPIPrincipal session EJB. Sets the user ID and URL within the environment. Performs three automatic retries if a login fails. You must specify the following arguments: owner - window in which message boxes and dialog boxes will be displayed url - BPM URL userId - user ID password - password maxRetries - maximum number of retries permitted autoLogon - flag specifying whether to attempt to logon using supplied values (true) or to prompt user for confirmation (false). graphical - flag specifying whether to perform a graphical dialog with the user (true) or not (false). You can obtain the user ID, password, and server URL by prompting the user for this information. For your convenience, the client.common.logon class is provided for generating a login dialog and capturing the user input. For more information about this class, see the com.bea.wlpi.client.common.logon Javadoc.
public boolean isConnected() | Checks whether the WLPI instance is connected; that is, whether a reference has been made to the WLPIPrincipal session EJB.
public javax.naming.Context getInitialContext() | Returns the host application JNDI context.

For more information, see the com.bea.wlpi.client.common.WLPI Javadoc.