Developing, Deploying and Managing Web Services Using JDeveloper and Oracle Application Server

Purpose
In this tutorial, you use JDeveloper to create and deploy a Java web service and manage it using Application Server Control.

Time to Complete
Approximately 30 minutes

Topics
This tutorial covers the following topics: Overview Scenario Prerequisites Creating the Java Class Creating the Web Service on the Java Class Exploring the WSDL Editor Deploying and Testing the Web Service Managing the Web Service Monitoring the Web Service Summary Related information

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, depending on your Internet connection, may result in a slow response time.) 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
Web services are discrete reusable software components that can be incorporated into applications. They build upon existing XML and HTTP protocols and use the following standards: WSDL (Web Services Description Language): an XML-based language for defining web services SOAP (Simple Object Access Protocol): an XML-based protocol for accessing services on the Web by using XML syntax to send commands over HTTP UDDI (Universal Description, Discovery, and Integration): a universal catalog of web services that enables software to discover and integrate with services on the Web 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 services

tools to create and optionally to monitor web services, and also how to use Application Server Control to manage a web service. Back to Topic List

Scenario
You want to use JDeveloper to develop components for common functions and deploy them as web services. You would also like to be able to manage the web service for such tasks as logging and security, and monitor HTTP requests and responses generated by invoking the web service. Back to Topic List

Prerequisites
Before starting this tutorial, you should: 1. 2. Have installed JDeveloper 10g (10.1.3.1.0). Have started JDeveloper by double-clicking <jdev_home>\jdeveloper.exe. If you receive a message asking if you want to migrate from a previous version, click No. 3. Start Oracle Application Server Containers for J2EE (OC4J) by doubleclicking<jdev_home>\jdev\bin\start_oc4j.bat. If prompted for a password, enter welcome1. Nothing displays as you enter the password. You will have to reenter it on the next line to confirm. If you are not asked for a password, for later steps you will need to know what password was set when OC4J was initially started. Watch the resulting command window and wait until you see the message 'Oracle Containers for J2EE 10g (10.1.3.1.0) initialized'. Then you can minimize the window, but do not close it. Create a connection in JDeveloper to OC4J:

4.

Click the Connections tab (If the Connections tab is not visible, choose View > Connection Navigator from the menu). Right-click the Application Server node and select New Application Server Connection from the context menu. If the Welcome page of the Create Application Server Connection wizard displays, click Next. On the Type page of the wizard, enter the Connection Name of oc4jconn and click Next. On the Authentication page of the wizard, enter a Password of welcome1 (or whatever password was used when OC4J was initially started) and select Deploy Password, then click Next. On the Connection page of the wizard, click Next. On the Test page of the wizard, click Test Connection. After testing, the Status message should display Success!. (If it displays error messages, click Back and correct the connection information that you have entered. ) Click Finish.

Back to Topic List

Creating the Java Class

JDeveloper allows you to use an existing web service or to create one with Java or PL/SQL. In this tutorial, you create a web service that is based on a Java class. To create the Java class for the web service, perform the following steps: 1. In the Applications Navigator, right-click the Applications node and select New Application from the context menu.

2.

In the Create Application dialog, enter the Application Name of JavaWebService. From the Application Template drop down list, select No Template [All Technologies]. Click OK.

3.

In the Create Project dialog, enter a Project Name of GetDates and click OK.

4.

In the Applications Navigator, right-click the GetDates project and select New from the context menu.

5.

In the New Gallery, select the General node in the Categories list, and then in the Items list select Java Class. Click OK.

6.

In the Create Java Class dialog, enter: Name: GetDates Package: datespackage Click OK.

The new Java class is created and displayed in the editor.

7.

In the editor, create a method getDate() that uses java.util.Calendar to return the date and time. public Calendar getDate() { return Calendar.getInstance(); }

8.

Because the code refers to a class that is not yet available to this package, you are prompted to import the class. Press [Alt]+[Enter] to import the suggested class java.util.Calendar.

9.

