building and using web services with jdeveloper 11g

Building and Using Web Services With JDeveloper 11g

Purpose

In this tutorial, you create a series of simple web service scenarios in JDeveloper. This is intended as a light introduction to some of the new web service functionality in Release 2 of JDeveloper 11g

To run the pages successfully, you must use IE7 or Firefox.

Topics

The tutorial covers the following topics:

Overview

Prerequisites

Building a POJO Annotation-Driven Service

Building a Declaratively-Driven POJO Web Service

Building a Web Service from an Existing WSDL

Building an Annotation-Driven EJB Web Service

Developing a Client for a Service Using Proxy Generation

Developing an ADF Client for a Service Using a Web Service Data Control

Summary

Viewing Screenshots

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.

Overview

The following are some core end-to-end scenarios for JDeveloper 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 (Java API for XML Web Services) and annotation handling. JAX-WS enables you to enter annotations directly into the Java source without the need for a separate XML deployment descriptor.

The scenarios test the web services using the integrated server in JDeveloper.

The OBE contains six 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. In the sixth scenario you build an ADF client and add to it a data control based on a web service.

Back to Topic Lis t

Prerequisites

Install Oracle JDeveloper 11g Version 11.1.1.2.0.

Install lab files

Start JDeveloper 11 g

Open a Startup Application and Project

Back to Topic Lis t

Installing Lab files

In the following steps, you install the lab files.

1. The lab files are available here. Save the webservice.zip file in the directory used for this tutorial (such as d:\Temp.)

2. Open the directory where the file is saved, right-click the WebService.zip file and select WinZip --> Extract to here.

Back to Topic

Back to Topic Lis t

Starting JDeveloper 11g

In the following steps, you start the JDeveloper 11g IDE.

1. Start JDeveloper by selecting Start > Programs > Oracle Fusion Middleware > JDeveloper Studio 11.1.1.2.0

2. If the Migrate User Settings dialog box opens, click NO.

If prompted for a User Role, choose Default Role.

Close the Tip of the Day window.

3. The JDeveloper IDE should now be displayed. You can close the Start page by hovering your mouse over the tab and clicking the X that appears.

Back to Topic

Back to Topic Lis t

Opening a Startup Application and Project

1. Select the Application Navigator tab and click Open Application (alternatively, you can select File | Open)

2. In the Open Application dialog box, locate the WebService directory created when unzipping the WebService.zip file and select WebService.jws.

Click Open.

3. The Application Navigator should look like this:

Back to Topic

Back to Topic Lis t

Building a POJO Annotation-Driven Service

Add a Plain Old Java Object (POJO) to contain the Web Service Method

Test the Web Service

Back to Topic Lis t

Add a Plain Old Java Object (POJO) to contain the Web Service Method

In this section you open your project with plain old Java classes. You add a method to return the employees and department information. You annotate a class to define it as a web service. You also add a web method

annotation to define a method as part of the web service. This section shows how to modify the method properties using the Code Editor, Property Inspector, and Structure window. Once you compile the web service and deploy it to the integrated server, you run it in the HTTP Analyzer, which returns the result of the method.

1. In the Application Navigator, expand the Annotation project nodes to show the POJO classes:

Dept.java describes the department structure. Emp.java describes the employee structure. MyCompany.java populates information about department and employees.

2. Double-click MyCompany.java to edit it.

3. Notice the existing data for departments and employees. Add a @WebService annotation after the importstatements. This annotation denotes that the class contains a method to be used by a web service.

In the margin, click the Quick Hint (light bulb icon) and select the Configure project for web services option.

4. In the Select Deployment Platform dialog box, ensure that Java EE 1.5, with support for JAX-WS Annotations is selected.

Click OK. This step adds the javax.jws.WebService import statement to the Java class and creates a web.xml file.

5. The Application Navigator should now look like the following:

Notice that the icon for MyCompany.java class is changed to represent a WebService class, and the web.xml file has been added to your project.

6. Scroll down at the bottom of the class and add the following statements.

public Dept getDeptInfo(int id){ for (Dept a : this.getMyDepts()){ if (a.getId()==id) {

return a; } } return null;}

