# Mapping properties

The following mapping properties apply only to Web services using the IBM® SOAP run-time environment.

Property descriptions:

- Mapping styles
- Mappings from Java™ to WSDL XSD (2001)
- Mappings from WSDL XSD (2001) to Java (SOAP binding)
- Mappings from WSDL XSD (2001) to Java (HTTP bindings)

#### Property descriptions

Property | Description
--- | ---
Encoding style | Rules for serializing data over SOAP protocol. Literal XML, http://xml.apache.org/xml-soap/literalxml, is based on an XML schema instance. SOAP encoding, http://schemas.xmlsoap.org/soap/ encoding/, is based on a simple type system that is a generalization of the common features found in type systems in programming languages, databases, and semi-structured data. Encodings define how data values, defined in the application, can be translated to and from protocol format. For more information on SOAP encoding, refer to www.w3.org/TR/SOAP
XML type namespace | Serves as a prefix in an XML document in order to uniquely identify an organization and to avoid element name conflicts.
XML type name | Name of a complex type or simple type as defined in XSD.
Bean class | The fully qualified name of a Java class that encapsulates a collection of data and methods to operate on the data.
Serializer class (SOAP only) | At run time, converts an instance of the bean class into an instance of the XML type according to the encoding style. The fully qualified name of a class that implements the org.apache.soap.util.xml.Serializer interface.
Deserializer class (SOAP only) | At run time, converts an instance of the XML types of the given Encoding style into an instance of the bean class. The fully qualified name of a class that implements the org.apache.soap.util.xml.Deserializer interface.
Marshaller method (HTTP only) | At run time, converts an instance of the bean class into a string for transmission over HTTP.
Unmarshaller method (HTTP only) | At run time, converts an instance of a string received over HTTP into an instance of the bean class.

#### Mapping styles

A mapping specifies an association between an XML Qname, a Java class name, an encoding style, and the serializer and deserializer used to convert between instances of the class and encoded instances of the XML Qname. The two mapping directions are referred to as Java to XML and XML to Java.

The SOAP V2.3 run-time environment holds a table of such mapping entries, called the `SOAPMappingRegistry`.

In the type mapping registry, a single Java type can map to at most one XSD type, and a single XSD type can map to at most one Java type. Most standard Java types as well as Java beans are supported by default.

Bean
  Mapping to or from any Java class other than org.w3c.dom.Element that can be configured automatically. The bean mapping style encompasses the primitive Java types, Java arrays, some of the common Java class types, such as java.lang.String, java.util.Date, and java.util.Vector.
Element
  Mapping to or from the Java type org.w3c.dom.Element that can be configured automatically.
Custom
  User-defined mapping. Mappings that default Bean or Element mapping styles may be switched to Custom mapping. This mapping style is used to create mappings for types (Java or XSD) that the run-time does not understand by default, for example user written Java classes that aren't beans, or XML complex types from non-XMLSchema2001 type systems.

#### Mappings from Java to WSDL XSD (2001)

The Mappings from Java to WSDL XSD (2001) table shows the default mappings from Java data types to WSDL part types for the SOAP and Literal XML encoding styles, as defined by the WSDL SOAP binding. The table also shows the serializer and deserializer configured into the SOAP run-time environment to perform the actual conversion between Java and XML. Combinations of Java type and encoding style that are not listed in this table default to Custom mapping.

Java Type | Encoding Style | XML Type namespace Note 1 | XML Type name | Serializer | Deserializer | Mapping Style | Comments
--- | --- | --- | --- | --- | --- | --- | ---
boolean, java.lang.Boolean | SOAP | xsd | boolean | - | - | Bean |
byte, java.lang.Byte | SOAP | xsd | byte | - | - | Bean |
short, java.lang.Short | SOAP | xsd | short | - | - | Bean |
int, java.lang.Integer | SOAP | xsd | int | - | - | Bean |
long, java.lang.Long | SOAP | xsd | long | - | - | Bean |
float, java.lang.Float | SOAP | xsd | float | - | - | Bean |
double, java.lang.Double | SOAP | xsd | double | - | - | Bean |
java.lang.String | SOAP | xsd | string | - | - | Bean |
java.math.BigDecimal | SOAP | xsd | decimal | - | - | Bean |
java.util.GregorianCalendar | SOAP | xsd | date | - | - | Bean |
java.util.Date | SOAP | xsd | dateTime | - | - | Bean |
java.util.Vector | SOAP | xml-soap Note 2 Note 20 | Vector | - | - | Bean |
java.util.Map | SOAP | xml-soap Note 2 Note 20 | Map | - | - | Bean |
java.util.Hashtable | SOAP | xml-soap Note 2 Note 20 | Map | - | - | Bean |
byte[] | SOAP | soap-enc Note 3 | base64 | - | - | Bean |
T[] (array of a type, T) | SOAP | soap-enc Note 3 | Array Note 4 | - | - | Bean | Provided T is neither byte nor org.w3c.dom.Element.
org.w3c.dom.Element | Literal XML | Note 5 | Note 6 | N/A | N/A | Element |
Java Bean | SOAP | Note 5 | Note 7 | BeanSerializer | BeanSerializer | Bean | The qualified serializer/deserializer class name is org.apache.soap. encoding.soapenc. BeanSerializer.

