| Oracle® Application Server Web Services Developer's Guide 10g Release 3 (10.1.3) B14434-01 |
|
 Previous |
 Next |
| Oracle® Application Server Web Services Developer's Guide 10g Release 3 (10.1.3) B14434-01 |
|
Previous |
Next |
This chapter describes how to develop a Web service client from within a J2EE container. Any component of a J2EE 1.4-compliant container, such as a version 2.4 servlet, 2.1 EJB, or 2.0 JSP application can act as a J2EE Web service client.
This chapter contains the following sections:
For information on assembling a Web service client that runs in the J2SE environment, see Chapter 14, "Assembling a J2SE Web Service Client".
The J2EE platform provides an environment that allows client applications to access Web services. In a J2EE environment, the deployment descriptors define the client-side Web service access information. This access information can be changed at deployment time. In addition, the J2EE platform handles the underlying work of creating and initializing access to Web services.
J2EE Web service clients inherit the advantages of the J2EE platform, such as declarative security, transactions, and instance management. In addition to these platform characteristics, the OracleAS Web Services management framework makes it possible to configure SOAP logging and auditing, WS-Reliability, and WS-Security.
Unlike the J2SE Web service client, the J2EE client resides in and is managed by the OC4J container. It requires no proxy code generation or packaging. You get a portable client application with Web service access that is easy to embed in JSPs, servlets, and EJBs. EJB variants such as Container Managed Persistence (CMP), Bean Managed Persistence (BMP), and Message-Driven Beans (MDB) can call out to Web service endpoints.
Before you begin, supply the following files and information.
The WSDL file or location from which the service endpoint interface and JAX-RPC mapping file will be generated.
The location where the generated service endpoint interface and JAX-RPC mapping file will be stored.
Use the WebServicesAssembler tool to assemble a service endpoint interface and the J2EE Web service client. Then, edit the deployment descriptor to add Web service access information. The following steps describe these tasks in more detail.
Provide the WSDL and the information described in the Prerequisites section as input to the WebServicesAssembler genInterface command. For example:
java -jar wsa.jar
-genInterface
-wsdl HelloService.wsdl
-output build -packageName oracle.demo.hello
This command line uses HelloService.wsdl to generate HelloInterface in the oracle.demo.hello package.
Edit the deployment descriptor of the J2EE component to add a <service-ref> element. This element captures all of the Web service access information.
See "Adding J2EE Web Service Client Information to Deployment Descriptors" for a sample of the <service-ref> element and its sub-elements.
If the client also provides message processing in the form of JAX-RPC handlers, then these also must be added to the deployment descriptor. See "Adding JAX-RPC Handlers to Deployment Descriptors" for more information on adding handler information to the deployment descriptor.
Assemble the client deployment module into an EAR file:
Compile all the client files.
Copy deployment descriptor files to their appropriate locations. For example, for an EJB, copy the WSDL to META-INF/wsdl/, the JAX-RPC mapping file and the deployment files such as ejb-jar.xml and orion-ejb-jar.xml to META-INF, and so on. For a description of where files should reside for servlet, EJB, or JSP Web service clients, see "Packaging Structure for Web Service Applications".
Package the client deployment module.
|
Note: The current tool set cannot package J2EE Web service clients. You must package the client manually. "Packaging a J2EE Client" provides more information on how to package a J2EE Web service client. |
Deploy the client deployment module.
The following steps will deploy an EJB, JSP, or other J2EE client. If you are deploying an application client, skip these steps and continue with "Deploying and Running an Application Client Module".
Start OC4J. The following is a sample command to start OC4J.
java -jar oc4j.jar
Deploy the client module into OC4J. The following is a sample deployment command.
java -jar admin_client.jar deployer:oc4j:<oc4jHost>:<oc4jPort> <adminID> <adminPassword> -deploy -file .\client\myClient.ear -deploymentName myClient -bindWebApp default-web-site
The oc4jHost and oc4jPort variables are the host name and port number of the OC4J server. The adminID and adminPassword are the OC4J server user name and password. The following are sub-switches of the -deploy switch.
file—path and filename of the EAR file to deploy.
deploymentName—user-defined application deployment name, used to identify the application within OC4J.
bindWebApp—specifies the Web site to which the web application should be bound. This is the Web site that will be used to access the application.
Run the EJB or JSP client.
If you are running an application client, see "Deploying and Running an Application Client Module".
The following steps describe how to deploy and run an application client module. Unlike EJB, JSP, or other J2EE clients, you must specify the directory where the generated deployment-cache.jar will be stored. You must also specify the location of the deployment-cache.jar in the run command.
Start OC4J. The following is a sample command to start OC4J.
java -jar oc4j.jar
Deploy the application client module into OC4J. The following is a sample deployment command.
java -jar admin_client.jar deployer:oc4j:<oc4jHost>:<oc4jPort> <adminID> <adminPassword> -deploy -file .\client\myAppClient.ear -deploymentName myAppClient -deploymentDirectory C:\home\myDir
This command creates a deployment-cache.jar file and stores it in C:\home\myDir.
The oc4jHost, oc4jPort, adminID, and adminPassword variables and the file and deploymentName sub-switches of -deploy are described in Step 4b of the previous section.
The deploymentDirectory sub-switch indicates the location where OC4J deploys deployment-cache.jar. In this example, OC4J deploys it into C:\home\myDir. If you do not specify this sub-switch, OC4J deploys the application into the OC4J_HOME/application-deployments/ directory. If you supply the empty string (" "), OC4J will always read the deployment configurations from the EAR file each time the application is deployed.
Run the client deployment module. For an application client, the location of the deployment-cache.jar must be present in the classpath. The following is a sample run command:
java -classpath .:C:\home\myDir\deployment-cache.jar:'oc4jclient.jar'
:appclient.jar oracle.myappclient.classname
In this sample, it is assumed that appclient.jar contains the class oracle.myappclient.classname.
The current release provides Ant tasks for Web service development. The following sample code shows how the genInterface command in the preceding example can be rewritten as an Ant task.
<oracle:genInterface wsdl="${etc.web1.dir}/HelloService.wsdl"
output="build"
packageName="oracle.demo.hello"
/>
You must edit the J2EE component's deployment descriptor to add information that allows the component to access the Web service endpoint.
For an EJB 2.1 Web service client, edit the META-INF/ejb-jar.xml deployment descriptor.
For a JSP 2.0 or servlet Web service client, edit the WEB-INF/web.xml deployment descriptor.
For an application client, edit the META-INF/application-client.xml deployment descriptor.
Edit the deployment descriptor to add a <service-ref> element. By adding this element, you can employ an EJB, JSP, or servlet as a Web service client that can invoke a remote Web service. The <service-ref> element and its subelements capture all the Web service access information, such as the location of the WSDL and mapping file, the service interface, the service ports, their related service endpoint interfaces, and so on. For a complete listing of all the information that can be included in the <service-ref> element, see the service-ref (J2EE client) schema.
http://java.sun.com/xml/ns/j2ee/j2ee_web_services_client_1_1.xsd
Example 13-1 illustrates a sample <service-ref> element that has been added to a web.xml deployment descriptor for the MyHelloService Web service. The <service-ref> subelements in this example are described in Table 13-1. Note that this sample <service-ref> uses only a subset of all of the Web service access information available in the schema.
Example 13-1 Contents of a Sample service-ref Element
<service-ref>
<service-ref-name>service/MyHelloServiceRef</service-ref-name>
<service-interface>javax.xml.rpc.Service</service-interface>
<wsdl-file>WEB-INF/wsdl/HelloService.wsdl</wsdl-file>
<jaxrpc-mapping-file>WEB-INF/HelloService-java-wsdl-mapping.xml
</jaxrpc-mapping-file>
<service-qname xmlns:service-qname_ns__="http://hello.demo.oracle/">
service-qname_ns__:HelloService</service-qname>
<port-component-ref>
<service-endpoint-interface>oracle.demo.hello.HelloInterface
</service-endpoint-interface>
<port-component-link></port-component-link>
</port-component-ref>
</service-ref>
Table 13-1 describes the <service-ref> sub-elements used in this sample.
Table 13-1 Sub-elements of the <service-ref> Element
| service-ref Subelement | Description |
|---|---|
|
Specifies the JNDI path and service name assigned by the client. |
|
|
Specifies the fully-qualified class name of the JAX-RPC Service interface the client depends on. In most cases the value will be |
|
|
Specifies the fully-qualified path to the WSDL file. |
|
|
Specifies the fully-qualified path to the JAX-RPC mapping file. |
|
|
Specifies the service
|
|
|
Declares a client dependency on the container for resolving a service endpoint interface to a WSDL port. It optionally associates the service endpoint interface with a particular port-component. The container uses this only for a |
|
|
Specifies the fully-qualified Java class that represents the service endpoint interface of a WSDL port. |
|
|
If the Web service is implemented in the same module as the client, you can add this element to access the service. For more information on this element, see "Accessing a Web Service". |
To enable the Oracle Application Server to access a Web service that resides in the same module as the client, add the <port-component-link> element to the <service-ref> clause of the client deployment descriptor and add the PortComponentLinkResolver property to the system-application.xml configuration. The following steps summarize these tasks.
Add the <port-component-link> element to the <service-ref> clause in the J2EE client deployment descriptor.
"Adding a Port Component Link to a J2EE Client Deployment Descriptor" provides more information on this step.
Shut down the Oracle Application Server.
Add the PortComponentLinkResolver property to the system-application.xml server configuration file. This file resides in the directory ORACLE_HOME/j2ee/home/config.
Add the following lines to this file.
<ejb-module id="PortComponentLinkResolver" path="../../../webservices/lib/wsserver.jar"/>
Re-start the Oracle Application Server.
If the Web service resides in the same container as the client, then you can access the service by adding the <port-component-link> element to the <service-ref> clause of the J2EE client deployment descriptor (web.xml, ejb-jar.xml, or application-client.xml).
The <port-component-link> element links a <port-component-ref> to a specific port component in the server-side deployment descriptor. The <port-component-name> element resides in the server-side deployment descriptor, webservices.xml.
The following examples illustrate this relationship. The webservices.xml fragment in Example 13-2 illustrates the deployment configuration for the Web service that exposes the EJB InterModuleEjb. In this fragment, the port component is named InterPC. Example 13-3 illustrates a fragment of a client-side deployment descriptor where this name is referenced from the <port-component-link> element in the <service-ref> clause. The presence of this element allows the J2EE client to look up the Web service.
These examples assume that the Web service is running in the same container as the J2EE Web service client.
Example 13-2 webservices.xml Fragment, Identifying a Port Component Name
<webservices>
<webservice-description>
<webservice-description-name>InterModuleEjb</webservice-description-name>
<wsdl-file>META-INF/wsdl/InterModuleService.wsdl</wsdl-file>
<jaxrpc-mapping-file>META-INF/InterModuleService.xml</jaxrpc-mapping-file>
<port-component>
<port-component-name>InterPC</port-component-name>
<wsdl-port
xmlns:wsdl1="http://PortCompLink.org/ejb/inter">wsdl1:InterModuleSeiPort
</wsdl-port>
<service-endpoint-interface>oracle.demo.InterModuleSei
</service-endpoint-interface>
<service-impl-bean>
<ejb-link>InterModuleEjb</ejb-link>
</service-impl-bean>
</port-component>
</webservices>
Example 13-3 illustrates a fragment of a client-side deployment descriptor where the value of the <port-component-name> element in the server-side deployment descriptor is referenced from the <port-component-link> element in the <service-ref> clause. The presence of this element allows the client to look up the Web service.
Note that the value of the port component name in the <port-component-link> is prefixed by PortCompLinkEjb-ejb.jar#. This value qualifies the name of the EJB with the JAR file where it resides.
Example 13-3 <port-component-link> Element in the Client-Side Deployment Descriptor
<service-ref>
<service-ref-name>service/portcomplink/inter</service-ref-name>
<service-interface>javax.xml.rpc.Service</service-interface>
<wsdl-file>META-INF/wsdl/InterModuleService.wsdl</wsdl-file>
<jaxrpc-mapping-file>META-INF/InterModuleService.xml</jaxrpc-mapping-file>
<port-component-ref>
<service-endpoint-interface>oracle.demo.InterModuleSei
</service-endpoint-interface>
<port-component-link>PortCompLinkEjb-ejb.jar#InterPC</port-component-link>
</port-component-ref>
</service-ref>
The <service-ref-mapping> element can appear as a subelement of the <orion-web-app> element in the orion-web.xml, orion-ejb-jar.xml, or orion-application-client.xml proprietary deployment descriptor files. It defines OC4J-specific runtime and deployment-time generated settings for a Web service reference. It also specifies security, logging, and auditing quality of service (QOS) features for the corresponding Web service.
The <service-ref-mapping> element is used in conjunction with the <service-ref> element that appears in the standard deployment descriptors. The <service-ref> element contains the information that lets you employ an EJB, JSP, or servlet as a Web service client that can invoke a remote Web service.
Note that whenever a <service-ref> element can appear in a web.xml, ejb-jar.xml, or application-client.xml file, a corresponding <service-ref-mapping> element can appear in an orion-web.xml, orion-ejb-jar.xml, or orion-application-client.xml file.
The <service-ref-mapping> element's supported features are described in the service-ref-mapping-10_0.xsd that is imported into the orion-web, orion-ejb-jar, and orion-application-client XSDs. Currently, there is no tool support, such as JDeveloper wizards, for providing values to service-ref-mapping-10_0.xsd. You must refer to the schema and edit the XML file by hand.
In its simplest case, the <service-ref-mapping> element contains only deployment information. Do not add run-time or quality of service elements if you do not want your client to be managed. A managed client is more expensive in terms of performance.
Example 13-4 contains a sample <service-ref-mapping> segment. So that you can see this element's hierarchy, all the subelements are displayed. The tables following the XML sample describe the sub-elements.
Example 13-4 Sample <service-ref-mapping> Segment
<service-ref-mapping name="service/MyJAXRPCTime">
<service-impl-class>oracle.demo.MyTime_Impl</service-impl-class>
<wsdl-file final-location="file:/myhome/mytime/client-wsdl/MyJAXRPCTime.wsdl">
<wsdl-location wsdl-override-last-modified=19NOV>
<service-qname namespaceURI="urn:oracle-ws" localpart="MyService" />
<stub-property>
<name>...</name>
<value>...</value>
</stub-property>
<call-property>
<name>javax.xml.rpc.service.endpoint.address</name>
<value>http://myhost:8888/time-ejb/timeport</value>
</call-property>
<port-info>
<wsdl-port>
<service-endpoint-interface>time.TimeService</service-endpoint-interface>
<stub-property>
<name>another.endpoint.address</name>
<value>http://anotherhost:8888/time-ejb/timeport</value>
</stub-property>
<call-property>
<name>...</name>
<value>...</value>
</call-property>
<runtime>...</runtime>
<operations>
<operation name="echo">
<runtime>
<auditing request="true" response="false" fault="false"/>
<reliability><reject-non-reliable-messages value="false"/></reliability>
...
</runtime>
</operation>
</operations>
</port-info>
</service-ref-mapping>
Table 13-2 describes the subelements of <service-ref-mapping>.
Table 13-2 Subelements of the <service-ref-mapping> Element
| Element Name | Description |
|---|---|
|
Defines a deployment-time generated name of a |
|
|
Defines a deployment-time generated name for the WSDL file. This element has this attribute: |
|
|
(Optional) Contains a valid URL pointing to a WSDL document. If a URL is specified, then the WSDL document at this URL will be used during deployment instead of the WSDL document associated with the This element has this attribute: |
|
|
Derived at deployment-time, this element contains the |
|
|
Defines the stub property values applicable to all ports. This is a convenient way to specify a property without specifying the port name. The Note that the |
|
|
Defines the call property values applicable to all ports. This is a convenient way to specify a property without specifying the port name. The Note that the |
|
|
Defines a port within a service-reference. See Table 13-3 for a description of the subelements of |
Table 13-3 describes the sub-elements for the <port-info> element. This element provides all of the information for a port within a service reference. You can specify either <service-endpoint-interface> or <wsdl-port> to indicate the port that the container will use for container-managed port selection. If you specify both, then the container will use the <wsdl-port> value. If you do not specify <wsdl-port> or <service-endpoint-interface>, then the <port-info> property values will apply to all available ports.
The <port-info> element also contains subelements that let you specify quality of service features that are available for the port and its operations.
Table 13-3 Subelements of the <port-info> Element
| Element Name | Description |
|---|---|
|
Specifies the name of a port in the WSDL that the container will use for container-managed port selection. In container-managed port selection, the container manages calls to the instance directly, and the client requests a generic port that might be used to access multiple different instances. |
|
|
Specifies the fully-qualified path to the service endpoint interface of a WSDL port. The container uses this port for container-managed port selection. |
|
|
Defines the stub property values applicable to the port defined by the Note that the |
|
|
Defines the call property values applicable to the port defined by the Note that the |
|
|
Contains client-side quality of service runtime information (security and/or reliability) applicable to all the operations provided by the referenced Web service. Each child element contains configuration for a specific feature. |
|
|
Contains a sequence of elements, one for each operation. The |
Table 13-4 describes the <operation> subelement of the <operations> element.
Table 13-4 Subelement of the <operations> Element
| Element Name | Description |
|---|---|
|
Specifies client-side quality of service configuration for a particular operation provided by the referenced Web service. The configuration appears within this element's This
|
Table 13-5 describes the <runtime> subelement of the <operation> element.
Table 13-5 Subelement of the <operation> Element
| Element Name | Description |
|---|---|
|
Contains client-side quality of service configuration for individual operations within the port. Each child element contains configuration for one of the quality of services features (security, reliability, and/or auditing). |
Table 13-6 describes the name and value subelements of the <stub-property> and <call-property> elements.
Table 13-6 Subelements of <stub-property> and <call-property> Elements
| Element Name | Description |
|---|---|
|
Defines the name of any property supported by the JAX-RPC |
|
|
Defines a JAX-RPC property value that should be set on a |
J2EE Web service clients can support JAX-RPC handlers to provide additional message processing facilities for Web service endpoints. For example, you can use a handler to process a SOAP message.
You must enter the handler information as a subelement of <service-ref> in a J2EE Web service client's deployment descriptor. The <handler> element encapsulates this information. For more information on client-side handlers and registering them with the deployment descriptor, see "Client-Side JAX-RPC Handlers".
This section describes some of the common code that allows a J2EE component to access a Web service. At runtime, all J2EE Web service clients use a standard JNDI lookup to find Web services. The following steps describe the general pattern for coding a JNDI lookup that could be used within a servlet, EJB, or a JSP.
Create the initial JNDI context.
Context ic = new InitialContext();
The OC4J container sets up the initial context properties.
Locate the service using the lookup method from the initial context. The comp/env/service/MyHelloServiceRef in Example 13-5 provides the service reference. The JNDI call returns a reference to a service object.
Service service = (Service) ic.lookup("java:comp/env/service/MyHelloServiceRef");
The client always accesses the service implementation by using a JNDI lookup. This lookup returns a container-managed service reference. This allows the container to intervene and provide the client with additional service functionality, such as logging, security, and management.
Get a handle to the service port using the getPort method on the container-managed service object. Cast the return value to the interface type.
HelloInterface helloPort = (HelloInterface) service.getPort(portQName, oracle.demo.hello.HelloInterface.class);
Note that this step assumes that a QName has already been defined. For example:
QName portQName = new QName("http://hello.demo.oracle/", "HelloInterfacePort");
Instead of getPort, the client can make a DII Web service call by using the service object to get a handle on the Call object.
Call call = service.createCall(new QName("http://hello.demo.oracle/", "HelloInterfacePort");
Call a method on the remote object.
resultFromService = helloPort.sayHello(name);
Example 13-5 illustrates code that a servlet or JSP Web service client can use to look up a Web service.
Example 13-5 Servlet or JSP Code to Look Up a Web Service
public String consumeService (String name)
{
......
Context ic = new InitialContext();
Service service = (Service)ic.lookup("java:comp/env/service/MyHelloServiceRef");
// declare the qualified name of the port, as specified in the wsdl
QName portQName= new QName("http://hello.demo.oracle/","HelloInterfacePort");
//get a handle on that port : Service.getPort(portQName,SEI class)
HelloInterface helloPort =
(HelloInterface) service.getPort(portQName,oracle.demo.hello.HelloInterface.class);
//invoke the operation : sayHello()
resultFromService = helloPort.sayHello(name);
.....
}
J2EE Web service clients can be configured, either by using configuration files or programmatically, to consume stateful Web services.
See "Exposing Java Classes as a Stateful Web Service" for more information on stateful Web services.
A J2EE client can be configured to consume stateful Web services by editing the <service-ref-mapping> clause of the appropriate Oracle-proprietary deployment descriptor (either orion-web.xml, orion-ejb-jar.xml, or orion-application-client.xml).
Within the <service-ref-mapping> clause, add a <stub-property> element with its <name> sub-element set to the javax.xml.rpc.session.maintain property and its <value> sub-element set to true.
The value of the J2EE standard property javax.xml.rpc.session.maintain indicates to the client whether it wants to participate in a session with a service endpoint. If this property is set to true, the client indicates that it wants the session to be maintained.
Example 13-6 illustrates a Web service client configuration for a stateful Web service. The definition of the <stub-property> allows the client to participate in a session with the port identified by the CycleCounterInterface service endpoint. The <stub-property> element, with its setting for javax.xml.rpc.session.maintain, is highlighted in bold.
Example 13-6 Configuration for a Client Participating with a Stateful Web Service
<service-ref-mapping name="service/CycleCounter">
<port-info>
<service-endpoint-interface>test.oracle.stateful.CycleCounterInterface</service-endpoint-interface>
<!-- set the javax.xml.rpc.session.maintain property to true for a stateful client -->
<stub-property>
<name>javax.xml.rpc.session.maintain</name>
<value>true</value>
</stub-property>
<stub-property>
<name>javax.xml.rpc.service.endpoint.address</name>
<value>http://%J2EE_HOST%:%HTTP_PORT%/testsfWS-session/testsfWS-session</value>
</stub-property>
</port-info>
</service-ref-mapping>
A J2EE client can be configured programmatically to consume stateful Web services. To do this, ensure that the client participates in the session by setting the SESSION_MAINTAIN_PROPERTY runtime property (javax.xml.rpc.session.maintain) to true either on the stub, the DII call, or the endpoint client instance.
For example, you can set the value of this property inside the generated implementation _port of javax.xml.rpc.Stub:
((Stub)__port)._setProperty(Stub.SESSION_MAINTAIN_PROPERTY, Boolean.valueOf (maintainSession));
Instead of setting this property directly, OracleAS Web Services provides a helpful wrapper class with a setMaintainSession(boolean) method. When this method is set to true the session is maintained. The wrapper takes care of setting the property inside of the client. For example, in the client code, you can enter the following:
HttpSoap11Client c = new HttpSoap11Client(); // client wrapper class c.setMaintainSession(true);
You can statically configure the J2EE client to make JMS transport calls. To do this, add a <service-ref-mapping> clause to the appropriate Oracle-proprietary J2EE client deployment descriptor file for your Web service (orion-web.xml, orion-ejb-jar.xml, or orion-application-client.xml). Within the clause, configure a <stub-property> element with name and value attributes for each of these items.
ReplyTo queue—Enter a <stub-property> element with the name attribute set to the ReplyToQueueName API (oracle.webservices.transport.ReplyToQueueName) and the value attribute set to the JNDI name of the ReplyTo queue.
ReplyTo factory name—Enter a <stub-property> element with the name attribute set to the ReplyToFactoryName API (oracle.webservices.transport.ReplyToFactoryName) and the value attribute set to the JNDI name of the ReplyTo factory.
service endpoint address—Enter a <stub-property> element with name attribute set to the service endpoint address API (javax.xml.rpc.service.endpoint.address) and the value attribute set to the service endpoint interface file.
Example 13-7 illustrates a sample configuration.
Example 13-7 J2EE Client Configuration for JMS Transport Calls
<service-ref-mapping name="service/MyJMSService">
<stub-property>
<name>oracle.webservices.transport.ReplyToQueueName</name>
<value>jms/receiverQueue</value>
</stub-property>
<stub-property>
<name>oracle.webservices.transport.ReplyToFactoryName</name>
<value>jms/receiverQueueConnectionFactory</value>
</stub-property>
<stub-property>
<name>javax.xml.rpc.service.endpoint.address</name>
<value>/bank/soap12bank</value>
</stub-property>
</service-ref-mapping>
OracleAS Web Services permits the chunked transfer encoding of messages when the protocol is HTTP 1.1. Chunked data transfer can be invoked on J2SE stub, J2EE stub and DII Web service clients.
Chunking can increase performance by breaking the payload into smaller pieces. These pieces can be sent over the wire faster than one large payload. Chunked transfer encoding includes all of the information that the recipient needs to verify that it has received the entire message. Chunked transfer encoding happens at the transport level; it is not detected or handled by the invoker of a Web services call or the server.
The following properties in the oracle.webservices.ClientConstants class can be set on the Stub or Call object to enable chunking and set the chunk size.
DO_NOT_CHUNK—if this property is not set, or set to true, then chunking is turned off by default. If this property is set to false, then chunking is enabled.
CHUNK_SIZE—sets the chunk size in bytes. If this property is not set, then the default chunk size is 4096 bytes.
Example 13-8 illustrates setting the chunking and chunk size property in client proxy stub code.
Example 13-8 Stub Code to Set Data Chunk Size
import oracle.webservices.ClientConstants ... ((OracleStub)port)._setProperty(ClientConstants.DO_NOT_CHUNK (true)); ((OracleStub)port)._setProperty(ClientConstants.CHUNK_SIZE (1024)); ...
Example 13-9 illustrates using the DO_NOT_CHUNK and CHUNK_SIZE properties in DII client code to set the chunk size to 1024 bytes.
Example 13-9 DII Client Code to Set Data Chunk Size
import oracle.webservices.ClientConstants
...
ServiceFactory factory = ServiceFactory.newInstance();
Service service = factory.createService(new QName("http://whitemesa.net/wsdl/rpc-lit-test", "tns" ) );
QName stringType = new QName( "http://www.w3.org/2001/XMLSchema", "string");
Call call = service.createCall();
...
call.setProperty(ClientConstants.DO_NOT_CHUNK (false));
call.setProperty(ClientConstants.CHUNK_SIZE (1024));
...
By default, a J2EE client (either static stub or DII) assembled under OracleAS Web Services sends a request message with a SOAP envelope encoded with UTF-8 characters. To override this behavior, you can set the following Oracle proprietary property:
oracle.webservices.ClientConstants.CHARACTER_SET_ENCODING
You can apply this property to the javax.xml.rpc.Stub or javax.xml.rpc.Call object with the setProperty method.
The value of the CHARACTER_SET_ENCODING property can be of type java.lang.String or java.nio.charset.Charset. The set of supported character encodings depends on the underlying Java Virtual Machine (JVM). Use the Charset.availableCharsets method to return the list of character encodings that are supported by your JVM. for more information on the Charset.availableCharsets method, see the output of the Javadoc tool for the java.nio.charset.Charset class.
This property can also be used for J2SE Web service clients.
Example 13-10 illustrates Stub client code that sets Shift_JIS as the character encoding that will be used by the SOAP envelope.
Example 13-10 Setting Shift_JIS Characters for a SOAP Envelope on a Stub Client
include oracle.webservices.ClientConstants ... ((OracleStub)port)._setProperty(ClientConstants.CHARACTER_SET_ENCODING, "Shift_JIS"); ...
Example 13-11 illustrates DII client code that sets Shift_JIS as the character encoding that will be used by the SOAP envelope.
Example 13-11 Setting Shift_JIS Characters for a SOAP Envelope on a DII Client
include oracle.webservices.ClientConstants
...
ServiceFactory factory = ServiceFactory.newInstance();
Service service = factory.createService(new URL("path to wsdl"),
new QName("service namespace", "service name" ) );
Call call = service.createCall();
call.setProperty(ClientConstants.CHARACTER_SET_ENCODING, Charset.forName("Shift_JIS"));
...
JDeveloper creates a standard packaging for Web application and EJB client files. This section describes that packaging structure in case you need to customize the contents of the client EAR file.
This section describes the packaging of servlet or Web application clients. The values for a number of elements in the deployment descriptors reflect the names of the files and their storage position in the EAR file. If you change the content of the EAR file, you might need to change the content of the deployment descriptors.
Servlet or Web application clients are packaged in an EAR file with the name <ear_file_name>.ear. At the top level, the EAR file contains a META-INF directory for the manifest file and the application.xml file and <war_file_name>.war file for the servlet or Web application files, the JAX-RPC mapping file, the WSDL file, and the deployment descriptors. Example 13-12 illustrates the standard package structure of the EAR file.
This section identifies the relationships between the J2EE standard deployment descriptor web.xml, the OC4J deployment descriptor for servlets or Web applications orion-web.xml, and the packaging structure of the client EAR file. These relationships are important because if you edit the structure or contents of the client EAR file, you might have to edit the content of the deployment descriptors.
The client information is contained in the <service-ref> element in web.xml. This element contains information about the Web service that can be looked up and consumed from inside a servlet or JSP. For example, it contains the locations for the WSDL (<wsdl-file>), the JAX-RPC mapping file (<jaxrpc-mapping-file>), the service interface used for JNDI lookup (<service-ref-name>), the service interface class (<service-interface>), and the service endpoint interface (<service-endpoint-interface>). Note that the <service-ref-name> in web.xml also appears as an attribute in the <service-ref-mapping> element in orion-web.xml. If you change the names and locations of any of these items in the EAR, then you must make the corresponding changes in the deployment descriptors.
See "Adding J2EE Web Service Client Information to Deployment Descriptors" for more information on the <service-ref> and <service-ref-mapping> elements and their subelements.
Example 13-13 lists the contents of web.xml for a servlet or Web application client. The <service-ref> element is highlighted in bold.
Example 13-13 web.xml Contents for a Servlet or Web Application Client
<web-app>
<servlet>
<servlet-name>consumer</servlet-name>
<servlet-class>oracle.ServiceConsumerServlet</servlet-class>
</servlet>
<servlet-mapping>
<servlet-name>consumer</servlet-name>
<url-pattern>/consumer</url-pattern>
</servlet-mapping>
<service-ref>
<service-ref-name>service/MyHelloServiceRef</service-ref-name>
<service-interface>javax.xml.rpc.Service</service-interface>
<wsdl-file>WEB-INF/wsdl/HelloService.wsdl</wsdl-file>
<jaxrpc-mapping-file>WEB-INF/HelloService-java-wsdl-mapping.xml</jaxrpc-mapping-file>
<service-qname
xmlns:service-qname_ns__="http://hello.demo.oracle/">service-qname_ns__:HelloService</service-qname>
<port-component-ref>
<service-endpoint-interface>oracle.demo.hello.HelloInterface</service-endpoint-interface>
</port-component-ref>
</service-ref>
</web-app>
Example 13-14 lists the contents of OC4J proprietary orion-web.xml deployment descriptor for Web applications and servlets. The <service-ref-mapping> element is highlighted in bold.
Example 13-14 orion-web.xml Contents for a Client-Side Servlet or Web Application
<orion-web-app
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="http://xmlns.oracle.com/oracleas/schema/orion-web-10_0.xsd">
<service-ref-mapping name="service/MyHelloServiceRef">
<!-- stub proprty applicable across all ports -->
<stub-property>
<name>javax.xml.rpc.service.endpoint.address</name>
<value>http://localhost:8888/hello/HelloService</value>
</stub-property>
</service-ref-mapping>
</orion-web-app>
This section describes the packaging of EJB clients. The values for a number of elements in the deployment descriptors reflect the names of the files and their storage position in the EAR file. If you change the content of the EAR file, you might need to change the content of the deployment descriptors.
EJB clients are packaged in an EAR file with the name <ear_file_name>.ear. At the top level, the EAR file contains a META-INF directory for the manifest file and the application.xml file, the EJB class files, and <ejb_jar_file_name>.jar file. The JAR file contains the JAR manifest file, the JAX-RPC mapping file, the WSDL file, and the deployment descriptors. Example 13-15 illustrates the packaging structure of an EJB client EAR file.
This section identifies the relationships between the J2EE standard deployment descriptor ejb-jar.xml, the OC4J deployment descriptor for servlets or Web applications orion-ejb-jar.xml, and the packaging structure of the EJB client EAR file. These relationships are important because if you edit the structure or contents of the client EAR file, you might have to edit the content of the deployment descriptors.
The client information is contained in the <service-ref> element in ejb-jar.xml. This element contains information about the servlet or Web application that can be used as a Web service client. For example, it contains the locations for the WSDL (<wsdl-file>), the JAX-RPC mapping file (<jaxrpc-mapping-file>), the service interface used for JNDI lookup (<service-ref-name>), the service interface class (<service-interface>), and the service endpoint interface (<service-endpoint-interface>). Note that the <service-ref-name> in ejb-jar.xml also appears as an attribute in the <service-ref-mapping> element in orion-ejb-jar.xml. If you change the names and locations of any of these items in the EAR, then you must make the corresponding changes in the deployment descriptors.
See "Adding J2EE Web Service Client Information to Deployment Descriptors" for more information on the <service-ref> and <service-ref-mapping> elements and their subelements.
Example 13-16 lists the contents of ejb-jar.xml for an EJB client. The <service-ref> element is highlighted in bold.
Example 13-16 ejb-jar.xml Contents for a Client-Side EJB Application
<ejb-jar>
<display-name>serviceConsumerEJB</display-name>
<enterprise-beans>
<session>
<ejb-name>ServiceConsumer</ejb-name>
<home>oracle.ServiceConsumerHome</home>
<remote>oracle.ServiceConsumerRemote</remote>
<ejb-class>oracle.ServiceConsumerBean</ejb-class>
<session-type>Stateless</session-type>
<transaction-type>Container</transaction-type>
<service-ref>
<service-ref-name>service/MyHelloService</service-ref-name>
<service-interface>javax.xml.rpc.Service</service-interface>
<wsdl-file>META-INF/wsdl/HelloService.wsdl</wsdl-file>
<jaxrpc-mapping-file>META-INF/HelloService-java-wsdl-mapping.xml</jaxrpc-mapping-file>
<service-qnamexmlns:ns="http://hello.demo.oracle/">ns:HelloService</service-qname>
<port-component-ref>
<service-endpoint-interface>oracle.demo.hello.HelloInterface</service-endpoint-interface>
</port-component-ref>
</service-ref>
</session>
</enterprise-beans>
</ejb-jar>
Example 13-17 lists the contents of OC4J proprietary orion-ejb-jar.xml deployment descriptor for Web applications and servlets. The <service-ref-mapping> element is highlighted in bold.
Example 13-17 orion-ejb-jar.xml Contents for a Client-Side EJB Application
<orion-ejb-jar>
<enterprise-beans>
<session-deployment name="ServiceConsumer">
<service-ref-mapping name="service/MyHelloService">
<stub-property>
<name>javax.xml.rpc.service.endpoint.address</name>
<value>http://localhost:8888/hello/HelloService</value>
</stub-property>
</service-ref-mapping>
</session-deployment>
</enterprise-beans>
</orion-ejb-jar>
For more information on:
assembling Web services from a WSDL, see Chapter 5, "Assembling a Web Service from a WSDL".
assembling stateful Web services, see Chapter 6, "Assembling a Web Service with Java Classes".
assembling Web services from EJBs, see Chapter 7, "Assembling a Web Service with EJBs".
assembling Web services from a JMS queue or topic, see Chapter 8, "Assembling Web Services with JMS Destinations".
assembling Web services from database resources, see Chapter 9, "Developing Database Web Services".
assembling Web services with J2SE 5.0 Annotations, see Chapter 10, "Assembling Web Services with Annotations".
building J2SE clients, see Chapter 14, "Assembling a J2SE Web Service Client".
using the WebServicesAssembler tool to assemble Web services, see Chapter 17, "Using WebServicesAssembler".
packaging and deploying Web services, see Chapter 18, "Packaging and Deploying Web Services"
jar files that are needed to assemble a client, see Appendix A, "Web Service Client APIs and JARs".
Web services interoperability, see "Ensuring Interoperable Web Services" in the Oracle Application Server Advanced Web Services Developer's Guide.
using quality of service features in Web service clients, see "Managing Web Services" in the Oracle Application Server Advanced Web Services Developer's Guide.
adding security to a Web service, see the Oracle Application Server Web Services Security Guide.
how to write clients to access Web services secured on the transport level, see "Adding Transport-level Security for Web Services Based on EJBs" and "Accessing Web Services Secured on the Transport Level" in the Oracle Application Server Web Services Security Guide.
adding reliability to a Web service, see "Ensuring Web Service Reliability" in the Oracle Application Server Advanced Web Services Developer's Guide.
adding an auditing and logging configuration to a Web service, see "Auditing and Logging Messages" in the Oracle Application Server Advanced Web Services Developer's Guide.
processing nonstandard data types, see "Custom Serialization of Java Value Types" in the Oracle Application Server Advanced Web Services Developer's Guide.
the JAX-RPC mapping file, see "JAX-RPC Mapping File Descriptor" in the Oracle Application Server Advanced Web Services Developer's Guide.
data types supported by OracleAS Web Services, see "Mapping Java Types to XML and WSDL Types" in the Oracle Application Server Advanced Web Services Developer's Guide.
JDeveloper tool support for Web service development, see the JDeveloper on-line help.
