# Step 1: Begin the Investigate Java Control

In this step, you create a simple Java control that assembles credit-worthiness reports on loan applicants. You will focus on the public interface that is presented to users rather than the underlying implementation code that assembles the credit report. The public interface you build works as follows: users begin by requesting a credit report from the Investigate Java control, then the Investigate Java control builds a credit report based on those requests, and finally sends a completed report back to the user through a callback.
Callbacks are part of your Java control's support for asynchronous communication with its users. By supporting asynchronous communication, users are not forced to halt execution of their own processes while the credit report is being prepared. For detailed information of callbacks and asynchronous communication, see Designing Asynchronous Interfaces.

The tasks in this step are:

- To start WebLogic Workshop
- To create a new application and select a WebLogic server domain
- To create a new project
- To start WebLogic Server
- To create the Investigate Java control
- To create the Applicant class
- To add a member variable
- To add a method
- To add a message buffer
- To a specify a parameter and method body
- To add a callback
- To add code to invoke the callback after the credit-worthiness report has been assembled
- To generate a test client for the Investigate Java control
- To test the Investigate Java control

To Start WebLogic Workshop

If you have an instance of WebLogic Workshop already running, you can skip this step.

... on Microsoft Windows

If you are using a Windows operating system, follow these instructions.

1. From the Start menu, choose Programs-->WebLogic Platform 8.1-->QuickStart.
2. In the QuickStart dialog, click Experience WebLogic Workshop 8.1.

...on Linux

If you are using a Linux operating system, follow these instructions.

1. Open a file system browser or shell.
2. Locate the Workshop.sh file at the following address:

       $HOME/bea/weblogic81/workshop/Workshop.sh

3. In the command line, type the following command:

       sh Workshop.sh

To Create a New Application and Select a WebLogic Server Domain

The Investigate Java control uses four different resources to assemble a credit report: (1) a web service, (2) a database, (3) an EJB application, and (4) a message driven EJB application. In this task you will create a new application that contains all four of these resources. The application you create below already contains the web service resource. The server domain you select below contains the remaining three resources.

1. From the File menu, select New --> Application. The New Application dialog appears.
2. In the New Application dialog, in the upper left-hand pane, select Tutorial.
   In the upper right-hand pane, select Tutorial: Java Control.
   In the Directory field, use the Browse button to select a location to save your source files. (The folder you choose is up to you, the default location is shown in the illustration below.)
   In the Name field, enter JavaControlTutorial.
   In the Server field, from the dropdown list, select BEA_HOME\weblogic81\samples\domains\workshop.
3. Click Create.

A new application is created. The application contains six sub-folders named CreditCardReport_JCSTutorial, Read_Me, Schemas, Modules, Libraries, and Security Roles.

The folder CreditCardReport_JCSTutorial contains a web service that your Java control will utilize. This web service offers credit card information on loan applicants. The Read_Me folder contains a message directing users to this tutorial. This message is provided in case a user should open a new Java Control Tutorial Application by accident. The Schemas folder contains schema files used for parsing XML documents. The Modules folder is provided with every WebLogic application: use this folder to store stand-alone applications. The Libraries folder is used to store JAR files and other application resources. The Security Roles folder is used to define the security roles used in your application.

## To Create a New Project

For the sake of convenience, you will develop your Java control within a web application project instead of a Java control project. This way, it is easier to generate and use Workshop's testing support. When the Investigate Java control is complete, you will move the source code to a Java control project for final packaging.

1. On the Application tab, right-click the JavaControlTutorial folder and select New-->Project.
2. In the New Project dialog, in the upper left-hand pane, confirm that All is selected.
   In the upper right-hand pane, select Web Project.
   In the Project Name field, enter JavaControlTutorialWeb.
3. Click Create.

To Start WebLogic Server

Since you will be deploying and running your Java control on WebLogic Server, it is helpful to have WebLogic Server running during the development process.

You can confirm whether WebLogic Server is running by looking at the status bar at the bottom of WebLogic Workshop. If WebLogic Server is running, a green ball is displayed as pictured below.

If WebLogic Server is not running, a red ball is displayed, as pictured below.

If you see the red ball in the status bar, then follow the instruction below to start WebLogic Server.

- To start WebLogic Server: from the Tools menu, choose WebLogic Server-->Start WebLogic Server.

Note: on the WebLogic Server Progress dialog, you may click Hide and continue to the next task.

To Create the Investigate Java Control