#### Mappings from WSDL XSD to Java (SOAP binding)

The Mappings from WSDL XSD to Java (SOAP binding) table describes the default mappings from WSDL part types to Java data types for the SOAP and Literal XML encoding styles, as defined by the WSDL SOAP binding. The table also shows the serializer and deserializer configured into the SOAP run-time environment to perform the actual conversion between Java and XML. Combinations of WSDL part type and encoding style that are not listed in this table default to Custom mapping.

XML Type namespace Note 1 | XML Type name | Encoding style | Java class | Serializer class | Deserializer class | Mapping style | Comments
--- | --- | --- | --- | --- | --- | --- | ---
xsd | boolean | SOAP | boolean, java.lang.Boolean Note 22 | - | - | Bean |
xsd | byte | SOAP | byte, java.lang.Byte Note 22 | - | - | Bean |
xsd | short | SOAP | short, java.lang.Short Note 22 | - | - | Bean |
xsd | int | SOAP | int, java.lang.Integer Note 22 | - | - | Bean |
xsd | long | SOAP | long, java.lang.Long Note 22 | - | - | Bean |
xsd | float | SOAP | float, java.lang.Float Note 22 | - | - | Bean |
xsd | double | SOAP | double, java.lang.Double Note 22 | - | - | Bean |
xsd | string | SOAP | string | - | - | Bean |
xsd | decimal | SOAP | java.math.BigDecimal | - | - | Bean |
xsd | date | SOAP | java.util.GregorianCalendar | - | - | Bean |
xsd | dateTime Note 10 | SOAP | java.util.Date | - | - | Bean |
xml-soap Note 2 | Vector | SOAP | java.util.Vector | - | - | Bean |
xml-soap Note 2 | Map | SOAP | java.util.Map Note 21 | - | - | Bean |
soap-enc Note 3 | base64 | SOAP | byte[] | - | - | Bean |
soap-enc Note 3 | Array | SOAP | T[] Note 4 | - | - | Bean | T is the mapping from wsdl:arrayType Note 4
some-namespace Note 12 | some-complex-type (in XSD 2001) Note 12 | SOAP | Note 14 | BeanSerializer | BeanSerializer | Bean | The qualified serializer/deserializer class name is com.ibm.etools. webservice.runtime. XSDAnyTypeSerializer BeanSerializer.
some-namespace Note 12 | some-complex-type (in XSD 2001) Note 12 | Literal XML | Note 14 | N/A | N/A | Bean | The conversion is handled in the generated proxy or skeleton, not in the SOAP run-time environment via SOAP serializers or deserializers.
some-namespace Note 12 | some-complex-type (in XSD 2001) Note 12 | Literal XML | org.w3c.dom.Element Note 15 | N/A | N/A | Element |
some-namespace Note 13 | some-type Note 13 | Literal XML | org.w3c.dom.Element Note 16 | N/A | N/A | Element |
xsd | anyType Note 11 | Literal XML | org.w3c.dom.Element | N/A | N/A | Element |
xsd | base64Binary | SOAP | byte[] | - | - | Bean |
xsd | hexbinary | SOAP | byte[] | - | - | Bean |
xml soap | Element | Literal XML | org.w3c.dom.Element | - | - | Element |

#### Mappings from WSDL XSD to Java (HTTP bindings)

The Mappings from WSDL XSD to Java (HTTP bindings) table describes the default mappings from WSDL part types to Java data types for the HTTP GET and POST bindings. Combinations of WSDL part type and encoding style that are not listed in this table default to Custom mapping and require the user to provide marshaller and unmarshaller methods.