This loop returns information about all employees working in a specific department.

7. Create a second annotation before the getDeptInfo() method. The annotation signifies this is the method to be exposed from the web service. Add a blank line above the getDeptInfo() method, and start typing @WebMethod. Code insight pops up up a list of available syntaxes. Select WebMethod from the list.

If suggested, press [Alt]+[Enter] to add the import javax.jws.WebMethod; statement (although this statement may be added automatically.)

The class should look like the image below.

8.Click Save All to save your work.

9. You can use the Property Inspector 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.

Note: If the Property Inspector opens in a different part of the IDE, you can drag its tab and drop it on the bottom panel if you would rather work with it there.

10. To display the properties of the MyCompany class in the Property Inspector, select the Source tab at the bottom of the Structure window, then select the top level MyCompany class name.

11. The Property Inspector displays a few finger tabs on the left side of the window. Select the Web Services tab and notice that the Service Name has the word 'Service' appended to the class name. If you don't want to have the service named "MyCompanyService", you can change it, and the class reflects the change.

Change the Service Name to MyCompanyWS.

Click Save All to save your work.

12. In the Code Editor you can see that 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 also.

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 Lis t


In this section you compile, deploy and test the web service. The HTTP Analyzer is the testing mechanism for web services. When you use the HTTP analyzer to test web services, the service is compiled and deployed to the integrated server. The analyzer is then invoked, enabling 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 > Preferencesand then scroll down the list on the left to select the Web Browser and Proxy page. Ensure that the Use HTTP Proxy Server check box is not selected, then click OK.

2. In the Application Navigator, right-click the MyCompany.java node and in the context menu, select Test Web Service.

This option invokes the integrated WebLogic Server, deploys the service, and then starts the analyzer. It may take a few seconds to start WebLogic Server if you are running it 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 editor window displays the URL for the web service, the WSDL URL, and the exposed Operations. Select the MyCompanyPort.getDeptInfo(,) operation from the list.

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 (in this case, only one argument.) When the web service is executed, the Response area shows the results.

4. In the Request area, enter a department number value (10, 20 or 30) in the arg0 field.

In the toolbar area of the analyzer, click Send Request, or click the Send Request button below the argument.

5. The analyzer sends the request to the service, returning after a few seconds the information about employees working in the specified department.

6. Click the HTTP Content tab at the bottom of the editor to look at the xml code.

7. Click the Raw Message tab at the bottom of the editor for another presentation of the code.

8. Click the SOAP Structure tab at the bottom of the editor, and then in the top part of the HTTP Analyzer, click theWSDL URL link.

9. This opens the visual editor for the web service. In the Port Types panel, expand the getDeptInfo | input | getDeptInfo nodes.

10. To the left of the Port Types panel, click the small Plus sign at the top of Messages to show message contents.

A new graphical representation shows the flow for any message you select.

11. Right-click any tab in the editor window and select the Close All option.

Collapse the Annotation project node in the Application Navigator.

Back to Topic

Back to Topic Lis t

Building a Declaratively-driven POJO Web Service

Create a Class Containing a Method to Publish as a Web Service

Test the Web Service by Using the Integrated Server Container

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 annotations 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 with the integrated server, just as you did before . You then deploy the web service to an instance of the integrated server, and 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 select New, and then in the New Gallery select General in the Categories list and Generic Project in the Items list. Click OK.

In the Create Project dialog, name the project Wizard.

Click Finish.

2. In the Application Navigator, right-click the new Wizard project and select New from the context menu.

In the New Gallery select General in the Categories list and Java Class from the Items list to create a new Java class. Name the class HelloService.

By default the package name should be the project name. Ensure that the package name is set to wizard. Leave the rest of the values at their defaults and click OK to invoke the Code Editor.

3. In the class, add the following method:

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 Select Deployment Platform step of the Create Java Web Service wizard, ensure that the Java EE 1.5, with support for JAX-WS Annotations is selected as the deployment platform.

Click Next.

