| Oracle® Application Server Web Services Developer's Guide 10g (10.1.3.5.0) Part Number E13982-01 |
|
|
View PDF |
| Oracle® Application Server Web Services Developer's Guide 10g (10.1.3.5.0) Part Number E13982-01 |
|
|
View PDF |
This chapter provides information on how to test your JAX-RPC or REST Web Service deployment. A Web service has deployed successfully if you can invoke its operations. To do this, Oracle Application Server Web Services provides a test page. You can use the Web Services Test Page to perform any of the following tasks:
View the Web service's deployed service description (WSDL)
Exercise Web service operations with different values
Exercise operations for different values for Web service security and reliability
Provide values for HTTP authentication for the request
Perform stress testing
The following sections provide more information on accessing and using the Web Services Test Page:
See Also:
Chapter 12, "Assembling REST Web Services" for more information about REST Web Services.
The following steps describe how to access and use the functionality in the Test Page for a JAX-RPC or REST Web Service. The following sections provide more detail on each step.
Access the Test Page for a Web Service.
You can access the Test Page through Application Server Control or through a Web browser. See "How to Access the Web Services Test Page" for more information on this step.
Select the operation you want to test from the Operation drop down list.
Enter the parameter values for the Web Service operation you want to test.
See "Editing Values in the Test Page" for more information on this step.
(Optional) Enter parameter values to exercise security and reliable messaging features (for JAX-RPC Web services only).
See "Testing WS-Security and Reliable Messaging Features" for more information on this step.
(Optional) Enter HTTP authentication values to access the Web service.
See "Enabling HTTP Authentication for the Web Service Test" for more information on this step.
(Optional) Enter parameters to enable stress testing.
See "Stress Testing the Web Service Operation" for more information on this step.
Click the Invoke button to send the test message to the service endpoint.
You can invoke the request to a JAX-RPC or REST Web service as a SOAP request. For a REST Web service, you can invoke it as a SOAP request, or an HTTP POST or HTTP GET operation. See "Invoking the Web Service Test" for more information on this step.
You can access the Test Page either by entering the URI for a JAX-RPC or REST Web service directly in a Web browser or by using Application Server Control.
To access a Test Page for a JAX-RPC or REST Web service directly, you can enter the address of its service endpoint in a Web browser. The address has the format:
http://host:port/context-root/service
Table 13-1 describes the components of the address.
Table 13-1 URL Components for Accessing the Test Page
You can use Application Server Control to access the Test Page for a particular JAX-RPC or REST Web service. The following steps provide a brief overview of how to use the tool to navigate to the Test Page. For more detailed information, see the topic "Web Services Page" in the Application Server Control on-line help.
Open Application Server Control
Click the Web Services tab on the OC4J: home page.
In the table of Web services, click the Select radio button associated with the Web service application and port that you want to test
Click the Test Service button to open Test Web Service: port_name page.
Enterprise Manager displays the Test Web service page, which lists the Web sites defined in your current environment.
Click the Select radio button to select a Web site listener for the Web service.
Enterprise Manager generates a URL based on information about the context root defined for the application and the Web site you selected. The URL appears in the URL field.
Click the Test Web Service button to open the Web Service Test Page.
If the Web Services Test Page is protected by SSL (Secure Sockets Layer), you must perform some additional configuration steps in order to use it. The steps are different depending on whether OracleAS Web Services is running on Oracle HTTP Server.
If you are running OracleAS Web Services as a standalone application, you only need to add keystore and truststore configuration properties to the opmn.xml file. This is the main configuration file for the Oracle Process Manager and Notification Server (OPMN).
If you are running OracleAS Web Services on Oracle HTTP Server, in addition to editing the opmn.xml file you must export the user certificate in Oracle Wallet and import it to the OC4J keystore as a trusted certificate.
See Also:
Oracle Process Manager and Notification Server Administrator's Guide for more information on OPMN.
Oracle Containers for J2EE Security Guide for more information on keystore and truststore properties.
The following sections describe how to make the necessary changes so that you can access the SSL-protected Test page.
Accessing the SSL-Protected Test Page when OracleAS Web Services Runs as Standalone
Accessing the SSL-Protected Test Page when OracleAS Web Services runs on Oracle HTTP Server
If you are running OracleAS Web Services as a standalone application, follow these steps to access an SSL-protected Web Services Test Page.
Locate the opmn.xml file in your installation.
The opmn.xml file can be found here:
ORACLE_HOME/opmn/conf/opmn.xml
Here, ORACLE_HOME is the directory where you installed OracleAS Web Services.
It is assumed that the file has already been configured for SSL.
Add the following properties to the OC4J start-parameters section of opmn.xml, then save the file. These properties are described in Table 13-2. See Example 13-1 for a sample opmn.xml file that uses these properties.
-Djavax.net.ssl.trustStore=<full path to OC4J keystore file>
-Djavax.net.ssl.trustStorePassword=<OC4J keystore password>
-Djavax.net.ssl.keyStore=<full path to OC4J keystore file>
-Djavax.net.ssl.keyStorePassword=<OC4J keystore password>
Restart OPMN.
For example, the following command will stop, then restart all OPMN processes.
prompt> opmnctl startall
Enter the URL for the Web Service's Test page in a browser.
Enter values to test the service and press Invoke button
You should receive the expected SOAP message response.
Table 13-2 describes the properties supported by Oracle HTTPS for keystores and truststores.
Table 13-2 Keystore and Truststore Properties
| Property Name | Description |
|---|---|
|
javax.net.ssl.keyStore |
Specifies the location and name of the keystore file or wallet file to use as the keystore. This property can be set to point to the text wallet file exported from Oracle Wallet Manager that contains the credentials that are to be used for a specific connection. If no other credentials have been set for the HTTPS connection, then the file indicated by this property is opened when a handshake first occurs. If any errors occur as this file is read, then the connection fails and an If this property has no setting, the application is responsible for verifying that the certificate chain contains a certificate that can be trusted. |
|
javax.net.ssl.keyStorePassword |
This property can be set to indicate the password that is necessary to open the keystore (keystore file or wallet file). |
|
javax.net.ssl.trustStore |
This property is used similarly to javax.net.ssl.keyStore, but specifies the location and name of the keystore file or wallet file to use as the truststore (a file that includes the trusted certificate authorities that a client will implicitly accept). |
|
javax.net.ssl. |
This property is used similarly to |
Example 13-0 illustrates a fragment of an opmn.xml file that contains the keystore and truststore properties. In this example, <ias-component id="default-group"> indicates the start of the OC4J start parameters section.
Example 13-1 opmn.xml Fragment with Keystore and Truststore Properties
<opmn>
...
<ias-component id="default-group">
<process-type id="home" module-id="OC4J" status="enabled">
<module-data>
<category-id="start-parameters">
<data-id="java-options" value=".. -Djavax.net.ssl.trustStore=<full path to OC4J keystore file>, -Djavax.net.ssl.trustStorePassword=<OC4J keystore password>, -Djavax.net.ssl.keyStore=<full path to OC4J keystore file>, -Djavax.net.ssl.keyStorePassword=<OC4J keystore password>, ...>
</category>
...
</module-data>
</process-type>
</ias-component>
...
</opmn>
If you are running OracleAS Web Services on a Oracle HTTP Server, follow these steps to access an SSL-protected Web Services Test Page.
Note:
In this procedure, you use the Oracle Wallet Manager and Java keytool utilities to export and import certificates. A discussion of how to use these utilities is beyond the scope of this manual. For detailed information, see the following resources:For Oracle Wallet Manager, see "Using Oracle Wallet Manager" in the Oracle Database Advanced Security Administrator's Guide. This document is available from the Oracle Server Technologies group.
For the Java keytool utility, see "keytool - Key and Certificate Management Tool" at the following Web site.
http://java.sun.com/j2se/1.4.2/docs/tooldocs/windows/keytool.html
Locate the opmn.xml file in your installation.
The opmn.xml file can be found here:
ORACLE_HOME/opmn/conf/opmn.xml
Here, ORACLE_HOME is the directory where you installed OracleAS Web Services.
It is assumed that the file has already been configured for SSL.
Add the following properties to the OC4J start-parameters section of opmn.xml, then save the file. These properties are described inTable 13-2 in the previous section. See Example 13-1 for a sample opmn.xml file that uses these properties.
-Djavax.net.ssl.trustStore=<full path to OC4J keystore file>
-Djavax.net.ssl.trustStorePassword=<oc4j keystore password>
-Djavax.net.ssl.keyStore=<full path to OC4J keystore file>
-Djavax.net.ssl.keyStorePassword=<oc4j keystore password>
Use Oracle Wallet Manager to export the user certificate from the Oracle HTTP Server wallet file.
You can find the Oracle Wallet manager here:
ORACLE_HOME/bin/owm
The following is a sample path to a wallet file:
ORACLE_HOME/Apache/Apache/conf/ssl.wlt/default/ewallet.p12
You can refer to Oracle Wallet Manager documentation for how to export the certificate.
Use the Java keytool utility to import the certificate into the OC4J keystore as a trusted certificate.
Restart OPMN.
For example, the following command will stop, then restart all OPMN processes.
prompt> opmnctl startall
Enter the URL for the Web Service's Test page in a browser.
Enter values to test the service and press Invoke button
You should receive the expected SOAP message response.
Oracle Application Server Web Services provides a Test Page for each deployed Web service. The Test Page can be used to exercise the operations exposed by either JAX-RPC Web services or REST services.
Figure 13-1 displays the Web Service Test Page for the sayHello operation of the HelloServiceEJB JAX-RPC Web service.
To view a JAX-RPC or REST Web service's WSDL, click the Service Description link. You can use your Web browser's File>Save As operation to save the WSDL locally.
Click the Return button to return to the Test Page.
Figure 13-2 illustrates a fragment of a WSDL for a JAX-RPC Web service.
Figure 13-2 WSDL Fragment for a JAX-RPC Web Service
Figure 13-3 illustrates a fragment of a WSDL for a REST Web service.
Figure 13-3 WSDL Fragment for a REST Web Service
The Test Page enables you to test any of the operations exposed by a JAX-RPC or REST Web service. By default, the editable parameters and attributes of the operation are displayed in an HTML form. Optional parameters and attributes on the form are indicated by a checkbox. Select the checkbox to provide a value for the parameter.
Note:
To distinguish attributes from parameters in the HTML Form, attributes are preceded with an "
@" symbol.Use the Operation drop-down list to select the Web service operation that you want to test.
A "+" link in the form indicates that you can add additional copies of a structure.
An "X" link in the form indicates that you can remove copies of a structure that you do not want.
Instead of entering values for a JAX-RPC or REST Web service operation in an HTML form, you can enter them directly in XML source code. To do this, select the XML Source radio button on the Test Page.
Note:
If you enter values in the XML source, you do not have to precede attributes with @ symbols.
If you enter values for an operation in XML source, then toggle to HTML Form mode, the values you entered will not be preserved. The form will display, cleared of any values.
You can invoke a JAX-RPC Web service operation with different values for security and reliability. To expose these parameters, expand the nodes next to Reliable Messaging and WS-Security.
Note:
REST Web Services, as implemented by OracleAS Web Services, do not support security or reliability features. If you specify any of the security or reliability options for a REST Web service request, they will be ignored.Figure 13-4 illustrates the parameters and default values for security and reliability in the HTML form.
Tip:
After you provide values for the parameters, you can click the XML Source radio button to see the reliability and security headers inserted into the SOAP request.Figure 13-4 WS-Security and Reliable Message Components in the Test Page
Expand the Reliable Messaging node to indicate that reliability features will participate in the test. A reliability SOAP header will be inserted into the SOAP envelope of the request.
You can choose different settings for these parameters:
Duplicate Elimination—turning this feature "on" will insert the Duplicate Elimination reliability header into the message. This tells the reliable endpoint to eliminate duplicates of the message that will be sent. The default value is on.
Guaranteed Delivery—turning this feature "on" will insert the Guaranteed Delivery reliability header into the message. This tells the reliable endpoint that it must acknowledge receiving the message. The default value is on.
Reply To URL—indicates the URL to which acknowledgments and faults will be sent for messages that want asynchronous acknowledgements. The URL is typically the host name of the client, with the port that the listener is on.
Reply Pattern—indicates how the client can interact with the endpoint. The values can be Callback (asynchronous acknowledgment/fault), Response (synchronous acknowledgement/fault), or Polling (the acknowledgment or fault must be polled for). The default value is Polling.
See Also:
"Ensuring Web Service Reliability" in the Oracle Application Server Advanced Web Services Developer's Guide for more information on reliability features.
Select the WS-Security checkbox to indicate that security features will participate in the test. A security SOAP header will be inserted into the SOAP envelope.
You can choose different settings for these parameters:
User Name
Password
See Also:
Oracle Application Server Web Services Security Guide for more information on the security features that are available for OracleAS Web Services.
Expand the Show Transport Info node to display the HTTP Authentication options for the JAX-RPC or REST Web service. If the HTTP service you are testing is password protected, the parameters under Show Transport Info enable you to provide a user name and password. You can also specify a value for SOAP Action in case the service needs to provide any specialized filtering on the SOAP request.
Figure 13-5 illustrates the Show Transport Info parameters in the Test Page.
Figure 13-5 HTTP Authentication and Stress Test Parameters in the Test Page
Expand the Perform Stress Test node to display the options to create and configure a continuous series of invocations of the JAX-RPC or REST Web service operation. The Perform Stress Test options are displayed in Figure 13-5.
Number of Concurrent Threads—The number of concurrent threads on which the invocations should be sent. The default is 10 threads.
Number of Loops—The number of times to invoke the operation. The default is 5 times for each thread.
Delay—Number of milliseconds to wait between operation invocations. The default is 1000 milliseconds (1 second).
When you invoke the test, a stress report page is returned. The report page identifies the service endpoint and operation being tested, the size of the message sent, the number of concurrent threads on which it is run, the number of times it is run on each thread, and the delay between each operation invocation. Figure 13-6 illustrates s fragment of a sample stress test report.
After you have specified the parameter values and functionality you want to test for the operation, you can send the message to the Web service endpoint. For a JAX-RPC Web service, the message is sent to the service as a SOAP request. For a REST Web service, the message can be sent as either a SOAP request, or an XML REST GET, or POST operation.
Click the Invoke button to send the message as a SOAP request to the JAX-RPC Web service endpoint. The Test Page displays the response from the service. The response can be displayed in formatted XML (default) or as raw XML (wire format).
Figure 13-7 Response from a JAX-RPC Web Service
The Test Page for a REST Web service enables you to send the test message to the REST service as either an XML REST POST or GET operation. In addition, OracleAS Web Services allows you the option of sending the message as a SOAP request.
The Test Page provides the following buttons that enable you to invoke the Web service operation on the test message.
Invoke—invokes the request as a SOAP request.
Invoke REST POST—generates and invokes a REST POST request.
Invoke REST GET—redirects the page to the GET URL.
Figure 13-8 illustrates a Test Page for a REST-enabled Web service operation.
Figure 13-8 Test Page for a REST Web Service Operation
Click the Invoke button to send the XML REST request to the service as a SOAP message over HTTP. The service returns a SOAP response message to the Test Page application. The response can be displayed in either formatted XML (default) or raw XML (wire format).
Figure 13-9 illustrates a SOAP response from a REST Web service in formatted XML.
Click Invoke REST POST on the Test Page to send the message to the REST Web service. The response is returned to the Test Page application. The response can be displayed in either formatted XML (default) or raw XML (wire format).
Note:
REST Web Services, as implemented by OracleAS Web Services, do not support security or reliability features. If you specify these options for a REST Web service request, they will be ignored.
REST Web service responses do not include the SOAP Envelope or Body elements.
Figure 13-10 illustrates a REST Web service response from a REST POST operation.
Click Invoke REST GET on the Test Page to send the request to the service as an HTML GET command in the Web browser. The response is displayed in the browser without the Test Page application.
Note:
REST Web Services, as implemented by OracleAS Web Services, do not support security or reliability features. If you specify these options for a REST Web service request, they will be ignored.
REST Web service responses do not include the SOAP Envelope or Body elements.
Figure 13-11 illustrates the REST Web service response from a REST GET operation.
Figure 13-11 Response from a REST GET Operation
Disabling the Test Page allows you to increase security by reducing the externally visible details of an application that exposes Web services.
To disable the Test Page, follow these general steps:
Extract the oracle-webservices.xml deployment descriptor from the JAR file before deployment.
Insert the boolean <expose-testpage> element set to false in the <webservice-description> section of the deployment descriptor.
Example 13-2 illustrates this step.
Replace the edited oracle-webservices.xml deployment descriptor in the JAR file.
Deploy the JAR file as usual.
Note:
WebServicesAssembler will overwrite this entry if you reassemble the Web service with a deployment descriptor passed in with the
ddFileName command.Example 13-2 illustrates a fragment of an oracle-webservices.xml deployment descriptor that disables the Test Page.
If you do not use the Web Services Test Page to get the WSDL file for a Web service, you can obtain it directly.
To obtain the WSDL, use the Web service URL and append a query string. The format for the URL to obtain the WSDL service description is:
http://host:port/context-root/service?WSDL
WSDL can be either uppercase or lowercase. Table 13-1 contains a description of the URL components.
This URL returns a WSDL description in the form service.wsdl. The service.wsdl description contains the WSDL for the Web service named service, located at the specified URL. Using the WSDL, you can build a client application to access the Web service.
For more information on Web services that can use the Web Services Test Page, see the following chapters:
"Using Web Service Providers" in the Oracle Application Server Advanced Web Services Developer's Guide.
For more information on Web service security and reliability, see these resources:
for adding security to a Web service, see the Oracle Application Server Web Services Security Guide.
for adding reliability to a Web service, see "Ensuring Web Service Reliability" in the Oracle Application Server Advanced Web Services Developer's Guide.
|
 Copyright © 2006, 2009, Oracle and/or its affiliates. All rights reserved. Legal Notices |
|