In the editor, create a second method getDateHence() that uses java.util.GregorianCalendar to add a user-defined number of days, specified as the int parameter daysHence, to today's date. Add the following code below the getDate() method, pressing [Alt]+[Enter] when prompted to importjava.util.GregorianCalendar: public Calendar getDateHence( int daysHence) { GregorianCalendar myCalendar = new GregorianCalendar(); myCalendar.add(GregorianCalendar.DATE, daysHence); return myCalendar; }

10. Click Make to compile the class. The log should show successful compilation.

Back to Topic List

Creating a Web Service on the Java Class

To create a web service based on the Java class that you just created, perform the following steps: 1. Right-click the GetDates project and select New from the context menu.

2.

In the New Gallery, expand Business Tier in the Categories list and select Web Services, then select Java Web Service from the Items list. Click OK.

3.

In the Select J2EE Web Service Version dialog, select J2EE 1.4 (JAX-RPC) Web Service, then click OK.

4.

If the Welcome page of the Create Java J2EE 1.4 Web Service dialog displays, click Next. In the Class page of the wizard

Enter GetDatesWS for the Web Service Name. Select datespackage.GetDates from the Component To Publish dropdown list. Select the "Generate annotations into class" check box. Click Next.

5.

On the Message Format page of the wizard, click Next. On the Specify Custom DataType Serializers page of the wizard, click Next. On the Mapping page of the wizard, click Next. On the Methods page of the wizard, select the check boxes next to both methods from the Available Methods list and click Finish.

6.

If it is not already open in the editor, open the WSDL document for the web service: Under the GetDates project in the Applications Navigator, expand Web Content and WEB-INF\wsdl, then double-click GetDatesWS.wsdl. Another way to open the WSDL is to right-click the GetDatesWS web service in the Applications Navigator and select Go to WSDL from the context menu.

7.

Click the Source tab of the WSDL editor. Scroll to the bottom of the WSDL file to the URL defined in the soap:address node. It should be similar to: http://138.3.51.14:8888/JavaWebService-GetDates-context-root/GetDatesWSSoapHttpPort Select the entire URL in the editor and press [Ctrl]+[C] to copy it to the clipboard. You will use this URL in a later step.

8.

If the file is still open, click the GetDates.java tab at the top of the editor, or reopen the GetDates.java file by doubleclicking it in the Applications Navigator: (JavaWebService > GetDates > Application Sources > datespackage >GetDates.java). Note the Java 5 annotation (line beginning with "@") that has been generated because of the selection you made above. Inclusion of annotations is optional.

9.

Click Save All

to save your work.

Back to Topic List

Exploring the WSDL Editor

There is another way to develop web services that is called contract-driven, or top-down, development. This approach is more responsive to business requirements, rather than simply creating a service layer in a bottomup manner by wrapping existing systems using web services. In JDeveloper, the top-down approach uses the WSDL editor, rather than the wizard, to create a new WSDL and generate all the classes and service artifacts. You will not use contract-driven development in this tutorial. However, now you can examine the WSDL editor to see what the wizard created for you and how all the elements are related. To explore the WSDL editor, perform the following steps: 1. If the file is still open, click the GetDatesWS.wsdl tab at the top of the editor, or reopen the GetDatesWS.wsdl file by double-clicking it in the Applications Navigator: (JavaWebService > GetDates > Web Content > WEBINF\wsdl> GetDatesWS.wsdl) Click the Design tab at the bottom of the editor to view the visual editor.

In the Services column, select the GetDatesWSSoapHttpPort node.

Observe how the content of the Bindings and Port Types columns are now highlighted and connected. Note: You may need to select View | Refresh from the JDeveloper menu in order to see all the connections. To make viewing easier, you can double-click the tab at the top of the editor to maximize the editor window. You can restore the window by double-clicking it again.

2.

In the Bindings column, select the getDate node.

Observe how the getDate binding is linked to the getDate operation in the Port Types column. Note: You may need to select View | Refresh from the JDeveloper menu in order to see all the connections.

3.

Expand the getDateHence binding node, and select the input node.

Observe how the GetDatesWS_getDateHence message (under Messages) is connected to the getDateHence operation (under Port Types), which is in turn connected to the input node of the getDateHence binding. Note: You may need to select View | Refresh from the JDeveloper menu in order to see all the connections. Back to Topic List