6. In the Generation Options step of the wizard, type MyWebService1 as the Web Service Name, and ensure that the Port Name is set to MyWebService1Port.

Click Next.

7. In the Message Format step of the wizard, select the SOAP 1.2 Binding option.

Click Next.

8. In the Methods step of the wizard, all the possible methods to publish are displayed so that ou can select the ones you wish to publish. Because in this case there is only one, it is selected by default.

The remaining pages are for including any additional classes the service may need, configuring policies for the service, and providing the handler details. You will not change any of these values, so click Finish at any of these screens to create the web service.

9. The class definition is updated with the annotation needed to publish the web service. Make sure that the port name is set to MyWebService1Port, or change it to this value in the editor.


Back to Topic

Back to Topic List

Test the Web Service by Using the Integrated Server Container

In this section you compile, deploy and test the web service. Just as before, you use the HTTP Analyzer for testing the web service. When you test web services using the analyzer, the service is compiled and deployed to the integrated server. The analyzer is then invoked, enabling you to send and receive values from the web service.

1. In the Application Navigator, right-click the HelloService.java node in the Wizard project and select Test Web Service from the context menu.

This option invokes the integrated 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 editor displays the URL for the web service, WSDL URL, and exposed Operations.

3. In the Request area, enter <your name> in the arg0 field and click Send Request.

4. The analyzer sends the request to the service, and after a few seconds the return parameter is displayed.

5. In preparation for the next task of creating a web service from a WSDL file, generate the WDSL to a file. Right-click the HelloService.java class in the Navigator and select Show WSDL for Web Service Annotations.

6. The generation of the WSDL file starts, and then MyWebService1.wsdl displays in the Design editor. You can expand and select the nodes to visualize the flows.

Click the Source tab at the bottom of the editor to look at the xml code.

7. From the menu, select File | Save As...

and save the file in the directory of your choice.

The saved file represents what is deployed to the integrated server.

8. Locate the directory where you saved the MyWebService1.wsdl file and open it in WordPad.

After you examine the file, close the WordPad window.

9. Close all the tabs in the Editor and collapse the Wizard node in the Application Navigator.

Back to Topic

Back to Topic List

Building a Web Service from an Existing WSDL

Create Web Service from a WSDL


Back to Topic List

Create a Web Service from a WSDL

In the previous 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 is the one that in the last section you saved to the file system.

1. Right-click the Annotation project node and select New, and then in the New Gallery select General in the Categories list and Generic Project in the Items list. Click OK.

Name the project TopDown, leaving other values at their defaults. Click Finish.

2. Right-click the new TopDown project and select New.

In the New Gallery, select the Business Tier | Web Services node in the Categories list. Select the Java Web Service from WSDL item and click OK.

3. In the Create Java Web Service from WSDL wizard, click Next to dismiss the Welcome page.

In the Select Deployment Platform step of the wizard, ensure that the Java 1.5, with support for JAX-WS Annotation is selected as the deployment platform, and then click Next.

4. In the Select Web Service Description step, you specify the source WSDL to be used in creating the web service. Click Browse and navigate to the WSDL you earlier saved (should be something like MyWebService1.wsdl). Select it and click Open.

The file path displays in the WSDL Document URL field.

Click Next.

5. Either click Finish to complete the process, or click Next to view all the defaulted options. The image below shows the last page of the wizard.


6. The Application Navigator now displays the Java web service and all the Java files.

The Design of the WSDL displays in the editor.

7. Since the web service is created top down, it creates all the headers, but you need to provide the bodies.

Set the sayHello() method to return something more reasonable. Double-click the MyWebService1Impl.javafile to open it in the editor.

8. Set the return to "Hello " + arg0. This returns the word Hello followed by the value that is entered in the argument.


Back to Topic

Back to Topic List



1. In the Application Navigator, right-click the MyWebService1 node and from the context menu, select Test Web Service.

This option invokes the integrated server, deploys the service, and then starts the HTTP Analyzer.

2. The top portion of the HTTP Analyzer editor displays the URL for the web service, WSDL URL, and exposed Operations.


4. The analyzer then sends the request to the service and after a bit, the return parameter is displayed.