You are now ready to begin development of your Java control.

1. On the Application tab, right-click the JavaControlTutorialWeb folder and select New-->Folder.
2. In the Create New Folder dialog, enter investigateJCS, as shown in the following illustration.
3. Click OK.
   A new folder named investigateJCS is created inside the JavaControlTutorialWeb folder.
4. Right-click the investigateJCS folder and select New-->Java Control.
5. In the New Java Control Extension dialog, select Custom.
   In the File Name field, enter InvestigateImpl. ("Impl" indicates that this file contains the implementation code for your control.)
6. Click Create.
   Note that two files are created: a JCS (Java Control Source) file, and a Java file.
   The JCS file contains the implementation code for your Java control, the Java file contains the public interface for the underlying implementation code. The Java file is the public face of your Java control: it is essentially a list of methods that users can call to access the functionality contained within the underlying implementation code. For the most part, you do not have to directly edit the Java file, because WebLogic Workshop automatically maintains the Java file as you edit the JCS file.

To Create the Applicant Class

The code you add below, the Applicant class, contains fields for storing the information about credit applicants, such as the applicant's name, currently available credit, and so on. Each time your Java control is invoked a new instance of the Applicant class is created to store data on a particular applicant.
(Note that the Applicant class implements the Serializable interface. This allows WebLogic Workshop to save a particular Applicant object to disk while it is assembling a credit-worthiness report. This is important for two reasons. First, assembling a credit-worthiness report may take a long time, so it is convenient to be able to save data to disk instead of keeping it in memory. Second, the Investigate Java control will ultimately be exposed through a web service access point and web services require that the data they transport over the wire be serializable.)

1. On the Application tab, right-click the investigateJCS folder and select New --> Java Class. The New File dialog appears.
2. In the New File dialog, in the upper right-hand pane, confirm that Java Class is selected.
   In the File name field enter Applicant.java.
   Click Create.
   A new Java file, Applicant.java, is created.
3. Edit Applicant.java to look like the following. Add the elements appearing in red.

    package investigateJCS;

    public class Applicant implements java.io.Serializable
    {
        /*
         * This long allows for versioning of this class.
         */
        static final long serialVersionUID = 1L;

        public String taxID;
        public String firstName;
        public String lastName;
        public boolean currentlyBankrupt;
        public int availableCCCredit;
        public int creditScore;
        public String approvalLevel;
        public String message;

        public Applicant() {}
    }

4. Press Ctrl+S to save Applicant.java, then press Ctrl+F4 to close the file.

To Add a Member Variable

Each time a new report is requested from the Investigate Java control, a new instance of the Applicant object is created to store the report data. The following code constructs a new Applicant object each time a new report is requested.

1. Confirm that InvestigateImpl.jcs is displayed in the main work area. (To display any file in the main work area, double-click its icon on the Application tab.)
2. Click the Source View tab.
3. Add the following code to body of InvestigateImpl.

           /*
            * Construct a new instance of the Applicant class to store
            * the credit report data.
            */
           public Applicant m_currentApplicant = new Applicant();

4. Press Ctrl+S to save your work.

To Add a Method

In this task you add a method through which users will request a new credit report. When users invoke this method, it starts off the process of assembling a credit report. (When the credit report is done, the report will be sent back to the user through a callback method, added below.)

1. Confirm that InvestigateImpl.jcs is displayed in the main work area.
2. Click the Design View tab.

3. In Design View, right-click the picture of your Java control and select Add Method.
4. In the space provided, replace newMethod1 with requestCreditReport and press Enter.

   > Note: If you switched from WebLogic Workshop to another application (for example, to read this topic), the method name may no longer be available for editing. To re-open it for editing, right click its name, select Rename, type requestCreditReport, and then press Enter.

5. Press Ctrl+S to save your work.

To Add a Message Buffer

By adding a message buffer to a method, the method immediately returns a simple method invocation acknowledgement to the user. This allows the user to continue with its own processes while the requestCreditReport method executes.

1. In Design View select the requestCreditReport method. You select a method by clicking the arrow icon next to the method's name.
2. On the Property Editor tab, in the section labeled message buffer, select the enable property. Using the drop-down list, set the value to true.
   A buffer icon is added to the method's arrow icon, as shown below.

To Specify a Parameter and Method Body

