1.

Creating and Using Web Services

2.

Purpose
This OBE tutorial describes how to create and use Web services with Oracle JDeveloper 10g.

3.

Topics
The tutorial discusses the following:
Overview
Prerequisites
Locating and Using an Existing Web Service
Creating and Using a Modeled Web Service
Creating and Using a PL/SQL Web Service
Using the TCP Packet Monitor to Examine the Web Service
Summary

Time to complete
90 minutes

4.

Viewing Screenshots
Move your mouse over this icon to show all screenshots. You can also move your mouse over
each individual icon to see only the screenshot associated with it.

5.

Overview
Web services are discrete reusable software components that can be incorporated into applications. They build
upon the existing XML and HTTP protocols and use the following standards:
WSDL (Web Services Description Language)
SOAP (Simple Object Access Protocol)
UDDI (Universal Description, Discovery, and Integration)
JDeveloper provides many features to help you to create and deploy Web services and to find existing Web
services to use in your applications. This tutorial shows you how to use some of JDeveloper's Web service
tools.
Back to Topic List

6.

Scenario

In developing Web applications with JDeveloper, you often find a need for functions such as stock quotes or
currency conversion. You know that Web services are available to incorporate these functions as components
in your application, but you are not sure where to find such services or how to use them. In addition to availing
yourself of existing services, you would like to develop Web components that you deploy as Web services for
such common functions as accessing employee information by supplying the employee identification number.

7.

Prerequisites
Back to Topic List
In order for this lesson to work successfully, you will need to have performed the following:
1.
Install Oracle JDeveloper 10g.

2.
Install the sample schemas and create a connection to the HR or HR8 schema to use in this lesson. SeeInstalling
the Sample Schemas and Establishing a Database Connection. For this tutorial, name the connectionHRconn; do
not use an underscore in the connection name

3.
You must have SQL*Plus installed on your local machine.

4.
To use the instance of OC4J that comes with JDeveloper as an external server on which to deploy the Web
services you create, you need to install and start OC4J:
To install, from the Command Prompt navigate to <jdev_install>/j2ee/home, where <jdev_install> is
the folder in which you installed JDeveloper, then issue the following command:
start java -jar oc4j.jar -install
When prompted, enter an admin password, such as welcome.
To start OC4J, issue the command:
start java -jar oc4j.jar
Keep this window open (you can minimize it if desired).

5.
You need to create an application server connection to the instance of OC4J that you installed and started, so that
you can deploy Web services to it. To create such a connection:
Open the Connections Navigator, right-click the Application Server node, and choose New Application Server
Connection from the context menu to launch the Create New Application Server Connection wizard.
If the Welcome page is displayed, click Next to display the Type page.
Change the Connection Name from AppServerConnection1 to WSConnection and leave the connection
type as Standalone OC4J. Click Next.

On the Authentication Page, leave the Username as admin, and enter the Password you used when you
installed OC4J. Select Deploy Password, and click Next to display the Connection page.
Leave the defaults, and click Next to display the Test page.
Click Test Connection. The results of testing are shown in the test window. If the test does not succeed, go
back and check that you have entered the correct password.
If you are working with DHCP, you may find that the connection works only if you use your IP number as part of
the URL on the Connection page.
When the test succeeds, click Finish.

6. You need to create a workspace to hold the projects you will create as you work through this lesson. To create a
workspace and project:
In the Applications Navigator, right-click Applications and choose New Application Workspace from the
context menu.
In the Create Application Workspace dialog, rename the application Application1 to WebServiceOBE.
Notice that the directory name changes to be the same.
From the list of available application templates, select No Template [All Technologies], then click OK.
TheWebServiceOBE application is created and displayed as a node in the navigator, and a project is
automatically created.

7. You must have access to the Internet to locate Web services in a public UDDI registry. If you are behind a firewall,
you must change JDeveloper's proxy settings so that it can access the Internet through the firewall. To change the
proxy settings:
Choose Tools > Preferences to open the Preferences dialog.
Select Web Browser\Proxy from the list, and select Use HTTP Proxy Server. Enter appropriate values for the
host name and port number.

8.

Locating and Using an Existing Web Service

Back to Topic List
This topic tells you how to locate and use a Web service that is available on the Internet. You will learn how to
use the Find Web Services wizard in JDeveloper to locate a Web service, then use the Create Web Service
Stub/Skeleton wizard to create a stub to the service. This topic covers the following subtopics:
Browsing a UDDI Registry
Creating a Stub to Use the Web Service

9.
Browsing a UDDI Registry