XML Type namespace Note 1 | XML Type name | MIME type(s) | Java class | Mapping style
--- | --- | --- | --- | ---
xsd | boolean | text/plain text/xml mimeXml | boolean | Bean
xsd | byte | text/plain text/xml mimeXml | byte | Bean
xsd | short | text/plain text/xml mimeXml | short | Bean
xsd | int | text/plain text/xml mimeXml | int | Bean
xsd | long | text/plain text/xml mimeXml | long | Bean
xsd | float | text/plain text/xml mimeXml | float | Bean
xsd | double | text/plain text/xml mimeXml | double | Bean
xsd | string | text/plain text/xml mimeXml | string | Bean
xsd | decimal | text/plain text/xml mimeXml | java.math.BigDecimal | Bean
xsd | date | text/plain text/xml mimeXml | java.util.GregorianCalendar | Bean
xsd | dateTime Note 10 | mimeXml text/plain text/xml | java.util.Date | Bean
some-namespace Note 12 | some-complex-type (in XSD 2001) Note 12 | mimeXml | Note 14 | Bean
some-namespace Note 12 | some-complex-type (in XSD 2001) Note 12 | mimeXml | org.w3c.dom.Element Note 17 | Element
some-namespace Note 12 | some-complex-type (in XSD 2001) Note 12 | text/xml | org.w3c.dom.Element Note 18 | Element
some-namespace Note 13 | some-type Note 13 | mimeXml text/xml | org.w3c.dom.Element Note 19 | Element
xsd | anyType Note 11 | mimeXml text/xml | org.w3c.dom.Element | Element

#### Notes

1. Namespace prefix xsd is defined to the URI http://www.w3.org/2001/XMLSchema.
2. Namespace prefix xml-soap is defined to the URI http://xml.apache.org/xml-soap. This is not a SOAP standard URI.
3. Namespace prefix soap-enc is defined to the URI http://schemas.xmlsoap.org/soap/encoding/. This is a SOAP standard URI.
4. Mapping is to a complexType that restricts soap-enc:Array and defines the base wsdl:arrayType, not directly to soap-enc:Array.
5. Schema namespace is created and named automatically based on the Java class name.
6. Schema type that describes "any XML" is created automatically.
7. Schema type is created and named automatically based on the Java class name.
8. SOAP 2.2 does not define a default mapping between Java char and XSD.
9. SOAP 2.2 does not define a default mapping between the java.lang primitive wrapper types (eg. java.lang.Integer) and XSD.
10. The type dateTime in the 2001 level of XSD is called timeInstant in the 2000/10 and 1999 levels of XSD.
11. Or the similar type generated per Note 6 above.
12. The namespace and type name identify a complexType or element defined using XSD 2001.
13. The namespace and type name identify a complexType or element defined using a type system other than XSD 2001.
14. The Java bean and any necessary nested beans are created and named automatically based on the complex type name or element name and the Java bean type structure.
15. Optionally, literal XML encoded instances of a complex type in XSD 2001 can be mapped to org.w3c.dom.Element instead of to Java beans.
16. Beans cannot be generated for types defined in a type system other than XSD 2001, so Literal XML encoded instances of such types can be mapped only to org.w3c.dom.Element.
17. Optionally, instances returned as <mime:mimeXml> and of a type in XSD 2001 can be mapped to org.w3c.dom.Element instead of to Bean.
18. For instances returned as <mime:content type="text/xml"> beans are not generated, therefore, types can only be mapped to org.w3c.dom.Element.
19. For types defined in a type system other than XSD 2001 beans cannot be generated, therefore, types can only be mapped to org.w3c.dom.Element.
20. For the contents of the Vector to be serialized/deserialized properly, each type inside the vector also needs to be mapped. For example, if the vector is populated with bean X, then a mapping entry for bean X must exist. Otherwise, the user will see a message similar to "Unable to serialize/deserialize type X" during run-time.
21. XML type name Map is now mapped to java.util.Map, not java.util.Hashtable.
22. These XSD types can be mapped to the wrappers provided that no wrapper appears along with its corresponding primitive type across the set of all input parameters of the Bean or EJB.

> Name mapping rules
> A mapping defines an association between a qualified XML element name, a Java class name, and an encoding. A mapping specifies how, under the given encoding, an incoming XML element with a fully qualified name is to be converted to a Java class and vice versa. The two mapping directions are referred to as Java to XML and XML to Java.

Parent topic: WSDL files generated by the IBM SOAP runtime

Related Tasks
Developing Web services

Terms of use | Feedback
(C) Copyright IBM Corporation 1999, 2004. All Rights Reserved.