As Published In
Oracle Magazine
March/April 2005

DEVELOPER: Forms


Oracle Forms in the SOA World

By Robin Zimmermann

Oracle Forms can be part of your service-oriented architecture.

Today's enterprise is under pres-sure to interconnect its many disparate systems and applications. This pressure to integrate is a major driving force behind the adoption of Web services and service-oriented architecture (SOA) as an enterprise blueprint for reducing the cost and complexity of integration initiatives. Business Process Execution Language (BPEL) has rapidly established itself as the industry standard for this integration, and Oracle BPEL Process Manager offers a comprehensive and easy-to-use infrastructure for creating, deploying, and managing business processes. Oracle Forms, with its support for Java, can participate in any BPEL process flow.

Oracle Forms interacts with Oracle BPEL Process Manager, using Java Importer, a feature that can expose your Oracle Forms applications to server-side Java classes. Java Importer allows you to import Java classes into your Oracle Forms modules, generating PL/SQL wrappers for the classes you select. You can then use PL/SQL throughout your Oracle Forms application, and at runtime Oracle Forms will send those PL/SQL calls to the Java classes you have imported.

This article illustrates how a simple Oracle Forms application can interact with Oracle BPEL Process Manager.

Background/Overview

The application in this article is based on an application called the Loan Flow Plus sample, which is part of the Oracle BPEL installation. The goal is to build a simple business process to determine the best interest rate for a prospective loan customer, as shown in Figure 1. After the customer provides the details, Oracle BPEL Process Manager retrieves that person's Social Security number (SSN) and uses it to obtain the applicant's credit rating. Oracle BPEL then queries the loan services of two banks on behalf of the customer to see what annual percentage rate (APR) the loan services offer. It then selects the best loan and reports the interest rate to the customer.

 

figure 1
Figure 1: Process flow for the Loan Flow Plus application


The Loan Flow Plus sample application illustrates some of the benefits of BPEL:

  • Integrating services from different vendors using different implementations

  • Handling asynchronous Web service invocations

  • Calling a Web service that is long-running and has to call back the originating Web service later

  • Invoking processes in parallel rather than in sequence

The original Loan Flow Plus sample application (installed under your Oracle BPEL Process Manager home directory) uses JavaServer Pages (JSP) to interact with a BPEL process flow. But there's no reason why Oracle Forms can't also interact with a BPEL process flow, so you will take one of the screens from the original sample application and implement it by using Oracle Forms instead. Here is how the sample application is implemented:

As you can see in Figure 1, Oracle BPEL Process Manager applies for a loan from both Star Loan Bank and United Loan Bank. The United Loan Bank service is automated and quickly returns a result to BPEL Process Manager. But Star Loan Bank requires human intervention to approve a loan. Figure 2 shows the Oracle Forms approval application that the Star Loan Bank lending officer uses, with a loan for Dave about to be approved with an APR of 7.4 percent.

 

figure 2
Figure 2: The Star Loan Bank approval form


Note that the form in Figure 2 is not retrieving any information from a database; indeed, this sample application does not even connect to any database. When the user clicks on the Refresh button, Oracle Forms calls out to a Java Virtual Machine (JVM) to invoke your Java classes, which, in turn, call out to Oracle BPEL Process Manager to get the information that is displayed on-screen. Similarly, when the user clicks on the Approve or Reject button, Oracle Forms calls out to the JVM, which notifies Oracle BPEL Process Manager whether the loan was rejected or approved (and what the APR is).

Figure 3 shows a high-level overview of the communication between Oracle Forms and Oracle BPEL Process Manager. Oracle Forms automatically starts the JVM the first time it needs to call out to Java. Oracle BPEL Process Manager is the engine that manages the process flow and the interaction with the various Web services and other processes.

 

figure 3
Figure 3: High-level architecture overview


Web Service Interface Versus Java API

Any BPEL process deployed to Oracle BPEL Process Manager is accessible via a Web service interface or through a Java API.