First you will rename the project so that your work is separate from your work in the other Web service topics.
Then you will use the Find Web Service wizard to locate a Web service.
Back to List
1.
Expand the WebServiceOBE node in the Applications Navigator and select Project.

2.
Choose File > Rename, and in the Rename dialog, change the file name
from Project.jpr toFindWebService.jpr and click Save.

3.
In the Connections Navigator, expand the UDDI Registry folder. JDeveloper comes with connections to three
public UDDI registries.

4.
Select the IBM Public UDDI v2 Registry, right-click and choose Find Web Services from the context menu to
launch the Find Web Services wizard.

5.
Click Next on the Welcome page to begin.

6.
In the Search Kind page, make sure that Name is selected and click Next to display the Search Criteria page.

You can search by category, but when you are just trying out the UDDI browser, it can be easier to get a result if
you search by name.

7.
In the Search Criteria page, you specify the criteria to use in searching for tModels. A tModel is a technical
specification that enables a client to determine if the Web service complies with a particular behavior or
programming interface.
In Search For, enter a search string such as ab% (% is a wild card). Click Next. This searches the UDDI registry
for tModels that start with the letters "ab".

If you get an error at this stage, make sure that you have a connection to the Internet and that JDeveloper's
proxy settings are correct. For more information, refer to Step 7 of Prerequisites.

8.
The tModels that fit the search criteria are displayed. Those that use a WSDL have a tick in the Is WSDL?
column. Select one of the tModels that has a tick, and click Next to display the Service page. (You do not have to
wait for all of the descriptions to load before selecting the one you want and clicking Next.) This example
uses Above All Software Test Service.

9.
The Service page of the wizard shows the services that implement the tModel you selected.
It is possible that you will get a message at this point, saying that no service implements the tModel you
selected, in which case click Back and select another service. From the Service page, click Next to display the
Finish page.

10
The wizard displays a report of the Web service you have found. Click Finish to display the Find Web Services
wizard dialog.
.

11.
Leave Generate stub code into project FindWebService.jpr to invoke this service selected, and click OK.
The Web Service Stub/Skeleton wizard is launched.

If Generate stub code to invoke this service is not displayed on the final dialog, it means that although the
UDDI browser has located a Web service that appears to meet your requirements, it has failed the validation that
the Web Services Stub/Skeleton wizard performs. There are a number of reasons why this can happen.
The most obvious reason is that although the Web service is registered in the UDDI registry, there is no WSDL at
the location specified. If this happens, click Cancel on the dialog, and use the Back button in the wizard to find
another Web service.
Another reason could be that the proxy settings in the browser do not match the proxy settings in JDeveloper.

Now that you have used JDeveloper's UDDI browser functions to locate a Web service, you can use the Web
Service Stub/Skeleton wizard to create a stub to that service.
10.

Creating a Stub to Use the Web Service

Back to List
The next step is to use the Web Service Stub/Skeleton wizard to create a proxy or stub to the service. To
create a stub, perform the following:
1.
In the Generate Web Services Stub/Skeleton wizard, if the Welcome page is displayed, click Next to display the
Select Web Service Description page.

2.
The URL of the Web service description (the WSDL Document URL) is already entered. Do not change it.
Leave Generate Client-Side Stubs selected, and select Generate Main Method into Stub. This will make it
easy for you to test your stub. Click Next to display the Select Stubs/Skeletons to Generate page.

3.
Click on the Web service (the second line in the pane identified by
). The Service Name is displayed, and
defaults are shown for the Package and the Class Name for the generated stub. Accept the defaults, and
clickFinish.

The business providing the service is added to the Connections Navigator under the UDDI registry you used, and
the stub to implement the service, which is called <service_name>Stub.java, is added to the Applications
Navigator under the FindWebService project. Depending on the Web service you chose, JDeveloper may add
other Java classes, which are JavaBeans to implement any complex types that it finds in the Web service.

4.
In the Applications Navigator, double-click the stub <service_name>Stub.java to open it in the Code Editor,
and scroll down until you find
// Add your own code here.
Immediately below that line, add some code that will return a value from the Web service. For example, look for a
method in the stub that returns a String, then add the code:
System.out.println(stub.<methodname>());

Then right-click the Code Editor and choose Make to make the stub.
Note: Depending on the Web Service that you choose, you may receive a compilation error stating that the class
UnknownType is not found. If you receive this error, add the following import statement to the stub and then
recompile:
import com.sun.corba.se.interceptor.UnknownType;
Right-click the Code Editor again and choose Run to run the stub. The stub connects to the Web service, and
returns a value which is displayed in the log window. If the Log Window is not visible, choose View > Log.

