Skip Headers

Oracle® Application Server Web Services Developer's Guide 10g Release 3 (10.1.3) B14434-01 |
| Home | Solution Area | Contents | Index

Previous | Next |

# C Troubleshooting

This appendix provides solutions to possible problems that may occur when working with Oracle Application Server Web Services. The section titles in this appendix correspond to chapter titles in the Oracle Application Server Web Services Developer's Guide and the Oracle Application Server Advanced Web Services Developer's Guide.

## OracleAS Web Services Messages

Cannot Serialize or Deserialize Array-Valued Elements to Collection Types

If you use a Java Collection type (such as `java.util.Map`, `java.util.Collection`, or a subclass of these) as a parameter or return type in your RPC-encoded Web service, then the runtime cannot properly serialize or deserialize array-valued elements to these collection parameters.

To ensure that serializers and deserializers are registered for Java array types when using the RPC-encoded message format, create a Java value type to represent each Java array.

1. Create a Java value type for each Java array type that you want to use.

   Note: Ensure that the Java value type does not contain the word "Array" in its name. "Array" is a recognized pattern.

   The following example represents the contents of the `demo/StringAry.java` file. A wrapper class, `StringAry`, represents the Java `String[]` array. Note that the name of the class uses the suffix "Ary".

       package demo;
       public class StringAry
       { public StringAry() { }
         public String[] getValue() { return m_value; }
         public void setValue(String[] value) { m_value=value; }
         private String[] m_value;
       }

2. Ensure that the proper serializers and deserializers are registered for all of your value types.

   To do this, use the `valueType` argument when you assemble the Web service. In the following example, the argument specifies the `demo/StringAry.java` file created in Step 1.

       java wsa.jar -assemble -valueType demo.StringAry ...

3. Use the value types you defined for setting and retrieving array-valued elements in your collection type parameter.

   For example, assume that you have the following class definition.

       package demo;
       public class Service extends java.rmi.Remote
       { java.util.Map getMap(String input)throws java.rmi.RemoteException
         { ... }
       }

   You can write the following code to return a `String[]` value as one of the elements in the map.

       HashMap map = new HashMap();
       String[] str_array = new String[]{"a","b","c"};
       StringAry sa = new StringAry();
       sa.setValue(str_array);
       map.put("myArray", sa);
       return map;

Errors Occur When Publishing a Web Service that Uses Multi-Dimensional Arrays

An error occurs when attempting to publish a Web service that uses multidimensional arrays. For example, an error can be returned when you attempt to publish a Java class that contains a method which takes a multidimensional array as an input or as a return argument.

There are two possible solutions to this problem:

- Create a Java Bean for each dimension of the array

- Use RPC-encoded message format to publish the Web service

Creating a Java Bean for each Dimensional of the Array: You can wrap each dimension of the array into a Java value type and work around the limitation.

Note: Ensure that the Java value type does not contain the word "Array" in its name. "Array" is a recognized pattern.

In the following example, the `public static class StringAry` wraps the inner array of strings. The `public` `StringAry[]` represents an array of the inner array. That is, it contains an array of `String` Java value types. Note that the code sample uses the suffix "Ary".

    package demo;
    public interface SampleItf extends java.rmi.Remote

     // wrap the inner array as a Java value type
    { public static class StringAry
      { public StringAry() { }
        public String[] getValue() { return m_value; }
        public void setValue(String[] value) { m_value=value; }
        private String[] m_value;
      }

      // create an  array of the inner array elements
      public StringAry[] echoString2(StringAry[] input)
            throws java.rmi.RemoteException;
    }

The `Service` class illustrates how you can then publish the `StringAry[]` array of `String` Java value types.

    package demo;
    public class Sample implements java.rmi.Remote, SampleItf
    { public SampleItf.StringAry[] echoString2(SampleItf.StringAry[] input)
             throws java.rmi.RemoteException
      { return input; }
    }

Using RPC-Encoded Style to Publish a Web Service: You can use the RPC-encoded style to publish a Web service that uses multidimensional arrays. For example:

    package demo;
    public interface SampleItf extends java.rmi.Remote
    { public String[][] echoString2(String[][] input)
             throws java.rmi.RemoteException;
    }

    package demo;
    public class Sample implements java.rmi.Remote, SampleItf
    { public String[][] echoString2(String[][] input)
             throws java.rmi.RemoteException
      { return input; }
    }

Restrictions on RPC-Encoded Format and Data Binding

OracleAS Web Services does not support the combination of RPC-encoded message formats and `databinding=false`. This combination is not considered a "best practice" within the industry.

Document-Encoded Message Format is not Supported by OracleAS Web Services

