Web services programming tips and tricks: Roundtrip issues: the mapping meta-data file

Russell Butek (butek@us.ibm.com), Software Engineer, IBM,Software Group

Russell Butek is one of the developers of the IBM WebSphere Web services engine. He is also an IBM representative on the JAX-RPC Java Specification Request (JSR) expert group. He was involved in the implementation of Apache's AXIS SOAP engine, driving AXIS 1.0 to comply with JAX-RPC 1.0. Previously, he was a developer of the IBM CORBA ORB and an IBM representative on a number of OMG task forces: the portable interceptor task force (of which he was chair), the core task force, and the interoperability task force.

Richard Scheuerle (scheu@us.ibm.com), Software Engineer, IBM,Software Group

Richard Scheuerle is one of the developers of the IBM WebSphere Web Services engine. He was involved in the implementation of Apache's AXIS SOAP engine. Richard has 10 years of development experience with compiler/language design. Currently he is concentrating on the Web service engine performance and API design. Richard has also worked on the development of CORBA tooling and chip validation software.

Summary: This final tip in the roundtrip series discusses how to use the mapping meta-data file to work around roundtripping issues.

Tag this!

Date: 18 May 2004
Level: Intermediate
Activity: 610 views

This final roundtrip tip will show you how to use the mapping meta-data file to work around the roundtrip issues, which we encountered in the first two tips of this series. See Resources for links to those tips.

What is the mapping meta-data file?

If you peel apart the EAR file from the last roundtrip tip (see Resources), you will find a WAR file. If you peel apart this WAR file, you will find WEB-INF/Roundtrip2_mapping.xml. This file contains information necessary for the runtime to map the WSDL/XML constructs, in the Web Services Description Language (WSDL) file, to the Java classes packaged in the WAR file. The format of this file is defined by the Web Services for J2EE specification.

The mapping file is generated by your vendor's WSDL-to-Java tool to designate how each WSDL/XML construct is mapped to the Java code. Normally, this file adheres to the mappings designated by the JAX-RPC specification. However, the file might differ from the JAX-RPC mapping, if a vendor supports alternative mappings.

Modifying the mapping meta-data file

If you want to change the mappings from the standard JAX-RPC mapping rules, you can modify the mapping meta-data file. There are a number of ways to change the mapping file.

Modify the mapping file directly in the EAR

You could modify the mapping file, and inject it back into the EAR file from the previous tip. But this wouldn't be enough. You would also have to change files such as: web.xml, webservices.xml, and other proprietary descriptor files. Don't forget, our existing EAR file is the one with the wrapper around the original legacy service implementation. You should also remove the unused wrapper classes from the EAR file. This approach involves a lot of work and there is a high probability of missing something.

Modify the mapping file when creating the EAR file

A better approach is to provide your modified mapping file as input to your favorite WSDL-to-Java tool when you are initially generating your artifacts. This way the generated artifacts will be aware of the changes to the mapping file from the beginning, and you won't have to change them. Please note that IBM® WebSphere® WSDL2Java tool provides a mechanism to directly provide the mapping file. Other vendors' WSDL-to-Java tools might have different approaches for making use of the modified mapping file. Also, the wrapper versions of the files won't be generated now, so the wrapper implementation won't be necessary.

Table 1 describes the changes needed in the mapping meta-data file to fix the roundtrip problems from the previous tips. To see the complete mapping meta-data file, see the included EAR file in the Resources section.

Table 1. Fixing Java code which does not roundtrip

Problem We want Date; not Calendar.

Correction

The java-xml-type-mapping construct maps dateTime to a Calendar class.

<java-xml-type-mapping>

								 <java-type>java.util.Calendar</java-type>

								 
								 <root-type-qnamexmlns:rtq="http://www.w3.org/2001/XMLSchema">

								 
								 
								 
								 rtq:dateTime

								 
								 </root-type-qname>

								 <qname-scope>simpleType</qname-scope>

</java-xml-type-mapping>

Change it to map dateTime to the Date class.

<java-xml-type-mapping>

								 <java-type>java.util.Date</java-type>

								 
								 <root-type-qnamexmlns:rtq="http://www.w3.org/2001/XMLSchema">

								 
								 
								 
								 rtq:dateTime

								 
								 </root-type-qname>

								 <qname-scope>simpleType</qname-scope>