11.

Creating and Using a Modeled Web Service

Back to Topic List
This topic shows you how to create a Web service starting off with a modeled Web service. In a development
environment, modeling the service on a class diagram enables you to easily visualize the elements in your
application.
This topic covers the following subtopics:
Modeling a Web Service
Running the Web Service in the Embedded Server
Testing the Web Service

12.

Modeling a Web Service

Back to List
First you will create a new project for your work, then you will create a class diagram, and finally you will create
a Web service from a modeled Java class.
1.
With the WebServicesOBE selected in the Application Navigator, right-click and choose New from the context
menu to display the New Gallery.

2.
In the Categories list, select General, and then in the Items list, select Empty Project, and click OK to open the
Create Project dialog.

3.
Change the name of the project from Project1 to ModelWebService and click OK. The new project is
created and displayed in the navigator.

4.
With the project ModelWebService selected in the navigator, right-click and choose New to open the New
Gallery.

5.
In the General category, select Diagrams, and then in the Items list, select Java Class Diagram. Click OK to
open the Create Java Class Diagram dialog.

6.
Accept the defaults, and click OK. An empty class diagram opens in JDeveloper.

7.
The Component Palette, located in the right section of the JDeveloper window, enables you to select diagram
elements for different palettes. If the Component Palette is not visible, choose View > Component Palette.
Have a look at the list to see the other palettes that are available. For this subtopic you will be using the Java
palette, so ensure that it is the selected palette.

8.
Click Java class in the Component Palette, then click on the class diagram. This creates a modeled Java class.
Resize it so that it is comfortable to work with.

9.
Click below the second line on the class, in the methods compartment, and type
+ getDate() : String

10

Examine the Java class that has been created. If necessary in the navigator, expand ModelWebService,
thenApplication Sources, then mypackage1 and double-click JavaClass1.java. This opens the Java
class in the Code Editor. You can also open the code editor by double-clicking on the class in the class diagram.

11.
Edit the class so that the method is:
public static String getDate()
{
return (new java.util.Date()).toString();
}

12
Return to the class diagram by clicking the Java Class Diagram1 tab above the Code Editor. Right-click the
modeled class and choose Generate > Web Service from the context menu to fast create a Web service from it.
.

13
The new modeled Web service is displayed on the diagram, and the Web service
container MyJavaClass1WSis displayed in the Application Navigator.
.

You now have a class diagram with both a modeled Java class and a modeled Web service, and from that you
have generated the files needed to try out the getDate() method as a Web service in JDeveloper's
embedded OC4J server, as you will do in the next step, or in any instance of OC4J.

13.

Running the Web Service in the Embedded Server

Back to List
Running the Web service in JDeveloper's embedded server is a simple procedure. To run the Web service, do
the following:
1.
On the diagram, right-click the modeled Web service and choose Run Embedded Server from the context
menu.
Alternatively, in the navigator, right-click MyJavaClass1WS and choose Run from the context menu.

2.
The Web service is deployed to JDeveloper's embedded OC4J server and the progress is recorded in the log
window.

14.

Testing the Web Service

Back to List
Now that you have created your Web service and have it running in JDeveloper's embedded server, you can
create a sample Java client to test that the service works as expected.
To create a sample Java client for a Web service stub, perform the following steps:
1.
In the navigator, right-click the Web service container, MyJavaClass1WS to invoke the context menu.
Alternatively, you can right-click the Web service in the class diagram to invoke the context menu.
Select Generate Sample Java Client from the context menu .This
createsEmbeddedMyJavaClass1WSStub.java which is listed in the navigator. The Java class opens in the
Code Editor.

2.
Scroll down until you find:
// Add your own code here.
Immediately below that line, add:
System.out.println("The date and time is " + stub.getDate());

3.
Right-click in the Code Editor and choose Make to make the class.

4.
Right-click again and choose Run to run the class. The log window shows the current date and time which has
been returned from the Web service.

If the log window shows an error at this point it is probably because the stub is not able to connect to the Web
service running in the embedded OC4J server. This can happen if you are running DHCP.
Go to Tools > Preferences and select Web Browser/Proxy to see the current settings. The list of proxy server
exceptions includes 127.0.0.1 and localhost. However, if you look at the stub you have just generated, at the line
starting "private String _endpoint", the actual IP address of your machine is used. The port is 8988, the
port for the embedded OC4J server.

To get the stub to work, you can do one of the following:

Add your machine's IP address to the list of proxy server exceptions. Go to Tools > Preferencesand select Web
Browser/Proxy. Add your IP address to the end of Exceptions.
or
Turn off the proxy server in the dialog, but remember to turn it back on again for the next topic.

15.

Creating and Using a PL/SQL Web Service

Back to Topic List
In this topic you learn to create a Web service based on program units in a PL/SQL package that is stored in
an Oracle database.
This topic covers the following subtopics:
Creating the PL/SQL Package in the Database
Creating the PL/SQL Web Service
Deploying the PL/SQL Web Service
Creating a Stub to Use the Web Service
Creating the PL/SQL Package in the Database
Back to List
This subtopic tells you how to create a package in the database that contains the program unit for which you
will create a Web service. It assumes that you have already defined a database connection to the HR or HR8
user, as described in Prerequisites, and that you have named that connection HRconn. You will not be able to
complete one of the later steps in this tutorial if you use a connection name that contains an underscore.
1.
To create a new project, right-click the WebServiceOBE workspace in the navigator and choose New Project to
open the New Gallery with Projects selected in the Categories list.

2.
Choose Empty Project from the Items list and click OK.

3.
In the Create Project dialog, change Project1 to PLSQLWebService and click OK.

4.
To create the package in the database, with PLSQLWebService selected in the Application Navigator, right-click
and choose New to open the New Gallery.

5.
In the Categories list, expand Database Tier and select Database Files, then select SQL File in the Items list.
Click OK.

6.
In the Create SQL File dialog, change the File Name to wsobe.sql and click OK. The new empty file opens in
the code editor.

7. Copy the code below and paste it into the code editor: Running this SQL file against the Human Resources
schema in the database creates an object type called EMP_REC and a package called EMP_FETCHER.
REM
REM Create object EMP_REC
REM
CREATE or REPLACE type EMP_REC as object
(
employee_id number(6),
last_name varchar2(25),
job_id varchar2(10),
manager_id number(6),
hire_date date,
salary number(8,2),
commission_pct number(2,2),
department_id number(4)
);
/
show errors;
REM
REM EMP_FETCHER package spec
REM
CREATE or REPLACE package EMP_FETCHER as
FUNCTION get_emp(emp_no IN NUMBER) RETURN emp_rec;
END;
/
show errors;
REM
REM EMP_FETCHER package body
REM
CREATE or REPLACE package body EMP_FETCHER as
FUNCTION get_emp(emp_no IN NUMBER) RETURN emp_rec IS
emp_found employees%rowtype;
emp_rtn emp_rec;
BEGIN
SELECT *
INTO emp_found
FROM employees
WHERE employees.employee_id=emp_no;
emp_rtn := emp_rec
(
emp_found.employee_id,
emp_found.last_name,
emp_found.job_id,
emp_found.manager_id,
emp_found.hire_date,
emp_found.salary,
emp_found.commission_pct,
emp_found.department_id
);
RETURN emp_rtn;

END;
END;
/
show errors;
Click the Save button to save the SQL file.

8.
Right-click wsobe.sql in the navigator, and choose Run in SQL*Plus > HRconn. (This assumes that you have
already defined a database connection to the HR or HR8 user, as described in Prerequisites. The example uses
HRconn for the name of that connection, but if you have used a different name, just select the connection that
you defined.) Running this SQL file against the Human Resources schema in the database creates an object
type called EMP_REC and a package called EMP_FETCHER.

If this is the first time you have run a file in SQL*Plus from JDeveloper, a dialog is displayed for you to enter the
path to the SQL*Plus Executable. In the SQL*Plus Executable dialog, enter the path or browse to the location of
the SQL*Plus executable on your machine.

When you click OK, or if you have already defined the path to the SQL*Plus executable, an Oracle SQL*Plus
window opens, and the script is run. You should see the following messages:
Type created.
No errors.
Package created.

No errors.
Package body created.
No errors.
Type exit to close the SQL*Plus window.

9.
In the Connections Navigator, expand the Database node. Expand the connection HRconn, then HR or HR8,
then Packages to find the new package, EMP_FETCHER. It is this that you will use to create the Web service.

Creating the PL/SQL Web Service

Back to List
In this subtopic you create a Web service directly from the new package in the Human Resources schema. To
create the PL/SQL Web service, perform the following steps:
1.
In the Connections Navigator, expand the HRconn node, then the HR or HR8 node, then the Packages node.
Right-click the EMP_FETCHER package and choose Publish as Web Service to launch the Create PL/SQL
Web Service wizard.

2.
If the Welcome page is displayed, review the information and click Next to open the Database Connection and
Package page.