Even though the combination of `style="document"` and `use="encoded"` is valid according to the SOAP specification, it is not supported by any of the major Web Services platforms, including OracleAS Web Services.

Document-Literal Bare Message Format is Limited to One Input Part

OracleAS Web Services supports only one part as input in the bare case. All other input parameters must be mapped into SOAP header parts.

Serialization of BigDecimal Values May Introduce Rounding Errors

There are several constructors available for `java.Math.BigDecimal`. The constructors can take the following types of input.

- a double-precision floating point

- an integer and a scale factor

- a String representation of a decimal number

You should be careful when you use the `BigDecimal(double)` constructor. It can allow rounding errors to enter into your calculations. Instead, use the `integer` or `String`-based constructors.

For example, consider the following statements which take the value 123.45.

    ...
    double d = 1234.45;
    System.out.println(d);
    System.out.println(new BigDecimal(d));
    ...

These statements produce the following output. The second value might not be the value you expected.

    1234.45
    1234.450000000000045474735088646411895751953125

## Assembling Web Services from a WSDL

Restrictions on Using Document Literal Message Formats

If you attempt to assemble a Web service top down that uses a document-literal message format, WebServicesAssembler will return a warning if it detects two or more operations in the WSDL that use the same input message. This is because the OC4J runtime will not be able to distinguish which method is being invoked.

For example, the following WSDL fragment will cause WebServicesAssembler to return a warning. The fragment defines the `addRelationship` and `addRelationship3` operations. Each of these operations use the `addRelationshipRequest` input message.

    ...
    <operation name="addRelationship">
         <input name="addRelationship1Request"
    message="tns:addRelationship1Request"/>
                <output name="addRelationship1Response"
    message="tns:addRelationship1Response"/>
            </operation>
             <operation name="addRelationship3">
                <input name="addRelationship1Request"
    message="tns:addRelationship1Request"/>
                <output name="addRelationship1Response"
    message="tns:addRelationship1Response"/>
            </operation>
    ...

If you were to invoke the `addRelationship` operation from your client, then depending on the order in which the operations appear in your implementation class, either `addRelationship` or `addRelationship3` would be invoked.

## Assembling Web Services from Java Classes

Limitations on Stateful Web Services

The support that OracleAS Web Services offers for stateful Web services is limited to services based on Java classes. These services contain Oracle-proprietary extensions and you should not consider them to be interoperable unless the service provider makes scopes with the same semantics available.

The support that OracleAS Web Services offers for stateful Web services is HTTP-based. Stateful Web services will work only for SOAP/HTTP endpoints and will not work for SOAP/JMS endpoints.

Assembling Web Services from Java Classes—Differences Between Releases 10.1.3 and 10.1.2

Note the following differences between Oracle Web Services release 10.1.2 (and earlier) and release 10.1.3.

- In release 10.1.2 there was no requirement to extend `RemoteInterface` or for methods to throw `RemoteException`. This is now required in release 10.1.3.

- In release 10.1.2 it was possible to publish a class by itself without providing an interface. In release 10.1.3 you must provide an interface to publish a class.

## Assembling Web Services From EJBs

Setting the Transaction Demarcation for EJBs

An EJB exposed as a Web service should not have `TX_REQUIRED` or `TX_MANDATORY` set as its transaction demarcation.

## Assembling Web Services with JMS Destinations

Supported Types for Message Payloads

For JMS endpoint Web services, OracleAS Web Services supports only instances of `java.lang.String` or `javax.xml.soap.SOAPElement` as the payload of JMS messages.

JMS Properties in the SOAP Message Header

Only a limited number of JMS properties can be transmitted by the SOAP header. If the value of the `genJmsPropertyHeader` argument is `true` (default), then the following JMS properties can be transmitted by the SOAP header.

- message-ID

- correlation-ID

- the reply-to-destination, including its name, type, and factory

## Developing Web Services From Database Resources

Datatype Restrictions

- Streams are not supported in Oracle Streams AQ Web services.

- SQL Type `SYS.ANYDATA` is not supported in PL/SQL Web services.

- `REF CURSOR` as a parameter is not supported in PL/SQL Web services.

- `REF CURSOR` returned as Oracle `WebRowSet` and `XDB` `RowSet` does not support complex types in the result.

- Due to a limitation in JDBC, PL/SQL stored procedures do not support the following SQL types as `OUT` or `INOUT` parameters.

  - `char` types, including `char`, `character`, and `nchar`

  - `long` types including `long` and `long raw`

Differences Between Database Web Services for 10.1.3 and Earlier Releases

