Skip Headers
Oracle® Application Server Web Services Developer's Guide
10g (

Part Number E13982-01
Go to Documentation Home
Go to Book List
Book List
Go to Table of Contents
Go to Index
Go to Feedback page
Contact Us

Go to previous page
Go to next page
View PDF

F 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.


    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/ 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/ 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(); 
    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:

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.


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 Sample 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; } 

Deserialization Errors Occur when Processing Responses or Requests

This error can occur when OracleAS Web Services attempts to perform schema validation during the deserialization step. The cause of the error is a mismatch between the schema definition found in the wsdl:types element and the format of the SOAP payload on the wire.

The error can occur when a client proxy, assembled with genProxy, attempts to deserialize a response from the server. It can occur on the server when it attempts to deserialize the request.

The following example illustrates a mismatch between the order of the elements on the wire and in the WSDL. As the deserialization code processes ParentItemId on the wire, it skips over the Quantity and PrePick elements from the schema. Processing fails when encountering PrePick on the wire, as this element is not expected after ParentItemId.

Wire format:


WSDL definition:

<xsd:complexType name="Product">
    <xsd:element name="Quantity" maxOccurs="1" minOccurs="0"
    <xsd:element name="PrePick" maxOccurs="1" minOccurs="0"
   <xsd:element name="ParentItemId" maxOccurs="1" minOccurs="0"

The following is an example deserialization error that can be thrown in this situation:

unexpected element name:

The following are possible ways to work around the error:

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.

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

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

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

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


Get NodeLists by Using getFirstChild and getNextSibling Instead of getChildNode

You may see a performance degradation when iterating over a NodeList obtained by using node.getChildNode. This degradation will only be significant for NodeLists with very long lengths.

Instead of using the NodeList obtained by node.getChildNodes, the current Oracle XDK implementation offers an optimization of navigating a list of child nodes by using node.getFirstChild and looping over node.getNextSibling. The following code sample illustrates this technique.