</java-xml-type-mapping>

Problem We want the original life bean; not the generated Life bean.

Correction

The java-xml-type-mapping is used to map XML life complexType to the generated Life class.

<java-xml-type-mapping>

								 <java-type>

								 
								 
								com.ibm.developerWorks.roundtrip.generated.Life
								

								 </java-type>

								 <root-type-qname xmlns:rtq="http://roundtrip.developerWorks.ibm.com">

								 
								 rtq:life

								 </root-type-qname>

								 ...

</java-xml-type-mapping>

Change java-xml-type-mapping to use the original life class.

<java-xml-type-mapping>

								 <java-type>

								 
								 
								com.ibm.developerWorks.roundtrip.life
								

								 </java-type>

								 <root-type-qname xmlns:rtq="http://roundtrip.developerWorks.ibm.com">

								 
								 rtq:life

								 </root-type-qname>

								 ...

</java-xml-type-mapping>

We also need to change the return value of the getALife method.

								 <service-endpoint-method-mapping>

								 
								 <java-method-name>getALife</java-method-name>

								 
								 <wsdl-operation>GetALife</wsdl-operation>

								 
								 <wsdl-return-value-mapping>

								 
								 
								 <method-return-value>

								 
								 
								 
								 
								com.ibm.developerWorks.roundtrip.generated.Life
								

								 
								 
								 </method-return-value>

								 
								 
								 <wsdl-message xmlns:wrvm="http://roundtrip.developerWorks.ibm.com">

								 
								 
								 
								 wrvm:GetALifeResponse

								 
								 
								 </wsdl-message>

								 
								 
								 <wsdl-message-part-name>GetALifeReturn</wsdl-message-part-name>

								 
								 </wsdl-return-value-mapping>

								 </service-endpoint-method-mapping>

The return class type is changed to the original life class.

								 <service-endpoint-method-mapping>

								 
								 <java-method-name>getALife</java-method-name>

								 
								 <wsdl-operation>GetALife</wsdl-operation>

								 
								 <wsdl-return-value-mapping>

								 
								 
								 <method-return-value>

								 
								 
								 
								 
								com.ibm.developerWorks.roundtrip.life
								

								 
								 
								 </method-return-value>

								 
								 
								 <wsdl-message xmlns:wrvm="http://roundtrip.developerWorks.ibm.com">

								 
								 
								 
								 wrvm:GetALifeResponse

								 
								 
								 </wsdl-message>

								 
								 
								 <wsdl-message-part-name>GetALifeReturn</wsdl-message-part-name>

								 
								 </wsdl-return-value-mapping>

								 </service-endpoint-method-mapping>

Problem The interface should be the original population; not the generated Population.

Correction

The service-endpoint-interface-mapping construct defines the interface.

<service-endpoint-interface-mapping>

								 <service-endpoint-interface>

								 
								 
								com.ibm.developerWorks.roundtrip.generated.Population
								

								 </service-endpoint-interface>

								 <wsdl-port-type xmlns:seimwpt="http://roundtrip.developerWorks.ibm.com">

								 
								 seimwpt:population

								 </wsdl-port-type>

								 <wsdl-binding xmlns:seimwb="http://roundtrip.developerWorks.ibm.com">

								 
								 seimwb:populationSoapBinding

								 </wsdl-binding>

								 <service-endpoint-method-mapping>

								 
								 ...

								 </service-endpoint-method-mapping>

</service-endpoint-interface-mapping>

Change the service-endpoint-interface-mapping to use the original population interface.

<service-endpoint-interface-mapping>

								 <service-endpoint-interface>

								 
								 
								com.ibm.developerWorks.roundtrip.population
								

								 </service-endpoint-interface>

								 <wsdl-port-type xmlns:seimwpt="http://roundtrip.developerWorks.ibm.com">

								 
								 seimwpt:population

								 </wsdl-port-type>

								 <wsdl-binding xmlns:seimwb="http://roundtrip.developerWorks.ibm.com">

								 
								 seimwb:populationSoapBinding

								 </wsdl-binding>

								 <service-endpoint-method-mapping>

								 
								 ...

								 </service-endpoint-method-mapping>

</service-endpoint-interface-mapping>

Problem The method on the interface should be the original GetALife; not the generated getALife

