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.
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.
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.
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. The WebServiceOBE
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.
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:
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.
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
to FindWebService.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.
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 click Finish.
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, chooseView > Log.
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.
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,
then Application 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 MyJavaClass1WS
is 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.
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.
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 creates EmbeddedMyJavaClass1WSStub.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 > Preferences and 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.
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 NewProject
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;
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.
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 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 select WSConnection.
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.
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, chooseNew 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 Generate Client-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
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.
Using the TCP Packet
Monitor to Examine the Web Service
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 >
Bookmark
). The Service Name is displayed, and defaults are shown
for the Package and the Class Name for the
generated stub. Accept the defaults, and click Finish.