Deploying and Testing the Web Service

To deploy and test the web service that you have created, perform the following steps: 1. In the Applications Navigator, expand the Resources node. Right-click WebServices.deploy, and select Deploy to> oc4jconn from the context menu. (Note: This assumes that you have started OC4J and have created a connection to it as described inPrerequisites.)

In the Configure Application dialog, click OK. The log window should show successful deployment.

2.

Open a browser and paste the URL you copied from the WSDL file above, which is the GetDatesWS endpoint page generated by OC4J. The endpoint page for the GetDatesWS displays. Note the dropdown list with links to the two methods: getDate and getDateHence.

Click getDate.

3.

The page displays an area where you can specify parameters for the method. Because this method does not take any parameters, just click the Invoke button to invoke the getDate method of the web service.

4.

After you invoke the web service, the window displays the SOAP envelope containing the test result, which is today's date and time. It looks something like this: <ns0:return>2006-08-23T18:14:00.713+01:00</ns0:return>

5.

Click Back to return to the GetDatesWS endpoint page, then select getDateHence.

6.

The GetDateHence method requires a parameter. In the box provided for the daysHence parameter enter the number 5, to return the date five days hence. ClickInvoke.

7.

After you invoke the web service, the Test Result window displays the date and time five days from today. It looks something like this: <ns0:return>2006-08-28T18:30:20.495+01:00</ns0:return>

8.

Retest the GetDateHence method with a different value:

Click Back to return to the getDatesHence page. In the parameter value field enter the number 365, to return the date a year hence. Click Invoke. The Test Result page contains the result, which is the date and time one year from today. It looks something like this: <ns0:return>2007-08-23T18:32:38.248+01:00</ns0:return>

Leave the browser open for the next section. Back to Topic List

Managing the Web Service

To use Oracle Application Server Control to manage the web service, perform the following steps: 1. Using the same server and port number, in the browser enter the URL for application server control: http://<server>:<port>/em The Application Server Control login screen displays. Enter a username of oc4jadmin and a password of welcome1 (or whatever password was used when initially starting OC4J), then click Login.

2.

On the home page, click the Web Services tab.

3.

Click the GetDatesWSSoapHttpPort link.

4.

You can view performance information from the service port home page. You can see the number of times the web service has been invoked, the number of faults, and the average response time in milliseconds. Click the Operations tab.

5.

On the Operations tab you can view the performance information for the getDate and getDateHence operations: 1. 2. 3. 4. 5. Total Requests Total Faults Response Time Active Requests Highest Concurrent Requests

Click the Home tab

6.

Click Test Service.

7.

Invoke each of the web service operations a few times, as you did in the testing steps 3-8 in the Deploying and Testing the Web Service topic. Now return to the Operations page. You should see that the Total Requests have been incremented according to the number of invocations you made for each operation.

8.

Click the Home tab. You should see that the Invocations value has been incremented to reflect the total number of invocations for both operations.

9.

Click the Administration tab, then click Enable/Disable Features.

10. In the Enable/Disable Features page, Ctrl-click to select Tracing and Auditing from the Available Features list, then click Move to shuttle them to the Enabled Features list.

Click OK.

11. On the Administration tab, click Edit Configuration for the Auditing feature.

12. By default, all auditing is available for both operations. Deselect the check boxes for Request Message, Response Message, and Fault Message for the getDateoperation, leaving the ones for the getDateHence operation selected. Click OK.

. 13. Again invoke each of the web service operations a few times, as you did in the testing steps 3-8 in the Deploying and Testing the Web Service topic. Use Windows Explorer to open the file<jdev_home>\j2ee\home\log\wsmgmt\auditing\log.xml.