A Web service client written for a database Web service generated under release 9.0.4 or 10.1.2, will fail if you try to use it against a database Web service generated bottom up under release 10.1.3. This will be true even if the PL/SQL structures have remained the same.

One of the reasons for this is that the SQL collection type was mapped into a complex type with a single array property in releases 9.0.4 and 10.1.2. In release 10.1.3, it is mapped directly into array instead.

If you regenerate the Web service client, you will have to rewrite the client code. This is because the regenerated code will now be employing an `array[]` instead of a `BeanWrappingArray`.

## Assembling Web Services with Annotations

Web Service Metadata Features that are Not Supported

There are parts of the Web Services Metadata for the Java Platform specification that OracleAS Web Services does not support. For example, OracleAS Web Services does not support the "Start With WSDL" or "Start With WSDL and Java" modes defined in sections 2.2.2 and 2.2.3 of the "Java Architecture for XML Binding" (JAXB) specification. OracleAS Web Services supports only the "Start With Java" mode.

If you use the `assemble` or the `genWsdl` WebServicesAssembler commands to generate a WSDL to use with J2SE 5.0 Web Service annotations, you must specify them differently than if you were using them to process files that do not contain annotations. See "assemble" and "genWsdl" for more information on using these commands to generate WSDLs for use with J2SE 5.0 Web Service annotations.

## Assembling REST Web Services

Restrictions on REST Web Services Support

The following list describes the limitations in OracleAS Web Services support for REST Web Services.

- REST support is available only for Web service applications with literal operations (both request and response should be literal).

- HTTP GET is supported only for Web service operations without (required) complex parameters.

- Some browsers limit the size of the HTTP GET URL. Try to keep the size of the URL small by using a limited number of parameters and short parameter values.

- REST Web services send only simple XML messages. You cannot send messages with attachments.

- Many management features, such as security and reliability, are not available with REST Web services. This is because SOAP headers, which are typically used to carry this information, cannot be used with REST invocations of services.

- REST invocations cannot be made from generated Stubs or DII clients. Invocations from those clients will be made in SOAP.

- There is no REST support for the Provider framework.

- Operation names in REST cannot contain multibyte characters.

- REST services cannot be managed through Application Server Control.

## Testing Web Service Deployment

The Web Service Home Page has the following limitations:

- The Web Service Home Page offers only basic support for WS-Security. The editors can enter only a username and password into the SOAP envelope. To enter any other complex or advanced WS-Security features, such as encryption and signing, in the SOAP request, you must edit the request directly in the Invocation Page.

- The Web Service Home Page does not allow you to upload attachments.

- You cannot invoke WSIF services using the test page.

- WSDL files that contain proprietary extensions may not work properly in the Web Service Home Page. For example, services that use JMS as a transport cannot be tested by using the Home Page.

## Assembling a J2EE Web Service Client

Client Applications and Thread Usage

If the client application creates its own threads for its processing (for example, if it enables an asynchronous call using a separate thread), the application server must be started with the `-userThreads` option.

    java -jar oc4j.jar -userThreads

The `-userThreads` option enables context lookup and class loading support from user-created threads.

## Understanding JAX-RPC Handlers

WebServicesAssembler provides Ant tasks that let you configure JAX-RPC message handlers. Handlers cannot be configured by using the WebServicesAssembler command line.

## Processing SOAP Headers

Strong Typing and the ServiceLifecycle Interface

Although the `ServiceLifecycle` interface enables you to access SOAP header blocks that may not have been declared in the WSDL file, the blocks are not strongly typed. You may also need to know the XML structure of a SOAP header in order to process it. For strong typing of SOAP header blocks, make sure that the `mapHeadersToParameters` argument for WebServicesAssembler is set to `true` (`true` is the default value). This is only possible if the SOAP header has been declared in the WSDL file and the type of the SOAP header is a supported JAX-RPC type.

## Using WebServicesAssembler

Long file names cause deployment to fail

If the combined length of the generated file and directory names passes a certain size limit, then deployment will fail and throw an error. This size limit varies for different operating systems. For example, on the Windows operating system, the size limit is 255 characters

The length of the names is controlled by WebServicesAssembler and the deployment code. WebServicesAssembler generates file names based on the method name in the Java class or the operation name in the WSDL. The deployment code creates directories for code generation based on the names of the EAR and the WAR files.

To avoid the generation of file and directory names that are too long, limit the number of characters in the following names to a reasonable length.

- method names in Java classes

- operation names in the WSDL

- directory name for the location of the OC4J installation

- file name for a WAR file

- file name for a EAR file