The Web service interface uses standard SOAP communication and can be used for clients that are implemented in any language. Alternatively, for clients written in Java, you can communicate with Oracle BPEL Process Manager via the Java API. There are two benefits to the Java API: You get better performance than with a Web service, and you can invoke/initiate the business processes transactionally.

Oracle Forms can easily interact with any Web service via the Java Importer feature. You can find articles on calling a Web service with Oracle Forms at oracle.com/technetwork/products/forms/techlisting9i.html and oracle.com/technetwork/products/forms/techlisting10g.html.

As this article continues, it shows Oracle Forms interacting with Oracle BPEL Process Manager by use of the latter product's Java API.

Step 1: Create the Java for calling BPEL. Because Oracle BPEL has a Java API and you can make Java calls from Oracle Forms, you can have your Oracle Forms application interact directly with Oracle BPEL Process Manager. However, there is more to the interaction than invoking some methods on the Java API: You need to, for example, manipulate XML messages that you will pass to and receive from the API. So it makes sense for you to write some Java that sits between Oracle Forms and Oracle BPEL Process Manager and passes to Oracle Forms only the information it needs. Therefore, you need to create a Java class for the Star Loan Bank screen that enables Oracle Forms to do the following:

A. Retrieve the list of loans awaiting the loan officer
B. Approve a specific loan and set the APR
C. Reject a specific loan

The following is an outline of the Java class, LoanFlowPlusForms , that you create and that gets imported into Oracle Forms, showing the methods that correspond to A, B, and C, above: 

public class LoanFlowPlusForms 
{
  public static String[] 
getLoanApplicationList(String pEmail)
  {
    ...
  }
  public static void 
approveLoan(String pTaskId, double pApr)
  {
   ...
  }
  public static void 
rejectLoan(String pTaskId)
  {
   ...
  }
}


The full code of the LoanFlowPlusForms class is available in Listing 3.

The getLoanApplicationList() method takes the pEmail parameter, the e-mail address of the loan officer at Star Loan Bank—each user (loan officer) should see only the loans that person needs to approve. The approveLoan() and rejectLoan() methods accept a parameter called pTaskId , which is the ID of the loan that is to be approved or rejected. The approveLoan() method takes another parameter for the APR of the loan.

The getLoanApplicationList() method returns an array of strings in the following format: 

<taskId>|<customerName>|<ssn>|
<carModel>|<carYear>|<vloanAmount>


Oracle Forms can parse these strings and display the data on-screen. The following is an example of data returned from getLoanApplicationList(). 

1466|Kris|bullit@cs.com|987-65-432|
583|HondaHybrid|2004|28000.0
1554|Dave|demo1@otn.com|123-12-1234|
560|BMW Z8|2001|100000.0
1893|Jonas|chef@bork.com|135-246-78|
517|Ford Freestar|1999|12000.0


Figure 2 shows how this data is displayed in the runtime sample application form.

Step 2: Merge the Java code with the Oracle Forms application. Before importing your Java class into Oracle Forms, you need to put it on the classpath, so that Oracle Forms Builder will be able to find it. In Windows, you can do this in the Microsoft Windows Registry. Modify the FORMS90_BUILDER_CLASSPATH variable, and add the path that points to your class file.

Start Oracle Forms Builder, and create or open your form. Choose Program->Import Java Classes... from the menu to open Java Importer. Select the path to LoanFlowPlusForms , and click on Import , as shown in Figure 4.

 

figure 4
Figure 4: Importing the LoanFlowPlusForms Java class


Java Importer examines th e Java class and creates a PL/SQL wrapper for it. You will see in Oracle Forms Object Navigator that there is a new package containing the PL/SQL version of the Java methods you have created, as shown in Figure 5. You can now call these procedures and functions from anywhere in your form and pass the necessary parameters.

 

figure 5
Figure 5: The PL/SQL wrapper for the Java class


Next you create the Star Loan application, which lists the loan application details to be approved or rejected.

