| Oracle® Application Development Framework Developer's Guide For Forms/4GL Developers 10g Release 3 (10.1.3.0) Part Number B25947-02 |
|
|
View PDF |
| Oracle® Application Development Framework Developer's Guide For Forms/4GL Developers 10g Release 3 (10.1.3.0) Part Number B25947-02 |
|
|
View PDF |
This chapter contains advice for using web services with ADF projects, and general advice for creating and using web services in JDeveloper
This chapter includes the following sections:
Section 33.4, "Publishing Application Modules as Web Services"
Section 33.5, "Calling a Web Service from an Application Module"
Web services is the term for a technology that consists of a set of messaging protocols and programming standards that expose business functions over the Internet using open XML-based standards, and an individual web service is a discrete, reusable software component that is accessed programmatically over the Internet, using HTTP or sometimes SMTP, to return a response.
Web services allow enterprises to expose business functionality irrespective of the platform or language of the originating application because the business functionality is exposed in such a way that it is abstracted to a message composed of standard XML constructs that can be recognized and used by other applications.
Oracle ADF has built in support to use web services as business service providers in applications. For example, an application could:
Use some functionality in an application run by another company and exposed as a web service to provide business-to-business e-commerce.
Use web service made available through a site such as Xmethods.com to provide some standard functionality.
Find a web service that provides the specified functionality in a UDDI registry and use it at runtime.
You can use Oracle ADF to build applications that target one or all of the tiers in the J2EE platform using your choice of implementation technologies. Using ADF business components to implement your business services, you gain the additional flexibility to be able to expose parts of your application as web services at any time without code changes.
Factors influencing the decision to deploy a component as a web service are:
Web services separate the application from the underlying architecture.
Web services are lightweight, which can result in improved performance across the Internet or an intranet.
Web services technology is designed to use the Web infrastructure, including HTTP.
It is useful to describe the XML standards on which web services are based.
The Simple Object Access Protocol (SOAP) is a lightweight XML-based protocol that is used for the sending and receiving over messages of a transport protocol, usually HTTP or SMTP. The SOAP specification, which you can see at web site of the World Wide Web Consortium, provides a standard way to encode requests and responses. It describes the structure and data types of message payloads using XML Schema.
A SOAP message is constructed of the following components:
A SOAP envelope that contains the SOAP body, the important part of the SOAP message, and optionally a SOAP header.
A protocol binding that specifies how the SOAP envelope is sent, that in the case of web services generated in JDeveloper, is via HTTP.
Web services use SOAP, the XML protocol for expressing data as XML and transporting it across the Internet using HTTP, and SOAP allows for more than one way of converting data to XML and back again. JDeveloper supports SOAP RPC encoding, SOAP RPC-literal style, and document-literal style (also known as message style).
The web services you create in JDeveloper can be either for deployment on Oracle SOAP, which is based on Apache SOAP 2.2 and is part of the Oracle Application Server, or to the SOAP server, which is one of the OC4J containers in Oracle Application Server.
The Web Services Description Language (WSDL) is an XML language used to describe the syntax of web service interfaces and their locations. You can see the WSDL v1.1 specification at the web site of the World Wide Web Consortium. Each web service has a WSDL document that contains all the information needed to use the service, the location of the service, its name, and information about the methods that the web service exposes. When you use one of JDeveloper's web service publishing wizards to produce your web service, the WSDL document for your service is automatically generated.
Universal Description, Discovery and Integration (UDDI) provide a standards-based way of locating web services either by name, or by industry category. UDDI registries can be public, for example the public UDDI registries that are automatically available from JDeveloper, or private, such as a UDDI registry used within an organization. This version of JDeveloper only supports web service discovery using UDDI, however future versions will provide full support for UDDI registration. You can see the UDDI v2 specification at http://www.uddi.org/.
JDeveloper's UDDI browser, in the Connections Navigator, stores information about a UDDI registry and allows you to search a UDDI registry using search criteria that you specify to find web services that are described by WSDLs.
You can create your own registry connections to another public UDDI registry, or to a private UDDI registry within your organization. This creates a connection descriptor properties file that contains the enquiry endpoint and the business keys of the registry. You can find this file at <JDEV_INSTALL>/system<release_and_build_number>/uddiconnections.xml, where <JDEV_INSTALL> is the root directory in which JDeveloper is installed.
JDeveloper's Find Web Service wizard browses UDDI registries to find web services by either name or category. You must have an appropriate connection from your machine so that JDeveloper can make a connection to the UDDI registry you select, for example, a connection to the internet if you want to search a public UDDI registry, and you can only generate a stub to a web service that has a tick in the Is WSDL? column that identifies the registry entry as being defined by a WSDL document.
When you use UDDI registries a term you will come across, and that you may be unfamiliar with, is tModel, short for Technical Model. This represents the technical specification of a web service, and when you search for a web service using the Find Web Service wizard, the wizard also displays other web services that are compatible with the same tModel.
The data structure types used in UDDI are:
Service Details This section gives information about the service, including the name.
Business Entity This is the top-level data structure called businessEntity that contains information about the business providing the web service.
Service Bindings contains the bindingTemplate, that contains information about the service access point, and the tModel that gives the technical specification of the web service.
When the Find Web Services wizard finds a web service, it lists all web services that are compatible with the same tModel.
A key issue facing web services is how interoperable web services actually are. The key feature of web services is that they use common standards to avoid the problems that earlier solutions to getting different applications to be able to use each other's components, for example CORBA, had. However the standards themselves have been being written at the same time as the organizations have been starting to write, deploy and use web services. This has led to interoperability issues such as web services being written using different standards, for example, not using WSDL to provide web service information.
The Web Services-Interoperability Organization (WS-I) was formed by Oracle and other industry leaders to address these issues of interoperability, and to provide tools so that web services can be tested to see how well they interoperate. JDeveloper helps you to test the interoperability of web services by analyzing a web service for conformity to the WS-I Basic Profile 1.0. First you have to download a WS-I compliant analyzer. There are a number of these available from independent vendors, and one from the WS-I web site. A set of test assertions is used to find out how well a web service conforms to the basic profile, and information is recorded for the following artifacts:
Discovery when a web service has been found using a UDDI registry. If the service has not been found using the Find Web Services wizard, this section of the report returns errors in the Missing Input section.
Description of a web service's WSDL document, where the different elements of the document are examined and non-conformities are reported. An example of a failure in this section is a failure of assertion WSI2703, that gives the message "WSDL definition does not conform to the schema located at http://schemas.xmlsoap.org/wsdl/soap/2003-02-11.xsd for some element using the WSDL-SOAP binding namespace, or does not conform to the schema located at http://schemas.xmlsoap.org/wsdl/2003-02-11.xsd for some element using the WSDL namespace."
Message that tests the request and response messages when the connection is made to the web service and it sends its reply.
For more information about WS-I including the specification, see the web site of The Web Services-Interoperability Organization (WS-I) at ws-i.org.
The most common way of using web services in an application developed using Oracle ADF is to create a data control for an external web service, and a usual reason for this is to add functionality that is readily available as a web service but which would be time consuming to develop with the application, or to access an application that runs on a different architecture.
Also, you can re-use components created by Oracle ADF to make them available as web services for other applications to access.
JDeveloper allows you to create a data control for an existing web service using just the WSDL for the service. You can browse to a WSDL on the local file system, locate one in a UDDI registry, or enter the WSDL URL directly.
Note:
If you are working behind a firewall and you want to use a web service that is outside the firewall, you must configure the Web/Browser Proxy settings in JDeveloper. Refer to the JDeveloper online help for more information.
To create a web service data control:
In the Application Navigator, right-click an application and choose New.
In the New Gallery, expand Business Tier in the Categories tree, and select Web Services.
In the Items list, double-click Web Service Data Control.
Follow the wizard instructions to complete creating the data control.
Alternatively, you can right-click on the WSDL node in the navigator and select the Create Data Control from the context menu.
Web services allow applications to exchange data and information through defined application programming interfaces. SSL (Secure Sockets Layer) provides secure data transfer over unreliable networks, but SSL only works point to point. Once the data reaches the other end, the SSL security is removed and the data becomes accessible in its raw format. A complex web service transaction can have data multiple messages being sent to different systems, and SSL cannot provide the end-to-end security that would keep the data invulnerable to eavesdropping.
Any form of security for web services has to address the following issues:
The authenticity and integrity of data.
Data privacy and confidentiality.
Authentication and authorization.
Non-repudiation.
Denial of service attacks.
The WS-Security specification unifies multiple security technologies to make secure web services interoperable between systems and platforms. The specification can be viewed at http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-soap-message-security-1.0.pdf.
WS-Security addresses the following aspects of web services security issues:
Authentication and Authorization
The identity of the sender of the data is verified, and the security system ensures that the sender has privileges to perform the data transaction.
The type of authentication can be a basic username password pair transmitted in plain text, or trusted X509 certificate chains. SAML assertion tokens can also be used to allow the client to authenticate against the service, or allow it to participate in a federated SSO environment, where in authenticated details are be shared between domains in a vendor independent manner
Data Authenticity, Integrity and Non-Repudation
XML digital signatures, which use industry standard messages, digest algorithms to digitally sign the SOAP message.
Data Privacy
XML encryption that uses industry standard encryption algorithms to encrypt the message.
Denial of Service Attacks
Defines XML structures to time stamp the SOAP message. The server uses the time stamp to invalidate the SOAP message after a defined interval.
Throughout this section the "client" is the web service data control, which sends SOAP messages to a deployed web service. The deployed web service may be:
a web service deployed on OC4J for testing purposes.
web service running on Oracle Application Server.
A web service running anywhere in the world that is accessible through the Internet
An ADF 10.1.3 Web Services data control can be configured for message level security using either Java Key Store (JKS), or the Oracle Wallet. For information on setting up and using Oracle Wallet, see the Oracle Technology Network at www.oracle.com/technology.This section describes:
Creating a keystore using the J2SE 1.4 Keytool utility
Building a keystore private/public key pairs, which are used for encryption and signing.
How to obtain a Certificate to issue digital signatures from a root certificating authority.
How to import the Certificate into the keystore.
How to export the Certificate with the public key for encryption.
This is illustrated by creating two keystores, one to be configured on the server side, and the other on the client side (the data control side).
Note:
The steps outlined in this section for requesting digital certificates is for test purposes only. Deployments intending to use Web Services data control with digital signatures enabled must ensure that trusted certificates are generated compliant to the security policies of the deployment environment.To create a public private key pair that can be used by the client for encryption and signing, at the command prompt run the following:
Example 33-1 Command to Create a Keystore
keytool -genkey -alias clientenckey clientsignkey -keyalg RSA -sigalg SHA1withRSA -keystore client.jks
The keystore utility will prompt you for the keystore password, and then asks questions to determine the distinguished name (DN), which is a unique identifier and consists of the following components:
CN= common name. This must be a single name without spaces or special characters.
OU=organizational unit
O=organization name
L=locality name
S=state name
C=country, a two letter country code
After you answer the questions, the Keytool utility will prompt you for the key password. If the key password is the same as the keystore password, press Enter without entering a value. Otherwise, enter the key password. After you enter the key password, the keystore file client.jks is created in the current directory. It contains a single key pair with the alias clientenckey which can be used to encrypt the SOAP requests from the data control.
Next, create a key pair for digitally signing the SOAP requests made by the data control. At the command prompt run the command again, but use clientsignkey for the alias of the signing key pair.
To list the key entries in the keystore, run the following:
The Keytool utility will prompt you for the store password. Enter the password that was used to create the keystore. Repeat the commands to create a keystore for the server side, and use serverenckey for the encryption key pair, and serversignkey for the signing key pair.
The keytool, by default, generates a self-signed certificate, that is a certificate whose issuer is the same as the generator of the key.
If your public key is to be distributed to the outside world, to allow verification of the digital signatures you have issued, then a trusted Certificate Authority (CA) must issue a certificate vouching your identity on your public key. To do this, create a Certificate request file for the signature key pair you have created and submit the request file to a CA.
At the command prompt, run the following:
Example 33-3 Command to Create a Certificate Request File
keytool -certreq -file clientsign.csr -alias clientsignkey -keystore client.jks
The Keytool utility will prompt you for the store and key passwords. After you enter the passwords, a certificate request is generated in a file called clientsign.csr for the public key aliased by clientsignkey.
When you are developing your application, you can use a CA such as Verisign to request trial certificates. Go to www.verisign.com, navigate to Free SSL Trial Certificate and create a request. You must enter the same DN information you used when you created the keystore. Verisign's certificate generation tool will ask you to paste the contents of the certificate request file generated by the keytool (in this case, clientsign.csr). Once all the information is correctly provided, the certificate will be sent to the email ID you have provided, and you have to import it into the keystore.
Open the contents of the certificate in a text editor, and save the file as clientsign.cer.
You also have to import the root certificate issued by Verisign into the keystore. The root certificate is needed to complete the certificate chain up to the issuer.
The root certificate vouches the identity of the issuer. Follow the instructions in the email you received from Verisign to access the root certificate, and paste the contents of the root certificate into a text file called root.cer.
Once you have the root.cer and clientsign.cer files created, run the following command to import the certificates into your keystore:
The Keytool utility will prompt you for the store password. Next you must import your public key certificate.
Example 33-5 Importing the Public Key Certificate
keytool -import -file clientsign.cer -alias clientsignkey -keystore client.jks
The Keytool utility will prompt you for the store and key password. After entering the passwords, execute the same commands to set up the trusted certificate chain in the server keystore.
Once the certificate chains are set up, the client and sever are ready to issue digitally signed SOAP requests.
Note:
Trusted certificates are mandatory when issuing digital signatures on the SOAP message. You cannot issue digital signatures with self-signed/untrusted certificates in your keystore.
The server must export its public key to the client so the client can encrypt the data it sends to the server. The server can then use its corresponding private key to decrypt the data. The server's public key certificate is imported into the client keystore.
At the command prompt, run the following:
Example 33-6 Command to Export the Server's Public Key Certificate
keytool -export -file serverencpublic.cer -alias serverenckey -keystore server.jks
The Keytool utility will prompt you for the store password.
In the example, serverencpublic.cer contains the public key certificate of the server's encryption key. To import this certificate in the client's keystore, run the following:
Example 33-7 Command to Import Client's Encription Key
keytool -import -file serverencpublic.cer -alias serverencpublic -keystore client.jks
The Keystore utility will prompt you for the store password.
Similarly, the client must export its public key so that it can be imported into the server's keystore, as shown in the following examples:
Example 33-8 Command to Export the Client's Public Key Certificate
keytool -export -file clientencpublic.cer -alias clientenckey -keystore client.jks
The Keytool utility will prompt you for the store password.
Example 33-9 Command to Import the Public Key Certificate
keytool -import -file clientencpublic.cer -alias clientencpublic -keystore server.jks
The Keytool utility will prompt you for the keystore password.
The server and client keystores are now ready to be used to configure security for the web service data control.
Once you have a web services data control in a JDeveloper project, you can define security using the Data Control Security wizard.
To invoke the data control security wizard:
Select the web service data control in the Application Navigator.
In the Structure window, right-click the web service data control, and choose Define Web Service Security.
Consult the following sections for more information, or click F1 or Help in the wizard for detailed information about a page of the wizard.
Figure 33-1 Invoking the Data Control Security Wizard
WS-Security allows for service level authentication by using either username tokens or binary tokens. In addition to these, the web service client can issue SAML assertion tokens that can be used for server side authentication, or for participation in a federated SSO environment.
Figure 33-2 Select the Type of Authentication
Oracle's WS-Security implementation is integrated with JAZN (JAAS) to achieve the authentication. How authentication using a certificate is done depends on the implementation and integration with the platform security system. This section discusses configuring OC4J as the server where the application is deployed.
Note:
When the application is deployed to Oracle Application Server, the administrator should use the security editing tool to add users to the security system, grouping them in the appropriate role and granting appropriate privileges. This example of manually editing
system-jazn-data.xml is just for testing, and not recommended for working applications.For Username Token authentication, username/password pair must be a trusted user entry in the JAZN repository.
For X509 Token authentication, the CN (Common Name) on whom the Certificate is issued must be a trusted user in the JAZN repository.
For SAML authentication, the user must be a valid user in the JAZN repository.
To edit the JAZN repository:
Open <JDEV_INSTALL>/J2EE/home/system-jazn-data.xml and enter the authentication details. For example, for X509 authentication, make an entry under the <users> section similar to:
<user>
<name>King</name>
<display-name>OC4J Administrator</display-name>
<description>OC4J Administrator</description>
<credentials>{903}/LptVQLDeA5sgZFLL5TKlr/qjVFPxB42</credentials>
</user>
Username tokens provide basic authentication of a username/password pair. The passwords can be transmitted as plain text or digest.
Note:
This is not the same as HTTP basic or digest authentication. The concept is similar, but it differs in that the recipient of HTTP authentication is the HTTP server, whereas for the web service data control, the username tokens are passed with the message, and the recipient is the target web service.Oracle's WS-Security implementation is integrated with JAZN (JAAS) to achieve the authentication. The username/password pair must be a trusted user entry in the JAZN repository.
To use username tokens for authentication:
In the Authentication page of the wizard, under Available Operations, select one or more ports or operations to apply the authentication to.
Select the authentication type as the Username Token.
Enter the remaining information required for username authentication.
An X509 certificate issued by a trusted CA is a binary security token which can be used to authenticate the client. The client sends its X509 certificate with a digital signature, which is used by the server for authentication. The X509 certificate chain associated with signature key is used for authentication.
You must have the keystore file, with the root certificate of the CA, installed on the server.
Note:
An X509 certificate can only be configured at port level, unlike the other authentication types that can be configured at port or operation level.To use X509 certificate authentication:
In the Authentication page of the wizard, select the authentication type as the X509 Token.
In the Keystore page of the wizard, and specify the location of the keystore file, and enter the signature key alias and password.
SAML assertion tokens can be used to allow client to authenticate against the web service, or allow the client to participate in a federated SSO environment, where authenticated details can be shared between domains in a vendor independent manner.
Note:
SAML Assertions will not be issued if the user identity cannot be established by JAZN.To use SAML authentication:
In the Authentication page of the wizard, select the authentication type as the SAML Token.
The Subject Name is the username name against which the SAML Assertions will be issued.
You can choose Confirmation method as SENDER-VOUCHES or SENDER-VOUCHES-UNSIGNED:
ISENDER-VOUCHES (default). The SAML tokens must be digitally signed. This is the preferred method to issue SAML tokens. If you choose this confirmation technique, then you must configure a keystore and enter keystore and signature key information on the Keystore page of the wizard.
SENDER-VOUCHES-UNSIGNED. The SAML tokens are transmitted without any digital signatures. If you choose this confirmation technique, then you need not configure a keystore and signature key.
You can configure digital signatures on the outgoing SOAP messages, and verify digital signatures on the incoming message from the web service your application is contacting. You can also enforce an expiration window for the digital signatures.
You can set a digital signature on the outgoing SOAP message at port or operation level in the Message Integrity page of the wizard, and verify the digital signatures from the incoming message of the web service.
To sign the SOAP request, and verify the signature of the SOAP response:
In the Message Integrity page of the wizard, select the appropriate options.
In the Keystore page of the wizard, and specify the location of the keystore file, and enter the signature key alias and password.
When you create a web service in JDeveloper, you can set security options in the Web Services Editor. These are then applied at the server side once the web service is deployed. Refer to the JDeveloper online help for complete information.
Before deploying the web service, run the editor and configure encryption and decryption details on the web service. Ensure that you have specified the client's (that is, the data control's) public key to be used for encryption.
Figure 33-4 Set Encryption and Decryption
You can encrypt and outgoing SOAP message at port or operation level in the Message Confidentiality page of the wizard, and decrypt the incoming message from the web service.
To encrypt the SOAP request, and decrypt the SOAP response:
In the Message Confidentiality page of the wizard, select the appropriate options. The encryption algorithm you select must be the same as that configured on the server side when the web service was deployed.
Enter the server's public key alias to allow the data control to encrypt the key details using the server's public key. In this example, serverencpublic is the server's public key certificate that imported in the key store configuration.
If the web service uses incoming message encryption, select Decrypt Incoming SOAP Response.
In the Keystore page of the wizard, and specify the location of the keystore file, and enter the encryption key alias and password.
How to Create a Keystore described setting up keystores for the client (the web service data control) and for the server (a deployed web service). In the Configure Key Store page of the Data Control Security wizard you enter the information needed for the keystore to be used for data control security.
The final stage of configuring WS-Security for a data control based on a web service is to specify the keystore details. Enter the information to access the client keystore here, and when the wizard is finished the keys configured in the store will be available for signatures and encryption for all requests generated by the data control and all responses processed by the data control.
To set key store access information:
In the Configure Key Store page of the wizard, enter the appropriate values.
Oracle ADF Business Components application modules offer built-in support for web services. Any custom method that you add to the client interface of your application module appears on its web service interface after you enable the optional web service deployment option.
To enable your application module as a web service:
Enable a custom Java class for your application module and add to it one or more custom methods that you want to appear on the web service interface.
Open the Application Module editor and on the Client Interface tab, select one or more custom methods to appear on the client interface.
With the Application Module editor still open, on the Remote panel, select Remoteable Application Module, select J2EE Web Service in the Available list and shuttle it to the selected list.
Then click OK to save your changes.
Once this J2EE Web Service remoteable option of your application module is enabled, every time you dismiss the Application Module editor, JDeveloper synchronizes your web service classes with any changes you made to the application module's client interface.
JDeveloper creates the generated web service class in the server.webservice subpackage of the package where your application module resides. For example, if you application module were named oracle.srdemo.model.SRService, its generated web service class would be named SRServiceServer in the oracle.srdemo.model.server.webservice package.
For each method named someMethod in your application module's client interface, JDeveloper adds a delegator method in the generated web service class that looks like what you see in Example 33-10. The code performs the following basic steps:
Acquires an application module instance from the pool.
Delegates the web service method call to the application module instance.
Returns the result if the method is non-void.
Releases the application module instance to the pool without removing it.
Since the web service code passes false to the releaseRootApplicationModule method of the Configuration object, the application module instance is not removed and remains in the pool ready to handle the next incoming stateless web service method invocation. Then the application pool grows and shrinks with load in the same way the web application will. The only difference is that here the pool is being used in a totally stateless way. For more information on tuning the application module pool, see Chapter 29, "Understanding Application Module Pooling".
Example 33-10 Generated Code for Each Method in Application Module Client Interface
// In YourAppModuleServer.java generated web service class
:
public void someMethod(int p1, String p2) {
AppModuleImpl _am = null;
try {
// 1. Acquire an application module instance from the pool
_am = (AppModuleImpl)Configuration.createRootApplicationModule(
"com.yourcompany.yourapp.YourAppModule", "YourAppModuleLocal");
// 2. Delegate a call to its someMethod() method, passing arguments
_am.someMethod(p1, p2);
// 3. If return of method is non-void, return the result here
} finally {
if (_am != null) {
// 4. Release application module to the pool, without removing it
Configuration.releaseRootApplicationModule(_am, false);
}
}
:
}
JDeveloper creates a web service deployment profile as part of enabling the web service remote option on your application module. To deploy the service, just select Deploy from the context menu of this deployment profile.
Your custom method parameters and return types can use any datatype that implements the java.io.Serializable interface. This excludes the use of any generic ADF Business Components interfaces from the oracle.jbo package like Row or ViewObject. While these types are allowed on the custom interface of an application module, in general, they are not supported for web services. To return collections of data through a web service interface, you will need to create custom data transfer objects that implement the Serializable interface and populate them from the results of your view object query results before returning them in an array.
For example, if you needed to return a single row of the ServiceRequests view object instance in the SRDemo application's SRService application module, you would need to create a new ServiceRequest bean with appropriate bean properties and corresponding getter and setter methods. This class would need to implement the Serializable interface. Since this is just a marker interface, there is no additional implementation required other than adding the implements Serializable keywords to the class definition. Once you have created this bean, you can populate its properties inside the custom method implementation, and then return it as the return value of a custom service method like:
public ServiceRequest findServiceRequest(int svrid)
If you need to return a collection of serializable objects, you can use any type supported by the web service infrastructure. For example, you could return an array of one or more service requests using a custom method signature like:
public ServiceRequest[] findServiceRequests(String status, String technician)
In a service-oriented architecture, sometimes your application module will need to take advantage of functionality offered by a web service. JDeveloper's built-in web services wizards make this an easy task. After creating a web service proxy class using the wizard, calling the service is as simple as calling a method in a local Java object.
A web service can be implemented in any programming language and can reside on any server on the network. Each web service identifies the methods in its API by describing them in a standard, language-neutral XML format. This XML document, whose syntax adheres to the Web Services Description Language (WSDL) described in Section 33.1.2, "WSDL", enables tools like JDeveloper to automatically understand the names of the web service's methods as well as the data types of the parameters they might expect and their eventual return value.
In order to work with any web service, you will need to know the URL that identifies its WSDL document. This URL could be a file-based URL like:
file:///D:/temp/SomeService.wsdl
if you have received the WSDL document as an email attachment, for example, and saved it to your local hard drive. Alternatively, the URL could be an HTTP-based URL like:
http://somerserver.somecompany.com/SomeService/SomeService.wsdl
Some web services make their WSDL document available by using a special parameter to modify the actual service URL itself. So, for example, a web service that expects to receive requests at the HTTP address of:
http://somerserver.somecompany.com/SomeService
might publish the corresponding WSDL document using the same URL with an additional parameter on the end like this:
http://somerserver.somecompany.com/SomeService?WSDL
Since there is no established standard, you will just need to know what the correct URL to the WSDL document is. With that URL in hand, you can then create a web service proxy class to call the service.
To call a web service from an application module, you create a web service proxy class for the service you want to invoke. A web service proxy is a generated Java class that represents the web service inside your application. It encapsulates the service URL of the web service and handles the lower-level details of making the call.
The web service proxy class presents a set of Java methods that correspond to the web service's public API. By using the web service proxy class, you can call any method in the web service in the same way as you work with the methods of any other local Java class.
To call a web service from an application module, you perform three steps:
Create a web service proxy class for the web service.
Create an instance of the web service proxy class in your application module.
Invoke one or more methods on the web service proxy object.
To create a web service proxy class for a web service you need to call, use the Create Web Service Proxy wizard. You'll find it in the Business Tier > Web Services category of the New Gallery. When the wizard appears, follow these steps:
In step 1on the Web Service Description page, enter the URL for the WSDL document that describes the service, then press [Tab].
For example, if the service is created to comply with the latest JAXRPC standard and deployed to an Oracle Application Server, the WSDL URL might look like this:
http://someserver:8888/StockQuoteService/StockQuoteServiceSoapHttpPort?WSDL
If the wizard displays the Next > button enabled, then JDeveloper has recognized and validated the WSDL document. You can click it and proceed to step 3. If the button does not enable, click Why Not? to understand what problem JDeveloper encountered when trying to read the WSDL document. If necessary, fix the problem after verifying the URL and try step 1 again.
In step 5 on the Default Mapping Options page, choose a Java package name for the generated web service proxy class, then click Finish.
JDeveloper generates the web service proxy class in the package you've indicated with a name that reflects the name of the web service port it discovered in the WSDL document. The web service port name might be a nice, human-readable name like StockQuoteService, or could be a less-friendly name like StockQuoteServiceSoapHttpPort. This port name is decided by the developer that published the web service you are using. Assuming that the port name of the service is StockQuoteServiceSoapHttpPort, JDeveloper will generate a web proxy class named StockQuoteServiceSoapHttpPortClient.
The web service proxy displays in the Application Navigator as a single, logical node called WebServiceNameProxy. For example, the node for the StockQuoteService web service above would appear in the navigator with the name StockQuoteServiceProxy. As part of generating the proxy class, in addition to the main web service proxy class that you will use to invoke the server, JDeveloper generates a number of auxiliary classes and interfaces. You can see these files in the Structure window by selecting the web service proxy node in the Application Navigator. The generated files are used as part of the lower-level implementation of invoking the web service.
The only auxiliary generated classes you will need to reference are those created to hold structured web service parameters or return types. For example, imagine that the StockQuoteService web service has a quoteForSymbol() method that accepts one String parameter and returns a floating-point value indicating the current price of the stock. If the designer of the web service chose to return a simple floating-point number, then the web service proxy class would have a corresponding method like this:
public float quoteForSymbol(String symbol)
If instead, the designer of the web service thought it useful to return multiple pieces of information as the result, then the service's WSDL file will include a named structure definition describing the multiple elements it contains. For example, assume the service returns both the symbol name and the current price as a result. To contain these two data elements, the WSDL file might define a structure named QuoteInfo with an element named symbol of String type and an element named price of floating-point type. In this situation, when JDeveloper generates the web service proxy class, the Java method signature will look like this instead:
public QuoteInfo quoteForSymbol(String symbol)
The QuoteInfo return type references one of the auxiliary classes that comprises the web service proxy implementation. It is a simple bean whose properties reflect the names and types of the structure defined in the WSDL document. In a similar way, if the web service accepts parameters whose values are structures or arrays of structures, then you will work with these structures in your Java code using the corresponding generated beans.
Once you've generated the web service proxy class, you can use it inside a custom method of your application module as shown in Example 33-11.
Example 33-11 Calling a Web Service Method Using the Web Service Proxy Class
// In YourModuleImpl.java
public void performSomeApplicationTask(String symbol) throws Exception {
// application-specific code here
:
// Create an instance of the web service proxy class
StockQuoteServiceSoapHttpPortClient svc =
new StockQuoteServiceSoapHttpPortClient();
// Call a method on the web service proxy class and get the result
QuoteInfo quote = svc.quoteForSymbol(symbol);
float currentPrice = quote.getPrice();
// more application-specific code here
}
When you invoke a web service from an application module, the web service proxy class handles the lower-level details of using the XML-based web services protocol described in Section 33.1.1, "SOAP". In particular, it does the following:
Creates an XML document to represent the method invocation
Packages any method arguments in XML
Sends the XML document to the service URL using an HTTP POST request
Unpackages the XML-encoded response from the web service.
If the method you invoke has a return value, your code receives it as an appropriately typed object to work with in your application module code.
By using the generated web service proxy class, invoking a remote web service becomes as easy as calling a method in a local Java class. The only real distinction to be aware of is that the web service method call could fail if there is a problem with the HTTP request involved. The method calls that you perform against a web service proxy should anticipate the possibility that the request might fail by wrapping the call with an appropriate try...catch block. Example 33-12 improves on the simpler example shown above by implementing the best practice of catching the web service exception. In this case it simply rethrows the error as a JboException, but you could implement more appropriate error handling in your own application.
Example 33-12 Wrapping Web Service Method Calls with a Try/Catch Block
// In YourModuleImpl.java
public void performSomeApplicationTask(String symbol) {
// application-specific code here
// :
QuoteInfo quote = null;
try {
// Create an instance of the web service proxy class
StockQuoteServiceSoapHttpPortClient svc =
new StockQuoteServiceSoapHttpPortClient();
// Call a method on the web service proxy class and get the result
quote = svc.quoteForSymbol(symbol);
}
catch (Exception ex) {
throw new JboException(ex);
}
float currentPrice = quote.getPrice();
// more application-specific code here
}
You will use some web services to access reference information. However, other services you call may modify data. This data modification might be in your own company's database if the service was written by a member of your own team or another team in your company. If the web service is outside your firewall, of course the database being modified will be managed by another company. In either of these situations, it is important to understand that any data modifications performed by a web service you invoke will occur in their own distinct transaction that is unrelated to the application module's current unit of work. For example, if you have invoked a web service that modifies data and then you later call rollback() to cancel the pending changes in the application module's current unit of work, this has no effect on the changes performed by the web service you called in the process. You may need to invoke a corresponding web service method to perform a compensating change to account for your rollback of the application module's transaction.
If the web service you need to call resides outside your corporate firewall, you need to ensure that you have set the appropriate Java system properties to configure the use of an HTTP proxy server. The Java system properties to configure are:
http.proxyHost
Set this to the name of the proxy server.
http.proxyPort
Set this to the HTTP port number of the proxy server (often 80).
http.nonProxyHosts
Optionally set this to a vertical-bar-separated list of servers not requiring the user of a proxy server (e.g. "localhost|127.0.0.1|*.yourcompany.com").
Within JDeveloper, you can configure an HTTP proxy server on the Web Browser and Proxy page of the IDE Preferences dialog. When you run your application, JDeveloper includes appropriate -D command-line options to set the above three system properties based on the settings you've indicated in this dialog.