14. In the log file you are able to see the invocations of the web service operations (screen shots show Notepad with Word Wrap turned on (Format > Word Wrap):

Header information

Arguments passed to the web service

Values returned by the web service

Note that you see the invocations of the getDateHence operation only, as you specified in the auditing options. When you are finished examining the log file, you can close it. Although you will not do so in this tutorial, another thing that you can do with Application Server Control of web services is to set the inbound security policies for JAX RPC web services deployed in OC4J container 10.1.3. You can set options such as requiring a username/password for authentication, requiring the message body to be signed, and requiring encryption of the message body. These administrative features can also be defined and managed from within JDeveloper. Back to Topic List

Monitoring the Web Service (optional)

This topic shows you how to use the HTTP Analyzer to examine the request/response packets sent and received by JDeveloper when you run a proxy to a web service. When you start the HTTP Analyzer, 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 HTTP Analyzer off, or when you exit JDeveloper. To monitor the web service, perform the following steps: Create a web service proxy Use the HTTP Analyzer Creating a web service proxy 1. To use the HTTP Analyzer, you need to create a web service proxy so that you can run the service from within JDeveloper. You must create the web service proxy in a new project. In the Applications Navigator, right-click the JavaWebService application and select New Project from the context menu.

The New Gallery opens with Empty Project highlighted -- just click OK.

2.

In the Create Project dialog, enter a Project Name of GetDatesWSProxy, then click OK.

3.

Right-click the GetDatesWSProxy project and select New from the context menu. In the New Gallery, expand Business Tier and select Web Services in the Categories list, then in the Items list select Web Service Proxy and click OK.

4.

If the Welcome page of the Create Web Service Proxy wizard displays, click Next. On the Web Service Description page of the wizard, invoke the WSDL Document URL dropdown list and select the WSDL that appears in the tooltip, which is similar to the following (although the initial part of the path is different for your computer): file:/D:/JDev10131/jdev/mywork/JavaWebService/GetDates/public_html/WEBINF/wsdl/GetDatesWS.wsdl Press the [Tab] key to validate the WSDL, then click Next.

5.

On the Port Endpoints page of the wizard, select the option Run against a service deployed to an external server. Select the Port Name and Endpoint URL that appear in the list, then click Next.

6.

Click Next on the next two wizard pages (Custom Mappings and Defined Handlers). On the Default Mapping Options page of the wizard, change the Package Name to datespackage.proxy, then click Next.

7.

Click Next on the Support Files page of the wizard. On the Finish page you should see both methods listed. Click Finish.

The web service proxy generation process creates four directories and numerous files, and opensdatespackage.GetDatesWSSoapHttpPortClient.java in the editor (if this file does not open automatically, double-click it in the Applications Navigator to open it).

8.

In the editor, locate the following line of comment in the main() method: // Add your own code here : Below that line, add the following code: int addDays = 5; System.out.println("The date and time " + addDays + " days hence is: " + myPort.getDateHence(addDays));

Click Make

to save and compile the file.

9. Click Run to run the class.

The message log displays the URL that is called on one line. On the next line it displays your message "The future date and time: " followed by the date as a GregorianCalendar object.

Back to Topic Using the HTTP Analyzer

1.

Display the HTTP Analyzer window by selecting View > HTTP Analyzer. The Http Analyzer window opens. By default it is docked at the lower right of JDeveloper's user interface. Start monitoring the packets by clicking Start in the HTTP Analyzer.

2.

Re-run the class. The request/response packets are listed in the HTTP Analyzer.

3.

To see the contents of a packet pair, select it in the History page, then click the Data tab. The data page shows the value that was sent to the web service in the request information (left panels), and the value returned by the web service in the response information (right panels).

If you have run other things with the HTTP Analyzer started, you can use the Previous Request/Response Pair and Next Request/Response Pair buttons to examine other packet pairs.

4.

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, in the request packet that sent the value 5, change the value to 365. Then click Resend Request .

5.

The amended packet is sent. Click Next Request/Response Pair change.

and examine the response packet to see the

6.

To close HTTP Analyzer window, click the x on the Http Analyzer tab.

Back to Topic

Back to Topic List

Summary
In this tutorial you published a Java class as a web service. You deployed and tested it, then used Application Server Control to manage the web service. You also created a web service proxy for the web service and monitored it with the HTTP Analyzer. Back to Topic List

Related Information
To learn more about using web services, refer to: Service-Oriented Architecture Technology Center on the OTN web site Web Services Management on OTN Web Services Forum on OTN Securing Web Services using JDeveloper and WS-Security on OTN

Place the cursor over this icon to hide all screenshots.