Listing 1 contains the code for the WHEN-BUTTON-PRESSED trigger behind the Refresh button that calls out to the JVM. The Java class returns an array of String objects containing the details of the loan applications to be approved, as shown in Figure 2. Remember that the getLoanApplicationList() method takes the e-mail address of the Star Loan employee. For the sake of brevity, it has been hard-coded in Listing 1 as 'jsmith@starloan.com'.

Code Listing 1: Code for WHEN-BUTTON-PRESSED trigger 

DECLARE
  loanList              ORA_JAVA.JARRAY;
  listLength            NUMBER;
  loanString            VARCHAR2(255);
  delimiterPos  NUMBER;

  -- Each loan has the following fields.
  taskId                VARCHAR2(50);
  customerName  VARCHAR2(50);
  email                 VARCHAR2(50);
  ssn                   VARCHAR2(50);
  creditrating          VARCHAR2(50);
  carmodel      VARCHAR2(50);
  caryear               VARCHAR2(50);
  loanamount    VARCHAR2(50);
BEGIN
  -- Call out to Java to get the list of loan applications to be approved.
  loanList := LoanFlowPlusForms.getLoanApplicationList('jsmith@starloan.com');

  -- How many strings did the Java return?
  listLength := ORA_JAVA.GET_ARRAY_LENGTH(myGlobal.loanList);

  -- For each string, extract the details of the loan.
  for i in 1..listLength loop

    -- Get element i from the array of strings.
    loanString := ORA_JAVA.GET_STRING_ARRAY_ELEMENT(loanList, i);

    -- Parse the string looking for the '|' character to get each field.
    delimiterPos := instr(loanString, '|');
    taskId       := substr(loanString, 1, delimiterPos-1);

    loanString   := substr(loanString, delimiterPos+1);
    delimiterPos := instr(loanString, '|');
    customerName := substr(loanString, 1, delimiterPos-1);

    -- Do the same for the rest of the fields
    ...

    -- Now that we have all of the loan information, display it on the screen.
    ...

  end loop;
END;


The code for the Approve button is shown in Listing 2. 

Next Steps


READ
more on Oracle BPEL
oracle.com/technetwork/products/ias/bpel
oracle.com/technetwork/oramag/oracle/web

more on Oracle Forms
oracle.com/technetwork/products/forms/techlisting9i.html
oracle.com/technetwork/products/forms/techlisting10g.html

DOWNLOAD
Oracle BPEL Process Manager

The code for the Reject button in Figure 2 is the same as the code in Listing 2, except that you replace the line

 

LoanFlowPlusForms.approveLoan
(jo, :applications.taskId, :applications.apr);


with the following line: 

LoanFlowPlusForms.rejectLoan
(jo, :applications.taskId);


Code Listing 2: Code for the Approve button 

DECLARE
  jo ora_java.jobject;
  ex ora_java.jobject;
  myAlert NUMBER;
BEGIN
  jo := LoanFlowPlusForms.new;
  LoanFlowPlusForms.approveLoan(jo, :applications.taskId, :applications.apr);
  clear_record;
END;


Now the form is ready to run. When the user clicks on the Refresh button in the runtime form, Oracle Forms will call out to the LoanFlowPlusForms class, which will communicate with Oracle BPEL Process Manager to get the list of loan applications. The details of the loan applications are extracted and displayed on-screen. You can then notify Oracle BPEL Process Manager of your action, by clicking on the Reject button or typing in an APR and clicking on the Approve button.

This article has covered important aspects of building one screen of the sample application, but there is much more to the application. You can download the full sample application from oracle.com/technology/sample_code/products/forms.

Conclusion

In this article, you've seen Oracle Forms interacting with a separate system that has an entirely independent implementation. Oracle Forms Java Importer allows you to integrate Oracle Forms with Oracle BPEL Process Manager, so that your Oracle Forms applications can interoperate with the other applications in your enterprise environment.


Robin Zimmermann (robin.zimmermann@oracle.com) is a senior product manager for tools at Oracle and has worked at Oracle for eight years.


Send us your comments