5. Close all the tabs in the editor and collapse the TopDown node in the Application Navigator.

Back to Topic

Back to Topic List

Building an Annotation Driven EJB Web Service

Create a New Project for an EJB 3.0 Session Bean


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. Right-click the Annotation project node and select New, and then in the New Gallery select General in the

Categories list and Generic Project in the Items list. Click OK.

Create a new Generic Project and name it EJB-Anno, leaving other values at their defaults.

Click Finish.

2. Right-click the EJB-Anno project and select New.

In the New Gallery, expand the Business Tier node and select EJB in the Categories list . In the Items column, select Session Bean.

Click OK.

3. In the new Session Bean Wizard, click Next up to Step 4. Accepting the defaults for the EJB Version (Enterprise JavaBeans 3.0), Name and Class Definition pages.

In the EJB Home and Component Interfaces page, deselect both check boxes so that no interfaces are implemented.

Click Next then Finish to create the bean.

4. The SessionEJBBean.java file opens in the editor. Add the same sayHello() method as in previous scenarios:

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 as you did with the POJO.

If requested, press [Alt]+[Enter] to add the import statement (although this statement may be added automatically.)


Back to Topic

Back to Topic List



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 editor displays the URL for the web service, WSDL URL, and exposed Operations.


4. The analyzer then sends the request to the service, and after a bit the return parameter is displayed.

5. Close all the tabs and collapse the EJB-Anno project.

Back to Topic

Back to Topic Lis t

Developing a Client for a Service Using Proxy Generation

Create the Web Service Proxy

Create and Test the Client

Back to Topic List

Create the Web Service Proxy

In this section, you use a wizard to generate a Java proxy for calling a web service. Once complete, you can create a client to connect to it and use it.

1. Right-click the Annotation project node and select New, and then in the New Gallery select General in the

Categories list and Generic Project in the Items list. Click OK.

Create a new Generic Project and name it ClientTester.

2. To use a client, you need to have the HTTP Analyzer up and running with one of your services. If it is not running, expand the Annotation project, and test the MyCompany class in the HTTP Analyzer. Confirm that it is up and working. (You could use any of the web services you created.) If you get errors and the test does not run, shut down JDeveloper and restart it.

Copy the URL from the analyzer. Do not close the HTTP Analyzer's tab.

3. To generate the proxy, right-click the ClientTester project and select New.

In the New Gallery, select the All Technologies tab. Expand the Business Tier node and select Web Services in the Categories list. Select the Web Service Proxy item and click OK.

This action invokes the Create Web Service Proxy wizard.

4. Click Next to dismiss the Welcome page.

In the Select Client Style page, select the JAX-WS Style.

Click Next.

5. In the Select 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, copy the URL from the HTTP Analyzer then paste it into the WSDL Document URL (such ashttp://localhost:7101/WebService-Annotation-context-root/MyCompanyPort).

Then append to the URL: ?WSDL

If you use the URL, then you must select the Copy WSDL into Project checkbox.

Alternatively you can use the browse button to find a WSDL file on your machine like you did earlier (for example,D:\Temp\MyWebService1.wsdl).

Click Next.

6. In the Specify Default Mapping Options, click Next to accept the default values.

In the Port Endpoints, you could change the Endpoint URL to run against a different server. However, you don't want to change this, so just click Next.

7. For the rest of the pages in the wizard, the default values are fine. Either click Next to examine the remaining steps, or click Finish to create the proxy.


9. Expand the ClientTester | Applications Sources | annotation | MyCompanyWSProxy nodes in the Application Navigator, which should look like the image below.

Back to Topic

Back to Topic List

Create and Test the Client

In this section you update the client class to invoke the web service proxy and return the result to the message window.

1. in the Application Navigator, dDouble-click the MyCompanyPortClient.java class to open it in the editor.

2. Add the following code to the main() method of the MyCompanyPortClient class:

Dept dept = myCompany.getDeptInfo(10);System.out.println(dept.getName() + " is at " + dept.getLocation());


3. Test the client. In the Application Navigator, right-click the MyCompanyPortClient.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 MyCompany.java file and select Test Web Service. If you get errors and the test does not run, shut down JDeveloper and restart it.)

