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
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.
-
From the Start menu, choose Programs-->WebLogic
Platform 8.1-->QuickStart.
-
In the QuickStart dialog, click Experience
WebLogic Workshop 8.1.
...on Linux
If you are using a Linux operating system, follow these instructions.
-
Open a file system browser or shell.
-
Locate the Workshop.sh file at the following
address:
$HOME/bea/weblogic81/workshop/Workshop.sh
-
In the command line, type the following command:
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.
-
From the File menu, select New -->
Application. The New Application dialog
appears.
- 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.

-
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.
- On the Application tab, right-click the JavaControlTutorial
folder and select New-->Project.
- 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.

- 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.
-
On the Application tab, right-click the JavaControlTutorialWeb
folder and select New-->Folder.
-
In the Create New Folder dialog, enter investigateJCS,
as shown in the following illustration.
-
Click OK.
A new folder named investigateJCS is created inside
the JavaControlTutorialWeb folder.
-
Right-click the investigateJCS folder and select New-->Java
Control.
- 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.)
-
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.)
- On the Application tab, right-click the investigateJCS
folder and select New --> Java Class. The New
File dialog appears.
-
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.
-
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() {}
}
- 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.
- 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.)
- Click the Source View tab.
-
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();
- Press Ctrl+S to save your work.
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.)
- Confirm that InvestigateImpl.jcs is displayed in the main
work area.
- Click the Design View tab.
-
In
Design View, right-click the picture of your Java
control and select
Add Method.
-
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.
- 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.
-
In
Design View select the
requestCreditReport
method. You select a method by clicking the arrow icon next to
the method's name.
-
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.
-
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.
- 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.";
}
-
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.
-
Confirm that InvestigateImpl.jcs is displayed in
the main work area.
-
Click the Design View tab.
- In Design View, right-click the picture of your Java
control and select Add Callback.
- In the space provided, replace newCallback1
with onCreditReportDone and press Enter.
A callback is added to your Java control.

- Click the name of the callback onCreditReportDone.

Clicking a callback opens the control's interface file (a Java file).
- Edit the Callback interface so it appears as follows.
interface Callback
{
void onCreditReportDone(investigateJCS.Applicant applicant);
}
- Press Ctrl+S to save your work.
- 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.
- Confirm that InvestigateImpl.jcs is displayed in the
main work area.
- If necessary, click the Design View tab.
- Click the name of the requestCreditReport method.

- 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);
}
- 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.
- 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.
- 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.
- On the Design View tab, right-click the startTestDrive
method and select Delete.

- In the dialog warning you that you are attempting to edit an auto generated
file, click OK.

- On the Design View tab, right-click the finishTestDrive
method and select Delete.
- On the Design View tab, select the arrow icon for the
requestCreditReport method.

- On the Property Editor tab, in the section labeled
conversation, find the phase property.
Using the drop-down list, set the value to start.

- On the Design View tab, select the arrow icon for the
onCreditReportDone method.

- 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.

- Click the Source View tab.
- 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); }
- 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.
- Confirm that InvestigateTest.jws is displayed in the
main work area.
- Click the Start button.

Workshop builds InvestigateTest.jws and launches the Workshop Test Browser.
-
In the
Workshop Test Browser, in the
taxID
field, enter some value
and click the
requestCreditReport button.
-
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.
- 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.
-
Return to
WebLogic Workshop and press the
Stop
button to close the Test Browser.