You can also avoid this problem by upgrading to a more recent version of the J2SE 5.0 JDK (jdk-1_5_0_06 or later).

Getting More Information on WebServicesAssembler Errors

You can get detailed diagnostic information on errors returned by WebServicesAssembler by including the `debug` argument in the command line or Ant task. For more information on this argument, see "debug".

WebServicesAssembler Cannot Compile Files

If WebServicesAssembler cannot compile files successfully, it will return the error:

    java? java.io.IOException: CreateProcess: javac -encoding UTF-8 -classpath

The `javac` compiler must be available so that WebServicesAssembler can compile your Java files. Make sure that `JAVA_HOME``/bin` is in your path.

WebServicesAssembler Cannot Find Required Classes

You may need to use some classes that are common to all J2EE 1.4 applications. All standard J2EE 1.4 classes and Oracle database classes are included automatically. When using Ant tasks, WebServicesAssembler must search for the JARs that contain these classes.

A WebServicesAssembler Ant task tries to load these extra classes by searching for `wsa.jar`. The task searches for the following Ant properties or environment variables in the following order. If the task does not find `wsa.jar`, or if a property is not defined, it searches the next property.

1. `oc4j.home`—an Ant property that specifies the root installation directory for OC4J. This property can be used instead of an environment variable.

2. `OC4J_HOME`—an environment variable that specifies the root installation directory for OC4J.

3. `oracle.home`—an Ant property that specifies the root installation directory for Oracle products. This property can be used instead of an environment variable.

4. `ORACLE_HOME`—an environment variable that specifies the root installation directory for Oracle products.

When the Ant task finds `wsa.jar`, it loads all of the classes listed in its manifest file, relative to the location of `wsa.jar`.

## Packaging and Deploying Web Services

Packaging for J2EE Clients

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.

Getting the Correct Endpoint Address when the WSDL Has More than One HTTP Port

If a you want to enter values for the `<web-site>` or `<wsdl-publish-location>` elements in `oracle-webservices.xml`, then the returned WSDL may not have the correct endpoint addresses if the WSDL has more than one HTTP port.

The WebServicesAssembler tool does not insert the `<web-site>` or `<wsdl-publish-location>` elements into the `oracle-webservices.xml` file that it creates. You must insert these elements manually.

## Ensuring Interoperable Web Services

Leading Underscores in WebServicesAssembler Generated Names

The default behavior of the WebServicesAssembler tool is to generate namespaces from the Java package name. If the Java package name begins with a leading underscore ("_"), then the generated namespace URI will contain an underscore. Some versions of the .NET WSDL tool may not be able to consume these namespaces, even though the generated namespace is valid.

To work around this .NET issue, use the WebServicesAssembler arguments `targetNamespace` and/or `mappingFileName` to avoid the default package-derived namespace.

## Working with Message Attachments

Adding Faults with swaRef Attachments to a Web Service

In OracleAS Web Services, you can add only `swaRef` MIME type attachments to SOAP fault messages. It does not support the adding of `SWA` type attachments.

Faults with attachments can be added to a Web service only when you are assembling it from a WSDL (top down). They cannot be added when assembling a Web service bottom up.

Supported Message Formats for Attachments

Only RPC-literal and document-literal Web services are supported by the WS-I Attachments Profile 1.0. Thus, only those types of services can use `swaRef` MIME type.

WebServicesAssembler will not be able to assemble a Web service that can pass `swaRef` MIME attachments if you specify an RPC-encoded message format. To assemble the service, you must select a different format.

## Managing Web Services

Limitations on Application Server Control

Application Server Control cannot modify everything that can be expressed in the `wsmgmt.xml` file. For example, it cannot be used to change parts of the reliability configuration.

## Ensuring Web Service Reliability

Reliability Limitations for OracleAS Web Services

- The reliability process on the client lives only as long as the client process. If the client process becomes permanently unavailable, then any messages that needed to be retried will be ignored.

- Asynchronous polling capabilities can be enabled only at the port level and only by using a configuration.

## Auditing and Logging Messages

Limitations on xpath Queries

An `xpath` query must return a primitive type. This means that the query must return the context of text nodes or attribute values.

The primitive type that the `xpath` query returns should have a small number of characters. For example, it should not exceed 120 characters.

## Custom Serialization of Java Value Types

This section describes limitations on the custom serialization of non-standard data types.

Literal Use

This release supports only literal as the `use` part of the message format. This includes RPC-literal and document-literal. RPC-encoded is not supported in this release.

Object Graph

Because RPC-encoded is not supported in this release, the initial support of serialization and deserialization does not allow object graph marshalling using `href`. If a Java Object has multiple references either in the parameters of a request or in the return value of a response, then serialization and deserialization might not preserve the object graph.