The results of the client can be viewed in the ClientTester.jpr -Log window. If successful, you should seeAdministration is at Redwood City.

4. Close all tabs in the editor, close the Run Manager window, and collapse all of the projects in the Application Navigator.

Back to Topic

Back to Topic List

Developing an ADF Client for a Service Using a Web Service Data Control

Create the Web Service Data Control

Create a JSF JSP Page and Include the Web Service

Back to Topic List

Create the Web Service Data Control

In this section you use the WSDL deployed to the integrated 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 you create the data control, any ADF client application can use it.

1. Next you create a new project a little differently than you have previously in this tutorial.

Open the Application Menu by clicking the down arrow to the far right of the Application name and select New Project from the context menu.

In the New Gallery, select Web Project.

Click OK.

2. In the Create Web Project wizard, name the project WebClient. Click Next and Next again.

In the Page Flow Technology step of the wizard, select JavaServer Faces (JSF), and click Next.

In the tag libraries, shuttle the ADF Faces Components 11 from Available Libraries to Selected Libraries.

Click Next.

Click Next and Finish.

3. In the Application Navigator, right-click the WebClient node and select New from the context menu.

In the New Gallery, in the Business Tier select the Web Services node and choose the Web Service Data Controlin the Items list.

Click OK.

4. In the first step of the Create Web Service Data Control wizard, name the data control MyCompanyDC, and then paste the WSDL URL that you copied earlier: http://localhost:7101/WebService-Annotation-context-root/MyCompanyPort

As before, append ?WSDL to the URL. When you press [Tab], the web service for the data control is populated.

Click Next.

5. In the Data Control Operations page, shuttle the getDeptInfo method to the Selected side.

Click Next, then Finish.

The Application Navigator now looks like the following image:


7. Expand the Data Controls accordion in the Application Navigator to expose the MyCompanyDC data control that has just been created.

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 Gallery from the WebClient project.

Expand the Web Tier node and select the JSF sub node. In the Items column, select JSF Page.

Click OK.

2. Name the page Dept_Emp, select the Create as XML Document check box, and checking the Page Template, select the Oracle Three Column Layout.

Click OK.

3. The page opens up in the editor.

4. You now add the data controls for the method. The page should accept a parameter, execute the call to the web service, and return the results in a Master Detail layout.

In the Data Control panel, expand the MyCompanyDC data control and select the getDeptInfo(Integer) method.

Drag the getDeptInfo(Integer) method onto the start facet of the page. When you drop it, a menu is displayed. Select ADF Parameter Form.

5. In the Edit Form Fields window click OK to accept the default values.

Click OK.

6. In the Data Controls panel, expand MyCompanyDC | getDeptInfo(Integer) | Return | Return and select employees.

Drag employees onto the center facet. In the dynamic menu select Master-Detail | ADF Master Form - Detail Table.


8. Right-click within the end facet and select Delete from the context menu.

9. In the Structure window for the page, expand the center facet. Under the center facet, expand theaf:panelGroupLayout - vertical and the af:panelHeader - employees nodes. Right-click the af:table - t1component and select Surround With from the context menu.

In the Surround With window select the Panel Collection and click OK.

10. Expand the panelCollection and select the af:table - t1 component. In the Property Inspector, set the Column Selection property to single.

11. Right-click within the page and select Run from the context menu.

12. The page loads into your browser.

13. In the parameter field enter a department value and click the getDeptInfo button.

14. The related employees are retrieved and displayed.

Congratulations - you have successfully completed this lab!

Back to Topic

Back to Topic Lis t

Summary

In this tutorial you've seen some features of JDeveloper 11g.

You've learned how to:

Build a POJO annotation-driven service

Build a declaratively-driven POJO web service

Build a web service from an existing WSDL

Build an annotation-driven EJB web service

Develop a client for a service using proxy generation

Develop an ADF client for a service by using a web service data control

building and using web services with jdeveloper 11g

Documents