Chapter 12   Scripting with EJB Components


This chapter describes how to call an Enterprise JavaBean (EJB) from JavaScript. You should be familiar with EJBs to understand the information in this chapter.

This chapter describes the following topics:

• Calling EJB Components from JavaScript

• A Sample Script

• Handling Exceptions

• Data Conversion Issues

• Adding EJB References to a Process Manager Application

• Adding iAS EJB References to a Process Manager Application

• Adding EJB References to an Application Using the Command Line Deploy Tool

Calling EJB Components from JavaScript

---

Your JavaScript process automation script can create an instance of an EJB and call the EJB's methods to perform business logic. For example, an order-entry application might create an instance of an EJB that represents a credit card authorization gateway. The application would call methods to check the credit card number, authorize the transaction, and create a charge on the account, as shown in Figure 12-1:

Figure 12-1    Programming logic for calling an EJB component

A Sample Script

---

To use an EJB, the calling JavaScript must perform the following actions:

• Look up the bean using the home interface's JNDI name

• Create an instance of the bean

• Call the bean's methods to perform tasks supported by the bean

The following JavaScript function shows an example of these actions:

function billCC () {    var pi = getProcessInstance ();    var wi = getWorkItem();    pi.setData("ccError",null);    var ccNumber = pi.getData("ccNumber");    // Get bean home, create it, and call the check method on it.    var home = ejbLookup("Netscape/CreditCardServer");    var ccs = home.create ( pi.getData("ccType") );        var result = ccs.check ( ccNumber );    if (! result.equals          ( Packages.com.netscape.pm.sample.ICreditCardServer.CARD_OK ))    {           pi.setData("ccError", result);           return true;    }    result = ccs.authorize ( ccNumber, 100, 25 );    if (result.startsWith (          Packages.com.netscape.pm.sample.ICreditCardServer.CREDIT_LIMIT_EXCEEDED)          || result.startsWith (          Packages.com.netscape.pm.sample.ICreditCardServer.CREDIT_DENIED) )    {           pi.setData("ccError", result);           return true;    }    // Charge the card the amount shown.    result = ccs.charge ( ccNumber, result );    if (! result.startsWith (          Packages.com.netscape.pm.sample.ICreditCardServer.OPERATION_OK ))    {           pi.setData("ccError", result);           return true;    }        pi.setData("ccAuthcode", result);    return true; }

You call the ejbLookup() function to create a reference to the EJB. This method uses the bean's JNDI name to determine the EJB to use. In this example, the name is Netscape/CreditCardServer. You can examine the bean's BeanHomeName property to determine the JNDI name.

You call the bean's factory method, which is defined in the bean's home interface class, to create the instance of the bean. In this example, the method is create(). You can examine the bean's HomeInterfaceClassName property to determine the home interface class.

You can then call the bean's methods, which are defined in the bean's remote interface class, to perform specific tasks. In this example, the JavaScript calls the bean's check(), authorize(), and charge() methods. You can examine the bean's RemoteInterfaceClassName property to determine the remote interface class.

Handling Exceptions

---

Java exceptions cannot be handled in JavaScript. You can implement your bean so that the script receives error information without needing to deal with an exception, as in the following example:

... catch (...Exception e) {    e.PrintStackTrace();        return true;    } }

If an exception is thrown, the process instance moves to the exception manager that you specify in the Inspector window, as shown in Figure 12-2:

Figure 12-2    Setting an exception manager in Process Builder

Data Conversion Issues

---

Process Manager uses LiveConnect's rules to convert between Java and JavaScript data types. When you call a Java method from JavaScript, JavaScript does not convert the data type of the data until it is manipulated by the script. For example, the result variable in the script contains a Java string data type after executing the Java EJB check() method in the following statement:

var result = ccs.check ( ccNumber );

You must compare the variable's contents using Java methods; comparing with JavaScript functions will not work as expected. The following statement shows the comparison using Java:

if (result.equals ( Packages.com.netscape.pm.sample.ICreditCardServer.CARD_OK )    == false) { ... }

To access Java data, you must qualify the package name with the Packages keyword unless the Java data is from the java package. JavaScript recognizes the java package without qualification. You can also create an instance of an object by specifying the new operator, as in the following examples:

var aResult = new java.lang.String; var CARD_OK = new    Packages.com.netscape.pm.sample.ICreditCardServer.CARD_OK

Note. Conversion between Java and JavaScript is implicit and occurs when the value is manipulated as a JavaScript data type. For example, if result contains a Java string data type, the following statement causes it to be converted to a JavaScript string data type:

result = result + "";

Adding EJB References to a Process Manager Application

---

In a J2EE environment, an EJB in one J2EE module or application that refers to another EJB in a different module or application must contain information about the EJB to which it refers. This referencing occurs in the deployment descriptor (ejb-jar.xml) file. You use an <ejb-ref> tag to declare the reference information.

Process Manager is itself a J2EE module. If an EJB needs to interact with the Process Manager runtime or applications, its deployment descriptor must contain an <ejb-ref> tag. Similarly, if a Process Manager application uses an external EJB (via custom activity, custom field or in the JavaScript associated with any activities), it should contain the necessary <ejb-ref> tags in the deployment descriptor when the application is registered with iAS. If you use EJB references in an application, you must map these references to iAS EJB references.

Adding EJB References

1. Launch Process Manager Builder.

2. Open the application to which you need to add EJB references.

3. Right click on the application name in the application tree view and select Properties.

   The properties Inspector appears.

Figure 12-3    The properties Inspector.