WSDL- and Service-Level Configuration

`SoapElementSerializer` is configured for each Service or for each WSDL. For example, a `SoapElementSerializer` implementation representing the mapping of `dateTime` to `oracle.sql.DATE` can be configured to replace the default mapping of `dateTime` to `java.util.Calendar`. Under this configuration, every instance of the mapping is replaced. Configuration for each operation or message level is not supported in this release.

Sub Tree Serialization

Each custom serializer gets the full XML sub-tree, and performs the serialization and deserialization of the entire XML element object model. For example, assume you have two custom serializers developed and configured for two top-level `complexTypes`, `TypeA` and `TypeB`. `TypeA` has a sub-element of `TypeB`. Even though a custom serializer has been configured for `TypeB`, this custom serializer cannot be automatically invoked by the OC4J runtime when the sub-element of `TypeB` is serialized inside the custom serializer for `TypeA`. The custom serializer of `TypeA` must handle the sub-element of `TypeB` by itself. The custom serializer of `TypeA` can, in turn, call the custom serializer of `TypeB`, but it is up to the implementation strategy.

Document-Literal Wrapper

Assume that a a custom serializer is used to handle a global `complexType` that is referred by a global element to define the single part of a document-literal operation. If you use the `unwrapParameters` argument to unwrap the return type and response type, it will be ignored for the operation(s) that use the global element as the body part of the input message.

## Using JMS as a Web Service Transport

Interoperability of Messages when using JMS as a Transport Mechanism

The WSDL extensions that enable JMS as a transport mechanism are Oracle-proprietary. The messages produced by the Web service may not be interoperable with applications or services provided by other vendors.

Retrieving Client Responses from JMS Web Service Transport

If the client process becomes unavailable without receiving its response and later returns, there is no facility provided for it to retrieve its old responses from the queue.

## Using the Web Service Invocation Framework

This section describes limitations in the OracleAS Web Services support for the Web Services Invocation Framework (WSIF).

- Database WSIF can pass only the data source, not the JDBC connection, to the provider for database access.

- Database WSIF is stateless. Each operation obtains a JDBC connection when it begins and closes it when it ends. Autocommit is always on for the JDBC connection. It is recommended that you use connection pooling when setting up data sources to reduce database overhead.

- Oracle's Application Server Control Web Services Management and Monitoring can only directly monitor SOAP services; it cannot monitor any service interactions that utilize WSIF bindings, such as Java, EJB, or database WSIF bindings. By bypassing the SOAP protocol entirely, you are also bypassing the management infrastructure for Web services provided by Oracle Application Server Control.

## Using Dynamic Invocation Interface to Invoke Web Services

To invoke a Web service by using the Dynamic Invocation Interface (DII) requires a number of steps. At each step, you typically have to make some choices. The examples at the end of this section display choices made at each of the steps.

Using DII to invoke a Web Service consists of the following general steps:

1. Create the call object.

2. Register parameters.

3. Invoke the Web service.

You can create the call object either with or without a WSDL. If you do not have a WSDL, or decide not to use the WSDL for creating the call dynamically, then follow the steps under "Basic Calls". If you do have a WSDL to construct the call, then follow the instructions under "Configured Calls".

### Basic Calls

For a basic call, the call object is created dynamically without a WSDL. The following steps provide more information on how to construct a basic call.

1. You are constructing a call object dynamically, without a WSDL. For examples, see:

   - Example C-1, "Basic Call with parameter registration and Java bindings"

   - Example C-4, "Basic Call with SOAPElement, but without parameter registration"

   - Example C-6, "Basic Call with document-literal invocation and SOAPElement, but without parameter registration"

2. Register parameters.

   - Case 1: You are constructing the SOAP request yourself as a `SOAPElement`, and are receiving the response as a `SOAPElement`. In this case, you do not have to register parameters or return types. For examples of this case, see:

     - Example C-4, "Basic Call with SOAPElement, but without parameter registration"

     - Example C-6, "Basic Call with document-literal invocation and SOAPElement, but without parameter registration"

   - Case 2: You are explicitly registering the parameters and returns (parts) that are being used in the Web service invocation in your Basic Call, including the part name, the XML and Java type names, and the parameter mode. In this case, you can furnish the individual parameters as Java object instances. For an example of this case, see:

     - Example C-1, "Basic Call with parameter registration and Java bindings"

