| Oracle® Application Server Advanced Web Services Developer's Guide 10g Release 3 (10.1.3) B25603-01 |
|
 Previous |
 Next |
| Oracle® Application Server Advanced Web Services Developer's Guide 10g Release 3 (10.1.3) B25603-01 |
|
Previous |
Next |
This chapter provides an overview of Web service management for Oracle Application Server Web Services.
Web service management is a set of policies applied against a message en-route to a target. In the case of OracleAS Web Services, the messages are SOAP requests, responses and faults, and the targets are the client and the business logic on the server. OracleAS Web Services supports policies for the following management features.
security—configures authentication, integrity with digital signatures, and confidentiality with encryption based on the WS-Security standard. For more information on the security features supported by OracleAS Web Services, see the Oracle Application Server Web Services Security Guide.
reliability—configures guaranteed message delivery and ordering, and eliminates duplicate messages based on the WS-Reliability standard. For more information on the reliability features supported by OracleAS Web Services, see Chapter 5, "Ensuring Web Service Reliability".
auditing and logging—auditing keeps a complete, persistent record of SOAP requests and faults. Logging enables content-based logging by using XPath to query the inbound and outbound SOAP messages. For more information on the auditing and logging features supported by OracleAS Web Services, see Chapter 6, "Auditing and Logging Messages".
life cycle management—enables and disables services and their managed capabilities. For more information, see "Web Service Management Life Cycle".
deployment—configures the OracleAS Web Services proprietary deployment descriptors based on J2EE 1.4 standards. For more information, see Chapter 18, "Packaging and Deploying Web Services", in the Oracle Application Server Web Services Developer's Guide.
Figure 3-1 illustrates the passage of a SOAP request from the client to the business logic on the server. The SOAP request passes from the client through a layer of management for outbound messages before it is sent over the wire. When it reaches the server, the request must pass through a layer of management configuration for inbound messages before it is used by the business logic. The values given to the server-side management must be coordinated with the values in the client; otherwise, the request might be rejected before reaching the service implementation.
Similarly, the response from the business logic on the server reverses the process. The response must pass through a layer of management for outbound messages before it is sent over the wire. When it reaches the client, the response must pass through a layer of management for inbound messages before the client can use it.
Figure 3-1 Web Services Message Flow with Management Enabled
As Figure 3-1 suggests, Web service management can consist of as many as four separate configurations. The server can have separate configurations for inbound messages (requests) and outbound messages (responses). The client can have separate configurations for outbound messages (requests) and inbound messages (responses).
These management policies can be configured pre-deployment within Oracle JDeveloper. Post-deployment you can configure the policies within the Oracle Application Server Control management environment. For more information see the JDeveloper on-line help and "Overview of Managing Web Services" and "Enabling and Disabling Web Services Management Features" in the Application Server Control on-line help.
Figure 3-2 illustrates the management environment. Three major product components make up this solution: the design time with Oracle JDeveloper or WebServicesAssembler, the runtime with OracleAS Web Services Release 10.1.3, and the management environment with Oracle Application Server Control.
Figure 3-2 Web Services Management Data Flow in the Server
The following steps correspond to the numbers in the figure:
A developer uses Oracle JDeveloper or its command-line counterpart, WebServicesAssembler, to author a Web service and to configure the Web service management information that will be applied at runtime.
JDeveloper (or WebServicesAssembler) can then be used to assemble the Web service and package it in an enterprise archive (EAR). Among other Web service artifacts, the EAR also contains the oracle-webservices.xml file that describes management policies. This file is the application server-specific binding to the Oracle infrastructure. The oracle-webservices.xml file can be considered to be a extension of the standard JAX-RPC webservices.xml file, which defines platform-independent Web service behavior.
Upon deployment to OC4J, the policies in the oracle-webservices.xml file are automatically copied to the runtime Web services management policy file, wsmgmt.xml. This file resides at ORACLE_HOME\j2ee\home\config\wsmgmt.xml where ORACLE_HOME is the installation directory for OC4J.
Application Server Control can be used to further manipulate the management policies in wsmgmt.xml.
The Web service clients can communicate with the Application Server through the OC4J runtime.
As this figure illustrates, the creation and administration of Web services management is completely separate from the Web service, business logic, and client implementation. The management configuration can be changed independently of the implemented business logic and does not require redeployment.
If you redeploy the EAR, any changes that Application Server Control has made to the policy in wsmgmt.xml will be overwritten. In effect, redeploying is the same as undeploying and then deploying. When a Web service is undeployed, all of the Web service management configuration is removed from wsmgmt.xml.
In addition to the server-side policy configuration, a symmetric policy configuration is often required on the client side. OC4J provides the option to have the server-side policy expressed in the WSDL in the form of capability assertions. By providing this information in the WSDL, client-generation tools can inspect this publicly available contract. The tools can use the capability assertions to know what questions to ask in order to create a configuration that will allow the client to communicate with the server. For more information on how information about the Web service management configuration can be added to the WSDL, see "Working with Capability Assertions".
An important part of managing a Web service is managing its life cycle. This includes the ability to enable or disable the service's management configuration. Application Server Control provides the ability to enable and disable security, reliability, auditing, and logging. Application Sever Control can also be used to enable or disable the entire Web service.
Other aspects of life cycle management, specifically deployment and undeployment, are covered in the Oracle Containers for J2EE Deployment Guide.
There are a number of techniques that you can use to configure server-side management information for a Web service. For example, you can write the management information into an existing oracle-webservices.xml file by hand or you can allow JDeveloper or WebServicesAssembler to automate the process. If the Web service is already deployed, you can use Application Server Control to configure many of the management options. The following sections summarize the ways in which you can configure server-side management information:
By Hand
Examine the oracle-webservices.xsd schema and write the management information into an existing oracle-webservices.xml file by hand.
Run the appropriate WebServicesAssembler *Assemble command to assemble your Web service.
Use the ddFileName argument to specify the modified oracle-webservices.xml file.
Optionally, use the genQosWsdl argument to insert capability assertions into the WSDL if you are generating the Web service bottom up or use genQosWsdl if you are generating the Web service top down.
Deploy the Web service.
With JDeveloper
Use the wizards in JDeveloper to configure a Web service. This will produce an oracle-webservices.xml file.
Run the appropriate wizard in JDeveloper to configure management information in the Web service.
Select the "add capability assertions" option if you want to insert capability assertions into the WSDL.
Deploy the Web service.
With WebServicesAssembler
Run WebServicesAssembler with the genDDs command to create a generic oracle-webservices.xml file.
This step will create a "skeleton" deployment descriptor file. This file will not contain any management configuration information. It will, however, provide the basic structure of the file and indicate where the management configuration should be placed.
Examine the oracle-webservices.xsd schema and write the management information into an existing oracle-webservices.xml file by hand.
Run the appropriate *Assemble command to assemble your Web service.
Use the ddFileName argument to specify the modified oracle-webservices.xml file.
Optionally, use the genQosWsdl argument to insert capability assertions into the WSDL.
Deploy the Web service.
With Application Server Control and WebServicesAssembler
This scenario enables you to establish a default server-side configuration without having to use JDeveloper or author the configuration by hand. The following steps describe how to use Application Server Control to define and populate a default management configuration for the server side. You then copy this configuration from the runtime configuration into the deployable EAR file.
Run WebServicesAssembler with the appropriate *Assemble command to create a Web service. Note that a Web service created by WebServicesAssembler will not have management information unless you explicitly build it in.
Deploy the Web service without management information. The deployment will cause a wsmgmt.xml file to be created in OC4J.
Use the Web services management screens in Application Server Control to configure server-side Web service management options. These values will be reflected in the wsmgmt.xml. file.
Copy Web service management information in the wsmgmt.xml file into the oracle-webservices.xml file that was created in Step 1.
Locate the <runtime> element and the <operations> element that appear under the <port> element in the wsmgmt.xml file. Note the value of the port attribute in the <port> element.
Locate the <port-component> element in the oracle-websrevices.xml file, whose name attribute has the same value as the port attribute of the <port> element in the wsmgmt.xml file.
Copy the <runtime> element, the <operations> element, and all of their child elements in the wsmgmt.xml file.
Paste these elements into the oracle-webservices.xml file, as a children of the <port-component> element located in Step 4b.
Repeat Steps 4a to 4d for each port you want to expose as a Web service.
Re-run the appropriate *Assemble command for your Web service.
Use the ddFileName argument to specify the modified oracle-webservices.xml file.
Optionally, use the genQosWsdl option to insert capability assertions into the WSDL.
Re-deploy the Web service.
Figure 3-3 presents an overview of how Web service management information is developed, transmitted, and manipulated in the J2SE client environment.
Figure 3-3 Web Services Management Data Flow in a J2SE Client
The data flow illustrated in Figure 3-3 is summarized in the following steps.
A developer creates a client-side configuration file. This can be done by using the wizards in JDeveloper, or by hand, using the oracle-webservices-client-10_0.xsd schema. The client-side configuration file contains the client-side configuration for Web services management features such as security, reliability, and auditing. (Note: logging is not available on the client.)
Use either JDeveloper or WebServicesAssembler to generate a J2SE client JAR file. If WebServicesAssembler is used, the ddFileName argument to the genProxy command specifies the configuration file.
Among the files contained in the J2SE client JAR are:
proxy class file—this file can send invocations to the server. This file typically has a <generated_name>_Stub.java extension, where generated_name is derived from the target namespace and port name in the WSDL.
client-side configuration file—this file typically resides in the same directory as the proxy class file. It has the same generated name as the proxy class file, but with a _Stub.xml extension.
For example, given a service endpoint interface, test\proxy\Test, you can use WebServicesAssembler to generate a proxy class file, test\proxy\runtime\Test_Stub.class. The client-side configuration file, specified with the ddFileName argument, will be copied to the same directory and will be called test\proxy\runtime\Test_Stub.xml.
"Assembling a J2SE Web Service Client" in the Oracle Application Server Web Services Developer's Guide provides more information on using WebServicesAssembler to generate J2SE Web service clients.
At runtime, the generated proxy class file will read the XML file and apply the management configuration settings to the messages.
Requests and responses can be passed between the client and server.
You can use JDeveloper or WebServicesAssembler to add a management configuration to the J2SE client.
With JDeveloper
Given a WSDL belonging to a Web service, use the wizards in JDeveloper to create the proxy class file and the client-side configuration file.
Run the appropriate wizards in JDeveloper to configure management information for the client.
Run the client.
With WebServicesAssembler
"Assembling a J2SE Web Service Client" in the Oracle Application Server Web Services Developer's Guide provides more detailed information on creating J2SE Web service clients.
Create a client-side configuration file. You can refer to the oracle-webservices-client-10_0.xsd schema and write the file by hand.
Given a WSDL belonging to a Web service, run WebServicesAssembler with the genProxy command to create a proxy class file. Use the ddFileName argument to specify the client-side configuration file.
<oracle:genProxy
wsdl="HelloService.wsdl"
output="src"
packageName="oracle.demo.hello"
ddFileName="clientConfig.xml"/>
This results in the generation of several Java source files beneath the directory specified by the output parameter. In this case, the Java source files are generated into the src directory. The generated Java source file that implements the port is oracle/demo/hello/runtime/HttpSoap11Binding_Stub.java. The name of this file is based on the way that Java class names are derived from the targetNamespaces and port names in the WSDL. In this example the WSDL targetNamespace is http://hello.demo.oracle/ and the name of the port is HttpSoap11Binding.
You can modify this default behavior using additional inputs to WebServicesAssembler. The generated _Stub.xml file will always have the same root name as the generated Java source file which implements the port.
Note that since the _Stub.xml file is generated into the source directory, you must ensure that this file is also copied to the directory into which you compile the Java source files. The following example shows how you might do this in an Ant task.
<copy todir="classes" >
<fileset dir="src">
<include name="**/*_Stub.xml"/>
</fileset>
</copy>
Use the client utility class file created by genProxy as your application client, or use it as a template to write your own client code. The client utility class file is one of a number of files created by genProxy.
Run the client.
Figure 3-4 illustrates how Web service management data is transmitted in a J2EE client.
Figure 3-4 Web Service Management Data Flow in a J2EE Client
To access the Web service, the J2EE client performs a JNDI lookup for a reference to the service endpoint interface.
At runtime, the object implementing the interface will use the management configuration used in either orion-ejb-jar.xml, orion-web.xml, or orion-application-client.xml, depending on the type of client.
The orion-*.xml file which is contained in the deployment archive has a <service-ref-mapping> element which contains the information needed to generate the service endpoint interface at runtime. The Web service management information is contained within the <service-ref-mapping> element.
"Adding OC4J-Specific Platform Information" in the Oracle Application Server Web Services Developer's Guide provides more information on the <service-ref-mapping> element.
You can use JDeveloper or WebServicesAssembler to add a management configuration to the J2EE client.
With JDeveloper
Given a WSDL belonging to a Web service, use JDeveloper to create the Java service endpoint interface file and the client component descriptor file. The configuration file will be either orion-ejb-jar.xml, orion-web.xml, or orion-application-client.xml, depending on the type of client.
Edit the <service-ref-mapping> tag in the orion-*.xml generated for your particular client. Enter the client-side Web service management configuration within this tag. For more information on the <service-ref-mapping> tag, see "Adding OC4J-Specific Platform Information" in the Oracle Application Server Web Services Developer's Guide.
Assemble and deploy the client module. "How to Assemble a J2EE Web Service Client" in the Oracle Application Server Web Services Developer's Guide provides more information on assembling and deploying J2EE Web service clients.
With WebServicesAssembler
Run WebServicesAssembler with the genInterface command to create a Java service endpoint interface file.
Edit the <service-ref-mapping> tag in the orion-*.xml generated for your particular Web service. Enter the client-side Web service management configuration within this tag. "Adding OC4J-Specific Platform Information" in the Oracle Application Server Web Services Developer's Guide provides more information on the <service-ref-mapping> tag.
Assemble the client deployment module:
Compile all of the client files.
Copy deployment descriptor files to their appropriate locations. "Packaging Web Service Applications" in the Oracle Application Server Web Services Developer's Guide describes where files should reside for servlet, EJB, or JSP Web service clients.
Package the client deployment module.
Deploy the client deployment module.
Run the client.
In all of the client-side dynamic configuration scenarios described in the following sections, the client provides a configuration for each invocation. The client does this by setting the value for the following property on either the call or the stub/port.
oracle.webservices.ClientConstants.WSM_INTERCEPTOR_PIPELINE_CONFIG
The value provided can be either an XML DOM element reference to the root node, or a java.io.File object of a document that conforms to the Web service management client-side configuration schema. If an XML DOM element reference is provided, the client must load and parse the configuration. If a java.io.File object is provided, the runtime will perform the loading and parsing.
The configuration provided by the ClientConstants.WSM_INTERCEPTOR_PIPELINE_CONFIG attribute will override any static configuration. The following example sets the configuration for an XML DOM element reference.
...setProperty(
"oracle.webservices.ClientConstants.WSM_INTERCEPTOR_PIPELINE_CONFIG",
parseAndReturnElement(config));
This example sets the configuration for a java.io.File object.
...setProperty(
"oracle.webservices.ClientConstants.WSM_INTERCEPTOR_PIPELINE_CONFIG",
new java.io.File("config file path"));
The override is all or nothing: if a dynamic configuration is provided, then any static configuration is completely ignored.
The following sections provide code examples of passing a management configuration to DII, dynamic proxy, static proxy, and J2EE Web service clients. In all of these cases, the configuration is defined in the following lines.
String config =
"<port-info>" +
...
"</port-info>";
This can be entered into the configuration file for J2SE clients or the deployment descriptors for J2EE clients.
Providing Dynamic Configuration for a DII Web Service Client
Providing Dynamic Configuration for a Dynamic Proxy Web Service Client
Providing Dynamic Configuration for a Static Proxy Web Service Client
Providing Dynamic Configuration for a J2EE Web Service Client
Example 3-1 displays management configuration being passed to a DII client. The setProperty statement is highlighted in bold. Note the presence of the <call-property> element in the example. You can use this element to pass information such as an endpoint address, a user name and password, and any other standard and proprietary properties.
Example 3-1 Properties and Management Configuration Dynamically Passed to a DII Client
...
String config =
"<port-info>" +
"<call-property>" +
"<name>...</name>" +
"<value>...</value>" +
"</call-property>" +
"<runtime>" +
"<security>" + ... + "<security>" +
"</runtime>" +
"<operations>" +
"<operation name='echo'>" +
"<runtime>" +
"<security>" + ... + "<security>" +
"</runtime>" +
"</operation>" +
"</operations>" +
"</port-info>";
call.setOperationName(
new QName("http://oracle.com/test/wsdl", "echo"));
call.setProperty(
"oracle.webservices.ClientConstants.WSM_INTERCEPTOR_PIPELINE_CONFIG",
parseAndReturnElement(config))
call.invoke(params);
...
Example 3-2 displays a management configuration being passed to a dynamic proxy. The setProperty statement is highlighted in bold. Note the presence of the <stub-property> element in the example. You can use this element to pass information such as an endpoint address, a user name and password, and any other standard and proprietary properties.
Example 3-2 Management Configuration Dynamically Passed to a Dynamic Proxy
...
String config =
"<port-info>" +
"<stub-property>" +
"<name>...</name>" +
"<value>...</value>" +
"</stub-property>" +
"<runtime>" +
"<security>" + ... + "<security>" +
"<reliability>" +...+"</reliability> +
"</runtime>" +
"<operations>" +
"<operation name='echo'>" +
"<runtime>" +
"<security>" + ... + "<security>" +
"<reliability>" +...+"</reliability>" +
"<auditing>" +...+ "</auditing>" +
"</runtime>" +
"</operation>" +
"</operations>" +
"</port-info>";
((Stub)port)._setProperty(
"oracle.webservices.ClientConstants.WSM_INTERCEPTOR_PIPELINE_CONFIG",
parseAndReturnElement(config));
port.echo("Hello");
...
Example 3-3 displays a management configuration being passed to a static proxy. The setProperty statement is highlighted in bold. Note the presence of the <stub-property> element in the example. You can use this element to pass information such as an endpoint address, a user name and password, and any other standard and proprietary properties.
Example 3-3 Properties and Management Configuration Dynamically Passed to a Static Proxy
...
String config =
"<port-info>" +
"<stub-property>" +
"<name>...</name>" +
"<value>...</value>" +
"</stub-property>" +
"<runtime>" +
"<security>" + ... + "<security>" +
"<reliability>" +...+"</reliability> +
"</runtime>" +
"<operations>" +
"<operation name='echo'>" +
"<runtime>" +
"<security>" + ... + "<security>" +
"<reliability>"+...+ "</reliability>" +
"<auditing>" +...+ "</auditing>" +
"</runtime>" +
"</operation>" +
"</operations>" +
"</port-info>";
port = service.getTestServicePort();
((Stub)port)._setProperty(
"oracle.webservices.ClientConstants.WSM_INTERCEPTOR_PIPELINE_CONFIG",
parseAndReturnElement(config));
port.echo("Hello");
..."
Example 3-4 displays a management configuration being passed to a J2EE Web service client. The setProperty statement is highlighted in bold.
Example 3-4 Management Configuration Dynamically Passed to a J2EE Web Service Client
...
String config =
"<port-info>" +
"<runtime>" +
"<security>" + ... + "</security>" +
"<reliability>" +...+"</reliability>" +
"</runtime>" +
"<operations>" +
"<operation name='echo'>" +
"<runtime>" +
"<security>" + ... + "<security>" +
"<reliability>"+...+ "</reliability>" +
"<auditing>" +...+ "</auditing>" +
"</runtime>" +
"</operation>" +
"</operations>" +
"</port-info>";
Context ic = new InitialContext();
Service service = (Service)ic.lookup(
"java:comp/env/service/MyTestServiceRef");
TestInterface port = (TestInterface)service.getPort(
portQName, j2ee.client.TestInterface.class );
((Stub)port)._setProperty(
"oracle.webservices.ClientConstants.WSM_INTERCEPTOR_PIPELINE_CONFIG",
parseAndReturnElement(config));
port.echo("Hello");
...
A static client-side configuration is supported only for J2SE and J2EE Web service clients. It is not supported for DII or dynamic proxies.
Static proxies are supported and are described in "Providing Dynamic Configuration for a Static Proxy Web Service Client".
The Enterprise Web Services 1.1 specification defines a deployment descriptor for each J2EE component type. The deployment descriptor contains information that allows the component to access a Web service endpoint.
Each standard J2EE Web services deployment descriptor has a corresponding Oracle-proprietary deployment descriptor. The purpose of an Oracle-proprietary deployment descriptor is to provide deployment-specific configuration information. While the application developer might specify suitable defaults, the Oracle-proprietary deployment descriptors allow the deployer to change deployment settings without affecting the application. The names of the Oracle-proprietary deployment descriptors are identical to the standard descriptors, except they have an orion- prefix. Table 3-1 lists the standard deployment descriptor and Oracle-proprietary deployment descriptor for each J2EE component.
Table 3-1 J2EE Components and their Corresponding Deployment Descriptors
| J2EE Component | Standard J2EE Web Services Deployment Descriptor | Oracle-Proprietary Deployment Descriptor |
|---|---|---|
|
JSP or Servlet |
web.xml |
orion-web.xml |
|
EJB |
ejb-jar.xml |
orion-ejb-jar.xml |
|
application client |
application-client.xml |
orion-application-client.xml |
The standard deployment descriptors contain a <service-ref> element. This element captures all of the Web service access information, such as the location of the WSDL and mapping file, the service interface, the service ports, and their related service endpoint interfaces. The <service-ref> element is described in "Adding J2EE Web Service Client Information" to Deployment Descriptors in the Oracle Application Server Web Services Developer's Guide.
One of the elements within <service-ref> is <service-ref-name>. The value of the <service-ref-name> element in the standard descriptor maps to the value of the name attribute in the <service-ref-mapping> element in the proprietary (that is, the orion-*) descriptor. This reference provides the JNDI path and service name assigned by the client.
The Oracle-proprietary deployment descriptors contain structures that use the value of the <service-ref-mapping> element to map to its corresponding standard deployment descriptor. Within this element is a <port-info> element. This element provides all of the information, including Web service management information, for a port within a service reference. The structure and content of the <port-info> element is the same for every type of client. For more information on the <service-ref-mapping> element, see "Adding OC4J-Specific Platform Information" in the Oracle Application Server Web Services Developer's Guide.
The following sections describe how the standard and Oracle-proprietary deployment descriptors are used to provide static configuration information to J2EE Web service clients.
Providing Static Configuration for a Servlet or JSP Web Service Client
Providing Static Configuration for an EJB Web Service Client
Providing Static Configuration for an Application Client Web Service Client
Example 3-5 displays a fragment of a web.xml deployment descriptor for a Servlet or JSP Web service client. The <service-ref-name> element contains the reference to the static configuration for the client.
Example 3-6 displays the corresponding orion-web.xml file. The <service-ref-mapping name="..."> element also contains the reference. The <port-info> element within <service-ref-mapping> contains the Web service management information.
The values for the <service-ref-name> and <service-ref-mapping> elements must match. These elements are highlighted in bold.
Example 3-5 web.xml—Static Configuration for a Servlet or JSP Web Service Client
<web-app>
...
<service-ref>
<service-ref-name>service/MyTestServiceRef</service-ref-name>
...
</service-ref>
...
</web-app>
Example 3-6 orion-web.xml—Static Configuration and Management Information for a Servlet or JSP Web Service Client
<orion-web-app ...>
<service-ref-mapping name="service/MyTestServiceRef">
<port-info>
...
<runtime>
...
<security/>
<reliability/>
...
</runtime>
<operations>
...
<operation name="echo">
<runtime>
...
<security/>
<reliability/>
<auditing/>
...
</runtime>
</operation>
...
</operations>
</port-info>
</service-ref-mapping>
</orion-web-app>
Example 3-7 displays a fragment of an ejb-jar.xml deployment descriptor for an EJB Web service client. The <service-ref-name> element contains the reference to the static configuration for the client.
Example 3-8 displays the corresponding orion-ejb-jar.xml file. The <service-ref-mapping name="..."> element also contains the reference. The <port-info> element within <service-ref-mapping> contains the Web service management information.
The values for the <service-ref-name> and <service-ref-mapping> elements must match. These elements are highlighted in bold.
Example 3-7 ejb-jar.xml—Static Configuration for an EJB Web Service Client
<ejb-jar ...>
...
<enterprise-beans>
<session>
<ejb-name>EjbServiceConsumer</ejb-name>
...
<service-ref>
<service-ref-name>service/MyTestServiceRef</service-ref-name>
...
</service-ref>
</session>
</enterprise-beans>
</ejb-jar>
Example 3-8 orion-ejb-jar.xml—Static Configuration and Management Information for an EJB Web Service Client
<orion-ejb-jar ...>
<enterprise-beans>
...
<session-deployment name="EjbServiceConsumer">
<service-ref-mapping name="service/MyTestServiceRef">
<port-info>
...
<runtime>
<security/>
</runtime>
<operations>
...
<operation name="echo">
<runtime>
...
<security/>
...
</runtime>
</operation>
</operations>
</port-info>
</service-ref-mapping>
</session-deployment>
</enterprise-beans>
</orion-ejb-jar>
Example 3-9 displays a fragment of an application-client.xml deployment descriptor for an application client Web service client. The <service-ref-name> element contains the reference to the static configuration for the client.
Example 3-10 displays the corresponding orion-application-client.xml file. The <service-ref-mapping name="..."> element also contains the reference. The <port-info> element within <service-ref-mapping> contains the Web service management information.
The values for the <service-ref-name> and <service-ref-mapping> elements must match. These elements are highlighted in bold.
Example 3-9 application-client.xml—Static Configuration for an Application Client Web Service Client
<application-client>
...
<service-ref>
<service-ref-name>service/MyTestServiceRef</service-ref-name>
...
</service-ref>
</application-client>
Example 3-10 orion-application-client.xml—Static Configuration and Management Information for an Application Client Web Service Client
<orion-application-client>
<service-ref-mapping name="service/MyTestServiceRef">
<port-info>
...
<runtime>
<security/>
</runtime>
<operations>
<operation name="echo">
<runtime>
<security/>
</runtime>
</operation>
</operations>
</port-info>
</service-ref-mapping>
</orion-application-client>
The following sections briefly describe the functionality for managing a Web service that is available by using Application Server Control.
Configuring, Enabling, and Disabling Web Service Management Features
You can use the Application Server Control to manage the Web services you deploy. For example, you can deploy your Web service applications, perform configuration tasks, and monitor your Web service ports.
In addition, you can perform administration tasks associated with standard Web Service Management features, which include auditing, logging, reliability, and security. Web Service Management is a set of policies applied against a message en-route to a target. In the case of OracleAS Web Services, the messages are SOAP requests, responses, and faults, and the targets are the client and the business logic on the server.
For instructions on how to configure, enable, and disable Web service management features, see the topics Overview of Web Services Management and Enabling and Disabling Web Service Management Features in the Application Server Control on-line help.
Enabling and Disabling a Web Service
You can use Application Server Control to enable a disabled Web service or disable an enabled Web service for an OC4J instance.
For instructions on how to enable and disable a Web service, see the topic Enabling and Disabling a Web Service in the Application Server Control on-line help.
Configuring Auditing for a Web Service
The Auditing feature of Web Service Management enables you to keep a complete, persistent record of SOAP requests, responses, and faults. During development it is often very convenient to be able to inspect the contents of SOAP requests and responses to diagnose problems.Auditing captures request, response, and fault messages and stores them in the following persistent file.
ORACLE_HOME\log\wsmgmt\audit\log.xml
For instructions on how to configure auditing, see the topic Configuring Auditing for a Web Service in the Application Server Control on-line help.
Configuring Logging for a Web Service
When you configure logging for a Web service, you can identify the attributes you want logged from incoming, outgoing, and fault SOAP messages.
For instructions on how to configure logging for a Web service, see the topic Configuring Logging for a Web Service in the Application Server Control on-line help.
Configuring Reliability for a Web Service
You can use Application Server Control to configure your Web service with reliable messaging. Reliable messaging allows users of the Web services stack to exchange SOAP messages without duplicates and with guaranteed delivery and message ordering.
For instructions on how to configure reliability for a Web service, see the topic Configuring Reliability for a Web Service in the Application Server Control on-line help.
Configuring Security for a Web Service
You can use Application Server Control to configure your Web service with authentication, integrity with digital signatures, and confidentiality with encryption based on the WS-Security standard.
For instructions on how to configure security for a Web service, see the topic Configuring Security for a Web Service in the Application Server Control on-line help.
Viewing the WSDL for a Web Service
You can use Application Server Control to view the WSDL for a Web service. You cannot edit the contents of the .wsdl file, but you can review the contents to verify the attributes and characteristics of the Web service.
For instructions on how to view the WSDL, see the topic Specifying an XPath When Configuring Web Services Logging in the Application Server Control on-line help
Testing a Web Service
You can use Application Server Control to test a Web service. When you test the Web service, you display its Home Page. The Web Services Home Page URL is also the service endpoint that the Web service exposes to its clients. From this URL you can invoke the operations for values that you enter and verify that the Web service is responding appropriately.
For instructions on how to use Application Server Control to test a Web service, see the topic Testing a Web Service in the Application Server Control on-line help.
Viewing Web Service Operations
You can use Application Server Control to view Web service operations and operation metrics.
For instructions on how to view Web service operations and operation metrics, see the topic Viewing Web Service Operations in the Application Server Control on-line help.
Capability assertions are descriptions of Web service management policies, such as security and reliability. They allow consumers of Web services to discover which management policies are enabled for the Web service.
For example, assume that you created a Web service that requires a security token, such as a user name and password. The client will not be able to access the service unless it is aware of this requirement. Capability assertions provide hints to the client that a user name and password must be placed in the message SOAP headers at runtime.
Capability assertions are derived from the server-side Web service management configuration in the oracle-webservices.xml deployment descriptor and generated into the WSDL. The generation can be performed either by JDeveloper wizards or WebServicesAssembler commands. In JDeveloper, the Web service management configuration wizard contains a "Capability Assertions" option. In WebServicesAssembler, you provide a WSDL, set the genQos argument to true, and set the ddFileName argument to an oracle-webservices.xml deployment descriptor that contains the server-side management configuration.
For the generation of an OracleAS Web Services client, a WSDL and configuration file are used as input. The configuration file describes some of the built-in behavior of the generated client and is based on the oracle-webservices-client-10_0.xsd schema. The configuration file can be written by hand or created by a tool, such as JDeveloper. The capability assertions from the WSDL are used as hints to help in the creation of the client-side configuration.
For a J2SE client, the client-side configuration file is automatically packaged with the proxy classes when they are generated. For a J2EE client, the client-side configuration is set up at deployment time.
Continuing the example described earlier in this section, the capability assertions generated into the WSDL will state that a user name and password are required to access the service. If you use JDeveloper to generate the client, it can take this information and prompt you for a user name and password. JDeveloper will create a client-side configuration file that will be used at runtime to place this user name and password into the message SOAP headers.
If you are using WebServicesAssembler instead of JDeveloper, you will have to understand the capability assertions in the WSDL and author the client-side configuration accordingly. You must then either pass the configuration to WebServicesAssembler with the ddFileName argument for packaging with the client proxy or pass it to the call/proxy at runtime.
The following generalized steps summarize the process of including capability assertions in your Web service:
Create the server-side Web service management configuration for security, reliability, auditing, and logging by hand or by using JDeveloper.
By Hand: enter the management configuration into the oracle-webservices.xml deployment descriptor by hand.
JDeveloper: use the JDeveloper wizards to choose the Web service management options. The wizards will enter this information into the oracle-webservices.xml deployment descriptor.
Generate the capability assertions into the WSDL by using either WebServicesAssembler or JDeveloper.
WebServicesAssembler: use the genQosWsdl command to produce a WSDL with capability assertions.
JDeveloper: select the appropriate options in the wizards to generate capability assertions into the WSDL.
Generate the client code by using either WebServicesAssembler or JDeveloper.
WebServicesAssembler: supply a WSDL and client-side configuration file to the genProxy command (for a J2SE client) or genInterface command (for a J2EE client); use the ddFileName argument to specify the client-side configuration file.
JDeveloper: use the appropriate JDeveloper wizard to generate either J2SE or J2EE client code.
Run the client code:
for a J2SE client, compile and run the client
for a J2EE client, deploy, then run the client
For more information on:
adding security features to a Web service, see Chapter 4, "Ensuring Web Services Security" and the Oracle Application Server Web Services Security Guide.
adding reliable messaging to a Web service, see Chapter 5, "Ensuring Web Service Reliability".
adding logging and auditing to a Web service, see Chapter 6, "Auditing and Logging Messages".
assembling a Web service top down, see "Assembling a Web Service from a WSDL" in the Oracle Application Server Web Services Developer's Guide.
using Java classes to assemble a Web service, see "Assembling a Web Service with Java Classes" in the Oracle Application Server Web Services Developer's Guide.
using EJBs to assemble a Web service, see "Assembling a Web Service with EJBs" in the Oracle Application Server Web Services Developer's Guide.
using JMS topics and destinations to assemble a Web service, see "Assembling Web Services with JMS Destinations" in the Oracle Application Server Web Services Developer's Guide.
using database resources, such as PL/SQL packages, SQL queries, DML statements, Oracle Streams AQ, or server-side Java classes, to assemble a Web service, see "Assembling Database Web Services" in the Oracle Application Server Web Services Developer's Guide.
assembling a J2EE Web Service client, see "Assembling a J2EE Web Service Client" in the Oracle Application Server Web Services Developer's Guide.
assembling a J2SE Web service client, see "Assembling a J2SE Web Service Client" in the Oracle Application Server Web Services Developer's Guide.
packaging and deploying of Web services, see "Packaging and Deploying Web Services" in the Oracle Application Server Web Services Developer's Guide.
using WebServicesAssembler commands to assemble Web service artifacts, see "Using WebServicesAssembler" in the Oracle Application Server Web Services Developer's Guide.
using JDeveloper to add management information to a Web service, see the JDeveloper on-line help.
using Application Server Control to add management information to a Web service, see the Application Server Control on-line help.