4. Select the arrow corresponding to EJB References.

   The EJB References editor window appears.

Figure 12-4    The EJB References editor.

5. Enter the EJB references in the editor window.

The syntax is identical to J2EE deployment descriptor files. For example, if your PM application uses EJBs called MyAccount and MyOtherAccount, the EJB references might look like this:

Code Example 12-1 Example of an EJB reference

<ejb-ref>         <ejb-ref-name>MyAccount</ejb-ref-name>        <ejb-ref-type>Session</ejb-ref-type>        <home>com.mycompany.MyAccountHome</home>        <remote>com.mycompany.MyAccount</remote>        <ejb-link>MyAccountLink</ejb-link> </ejb-ref> <ejb-ref>        <ejb-ref-name>MyOtherAccount</ejb-ref-name>        <ejb-ref-type>Session</ejb-ref-type>        <home>com.mycompany.MyOtherAccountHome</home>        <remote>com.mycompany.MyOtherAccount</remote>        <ejb-link>MyOtherAccountLink</ejb-link> </ejb-ref>

6. Select OK to save your edits.

   Once you have created and saved the EJB reference in the editor, the reference appears as an item in the drop-down list on the properties Inspector window.

   You can add as many EJB references as you need in the free form editor. Note that the text you enter is not validated. Anything you type is sent verbatim to the server and placed in the deployment descriptor of the PM application.

Adding iAS EJB References to a Process Manager Application

---

In addition to declaring EJB references in the deployment descriptor file, you must declare an <ejb-ref> tag that maps the <ejb-ref-name> declared in the <ejb-ref> tag to the name in its registry (via <jndi-name> tag). This is known as an iAS EJB reference. If you do not declare an iAS EJB reference, the iAS environment will not register the EJB reference.

For more specific information about iAS EJB references, refer to the iPlanet Application Server Java Programmers Guide.

Adding iAS EJB References

1. Launch Process Manager Builder.

2. Open the application to which you need to add iAS EJB references.

3. Right click on the application name in the application tree view and select Properties.

   The properties Inspector appears.

Figure 12-5    The properties Inspector.

4. Select the arrow corresponding to iAS EJB References.

   The iAS EJB References editor window appears.

Figure 12-6    The iAS EJB References editor.

5. Enter the iAS EJB references in the editor window.

   The syntax is identical to J2EE deployment descriptor files. For example, if your PM application uses EJBs called MyAccount and MyOtherAccount, the iAS EJB mappings might look like this:

Code Example 12-2 Example of an iAS EJB Reference

<ejb-ref>        <ejb-ref-name>MyAccount</ejb-ref-name>        <jndi-name>ejb/AccountJar/MyAccount</jndi-name> </ejb-ref> <ejb-ref>        <ejb-ref-name>MyOtherAccount</ejb-ref-name>        <jndi-name>ejb/AccountJar/MyOtherAccount</jndi-name> </ejb-ref>

6. Select OK to save your edits.

Once you have created and saved the iAS EJB reference in the editor, the reference appears as an item in the drop-down list on the properties Inspector window.

You can add as many EJB references as you need in the free form editor. Note that the text you enter is not validated. Anything you type is sent verbatim to the server and placed in the deployment descriptor of the PM application.

Adding EJB References to an Application Using the Command Line Deploy Tool

---

You can add EJB references to an application using the Command Line Deploy Tool. The Command Line Deploy Tool delivers the deployment functionality of the Process Manager Builder Deploy function without having to use the Builder's UI.

To learn how to use the Command Line Deploy Tool, see Deploying Applications with the Command Line Deploy Tool.

EJB references must be specified in the deployment descriptor (.dd) file when using the Command Line Deploy Tool. If you use this tool to register EJB references, you must specify all the EJB references on one single line following ejbRefField or iasEjbRefField. If you want to specify this on multiple lines, you need to escape each end of line with a \. The following example shows a typical EJB reference in the deployment descriptor file:

Code Example 12-3 Example of an EJB reference in a deployment descriptor (.dd) file

ejbRefField: <ejb-ref>\n \   <ejb-ref-name>MyAccount</ejb-ref-name>\n \   <ejb-ref-type>Session</ejb-ref-type>\n \   <home>com.mycompany.MyAccountHome</home>\n \   <remote>com.mycompany.MyAccount</remote>\n \   <ejb-link>MyAccountLink</ejb-link>\n \ </ejb-ref>\n \ <ejb-ref>\n \   <ejb-ref-name>MyOtherAccount</ejb-ref-name>\n \   <ejb-ref-type>Session</ejb-ref-type>\n \   <home>com.mycompany.MyOtherAccountHome</home>\n \   <remote>com.mycompany.MyOtherAccount</remote>\n \   <ejb-link>MyOtherAccountLink</ejb-link>\n \ </ejb-ref>\n \ iasEjbRefField: <ejb-ref>\n \   <ejb-ref-name>MyAccount</ejb-ref-name>\n \   <jndi-name>ejb/AccountJar/MyAccount</jndi-name>\n \ </ejb-ref>\n \ <ejb-ref>\n \   <ejb-ref-name>MyOtherAccount</ejb-ref-name>\n \   <jndi-name>ejb/AccountJar/MyOtherAccount</jndi-name>\n \ </ejb-ref>\n \

---

Note

The \n in the above example instructs the system to insert a newline. This allows you to inspect the references in the Process Builder EJB References text editor at a later time. The text you enter is not validated. Anything you type is sent verbatim to the server and placed in the deployment descriptor of the PM application.

---