3.
Ensure that the Target Project is WebServiceOBE.jws/PLSQLWebService.jpr.
You cannot change the database connection and database package because you started the wizard from a
specific database package. If you launched the wizard by selecting a project and choosing the wizard from the
New Gallery, you would be able to select the database connection and the package, but you would not be able to
change the project.
Accept the defaults, and click Next to open the Program Units to Publish page.

4.
Select the FUNCTION GET_EMP(IN NUMBER) RETURN EMP_REC program unit, then click Next to open the
Endpoint page.

5.
Accept the defaults, and click Next and then Finish.

JDeveloper connects to the database and creates the Web service. This may take a few seconds.

The generated Web service is listed in the Application Navigator, and the WSDL document is opened in
JDeveloper's XML Editor.

JDeveloper uses JPublisher to translate from PL/SQL to Java, a process which generates several files such as
Java classes and beans to act as a Java wrapper to the PL/SQL. The files that are generated are displayed in the
Structure Pane when you select the Web service in the Application Navigator.

Deploying the PL/SQL Web Service

Back to List
Deploying a J2EE Web service is a simple procedure. To deploy the Web service:
1.
In the Applications Navigator, right-click the WebServices.deploy file and choose Deploy to and
selectWSConnection. If WSConnection is not shown, see steps 4 and 5 of Prerequisites.

The Web service is deployed to the external instance of OC4J and the progress is recorded in the log window.

The final step in Web service development is to use a proxy or stub to the service to check that it works at its
deployed location.

Creating a Stub to Use the Web Service

Back to List
Now that you have created and deployed your Web service, you can create a proxy or stub to the service.
To create a stub, perform the following steps:

1.
With the project PLSQLWebService selected in the Applications Navigator, choose New to open the New
Gallery.

2.
In the Categories list, expand Business Tier and choose Web Services. In the Items list, select Web Service
Stub/Skeleton and click OK to launch the Web Service Stub/Skeleton wizard.

3.
If the Welcome page is displayed, click Next to display the Select Web Service Description page.

4.
From the list, select the URL of the Web service, <location>/MyWebService1.wsdl .
Leave GenerateClient-Side Stubs selected, and select Generate Main Method into Stub. Click Next to display
the Select Stubs/Skeletons to Generate page.

5.
Click Finish.

6.
The new Java class, MyWebService1Stub.java is listed in the navigator and opened in the Code Editor. Scroll
down until you find
// Add your own code here.
Immediately below that line, add:
EmpRecUser1 emp = stub.getEmp(new BigDecimal(111));
System.out.println("ID = "+ emp.getEmployeeId());
System.out.println("NAME = "+ emp.getLastName());
System.out.println("SALARY = "+ emp.getSalary());

7.
Right-click the Code Editor and choose Make to make the stub. Then right-click again and choose Run to run the
stub.

The stub connects to the Web service in the external server using the employee id 111 as a parameter, and
returns information about the employee, which is displayed in the log window.

16.

Using the TCP Packet Monitor to Examine the Web Service

Back to Topic List
This topic shows you how to use the TCP Packet Monitor to examine the request/response packets sent and
received by JDeveloper when you run a stub to a Web service. When you start the TCP Packet Monitor, it
updates the proxy settings in JDeveloper so that all TCP data is sent through an intermediate port and then on
to your original proxy, if one is defined. The proxy settings are restored when you turn the TCP packet monitor
off, or when you exit JDeveloper.

To use the TCP Packet Monitor, perform the following steps:

1.
Display the TCP Packet Monitor window by choosing View > TCP Packet Monitor. The TCP Packet Monitor
window opens. By default it is docked at the lower right of JDeveloper's user interface.

2.
Start monitoring the packets by clicking

3.
Run one of the Web service stubs you have already created. In the navigator, right-click the stub and chooseRun.
The request/response packets are listed in the TCP Packet Monitor.

Note: If no message is shown in the TCP Packet Monitor, check the browser and proxy exception list and ensure
that the local machine name is not listed.
4.
To see the contents of a packet pair, select it in the History page, then click the Data tab.

5.
Use the

and

buttons to examine other packet pairs.

6.
When you are debugging a Web service, you can change the contents of a request packet and resend it so as to
see the changes in the response packet. To try this, make the appropriate change to the request packet, and
click

The amended packet is sent and you can examine the response packet to see the change.

7.
To stop the TCP Packet Monitor, click

8.
To close TCP Packet Monitor window, click the Close icon at the top right of the window.

You can use the TCP Packet Monitor to examine any HTTP traffic to and from JDeveloper.