3. Invoke the Web service. You can invoke the Web service either by using `SOAPElement` or by Java bindings.

   - Case 1: Using `SOAPElement`. If you are using a document-literal invocation, then you will typically construct a `SOAPElement` for your message and pass it to the `invoke()` method. Note that this invocation employs the public, Oracle-specific API from `OracleCall`. For examples of this case, see:

     - Example C-4, "Basic Call with SOAPElement, but without parameter registration"

     - Example C-6, "Basic Call with document-literal invocation and SOAPElement, but without parameter registration"

   - Case 2: Using Java bindings. If you are using an RPC-literal or RPC-encoded invocation, then you will typically supply an array containing Java objects in the `invoke()` method and cast the return object to the anticipated return type. For examples of this case, see:

     - Example C-1, "Basic Call with parameter registration and Java bindings"

     - Example C-2, "Configured Call with Java bindings, but without parameter registration"

     - Example C-3, "Configured Call with registration of wrapper parameters and Java bindings"

     - Example C-5, "Configured Call with a WSDL, complex return parameter registration, and Java bindings"

     - Example C-7, "Configured Call with RPC-encoded invocation, complex parameter registration, and Java bindings"

### Configured Calls

For a configured call, the call object is constructed from a WSDL. The following steps provide more information on how to construct a configured call.

1. Provide the WSDL for constructing the call object. For examples, see:

   - Example C-2, "Configured Call with Java bindings, but without parameter registration"

   - Example C-3, "Configured Call with registration of wrapper parameters and Java bindings"

   - Example C-5, "Configured Call with a WSDL, complex return parameter registration, and Java bindings"

   - Example C-7, "Configured Call with RPC-encoded invocation, complex parameter registration, and Java bindings"

2. Register parameters. For a Configured Call, you must register parameters for the following cases:

   - Case 1: You are employing a complex or other type that is not being mapped to a primitive Java type (or an Object variant of a primitive Java type). For examples of this case, see:

     - Example C-5, "Configured Call with a WSDL, complex return parameter registration, and Java bindings"

     - Example C-7, "Configured Call with RPC-encoded invocation, complex parameter registration, and Java bindings".

   - Case 2: You are using a document-literal wrapped style and do not want to create a `SOAPElement` like the ones illustrated in Example C-4 and Example C-6 for Basic Call. In this case, the name of the parameter must be the `QName` of the wrapper. For an example of this case, see:

     - Example C-3, "Configured Call with registration of wrapper parameters and Java bindings"

   - Case 3: If Case 1 and Case 2 do not apply, then you do not have to register parameters or returns. For an example of this case, see:

     - Example C-2, "Configured Call with Java bindings, but without parameter registration"

3. Invoke the Web service. You can invoke the Web service either by using `SOAPElement` or by Java bindings.

   - Case 1: Using `SOAPElement`. If you are using a document-literal invocation, then you will typically construct a `SOAPElement` for your message and pass it to the `invoke()` method. Note that this invocation employs the public, Oracle-specific API from `OracleCall`. For examples of this case, see:

     - Example C-4, "Basic Call with SOAPElement, but without parameter registration"

     - Example C-6, "Basic Call with document-literal invocation and SOAPElement, but without parameter registration"

   - Case 2: Using Java bindings. If you are using an RPC-literal or RPC-encoded invocation, then you will typically supply an array containing Java objects in the `invoke()` method and cast the return object to the anticipated return type. For examples of this case, see:

     - Example C-1, "Basic Call with parameter registration and Java bindings"

     - Example C-2, "Configured Call with Java bindings, but without parameter registration"

     - Example C-3, "Configured Call with registration of wrapper parameters and Java bindings"

     - Example C-5, "Configured Call with a WSDL, complex return parameter registration, and Java bindings"

     - Example C-7, "Configured Call with RPC-encoded invocation, complex parameter registration, and Java bindings"

### Examples of Web Service Clients that use DII

This section provides a variety of client examples that use basic calls or configured calls to invoke a Web service.

The following code snippet illustrates an `import` statement that can be used by the following code examples.

    import javax.xml.rpc.ServiceFactory;
    import javax.xml.rpc.Service;
    import javax.xml.rpc.Call;
    import javax.xml.rpc.ParameterMode;
    import javax.xml.namespace.QName;
    import javax.xml.soap.SOAPFactory;
    import javax.xml.soap.SOAPElement;
    import java.net.URL;
    import oracle.webservices.OracleCall;
    import oracle.xml.parser.v2.XMLElement;