Correction

The service-endpoint-interface-mapping contains service-endpoint-method-mapping constructs that describe the method signatures.

								 <service-endpoint-method-mapping>

								 
								 <java-method-name>getALife</java-method-name>

								 
								 <wsdl-operation>GetALife</wsdl-operation>

								 
								 <wsdl-return-value-mapping>

								 
								 
								 <method-return-value>

								 
								 
								 
								 com.ibm.developerWorks.roundtrip.generated.Life

								 
								 
								 </method-return-value>

								 
								 
								 <wsdl-message xmlns:wrvm="http://roundtrip.developerWorks.ibm.com">

								 
								 
								 
								 wrvm:GetALifeResponse

								 
								 
								 </wsdl-message>

								 
								 
								 <wsdl-message-part-name>GetALifeReturn</wsdl-message-part-name>

								 
								 </wsdl-return-value-mapping>

								 </service-endpoint-method-mapping>

Change the java-method-name to the original GetALife.

								 <service-endpoint-method-mapping>

								 
								 <java-method-name>GetALife</java-method-name>

								 
								 <wsdl-operation>GetALife</wsdl-operation>

								 
								 <wsdl-return-value-mapping>

								 
								 
								 <method-return-value>

								 
								 
								 
								 com.ibm.developerWorks.roundtrip.life

								 
								 
								 </method-return-value>

								 
								 
								 <wsdl-message xmlns:wrvm="http://roundtrip.developerWorks.ibm.com">

								 
								 
								 
								 wrvm:GetALifeResponse

								 
								 
								 </wsdl-message>

								 
								 
								 <wsdl-message-part-name>GetALifeReturn</wsdl-message-part-name>

								 
								 </wsdl-return-value-mapping>

								 </service-endpoint-method-mapping>

Problem We want the data within the life bean exposed as public variables.

Correction

The variable-mapping constructs define the data inside a bean. By default, the data is mapped as a bean property (in other words, it has setters and getters).

<java-xml-type-mapping>

								 <java-type>com.ibm.developerWorks.roundtrip.generated.Life</java-type>

								 <root-type-qname xmlns:rtq="http://roundtrip.developerWorks.ibm.com">

								 
								 rtq:life

								 </root-type-qname>

								 <qname-scope>complexType</qname-scope>

								 <variable-mapping>

								 
								 <java-variable-name>deathday</java-variable-name>

								 
								 <xml-element-name>deathday</xml-element-name>

								 </variable-mapping>

								 <variable-mapping>

								 
								 <java-variable-name>birthday</java-variable-name>

								 
								 <xml-element-name>birthday</xml-element-name>

								 </variable-mapping>

</java-xml-type-mapping>

Adding the data-member element to a variable-mapping causes the data to be mapped as a public variable.

<java-xml-type-mapping>

								 <java-type>com.ibm.developerWorks.roundtrip.life</java-type>

								 <root-type-qname xmlns:rtq="http://roundtrip.developerWorks.ibm.com">

								 
								 rtq:life

								 </root-type-qname>

								 <qname-scope>complexType</qname-scope>

								 <variable-mapping>

								 
								 <java-variable-name>deathday</java-variable-name>

								 
								 
								<data-member/>
								

								 
								 <xml-element-name>deathday</xml-element-name>

								 </variable-mapping>

								 <variable-mapping>

								 
								 <java-variable-name>birthday</java-variable-name>

								 
								 
								<data-member/>
								

								 
								 <xml-element-name>birthday</xml-element-name>

								 </variable-mapping>

</java-xml-type-mapping>

Mapping meta-data file versions

The Web Services for J2EE specification has gone through a couple versions. The mapping meta-data file shown in the table above is from Version 1.1, which is part of J2EE 1.4. Earlier versions are slightly different.

The complete format details of the mapping meta-data file can be found in the Web Services for J2EE specification.

The mapping meta-data file is no panacea

The mapping meta-data file can fix a lot of roundtrip problems. But it is not a cure-all. The mapping meta data file is useful for fixing some Java coding convention problems, and it is useful for fixing some ambiguities in the type mapping. But there are a number of problems that cannot be solved by the mapping meta-data file.

Different types per property