The Investigate Java control assembles a credit report based on a subject's tax identification number. In this task you will add a parameter to the requestCreditReport method through which you can specify the subject's tax identification number.
You will also add code to the method body that assembles a credit report on the applicant. For the time being the assembly process is not very informative about the applicant, but as you progress in the tutorial, the assembly process will become more complex.

1. In Design View, click the name of the requestCreditReport method, as shown in the following illustration.
   Clicking the method's name in Design View, displays the method's source code in Source View.
   Note the two Javadoc annotations that appear above the requestCreditReport method.
   The Javadoc annotation @common:operation indicates that this method is part of the public interface of InvestigateImpl.jcs. When this annotation is present, WebLogic Workshop includes this method as part of the public interface listed in Investigate.java. In Design View, this annotation is depicted by the blue arrow icon.
   The Javadoc annotation @common:message-buffer indicates that this method immediately returns an acknowledgment to the user after he invokes the method. In Design View this annotation is depicted by the buffer icon.
2. Edit the requestCreditReport method declaration and body so that they appear as follows. Code to add appears in red. Do not edit the annotations above the method declaration.

           public void requestCreditReport(String taxID)
           {
               /*
                * Assemble a credit worthiness report on the applicant.
                */
               m_currentApplicant.taxID = taxID;
               m_currentApplicant.firstName = "unknown";
               m_currentApplicant.lastName = "unknown";
               m_currentApplicant.approvalLevel = "unknown";
               m_currentApplicant.message = "There was insufficient data available to assemble a full report on this applicant.";
           }

3. Press Ctrl+S to save your work.

To Add a Callback

When the Investigate Java control has assembled a complete credit report it sends the report to the user through a callback method. In this task you will add the callback method through which users will receive the completed credit report. You will also add a parameter to your callback method. When you add a parameter to a callback method, the parameter you add will be sent to the client of your Java control.

1. Confirm that InvestigateImpl.jcs is displayed in the main work area.
2. Click the Design View tab.
3. In Design View, right-click the picture of your Java control and select Add Callback.
4. In the space provided, replace newCallback1 with onCreditReportDone and press Enter.
   A callback is added to your Java control.
5. Click the name of the callback onCreditReportDone.
   Clicking a callback opens the control's interface file (a Java file).
6. Edit the Callback interface so it appears as follows.

           interface Callback
           {
               void onCreditReportDone(investigateJCS.Applicant applicant);
           }

7. Press Ctrl+S to save your work.
8. Click the X in the upper right-hand corner of the main work area to close the Investigate.java file.

Add Code to Invoke the Callback After the Credit-worthiness Report Has Been Assembled

At this point the Investigate Java control has (1) a method through which a client can request a credit-worthiness report (requestCreditReport) and (2) a callback methods which sends the credit-worthiness report to the client (onCreditReportDone). In this following task you will connect these two methods, so that when the credit-worthiness report is complete, it will be sent to the client.

1. Confirm that InvestigateImpl.jcs is displayed in the main work area.
2. If necessary, click the Design View tab.
3. Click the name of the requestCreditReport method.
4. Edit the source code for the requestCreditReport method so it appears as follows. Code to add appears in red.

           public void requestCreditReport(String taxID)
           {
               /*
                * Assemble a credit-worthiness report on the applicant.
                */
               m_currentApplicant.taxID = taxID;
               m_currentApplicant.firstName = "unknown";
               m_currentApplicant.lastName = "unknown";
               m_currentApplicant.approvalLevel = "unknown";
               m_currentApplicant.message = "There was insufficient data available to assemble a full report on this applicant.";

               /*
                * Send the credit-worthiness report to the client via a callback.
                */
               callback.onCreditReportDone(m_currentApplicant);
           }

5. Press Ctrl+S to save your work.

As it is now written, the Investigate Java control works like this: the user begins the process by invoking the requestCreditReport method, supplying a tax identification number as a method parameter. The requestCreditReport then immediately returns a request acknowledgement to the user (this is the role of the message buffer). Next the Investigate Java control assembles a credit report on the applicant. Finally the completed credit report is sent back to the user through the callback onCreditReportDone.

To Generate a Test Client for the Investigate Java Control

In this task you will generate a client to test your Java control. The test client is a web service that allows you to invoke the methods of the Investigate Java control and view the results of those method invocations.

1. On the Application tab, right-click InvestigateImpl.jcs and select Generate Test JWS File (Conversational).
   A new web service, InvestigateTest.jws, is created and placed in the investigateJCS folder.