Node n = ...;
if (n.hasChildNodes()) {
   for(Node nd=n.getFirstChild(); nd!=null; nd=nd.getNextSibling()){
         nd.getValue(); // do something with nd       

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"  
            <output name="addRelationship1Response"
         <operation name="addRelationship3">
            <input name="addRelationship1Request"
            <output name="addRelationship1Response"

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.

Schema Features Limitations

Schema Features that are Mapped to a SOAPElement

If any of the following schema features are encountered in the WSDL, they will be mapped to a SOAPElement.

  • any model group with multiple xsd:any elements

  • xsd:choice elements

  • mixed content

  • substitution groups

  • a type with multiple xsd:any attributes

If you are assembling Web Services top down or assembling Web service proxies, WebServicesAssembler cannot consume WSDLs that contain the xsd:choice or xsd:group XML types. If you want to consume a WSDL that contains these XML types, set the WebServicesAssembler dataBinding argument to false and code the SOAPElement so that the payload conforms to the schema definition in the WSDL file.

RPC Encoded Does Not Support Complex Types With Attributes

If the schema contains a binding with an RPC-encoded message format and WebServicesAssembler encounters a complexType with attributes, then it will throw an "unsupported type encountered" error message.

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 and 10.1.2

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

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.

Developing Web Services From Database Resources

Datatype Restrictions

Differences Between Database Web Services for 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 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, 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 Also:

"assemble" and "genWsdl" for more information on using these commands to generate WSDLs for use with J2SE 5.0 Web Service annotations.

Annotated Classes Must be Listed in the classpath Argument for the WebServicesAssembler assemble Command

If you are using the WebServicesAssembler assemble command to assemble an annotated class into a Web service, then the class must be placed in the both the input and the classpath arguments. The classpath should not be needed, as files listed in the input argument are implied to be part of the classpath for non-annotated classes.

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.

Testing Web Service Deployment

The Web Service Test Page has the following limitations:

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.

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.

See Also:

"debug" for more information on this argument.

WebServicesAssembler Cannot Compile Files

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

java? 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.

Web Service and Message Parts are Generated into Separate Directories

It is possible, either intentionally or unintentionally, to generate the Web service and the message parts into separate directories. One of the ways this can happen is by setting the targetNamespace argument incorrectly.

The value of targetNamespace can be either a conforming HTTP URL, a non-conforming HTTP URL, or even a URI. The value of targetNamespace maps to a package name in the following ways:

For example, assume you are assembling a Web service with a package path oracle/demo/hello. If you set the targetNamespace argument to (a non-conforming URL), then the target namespace in the WSDL will be, but the message parts will still use the namespace oracle.demo.hello (from the service package name). If you then generate a proxy with this WSDL, then the service will be generated into and the message parts will be generated into oracle.demo.hello.

In this case, you should use http://oracle.demo.hello as the value of the targetNamespace argument. As an alternative, if the Java code resides in com/oracle/demo/hello, then use as the value of the targetNamespace argument. This ensures that the generated code will be placed in the expected Java package.

See Also:

  • "targetNamespace" for more information on how this argument responds to different URI values.

  • "packageName" for more information on the behavior of this argument.

genInterface, genProxy, and topDownAssemble Cannot Process WSDL Files Correctly that Contain Multibyte Characters in Element Names

The genInterface, genProxy, and topDownAssemble commands cannot process a WSDL file correctly if it uses multibyte characters in element names. The commands will produce Java source files, but they will not compile.

To work around this limitation, set the dataBinding argument to false when generating the interface.

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.

See Also:

"Understanding the Packaging Structure for J2EE Clients" 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.

OWS-04005 Error Returned when Generated Client and Service Classes Appear in the Same EAR File

If you generate client and Web service classes into the same directory, WebServicesAssembler might package client classes in the Web service EAR file. When you deploy the EAR file to the server, the deployment will fail with an OWS-04005 error from OracleAS Web Services:

OWS-04005 An error occurred for port: ...

For example, using Application Server Control to deploy an EAR file that contains generated client classes might return an error similar to the following:

ERROR OWS-04005 An error occurred for port: {}HttpSoap11: no serializer is registered for (class, {}sayHelloResponse)

If an attempt to invoke this service in the Web Services Test Page, the page will respond with a diagnostic message. For example, a response message similar to the following can be displayed on the Test Page:

<env:Envelope  xmlns:env="">
  <faultstring>no serializer is registered for (class, {}sayHelloResponse)</faultstring>

To work around this problem, generate your client and Web service classes into separate directories.

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.

AXIS Platform Cannot Deserialize "0" as the Value of a URI Response

According to the JAX-RPC specification, the xsd:anyURI type must be mapped to the class in applications that are intended to run on J2SE 1.4 or later. For compatibility with pre-1.4 environments, JAX-RPC implementations are allowed to map this type to java.lang.String.

The AXIS platform, however, maps xsd:anyURI to the proprietary class org.apache.axis.types.URI. This can cause problems if "0" is passed to instantiate a new URI.

For example, when the AXIS platform consumes the value "0" in the following code sample, the URI-parser assigns "0" to the port and calls the constructor for instantiation. = new"0"); // <wsdl:part
    name="inUri" type="xsd:anyURI"/>
    return ret;

This situation will cause the setPort method on AXIS platform to throw an error such as the following:

org.apache.axis.types.URI$MalformedURIException: Port cannot be set when host is null!

As a work around, use xsd:string instead of xsd:anyURI on the AXIS platform.

.NET Clients Cannot Correctly Deserialize Multi-dimensional soapenc:array Responses from OracleAS Web Services

.NET clients incorrectly represent the multi-dimensional SOAP-encoded array (soapenc:array) as an array of arrays. When these clients receive a response from OracleAS Web Services that contains a soapenc:array, they return an error similar to the following:

Unhandled Exception: System.InvalidOperationException: There is an error in XML document (2, 713). ---> System.ArgumentException: SOAP-ENC:arrayType with multdimensional array found at <ArrayOfArrayOf_xsd_anyType  xmlns=''>.

To work around this limitation in .NET clients, do not use multi-dimensional soapenc:array if interoperability with .NET is required. Use single dimensional arrays, or an array of arrays instead.

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

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 subelement 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 subelement of TypeB is serialized inside the custom serializer for TypeA. The custom serializer of TypeA must handle the subelement 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.

Changing JMS Properties

If you need to change the properties of your JMS binding after Web service deployment, you must manually edit the WSDL document to enter the correct values for the JMS address (<jms:address>) and JMS property value (<jms:propertyValue>) elements. After editing the WSDL document, redeploy the service.

Do not try to solve the problem by editing the JMS values in the oracle-webservices.xml file. The JMS part of this file is not reloaded when the service is redeployed. If you want to use the oracle-webservices.xml file to resolve the problem, then you must use WebServicesAssembler to regenerate the service.

See Also:

The JMS address and JMS property value WSDL elements are described in "WSDL Extensions for JMS Transport" in the Oracle Application Server Advanced Web Services Developer's Guide.

Using the Web Service Invocation Framework

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

Using Web Service Providers

Duplicate MBeans Appear for Web Service Provider Operations

If you are using a dynamic provider endpoint and notice duplicate MBeans appearing for an operation in Application Server Control, then ensure that the inputName and outputName attributes are specified for the operation in the oracle-webvservices.xml file.