Example C-1 Basic Call with parameter registration and Java bindings

    // (1) Creation of call object without WSDL.
    String endpoint = "http://localhost:8888/echo/DiiDocEchoService";
    ServiceFactory sf = ServiceFactory.newInstance();
    Service service = sf.createService(new QName("http://echo.demo.oracle/", "tns"));
    Call call = service.createCall();

    // (2) Configuration of call and registration of parameters.
    call.setTargetEndpointAddress(endpoint);
    call.setProperty(Call.SOAPACTION_USE_PROPERTY, new Boolean(true));
    call.setProperty(Call.SOAPACTION_URI_PROPERTY, "");
    call.setProperty(Call.ENCODINGSTYLE_URI_PROPERTY, "http://schemas.xmlsoap.org/soap/encoding/");
    call.setProperty(Call.OPERATION_STYLE_PROPERTY, "rpc");
    QName QNAME_TYPE_STRING = new QName("http://www.w3.org/2001/XMLSchema", "string");
    call.addParameter("s", QNAME_TYPE_STRING, ParameterMode.IN);
    call.setReturnType(QNAME_TYPE_STRING);

    // (3) Invocation.
    System.out.println("Response is " + call.invoke(new Object[]{"hello"}));

Example C-2 Configured Call with Java bindings, but without parameter registration

    /// (1) Creation of call object using WSDL.
    String namespace = "http://www.xmethods.net/sd/CurrencyExchangeService.wsdl";
    URL wsdl=new URL(namespace);
    ServiceFactory factory = ServiceFactory.newInstance();
    QName serviceName = new QName(namespace, "CurrencyExchangeService");
    Service service = factory.createService(wsdl, serviceName);
    QName portName = new QName(namespace, "CurrencyExchangePort");
    Call call = service.createCall(portName);

    // (2) Registration of parameters.
    //     -> taken from the WSDL

    // (3) Configuration of operation and invocation.
    QName operationName = new QName("urn:xmethods-CurrencyExchange", "getRate");
    call.setOperationName(operationName);
    Float rate = (Float) call.invoke(new Object[]{"usa", "canada"});
    System.out.println("getRate: " + rate);

Example C-3 Configured Call with registration of wrapper parameters and Java bindings

    // (1) Creation of call object using WSDL.
    String namespace = "http://server.hello/jaxws";
    ServiceFactory factory = ServiceFactory.newInstance();
    QName serviceName = new QName(namespace, "HelloImplService");
    URL wsdl=new URL(namespace+"?WSDL");
    Service service = factory.createService(wsdl, serviceName);
    QName portName = new QName(namespace, "HelloImpl");
    Call call = service.createCall(portName);

    // (2) Registration of SayHello and SayHelloResponse wrapper classes
    //     These must be available in the classpath.
    String TYPE_NAMESPACE_VALUE = "http://server.hello/jaxws";
    QName reqQname = new QName(TYPE_NAMESPACE_VALUE,"sayHelloElement");
    QName respQName = new QName(TYPE_NAMESPACE_VALUE,"sayHelloResponseElement");
    call.addParameter("name", reqQname, SayHello.class, ParameterMode.IN );
    call.setReturnType(respQName, SayHelloResponse.class );

    // (3) Invocation
    SayHello input = new SayHello("Duke");
    Object[] params = new Object[] { input };
    SayHelloResponse result = (SayHelloResponse) call.invoke( params );
    String response = result.getResult();

Example C-4 Basic Call with SOAPElement, but without parameter registration

    // (1) Creation of call object without WSDL
    ServiceFactory sf = ServiceFactory.newInstance();
    Service service = sf.createService(new QName("http://echo.demo.oracle/", "tns"));
    Call call = service.createCall();
    call.setTargetEndpointAddress("http://localhost:8888/echo/DiiDocEchoService");

    // (2) No registration of parameters

    // (3a) Direct creation of payload as SOAPElement
    SOAPFactory soapfactory = SOAPFactory.newInstance();
    SOAPElement m1 = soapfactory.createElement("echoStringElement", "tns", "http://echo.demo.oracle/");
    SOAPElement m2 = soapfactory.createElement("s", "tns", "http://echo.demo.oracle/");
    m2.addTextNode("Bob");
    m1.addChildElement(m2);
    System.out.println("Request is: ");
    ((XMLElement) m1).print(System.out);

    // (3b) Invocation
    SOAPElement resp = (SOAPElement) ((OracleCall) call).invoke(m1);
    System.out.println("Response is: ");
    ((XMLElement) resp).print(System.out);