2. On the Application tab, double-click InvestigateTest.jws to open the file.
   When you auto generate a test web service, WebLogic Workshop creates a set of web service methods corresponding to the methods of your Java control plus two more: a startTestDrive method and a finishTestDrive method. These two extra methods are used to start and finish a web service conversation. Conversations are used to group together the different method calls and callbacks into a single session. This is especially useful if you make multiple requests for credit reports: it lets you associate each invocation of the requestCreditReport method with the corresponding credit report returned by the callback onCreditReportDone. The green, yellow, and red icons on the web service methods indicate the phases of the conversation: a green icon indicates that the method starts a new conversation, a yellow icon indicates that the method continues an already existing conversation, and a red icons indicates that the method ends an already existing conversation.
   Autogenerated test web services are optimized for Java controls with complex public interfaces. In a typical test cycle you would start a new conversation by invoking the startTestDrive method, continue the conversation by invoking the methods corresponding to your Java control, and finally end the conversation by invoking the finishTestDrive method. But our Java control has a simple public interface, so you will modify the test web service to make it easier to use.
3. On the Design View tab, right-click the startTestDrive method and select Delete.
4. In the dialog warning you that you are attempting to edit an auto generated file, click OK.
5. On the Design View tab, right-click the finishTestDrive method and select Delete.
6. On the Design View tab, select the arrow icon for the requestCreditReport method.
7. On the Property Editor tab, in the section labeled conversation, find the phase property. Using the drop-down list, set the value to start.
8. On the Design View tab, select the arrow icon for the onCreditReportDone method.
9. On the Property Editor tab, in the section labeled conversation, find the phase property. Using the drop-down list, set the value to finish.
   Design View should look like the following.
10. Click the Source View tab.
11. Edit the requestCreditReport method so it looks like the following. Add the code appearing in red.

            /**
             * <p>Use the following taxID's to test the Investigate web service.</p>
             *
             * <blockquote>111111111<br>
             * 222222222<br>
             * 333333333<br>
             * 444444444<br>
             * 555555555<br>
             * 123456789</blockquote>
             *
             * @common:operation
             * @jws:conversation phase="start"
             */
            public void requestCreditReport(java.lang.String taxID)
            { investigate.requestCreditReport(taxID); }

12. Press Ctrl+S to save your work.

To Test the Investigate Java Control

In the following task you will use the test web service to invoke the methods of the Investigate Java control. The test web service also lets you view detailed information about the methods while they are executing.
1. Confirm that InvestigateTest.jws is displayed in the main work area.
2. Click the Start button.
   Workshop builds InvestigateTest.jws and launches the Workshop Test Browser.
3. In the Workshop Test Browser, in the taxID field, enter some value and click the requestCreditReport button.
4. Click Refresh until the callback.onCreditReportDone appears in the Message Log.
   In the image above, the Message Log contains information about the method invocation requestCreditReport and the callback onCreditReport. The right-hand column, underneath the heading Service Request requestCreditReport, gives detailed information about the time the requestCreditReport method was invoked, the parameter that was entered, the conversation phase, and the conversation ID that was assigned to this method invocation.
   In the left-hand column, note the number appearing directly above requestCreditReport. This is the conversation ID that groups together the requestCreditReport method and the onCreditReport callback. This conversation ID appearing in your Test Browser will be different than the one illustrated here: this is because a new conversation ID is generated each time the requestCreditReport method is invoked.
   The right-hand column (not fully pictured here, see your Test Browser) gives you the run-time implementation details about how the web service and the Investigate Java control interact. (As you can see, from a run-time perspective their interaction is fairly complex. But from an application development perspective you do not have to worry about these details, they are taken care of by the WebLogic Workshop runtime.) The most important part of this interaction is the invocation of the requestCreditReport method on the Investigate Java control and the acknowledgment it immediately returns to the web service client (illustrated below). Recall that the acknowledgment is returned because you placed a message buffer on the requestCreditReport method.
5. In the Message Log, click callback.onCreditReportDone.
   Notice that the results are displayed in the form of an XML document. This is because the test web service converts the Applicant object into an XML message before it is displayed in the test browser. (Note that web services always send XML messages to their clients, typically in a SOAP format.)
   Also notice the <conversationID> element. This is the same conversation ID that was assigned to the requestCreditReport method when the conversation began.
6. Return to WebLogic Workshop and press the Stop button to close the Test Browser.

Related Topics

Designing Asynchronous Interfaces

Building Custom Java Controls

Click one of the following arrows to navigate through the tutorial.