October 26, 2016
Hot Topics:

Building Web Services with User-Defined Data Types

  • February 1, 2005
  • By Nandhini Arumugam
  • Send Email »
  • More Articles »
Method Description

The Serialization classes needs to extend weblogic.webservice.encoding.AbstractCodec.

The weblogic.webservice.encoding.AbstractCodec is an abstract class that contains the default implementation for serializers, deserializers, exceptions, and their contexts. You need to provide the custom implementation for the serialize() and deserialize() methods.

void serialize(Object obj,XMLName name,
                 XMLOutputStream writer,
                 SerializationContext context)
    throws SerializationException;

The serialize() method contains implementation for converting the data from Java to XML. The first parameter for this method is an Object parameter that represents the user-defined object. In this example, it represents the personSample object. Using the XML Streaming API, the Java objects are written to the XMLOutputStream parameter. The XMLName parameter is used as the name of the resulting element. The SerializationContext object is used by the Weblogic internally.

Object deserialize(XMLName name,
                   XMLInputStream reader,
                   DeserializationContext context)
    throws DeserializationException;

The deserialize() method is used to convert the XML to Java objects. The XMLInputStream will contain the XML. You need to parse the XML using the Weblogic Streaming APIs and contruct the Java Object. While using XML Streaming APIs, the stream needs to be read until the EndElement is reached. Deserialization of subsequent elements might fail otherwise. DeserializationContext is used by Weblogic internally.

Creating the data type mapping file

The data type mapping file is a subset of the web-services.xml deployment descriptor file. It contains some of the information about non–built-in data types, such as the name of the Java class that describes the Java representation of the data, the name of the serialization class that converts the data between XML and Java, and so on. The servicegen Ant task uses this data type mapping file when creating the web-services.xml deployment descriptor for the WebLogic Web Service that uses the non–built-in data type.

Following are the steps to create the data type mapping file:

  1. Create a text file named personSampleMapping.
  2. Within in the text file, add a <type-mapping> root element:
  3. For each non–built-in data type for which you have created a serialization class, add a <type-mapping-entry> child element of the <type-mapping> element. Include the following attributes:
    • xmlns:name—Declares a namespace.
    • class-name—Specifies the fully qualified name of the Java class.
    • type—Specifies the name of XML Schema type for which this data type mapping entry applies.
    • serializer—The fully qualified name of the serialization class that converts the data from its Java to its XML representation.
    • deserializer—The fully qualified name of the serialization class that converts the data from its XML to its Java representation.
    The following example is shows a data type mapping file with one <type-mapping> entry for the personSample XML Schema data type.
       deserializer="Sample.personSampleCodec" >

Creating the service with a non–built-in type

The following code shows a service that uses a personSample (user-defined) data type as its parameter and also as a return type.

package Sample;
public class MySample
  public personSample getset(personSample n)
    System.out.println("Name : "+n.getName());
    System.out.println("Age  : "+n.getAge());
    return n;


Complile the personSampleCodec and MySample Java files into classes. Ensure that the CLASSPATH variable can locate the classes. In your example, the classes will be under the "Sample" directory.

Assembling the Web service using servicegen

Assembling into Web service can be done by running a Weblogics Ant task called servicegen. The necessary information needs to be provided in a build.xml file. The build.xml for your example is shown below.

<project name="MySampleWebservice" default="ear">
<target name="ear">
<servicegen destEar="MySample.ear" contextURI="MySample" >
<service javaClassComponents="Sample.MySample"
         serviceName="MySample" serviceURI="/MySample"
         style="rpc" >

The only difference in build.xml from using a built-in data type is that here you need to provide an extra attribute called typeMappingFile, whose value will be the name of the file where the datatype mapping is written. In your example, it is placed at the "c:/personSampleTypeMapping.txt" location.

The next step is to run Ant to assemble the classes. Before that, you need to set the environment by running the setWLSEnv.bat file of Weblogic Server. This will set the necessary environment for running the servicegen task. Once the environment is set, the task can be done by issuing the command "ant" from the prompt. This servicegen task will create an EAR file; in your example, it is MySample.ear. It will contain the Web-services.war that internally contains the web-services.xml file. The .EAR file will contain the following structure.

    Necessary class file
    ... ... ...

Updating the web-services.xml file

The web-services.xml file generated by servicegen will not have the XML Schema information for the non–built-in data type for which you have created your own custom serialization class. For this reason, you must manually add the XML Schema information to the deployment descriptor under the <types></types> tag that is a child element of <web-service>.

In our example, after modification, web-services.xml will look like

<?xml version="1.0" encoding="UTF-8"?>
<web-service useSOAP12="false"
             name="MySample" style="rpc" uri="/MySample"
    <xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"
      <xsd:complexType name="personSample">
        <xsd:element name="name" type="xsd:string"
                     nillable="true" minOccurs="1"
        <xsd:element name="age" type="xsd:int" minOccurs="1"
    <type-mapping-entry deserializer="Sample.personSampleCodec"
        <java-class name="jcComp0" class-name="Sample.MySample">
        <operation name="getset" method="getset(Sample.personSample)"
            <param style="in" xmlns:p2="java:Sample.personSample"
                    type="p2:personSample" location="body"
              <return-param xmlns:p2="java:Sample.personSample"
                            location="body" name="result"

Now, the MySample.ear is updated and it is ready for deployment. In the weblogic administration console, deploy this MySample.ear under Deployments>Application. The URL for accessing this Web service will be http://hostname:portname/servicename. For example: http://localhost:7001/mySample/mySample.


Enabling a progarmmer to create Web services from complex data types opens up a wide area of possible applications in e-commerce. There will be more Web services that will address the exact needs of the target customer in a more efficient manner.

About the Author

Nandhini Arumugam holds a Masters degree in Computer Applications from PSG College of Technology, Coimbatore. She has been working as a software designer in the Telecom and Mobile Solutions Lab, Hewlett-Packard, Bangalore for more than one year. The domain of her experience includes Web services and J2EE-related technologies. She can be reached at nandhini.arumugam@hp.com.

Page 2 of 2

Comment and Contribute


(Maximum characters: 1200). You have characters left.



Enterprise Development Update

Don't miss an article. Subscribe to our newsletter below.

Sitemap | Contact Us

Thanks for your registration, follow us on our social networks to keep up-to-date
Rocket Fuel