Developing Contract-Driven Web Services Using JDeveloper
Developing Contract-Driven Web Services Using JDeveloper
In this tutorial, you use JDeveloper to develop a Java web service using a top-down approach.
Approximately 30 minutes
This 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, 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.
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.
The top-down web service development paradigm means that you start with the WSDL and generate all the classes and service artifacts using the definition of types and operations in the WSDL. This is more complex to achieve than bottom-up development, which allows existing systems to be wrapped as web services. But is bottom-up development the best approach? Many experts say that SOA is a business-driven architectural style, and for it to be successful it must employ a top-down approach.
In this tutorial you use JDeveloper's tools for end-to-end contract driven development, including WSDL editing, top-down web service generation, Web Services Interoperability (WS-I) conformance, and client creation and testing.
Back to Topic List
Before starting this tutorial, you should:
| 1. |
Have installed the JDeveloper 10g (10.1.3).
|
| 2. |
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.
|
Back to Topic List
To create the WSDL contract document, perform the following steps:
Associating a schema with a WSDL document
| 1. |
In the Application Navigator, right-click the Applications node and select New Application from the context menu.
|
| 2. |
In the Create Application dialog, enter TopDownContractDevelopment as the application name and select the No Template option. Click OK.
|
| 3. |
In the Create Project dialog, enter the Project Name WSDLDocument and click OK.
|
| 4. |
Right-click the WSDLDocument project and select New from the context menu.
|
| 5. |
In the New Gallery, expand Business Tier in the Categories list and select Web Services, then from the Items list select WSDL Document. Click OK.
|
| 6. |
In the Create WSDL Document dialog, enter a WSDL Name of CreditRating, then click OK.
The WSDL document is created and opened in the editor.
|
| 7. |
You now begin to add artifacts to the WSDL definition. To do so, you can use the Structure window in the lower left part of the JDeveloper window, and you can modify what is created by default in the Source tab of the code editor.
In the Structure window, click the Design tab.
|
| 8. |
Right-click Types and select Insert Types from the context menu.
|
| 9. |
Right-click types and select Insert inside types > http://www.w3.org/2001/XMLSchema... from the context menu.
|
| 10. |
From the Insert dialog, select <> schema and click OK.
|
| 11. |
In the editor, click the Source tab and change the line:
<xsd:schema/>
to:
<schema targetNamespace="http://CreditRating.xsd"
xmlns="http://www.w3.org/2001/XMLSchema"
xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"/>
Note: For documentation of the schema element, see the W3C Recommendation. For a description of declaring namespaces, see Namespaces in XML. Both documents are from the World Wide Web Consortium (W3C).
|
| 12. |
Next you add elements to the schema. In the Structure window, right-click schema and select Insert inside schema > element from the context menu.
Elements are like variables that are global to the web service.
|
| 13. |
In the Insert element dialog, enter a name of ssn.
Click the Advanced Properties tab and enter a type of string, then click OK.
|
| 14. |
In a similar fashion, add the following additional two elements by right-clicking schema in the Structure window:
| Element Name |
Type |
| rating |
int |
| error |
string |
You can see that the source code reflects the addition of these elements.
|
| 15. |
In the editor, click the Source tab. Add the following attribute to the <definitions> tag at the beginning of the file:
xmlns:types="http://CreditRating.xsd"
The tag should now be:
<definitions targetNamespace="urn:CreditRating"
xmlns="http://schemas.xmlsoap.org/wsdl/"
xmlns:tns="urn:CreditRating"
xmlns:mime="http://schemas.xmlsoap.org/wsdl/mime/"
xmlns:soap12="http://schemas.xmlsoap.org/wsdl/soap12/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
xmlns:types="http://CreditRating.xsd">
|
Back to Topic
Defining the Service Interface
Now you add the abstract or reusable elements of the WSDL. This is all the developer might create at this stage to allow others to use the WSDL to generate the underlying Java implementation class that they must code to.
You define the service interface by specifying:
- Messages: the XML datatypes that are the in/out parameters of the operation
- PortType: the equivalent of the method signature, including operations and the messages (parameters) that they use
- Bindings: association of a PortType with a specific protocol and data format
In this example, you define one operation for this service that gets the credit rating of the loan applicant. To define the service interface, perform the following steps:
| 1. |
First you add three messages.
In the editor window, click the Design tab of CreditRating.wsdl, then click Switch View so that the Messages element is in the left-most position. This step is not necessary, but makes it easier to see what you are creating first.
|
| 2. |
In the Structure window, select the Design tab.
Right-click Messages and select Insert Message from the context menu.
|
| 3. |
In the New Message dialog, enter the Message Name CreditRatingRequestMessage, then click OK.
|
| 4. |
In the Structure window, right-click message - CreditRatingRequestMessage and select Insert Inside Message > http://schemas.xmlsoap.org/wsdl/ > part.
|
| 5. |
In the New Part dialog, enter a Part Name of ssn and a Part Type of types:ssn.
|
| 6. |
In the same manner as in steps 2 - 5, add the following messages and their corresponding parts:
| Message Name |
Part Name |
Part Type |
| CreditRatingResponseMessage |
rating |
types:rating |
| CreditRatingFaultMessage |
error |
types:error |
After adding the messages, you can click on any element in the Structure window or the Design tab of the editor and you are able to see and modify its values in the Property Inspector.
|
| 7. |
Now you define the PortType, which is the service interface, the equivalent of the method signature that specifies operations and the messages (parameters) that they use.
In the Structure window, right-click PortTypes and select Insert portType.
|
| 8. |
In the New Port Type dialog, enter the Port Type Name of CreditRating, then click OK.
|
| 9. |
Either in the Structure window or in the editor, right-click the CreditRating portType and select Insert inside portType - Credit Rating > operation.
|
| 10. |
In the New Operation dialog, enter the Operation Name processCreditRating.
The Operation Type should be Request Response.
From the Input drop-down list, select tns:CreditRatingRequestMessage, which is one of the messages you defined earlier.
From the Output drop-down list, select tns:CreditRatingResponseMessage, which is another of the messages you defined earlier.
Select Add Fault.
Enter a Fault Name of NegativeCredit.
From the Fault drop-down list, select tns:CreditRatingFaultMessage, which is the third message you defined earlier.
Click OK.
|
| 11. |
Expand the CreditRating Port Type in the WSDL editor to see how the messages are associated with the operation. Click the different components of the operation to see the messages associated with each.
Note that the request message is associated with the input to the process, the response message is associated with the output from the process, and the fault message is associated with the NegativeCredit named fault.
|
| 12. |
The final part of creating the service interface is defining the bindings. You bind the Port Type to a specific protocol (HTTP) and data format (SOAP).
In the Structure window, right-click Bindings and select Insert binding from the context menu.
|
| 13. |
In the New Binding dialog, enter a binding Name of CreditRatingSoapHttp.
Leave all other fields as defaults. The Port Type defaults to the Port Type that you created.
Click OK.
|
| 14. |
In the design editor, expand the binding that you just created to see the details.
Notice that when you click any element, the Design tab of the editor shows its relationship to other elements.
|
| 15. |
In the editor, click the Source tab.
Scroll to the NegativeCredit fault definition toward the end of the file. Change the line:
<soap:body use="literal" parts="ssn"/>
to:
<soap:fault use="literal" name="NegativeCredit"/>
|
Back to Topic
Defining the Service Implementation
The final step in creating a WSDL document is to create the service implementation definition. This definition includes the port that specifies the binding that a particular implementer is going to implement and possibly the server where the service will run.
To define the service implementation, perform the following steps:
| 1. |
In the Design tab of the Structure window, right-click Services and select Insert service from the context menu.
|
| 2. |
In the Insert Service dialog, enter a name of CreditRatingService, then click OK.
|
| 3. |
In the Structure window, right-click service - CreditRatingService, then from the context menus select Insert inside service > http://schemas.xmlsoap.org/wsdl/ > port.
|
| 4. |
In the New Port dialog, enter a Port Name of CreditRatingServiceSoapHttpPort. The Binding Name defaults to the binding that you created. Click OK.
|
| 5. |
In the Structure window, right-click port - CreditRatingServiceSoapHttpPort, then from the context menu select Insert inside port > soap:address.
|
| 6. |
In the Insert Address dialog, enter any string, such as tbd, because it is not necessary at this stage to specify where the finished service will run. Click OK.
|
| 7. |
In the Application Navigator, right-click CreditRating.wsdl and select Validate WSDL from the context menu.
The Message tab in the log window tells you if there are any errors, and the Source tab in the Structure window gives you details of any errors.
|
| 8. |
In the WSDL editor, click the Source tab, then right-click in the code and select Reformat from the context menu to tidy up the XML layout.
|
| 9. |
Click Save All  to save your work. |
Back to Topic
Back to Topic List
For guaranteed interoperability between different web services systems, the WS-I Basic Profile enables you to test your service for compliance. The Web Services Interoperability Organization (http://www.ws-i.org) is dedicated to promoting interoperability of web services across platforms, operating systems, and programming languages. Support for the WS-I Basic Profile is a baseline for interoperable web services.
To ensure that the WSDL is compliant, perform the following steps:
| 1. |
Download the Basic Profile Testing Tools from this location. The file to download is the Java link under the heading Interoperability Testing Tools 1.1.
After downloading, unzip the file to your hard drive.
|
| 2. |
In JDeveloper select Tools > Preferences from the menu.
In the Preferences dialog, select WS-I Testing Tools in the tree on the left side.
On the right side, click Browse and navigate to the location where you unzipped the downloaded file. Select the location and click Select.
Select Specify Test Assertions Document.
Click Browse and navigate to the \common\profiles subdirectory of the location where you unzipped the downloaded file. Select the BasicProfile_1.1_TAD.xml file and click Open.
Click OK.
|
| 3. |
In the Application Navigator, right-click CreditRating.wsdl and select WS-I Analyze WSDL from the context menu.
|
| 4. |
In the WS-I Analyze Web Service wizard, click Next on the Welcome page, then accept the defaults and click Finish on the Validate WSDL page.
The WS-I report appears in the editor.
|
| 5. |
In the editor for wsi-report.html, scroll down to the Summary section. It should show that the WSDL has passed.
|
Back to Topic List
To generate the web service, perform the following steps:
| 1. |
In the Application Navigator, right-click the TopDownContractDevelopment application and select New Project from the context menu.
In the New Gallery, select Empty Project in the Items list and click OK.
|
| 2. |
In the Create Project dialog, enter a Project Name of Service, then click OK.
|
| 3. |
Right-click the Service project and select New from the context menu.
In the New Gallery, expand Business Tier and select Web Services in the Categories list, then select Java Web Service from WSDL in the Items list. Click OK.
|
| 4. |
Click Next on the Welcome Page of the Create J2EE 1.4 Java Web Service from WSDL wizard.
On the Web Service Description page of the wizard, from the WSDL Document URL drop-down list select the CreditRating.wsdl that you just created, which populates the Service Name. Click Next.
|
| 5. |
On the Default Mapping options page of the wizard, you could click Next to page through all the options. However, because you are accepting all the defaults, you can just click Finish.
Now you have a full web service and all the JAX-RPC files to deploy and run the service.
|
| 6. |
In the Application Navigator, expand Application Sources and the service package under the Service project.
Note that JDeveloper has created a new service called CreditRatingService. Select CreditRatingService in the Application Navigator to see other associated files displayed in the Structure window.
|
| 7. |
The CreditRatingService.wsdl file opens in the editor. Click the Design tab. Under Services, expand CreditRatingService and CreditRatingServiceSoapHttpPort.
Select soap:address and look at its Property Inspector. You can see that the location, which you had specified as tbd, has now defaulted to your local machine. This changes depending on where you actually deploy the service. This soap address, or endpoint, is the location (URI) of the web service on the network.
By default, JDeveloper creates WSDLs with an endpoint that uses port 8888, because that is the default that would be used with an external server. Because you are testing the web service with the embedded (not external) OC4J, you should change the default port number to the port being used by the embedded OC4J server. To see what port that is, you can invoke Tools > Embedded OC4J Server Preferences, then click Startup in the tree at the left. The port number for the embedded server is shown in the HTTP field. Once you have obtained the port number, you can dismiss the preferences window.
If the soap:address in the WSDL is different from that of the embedded OC4J port, change it to the correct port number.
|
| 8. |
Select CreditRatingService in the Application Navigator and in the Structure window double-click CreditRatingImpl.java to open it in the editor. Notice that it takes a String as a parameter and that the name of the parameter is ssn, which is the name of the Message parameter that you created earlier.
You need to add the actual implementation of the method. Replace:
return 0;
with:
int id;
try
{
// Parses integer value of first 3 numbers form SSN
id = Integer.parseInt(ssn.substring(0,3));
}
catch(NumberFormatException e)
{
// if SSN is invalid returns -1
return -1;
}
if(id < 300)
{
// If value of the first 3 numbers from customer SSN is less
// than 300, credit rate is 1.
return 1;
}
else if(id < 600)
{
// If value less than 600, credit rate is 2.
return 2;
}
else if(id <900)
{
// If value less than 900, credit rate is 3.
return 3;
}
else
{
// Otherwise, credit rate is 0.
return 0;
}
|
| 9. |
You also need to ensure that CreditRatingImpl.java correctly implements the endpoint interface CreditRating.java.
In the interface, the processCreditRating() method throws a CreditRatingFaultMessage exception, so check to see that the processCreditRating() method in CreditRatingImpl.java also throws a CreditRatingFaultMessage exception. If it does not, add the following code to the processCreditRating() method signature in CreditRatingImpl.java:
throws CreditRatingFaultMessage
Click Save All to save your work.
|
| 10. |
In the Application Navigator, right-click CreditRatingService and select Run from the context menu. This deploys the web service to JDeveloper's embedded OC4J server. You should see a message in the log window indicating that the web service has been started.
|
Back to Topic List
Now you test the web service by creating a client to call it. To test the web service, perform the following steps:
| 1. |
In the Application Navigator, right-click the TopDownContractDevelopment application and select New Project from the context menu.
In the New Gallery, select Empty Project in the Items list and click OK.
|
| 2. |
In the Create Project dialog, enter a Project Name of Client, then click OK.
|
| 3. |
Right-click the Client project and select New from the context menu.
In the New Gallery, expand Business Tier and select Web Services in the Categories list, then select Web Service Proxy in the Items list.
This uses the web service's WSDL to generate a client proxy that has all the public available data interfaces as the web service. Client applications can then use the proxy object to access the web service.
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, select CreditRatingService.wsdl from the drop down list. Selecting this file populates the other fields.
You can click Next to tab through the pages if you wish. However, you are accepting all defaults, so you can just click Finish.
The file CreditRatingServiceSoapHttpPortClient.java is created and automatically opened in the editor window.
|
| 5. |
You need to add code to call the web service. In the code editor, after the line:
// Add your own code here
Add the following code:
int rating = myPort.processCreditRating("78964022");
System.out.println("Credit Rating is " + rating);
|
| 6. |
Click Run  . The web service returns its results to the log window.
|
Back to Topic List
In this tutorial you used JDeveloper's WSDL editor to develop a web service with the top-down approach. You tested the WSDL that you created for WS-I compliance and you tested the web service by creating and running a web service client proxy.
Back to Topic List
To learn more about using web services, refer to:
Place the cursor over this icon to hide all screenshots.
|
Bookmark
