Build Web Services
Building Web Services
In this tutorial, you create a series of simple web service
scenarios in JDeveloper 11g. This is intended as a light introduction to some
of the new web service functionality in Release 11 of Developer
To run the pages successfully, you must use IE7 or Fire fox.
The tutorial covers the following topics:
Place
the cursor over this icon to load and view all the screenshots for this tutorial.
(Caution: This action loads all screenshots simultaneously, so response time
may be slow depending on your Internet connection.)
Note: Alternatively, you can place the cursor over
an individual icon in the following steps to load and view only the screenshot
associated with that step. You can hide an individual screenshot by clicking
it.
The following are a set of core end-to-end scenarios for JDeveloper
and OC4J for web service development. The focus of these scenarios is to demonstrate
(and test) Java EE 5 web services. In particular this means JAX-WS and annotation
handling.
The scenarios test the web services using the Integrated OC4J
in JDeveloper.
The OBE contains seven web service scenarios. The first three
create POJO web services, each using a different approach: annotations, declarative
development, and using a WSDL file. The fourth scenario creates a web service
from an EJB 3.0 Session Bean.
The next scenarios focus on the client side. In the fifth
one you create a web service proxy and a simple client to access it, and in
the sixth one you build an ADF client and add a data control, based on a web
service, to it.
In the final scenario, you add policies to the web service.
The first policy writes a message to a log file every time it's accessed. The
second policy enables security to access the web service. In both cases, you
test them using integrated OC4J.
Back to Topic List
Back to Topic List
Set the Environment
Variable for JDeveloper
Before starting you need to set a user variable for JDeveloper
to avoid spaces in the Web Service directory path.
| 1. |
In a Windows environment, open the Control
Panel and select the System folder. In the
System Properties, select the Advanced tab.
Click the Environment
Variables button.
|
| 2. |
In the Environment Variables dialog,
click the New button and in the New User Variable dialog,
enter JDEV_USER_DIR as the Variable Name and enter
a directory of your choice (avoiding space in the path name (i.e c:\JDeveloper\)
Click OK twice to terminate the variable
definition.
(For other OS environments, please refer to the JDeveloper
Installation Guide.)
|
Back to Topic
Back to Topic List
Start JDeveloper 11g
| 1. |
Have access to or have installed Oracle JDeveloper
11g (TP4). You can download it from Oracle
Technology Network. For more details about installing and starting
JDeveloper (for example, system requirements, installing on other operating
systems, configuring where JDeveloper stores projects and user settings,
etc) please refer to the JDeveloper
Installation Guide.
|
| 2. |
Start JDeveloper. Double-click
the JDeveloper executable jdeveloper.exe
found in the root directory (<jdev_home>)
where you unzipped it.
|
| 3. |
If the Migrate User Settings dialog box opens, click
NO.
If prompted for a User Role, choose Default.
Close the Tip of the Day window.
|
| 4. |
The JDeveloper IDE should now be displayed.
|
| 5. |
Set JDeveloper to use the Integrated OC4J. Select
Tools | Java EE Runtime Preferences...
|
| 6. |
In the Preferences dialog, select Integrated
OC4J and click OK.
|
Back to Topic
Back
to Topic List
Create a New Application
and Project
| 1. |
Select the Application tab and click New
Application (alternatively, you can select File | New
to bring up the New Gallery, then select General | Application
to create a new application.)
|
| 2. |
In the Create Application dialog box, set the application name to
WebService.
Leave the Application
Package Prefix property to null.
Select the application
template to No Template [All Technologies]
Click OK.
|
| 3. |
Name the default Project Annotation. Each web service
scenario will be created in its own project. This project will be used
for the annotation web service scenario.
|
| 4. |
The Application Navigator should look like this:
|
Back to Topic
Back to Topic List
Back to Topic List
Add a Plain Old Java
Object (POJO) to contain the Web Service Method
In this section you create a plain Java
class containing a method to return an input value with some text. The class
is annotated to define it as a web service. It then contains an annotation to
define the method as part of the web service. This section shows how to modify
the method properties using the Code Editor, Property Inspector and Structure
pane. Once compiled and deployed to the Integrated OC4J server, the web service
is then run using the HTTP Analyzer which returns the result of the method.
| 1. |
Create the Java class from the Application Navigator. Right click
the Annotation project and select New.
|
| 2. |
In the New Gallery, select the General category,
then select the Java Class item, and press OK.
Name the class HelloService and set the Package
to annotation. The remaining properties can be left
at their default.
Press OK to create the class and display it in the
Code Editor.
|
| 3. |
Following the class definition in HelloService, add a method named
sayHello() that accepts
an input and returns "Hello" and the value of the input.
public String
sayHello (String s) {
return "Hello " + s;
}
Save your work.
|
| 4. |
While still in the class, add an @WebService
annotation before the class definition. This annotation denotes that
the class contains a method to be used by the web service.
|
| 5. |
In the margin, click the Quick Hint (light bulb
icon) and select Configure project for web services.
|
| 6. |
A Select Deployment Platform dialog is invoked. Ensure Java
EE 1.5, with support for JAX-WS Annotations is selected,
then press OK.
This step adds the javax.jws.WebService
import statement, creates a
web.xml file and deployment profile.
|
| 7. |
Back in the class, create a second annotation before the sayHello()
method. The annotation signifies this is the method to be exposed
from the web service. Add a blank line above the sayHello()
method, and start typing @WebMethod.
A popup shows you the available syntaxes. Select WebMethod.
A new import statement is automatically added. The class should look
like the image below.
Save your work.
|
| 8. |
The Property Inspector can be used to modify the characteristics
of the class. In the menu bar, select View | Property Inspector
and it will open as a tab in the bottom portion of the IDE.
|
| 9. |
In the Structure pane, select the Source tab,
then select the top level HelloService class name
and the properties will display in the property inspector.
|
| 10. |
The Property Inspector displays a few finger tabs on the left hand
side of the window. Click the Web Services tab and notice the Service
Name has the word 'Service' appended to the class name. If you don't
want to have the service named "HelloServiceService", you
can change it and it will be reflected in the class.
Change the Service Name to HelloService and save
your work.
Click in the Code Editor to see the @WebService
annotation updated to reflect the new service name. Conversely, changes
in the Code Editor, are synchronized in the Property Inspector. This
functionality is available at the method level, too.
|
| |
You now have a class, defined as a web service that contains an
exposed method. In the next section you test the web service.
|
Back to Topic
Back to Topic List
Test the Web Service
In this section you compile, deploy
and test the web service. The HTTP Analyzer is the testing mechanism for web
services. When you test web services using the analyzer, the service is compiled
and deployed to the Integrated OC4J server. The analyzer is then invoked allowing
you to send and receive values from the web service.
| 1. |
Before testing the web service, check that your web browser settings
are correct.
Choose Tools-->Preferences and then scroll down
the list on the left to select the Web Browser and Proxy
page. Ensure the Use HTTP Proxy Server checkbox is
not selected, then click OK.
|
| 2. |
In the Application Navigator, right click the HelloService.java
node and in the context menu, select Test Web Service.
This option invokes the Integrated OC4J server, deploys the service
and then starts the analyzer. It may take a few seconds to start the
Integrated server if it is being run for the first time. If this is
the first time you test a service, Windows may ask you about blocking
content. Allow the content to be displayed.
|
| 3. |
The top portion of the HTTP Analyzer displays the URL for the
web service, WSDL URL, Service Name and exposed Operations.
The bottom portion of the analyzer is split into two areas: Request
and Response. The request area shows all the arguments from the exposed
method. When the web service is executed, the Response area shows
the results.
|
| 4. |
In the Request area, enter <your
name> in the arg0 field.
In the top area of the analyzer, press the Send Request
button.
|
| 5. |
The analyzer sends the request to the service and after a few
seconds, the return parameter is displayed at the bottom of the area.
|
Back to Topic
Back to Topic List
Back to Topic List
Create the Class Containing
a Method to Publish as a Web Service
In this section you create a new project
and Java class, just as you did earlier. In this scenario, rather than using
annotation to create the web service you use a wizard. The wizard creates all
the necessary files and entries to enable the class as a web service.
Once the wizard steps are complete,
you test the web service using the HTTP Analyzer just as before using the Integrated
OC4J server. You then deploy the web service to a integrated instance of OC4J,
then use a browser rather than the Analyzer to test the service.
| 1. |
Create a new Empty Project. Right click the Annotation
project node and in the New Gallery select Empty Project.
Click OK. In the Create Project dialog, name it
Wizard. Then OK.
|
| 2. |
In the new Wizard project, create a new Java class, named HelloService.
Ensure the package name is set to wizard. Leave the
rest of the values at their defaults and press OK to
invoke the Code Editor. By default the package name should be the project
name.
|
| 3. |
In the class, add the same sayHello method as in the Annotation
scenario. Only this time, do not add the annotation. Save your work.
public String sayHello
(String s) {
return "Hello " + s;
}
At this point you just have a class with some very simple business
logic to return the word Hello followed by the value entered as a
parameter.
|
| 4. |
In the Application Navigator, right click the HelloService.java
node and select Create Web Service. This starts the
wizard to create the class as a web service.
|
| 5. |
In the second step of the wizard, ensure the Java EE 1.5,
with support for JAX-WS Annotations is selected as the deployment
platform, and click Next.
|
| 6. |
The third step of the wizard displays the Web Service Name. Change
it to MyWebService1, and set the Port Name to MyWebService1Port
and click Next.
|
| 7. |
The property values for the fourth step can be left at their defaults.
They control the message format and how attachments are delivered.
Click Next.
|
| 8. |
In the fifth step, all the possible methods to publish are displayed.
You can select the ones you wish to publish. Since there is only one,
and it is selected by default, press Next.
|
| 9. |
The remaining pages allow for defining the handler details, determining
if the service should be stateful and including any additional classes
the service may need. Press Finish at any of these
screens to create the web service.
The class definition is updated with the annotation needed to publish
the web service.
Save all your work.
|
Back to Topic
Back to Topic List
Test the Web Service
using the Integrated OC4J Container
In this section you compile, deploy
and test the web service. Just as before, you use the HTTP Analyzer for the
testing web services. When you test web services using the analyzer, the service
is compiled and deployed to the Integrated OC4J server. The analyzer is then invoked
allowing you to send and receive values from the web service.
| 1. |
In the Application Navigator, right click the HelloService.java
node and in the context menu, select Test Web Service.
This option invokes the Integrated OC4J server, deploys the service
and then starts the analyzer. It may take a few seconds to start the
Integrated server if it is being run for the first time.
|
| 2. |
Just like earlier, the top portion of the HTTP Analyzer displays
the URL for the web service, WSDL URL, Service Name and exposed Operations.
The bottom portion of the analyzer, is split into to areas: Request
and Response. The request area shows all the arguments from the exposed
method. When the web service is executed, the Response area shows
the results.
|
| 3. |
In the Request area, enter <your
name> in the arg0 field.
In the top area of the analyzer, press the Send Request
button.
|
| 4. |
The analyzer sends the request to the service and after a few
seconds, the return parameter is displayed.
|
| 5. |
In preparation for creating a Web Service from a WSDL file, save
the WDSL to a file. Right click the HelloService.java class
in the Navigator and select ShowWSDL for Web Service Annotations.
|
| 6. |
The generation of the wsdl file starts. Then MyWebService1.wsdl
displays in the Design editor.
Click the Source tab at the bottom of the editor
to visualize the xml code.
|
| 7. |
From the menu, select File | Save As... and save
the file in the directory of your choice.
On the Confirm Search dialog, click No.
Saving the file from represents what is deployed to the Integrated
OC4J server.
|
| 8. |
Locate the directory where you saved the MyWebService1.wsdl
file and double click on it to open it.
Close the window. |
Back to Topic
Back to Topic List
Back to Topic List
Create a Web Service
from a WSDL
In the last two sections you created web services using annotation,
and a wizard. In this section you create a web service
from an existing WSDL file. The WSDL file you use, is the one deployed to the
integrated OC4J container from the last section. You need the URL from the browser
during the process. If you closed the browser, run the HTTP Analyzer again and
copy the URL, if necessary, change the port to 8988 and append "?WSDL"
to the end of it. Then use it when prompted by the wizard.
| 1. |
Create a new Empty Project and name it TopDown.
|
| 2. |
Right click the new TopDown project and expand Business
Tier | Web Services nodes. Select the Java web Service
from WSDL item.
Press OK.
|
| 3. |
In the Welcome page, press Next. In the
second step, ensure the Java 1.5, with support for JAX-WS
Annotation is selected as the deployment platform.
Press Next.
|
| 4. |
In the third step, you specify the source WSDL to be used in creating
the web service. Press the Browse button and navigate
to the WSDL you earlier saved (should be something like mywebservice1port.wsdl).
Select it and press Open.
Click Next.
|
| 5. |
The rest of the default values in the wizard can be accepted.
Either click Finish to complete the process, or
click Next to view all the properties. You may specify
the default mappings from the WSDL namespaces to Java packages, add
new JAX-WS and JAXB binding files, provide any handler classes for
messaging. The image below shows the last page of the wizard.
|
| 6. |
Save your work. The Application Navigator now displays the java
web service and all the java files.
|
| 7. |
Since the web service is created top down, it creates all the headers
and you need to provide the bodies. Set the sayHello method to return
something more reasonable. Double click the MyWebService1Impl.java
file.
|
| 8. |
Set the return to "Hello
" + arg0. This returns the word Hello followed
by what ever is entered in the argument.
Save all your work.
|
Back to Topic
Back to Topic List
Test the Web Service
In this section you compile, deploy
and test the web service. Just as before, you use the HTTP Analyzer for the
testing web services. When you test web services using the analyzer, the service
is compiled and deployed to the Integrated OC4J server. The analyzer is then invoked
allowing you to send and receive values from the web service.
| 1. |
In the Application Navigator, right click the MyWebService1
node and from the context menu, select Test Web Service.
This option invokes the Integrated OC4J server, deploys the service
and then starts the analyzer. It may take a few seconds to start the
Integrated server if it is being run for the first time.
|
| 2. |
The top portion of the HTTP Analyzer displays the URL for the
web service, WSDL URL, Service Name and exposed Operations.
The bottom portion of the analyzer, is split into two areas: Request
and Response. The request area shows all the arguments from the exposed
method. When the web service is executed, the Response area shows
the results.
|
| 3. |
In the Request area, enter <your
name> in the arg0 field.
Press the Send Request button.
|
| 4. |
The analyzer then sends the request to the service and after a
bit, the return parameter is displayed.
|
Back to Topic
Back to Topic List
Back to Topic List
Create a New Project
for an EJB 3.0 Session Bean
In this section you create a Session Bean and implement it
as a web service using annotation.
| 1. |
Create a new Empty Project and name it EJB-Anno.
Click OK.
|
| 2. |
Right click the EJB-Anno project and select New.
In the New Gallery, expand the Business Tier node
and select EJB. In the Items column, select Session
Bean and press OK.
|
| 3. |
In the new Session Bean Wizard, accept the defaults for the EJB
Version, Name and Class Definition
pages.
In the EJB Home and Component Interfaces page, do not
implement any interfaces.
Press Finish to create the bean.
|
| 4. |
In the SessionEJBBean.java file, add the same sayHello()
method as in the Annotation scenario. Only this time, do not add the
annotation. Save your work.
public String sayHello
(String s) {
return "Hello " + s;
}
At this point you just have a class with simple business logic to
return the word, Hello, followed by the value entered for a parameter.
|
| 5. |
Above the class definition add the @WebService
annotation, and clicking on the light bubble in the left margin, select
Configure project for web services to generate the
WebService (javax.jws) import statement.
|
| 6. |
Above the sayHello method, add the @WebMethod
annotation just like with the POJO and include the import statement.
Save all your work.
|
Back to Topic
Back to Topic List
Test the Web Service
Using the Integrated OC4J Container
In this section you compile, deploy
and test the web service. Just as before, you use the HTTP Analyzer for the
testing web services. When you test web services using the analyzer, the service
is compiled and deployed to the Integrated OC4J server. The analyzer is then invoked
allowing you to send and receive values from the web service.
| 1. |
In the Application Navigator, right click the SessionEJBBean.java
node and in the context menu, select Test Web Service.
|
| 2. |
Like earlier, the top portion of the HTTP Analyzer displays the
URL for the web service, WSDL URL, Service Name and exposed Operations.
|
| 3. |
In the Request area, enter <your
name> in the arg0 field.
Press any Send Request button.
|
| 4. |
The analyzer then sends the request to the service and after a
bit, the return parameter is displayed.
|
Back to Topic
Back to Topic List
Back to Topic List
Create the Web Service
Proxy
In this section, using a wizard, you generate a Java proxy
for calling a web service. Once complete, you can create a client to connect
to it and use it.
| 1. |
Create a new Empty Project and name it HelloClient.
|
| 2. |
To use a client, you need to have the HTTP Analyzer up and running
with one of your services. Expand the Annotation
project, and Test the HelloService class in the HTTP
Analyzer, and confirm it is up and working. (You could use any of
the web services you created.)
Copy the URL from the analyzer.
Do not close the HTTP Analyzer's tab.
|
| 3. |
To generate the proxy,
right click the HelloClient project and select New.
Ensure the Filter By: property is set to All Technologies.
Expand the Business Tier node and select Web
Services. Select the Web Service Proxy item
and press OK.
This action invokes the Create Web Service Proxy wizard.
|
| 4. |
Press Next in the Welcome page and in the Client
Style page, select the JAX-WS Style.
Press Next.
|
| 5. |
In the Web Service Description page, you determine the location
of the wsdl service. There are two ways you can reference the WSDL:
URL and FIle.
To use the URL, go to the HTTP Analyzer and copy the URL. Paste it
into the WSDL Document URL, and append "?wsdl"
(e.g. http://localhost:8988/WebService-Annotation-context-root/helloserviceport?wsdl).
If you use the URL, then you must select the Copy WSDL into
Project checkbox.
You can also use the browse button to find a wsdl file on your machine
like you did earlier (e.g. D:\temp\mywebservice1port.wsdl).
Press Next.
In the Port Endpoints select Run against
a service deployed to Embedded OC4J.
Press Next.
|
| 6. |
For the rest of the pages in the wizard, the default values are
fine. Either press Next to examine the Asynchronous
Methods, Binding Files, Defined Handlers, Mapping and Support Files
or press Finish to create the proxy.
Save your work. Expand the HelloServiceProxy node, and the Application
Navigator should look like the image below.
|
| 7. |
If you wish to inspect the WSDL, expand the HelloClient
| Web Content | helloserviceport nodes and double click on
the HelloService.wsdl file.
|
Back to Topic
Back to Topic List
Create and Test the
Client
In this section you create a java class
which acts as a client to invoke the web service proxy, and return the result
to the message window.
| 1. |
Select the helloclient.proxy
package and create a new Java Class.
Name it HelloClient, select the checkbox to Generate
Main Method and press OK.
|
| 2. |
Within the Main method of the HelloClient class, add the code
to call the proxy.
First instantiate a port, then print out the result.
HelloService myPort
= new HelloService_Service().getHelloServicePort();
System.out.println(myPort.sayHello("Jeff"));
If prompted, click Alt + Enter to accept the import
statement. Save your work.
|
| 3. |
Test the client. In the Application Navigator, right click the
HelloClient.java file and select
Run. The HTTP Analyzer must be up and running to
process the client request. If it is not up, go back to the Annotation
project, right click the HelloService.java file and select Test
Web Service.
The results of the client can be viewed in the HelloCient.jpr
-Log window. If successful, you should see Hello
Jeff.
|
Back to Topic
Back to Topic List
Back to Topic List
Create the Web Service
Data Control
In this section you use the WSDL deployed
to the integrated OC4J server and create a data control from it. Your application
will not contain the original Java code as in the previous scenarios, it creates
the data control from the deployed WSDL. Once the data control is created, any
ADF client application can use it.
| 1. |
Create a new empty project and name it HelloClientADF.
|
| 2. |
Create a data control to expose the web service. In the new project,
invoke the New Gallery. Expand the Business Tier nodes and select
Web Services. From the Item column, select Web Service Data
Control and press OK.
|
| 3. |
In the first step, name the data control HelloDC,
and then paste in the WSDL URL (http://localhost:8988/WebService-Wizard-context-root/mywebservice1port?wsdl).
You can copy it from the browser, but ensure it is from the integrated
OC4J instance.
When you press the Tab key, the web service for the data control
will be populated. Since there is only one web service in the wsdl,
press Next.
|
| 4. |
In the Data Control Operations page, shuttle the sayHello
method to the Selected side. Press Next, then Finish.
The Application Navigator, now looks like the following image.
Save your work.
|
| 5. |
Expand the Data Control accordion in the Application
Navigator to expose the HelloDC data control.
At this point you are ready to create the JSF JSP page and use the
data controls.
|
Back to Topic
Back to Topic List
Create a JSF Page
and Include the Web Service
In this section you create a JSF page
which contains fields created from the data control, and returns the result
back to the page.
| 1. |
Invoke the New Galley from the HelloClientADF
project. Expand the Web Tier node and select the JSF sub node. In
the Items column, select JSF Page.
Press OK.
|
| 2. |
Name the page HelloClientADF.jsp
press OK.
|
| 3. |
Once the page is opened in the editor add the datacontrols from
the method. The page should accept a parameter, execute the call to
the web service and return the results.
Expand the HelloDC data control and drag the sayHello(String)
method onto the page.
When you drop it, a menu is displayed. Select Methods | JSF
HTML Button.
|
| 4. |
An Action Binding window is invoked and displays the data control
and parameters. Leave them at their default values.
Press OK. This adds a button to the page to call
the operation.
|
| 5. |
Provide an input for the operation. In the Data Controls pane,
expand the HelloDC | sayHello(String) | Parameters nodes
and select the arg0 node.
Drop it on the page as a Text | JSF HTML Input Text.
|
| 6. |
Display the results of the web service in a separate field. In
the Data Control pane, drag the String node onto
the page.
Drop it on the page as a Text | JSF HTML Output Text.
|
| 7. |
Your page should now look something like the screenshot below.
|
| 8. |
Save your work, and run the page. Right click anywhere on the page
and select Run. This page will run in the Integrated
server, and communicate with the web service on the integrated server.
|
| 9. |
Test the page. Type a value in the input box, and click the sayHello
button. The 'hello' message should be displayed in the output field.
|
Back to Topic
Back to Topic List
|
Bookmark