In our example, birthday and deathday both use the Date class. We were able to change them to the Date class by changing the global mapping of datetime in the mapping meta-data file. There is no way to change the types on a case-by-case basis. So, the mapping file cannot support a Date birthday and a Calendar deathday.

This is a common problem, and the WSDL2Java tool in WebSphere has a means to handle it (see the next section).

Boolean Accessors

Given a bean property, property, the JavaBean normally has getProperty and setProperty accessors. But if property is a boolean, the bean must have isProperty and setProperty methods. This is more than just a Java coding convention, it is a rule in the description of JavaBeans. If this rule is not followed, the bean is not strictly a JavaBean, and the JAX-RPC Java-to-WSDL tool might not respect this property or even the entire bean.

The WSDL2Java tool in WebSphere will recognize boolean getProperty methods and generate the appropriate WSDL. But the WSDL2Java tool will generate boolean isProperty methods. There is no mechanism in the mapping meta-data file to distinguish these two styles of boolean property because the boolean getProperty is an incorrect accessor.

Using getProperty for a boolean is incorrect, but it is so common that the WSDL2Java tool in WebSphere can handle these differences.

Non-camelcase accessors

Given a bean property, property, the bean normally has getProperty and setProperty accessors. Sometimes beans have getproperty and setproperty methods instead. Like the boolean getProperty, non-camelcase accessors are not legal and are not recognized as accessors. Properties with these illegal accessors tend to be ignored when mapping a bean to WSDL.

A possible panacea?

The WSDL2Java tool in WebSphere Version 6.0 has a function beyond using a mapping meta-data file. Instead of using a mapping file as the meta-data describing the Web service, it can use the original classes themselves. It uses introspection of the original classes in place of a mapping meta-data file. In this way, you can use the original service classes as input to WSDL2Java, along with the WSDL file to describe the Web service.

Summary

The roundtrip problems shown in the first two roundtrip tips can be fixed by the mapping meta-data file. This will cover the vast majority of roundtrip problems. However, there are some roundtrip problems which cannot be fixed by the mapping meta-data file. Many of these can be fixed by the introspection function provided by the WebSphere WSDL2Java tool.

Download

Name	Size	Download method
ws-roundtrip3server.ear		HTTP

Information about download methods

Resources

Download the EAR file used in this article.
Read the first tip in this series, "Roundtrip issues, an introduction" (developerWorks, March 2004).
Read the second tip in this series, "Roundtrip issues, Java coding conventions" (developerWorks, April 2004).
Read the specification Web Services Description Language (WSDL) 1.1.
Get IBM WebSphere Application Server Technology for Developers, Version 6.0, an early release of WebSphere Application Server supporting the latest J2EE, Version 1.4.
Java API for XML-Based RPC (JAX-RPC) Downloads & Specifications provides links to the JAX-RPC 1.1 specification itself, as well as javadocs, class files, and Sun's JAX-RPC reference implementation.
Download Version 1.1 of the Web Services for J2EE (JSR-109) specification.
Browse for books on these and other technical topics.

About the authors

Comments (Undergoing maintenance)

Trademarks | My developerWorks terms and conditions

Close [x]

Help: Update or add to My dW interests

What's this?

This little timesaver lets you update your My developerWorks profile with just one click! The general subject of this content (AIX and UNIX, Information Management, Lotus, Rational, Tivoli, WebSphere, Java, Linux, Open source, SOA and Web services, Web development, or XML) will be added to the interests section of your profile, if it's not there already. You only need to be logged in to My developerWorks.

And what's the point of adding your interests to your profile? That's how you find other users with the same interests as yours, and see what they're reading and contributing to the community. Your interests also help us recommend relevant developerWorks content to you.

View your My developerWorks profile

Return from help

Close [x]

Help: Remove from My dW interests

What's this?

Removing this interest does not alter your profile, but rather removes this piece of content from a list of all content for which you've indicated interest. In a future enhancement to My developerWorks, you'll be able to see a record of that content.

View your My developerWorks profile

Return from help

static.content.url=http://www.ibm.com/developerworks/js/artrating/

SITE_ID=1

Zone=SOA and Web services

ArticleID=11917

ArticleTitle=Web services programming tips and tricks: Roundtrip issues: the mapping meta-data file

publish-date=05182004

author1-email=butek@us.ibm.com

author1-email-cc=

author2-email=scheu@us.ibm.com

author2-email-cc=