Example C-5 Configured Call with a WSDL, complex return parameter registration, and Java bindings

    // (0) Preparing a complex argument value
    Integer  req_I = new Integer( Integer.MAX_VALUE );
    String   req_s = "testDocLitBindingAnonymAll & <body>";
    Integer  req_inner_I = new Integer( Integer.MIN_VALUE );
    String   req_inner_s = "<inner> & <body>";
    int[]    req_inner_i = {0,Integer.MAX_VALUE, Integer.MIN_VALUE};
    InnerSequence req_inner = new InnerSequence();
    req_inner.setVarInteger( req_inner_I );
    req_inner.setVarString ( req_inner_s );
    req_inner.setVarInt    ( req_inner_i );
    EchoAnonymAllElement req = new EchoAnonymAllElement();
    req.setVarInteger   ( req_I );
    req.setVarString    ( req_s );
    req.setInnerSequence( req_inner);

    // (1) Creation of call object using the WSDL
    String TARGET_NS = "http://soapinterop.org/DocLitBinding";
    String TYPE_NS = "http://soapinterop.org/xsd";
    String XSD_NS = "http://www.w3.org/2001/XMLSchema";
    QName SERVICE_NAME = new QName( TARGET_NS, "DocLitBindingService" );
    QName PORT_NAME = new QName( TARGET_NS, "DocLitBindingPort");
    String wsdlUrl = "http://"+getProperty("HOST")+
                     ":"+getProperty("HTTP_PORT")+
                     "/doclit_binding/doclit_binding";

    QName operation = new QName(TARGET_NS, "echoAnonymAll");
    ServiceFactory factory = ServiceFactory.newInstance();
    Service srv = factory.createService( new URL(wsdlUrl + "?WSDL"), SERVICE_NAME);
    Call call = srv.createCall( PORT_NAME, operation );

    // (2) Registration of complex return parameter
    call.setReturnType(new QName(TYPE_NS, "EchoAnonymAllElement"), EchoAnonymAllElement.class);

    // (3) Invocation
    EchoAnonymAllElement res = (EchoAnonymAllElement) call.invoke( new Object[]{req} );
    System.out.println( "AnonymAll body  : " +res.getVarString() );
    System.out.println( "AnonymAll inner : " +res.getInnerSequence() );

Example C-6 Basic Call with document-literal invocation and SOAPElement, but without parameter registration

    // (1) Creation of Basic Call
    ServiceFactory sf = ServiceFactory.newInstance();
    Service service = sf.createService(new QName("http://echo.demo.oracle/", "tns"));
    String endpoint="http://localhost:8888/test/echo";
    Call call = service.createCall();
    call.setTargetEndpointAddress(endpoint);

    // (2) No parameter registration

    // (3) Invocation using SOAPElement
    SOAPFactory soapfactory = SOAPFactory.newInstance();
    SOAPElement m1 = soapfactory.createElement("echoStringElement", "tns", "http://echo.demo.oracle/");
    SOAPElement m2 = soapfactory.createElement("s", "tns", "http://echo.demo.oracle/");
    m2.addTextNode("Bob");
    m1.addChildElement(m2);
    System.out.println("Request is: ");
    ((XMLElement) m1).print(System.out);
    SOAPElement resp = (SOAPElement) ((OracleCall) call).invoke(m1);
    System.out.println("Response is: ");
    ((XMLElement) resp).print(System.out);

Example C-7 Configured Call with RPC-encoded invocation, complex parameter registration, and Java bindings

    // (1) Creation of ConfiguredCall using WSDL
    ServiceFactory sf = ServiceFactory.newInstance();
    String endpoint="http://localhost:8888/test/echo";
    Service service = sf.createService(new java.net.URL(endpoint + "?WSDL"), new QName("http://echo.demo.oracle/", "DiiRpcEchoService"));
    Call call = service.createCall(new QName("http://echo.demo.oracle/", "HttpSoap11"), new QName("http://echo.demo.oracle/", "echoStrings"));
    call.setProperty(Call.SOAPACTION_USE_PROPERTY, new Boolean(true));
    call.setProperty(Call.SOAPACTION_URI_PROPERTY, "");
    call.setProperty(Call.ENCODINGSTYLE_URI_PROPERTY, "http://schemas.xmlsoap.org/soap/encoding/");
    call.setProperty(Call.OPERATION_STYLE_PROPERTY, "rpc");

    // (2) Registration of complex input and return arguments
    QName stringArray = new QName("http://echo.demo.oracle/", "stringArray");
    call.addParameter("s", stringArray, String[].class, ParameterMode.IN);
    call.setReturnType(stringArray, String[].class);

    // (3) Invocation
    String[] request = new String[]{"bugs", "little_pieces", "candy"};
    String[] resp = (String[]) call.invoke(new Object[]{request});
    System.out.println("Response is: ");
    for (int i = 0; i < resp.length; i++) {
       System.out.print(resp[i] + " ");
    }
    System.out.println();