Oracle TopLink as a Custom Serializer in a JAX-RPC 1.1 Web Service

Step 1: Folder Setup

Create the <DEMO_HOME> folder and copy the Customer.xsd file and the Customer.xml deployment descriptor file (created in the TopLink O-X How-To) to its root level.

Also copy the Customer.xml deployment descriptor file to the root level of the <DEMO_HOME>/classes folder.

Step 2: Compile the Customer Model Classes

Extract the Java source files from CustomerModel.zip to the <DEMO_HOME>/src folder and compile them to the <DEMO_HOME>/classes folder.

Create a model.jar file that contains the compiled model class files Customer.class, Address.class, and PhoneNumber.class. Copy the model.jar file to the <DEMO_HOME> folder. The model.jar file is used by the client.

Step 3: Create the Web Service Interface and Implementation Classes

Create a <DEMO_HOME>/src/examples/jaxrpc/jaxrpc11/service folder and create a CustomerLocatorService.java interface and CustomerLocatorServiceImpl.java class file in it. The Web service for this How-To will have a single method with signature public Customer findCustomer(). This method simply returns a newly created Customer object (see Example: Implementation for the findCustomer Web Service Method).

public Customer findCustomer(String firstName, String lastName) throws java.rmi.RemoteException {
    System.out.println("[SERVICE] Customer '" + firstName + " " + lastName + "' requested");
 
    // create a customer to return to the client
    Address billingAddress = new Address();
    billingAddress.setStreet("123 Any St.");
    billingAddress.setSuite("Suite 1");
    billingAddress.setCity("Ottawa");
    billingAddress.setProvince("ON");
    billingAddress.setPostalCode("A1B 2C3");
 
    Address shippingAddress = new Address();
    shippingAddress.setStreet("456 Another Street");
    shippingAddress.setCity("Raleigh");
    shippingAddress.setProvince("NC");
    shippingAddress.setPostalCode("12345");
 
    PhoneNumber workPhoneNumber = new PhoneNumber();
    workPhoneNumber.setType("work");
    workPhoneNumber.setNumber("(613) 555-1111");
 
    PhoneNumber cellPhoneNumber = new PhoneNumber();
    cellPhoneNumber.setType("cell");
    cellPhoneNumber.setNumber("(613) 555-2222");
 
    java.util.Calendar dob = java.util.Calendar.getInstance();
    dob.clear();
    dob.set(1975, 02, 21);
 
    Customer customer = new Customer();
    customer.setFirstName(firstName);
    customer.setLastName(lastName);
    customer.setDateOfBirth(dob);
    customer.setBillingAddress(billingAddress);
    customer.setShippingAddress(shippingAddress);
    customer.getPhoneNumbers().add(workPhoneNumber);
    customer.getPhoneNumbers().add(cellPhoneNumber);
 
    return customer;
}

Compile the Web service interface and implementation classes to the <DEMO_HOME>/classes folder.

Step 4: Create the Custom Serializer

Create a <DEMO_HOME>/src/examples/jaxrpc/jaxrpc11 folder and create a CustomerSerialzer.java file in it. The custom serializer class must implement the oracle.webservices.databinding.SOAPElementSerializer interface and include the following SOAPElementSerializer methods:

• public Object deserialize(SOAPElement ele)

• public SOAPElement serialize(QName qname, Object obj)

• public void init(Map props)

The serialize method is responsible for converting a Customer object to XML. Example: Implementation for the serialize Method shows an implementation of the serialize method that uses TopLink.

public SOAPElement serialize(QName qname, Object object) {
    SOAPElement soapElement = null;
    try {
        soapElement = soapFactory.createElement(qname.getLocalPart(), qname.getPrefix(), qname.getNamespaceURI());
        marshaller.marshal(object, soapElement);
    } catch (SOAPException ex) {
        // Handle the exception
        ex.printStackTrace();
    }
    return soapElement;
}

Note how this method creates a SOAPElement to marshal the Customer object to.

The deserialize method is responsible for converting XML into a Customer object. Example: Implementation for the deserialize Method shows an implementation of the deserialize method that uses TopLink.

public Object deserialize(SOAPElement soapElement) {
    Object unmarshalledObject = unmarshaller.unmarshal(soapElement, Customer.class);
    return unmarshalledObject;
}

Note that in the unmarshall call, the Customer.class argument identifies the class that the complex type customer-type is to be unmarshalled to.

The primary function of the init method is to initialize a SOAPFactory instance, XMLMarshaller and XMLUnmarshaller. Add the following instance variables to your class:

• protected SOAPFactory soapFactory;

• protected XMLMarshaller marshaller;

• protected XMLUnmarshaller unmarshaller;

Example: Implementation for the init Method shows an implementation of the init method.

public void init(Map prop) {
    try {
      XMLProjectReader reader = new XMLProjectReader();
      Project project = reader.read("Customer.xml", this.getClass().getClassLoader());
      XMLContext xmlContext = new XMLContext(project);
      marshaller = xmlContext.createMarshaller();
      unmarshaller = xmlContext.createUnmarshaller();
      soapFactory = SOAPFactory.newInstance();
  
    } catch (SOAPException e) {
        e.printStackTrace();
    }
}

Before compiling the custom serializer classes, ensure that the following archives are on your classpath:

• <ORACLE_HOME>/toplink/jlib/toplink.jar

• <DEMO_HOME>/model.jar

• <OC4J_HOME>/lib/xml.jar

• <OC4J_HOME>/webservices/lib/saaj-api.jar

• <OC4J_HOME>/webservices/lib/wsclient.jar

Compile the custom serializer to the <DEMO_HOME>/classes folder.

Step 5: Create the Oracle Web Services Type Mapping Configuration XML File

In the <DEMO_HOME> folder create a file called custom_type_schema_pdd.xml. The purpose of this file is to associate an XML type with a Java class and to specify a custom serializer to convert instances of the Java classes to/from XML. An entry should be added for each Java class that corresponds to a global XML type.

Example: The custom_type_schema_pdd.xml File shows the custom_type_schema_pdd.xml file for this How-To.

<oracle-webservices 
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
    xsi:noNamespaceSchemaLocation="http://xmlns.oracle.com/oracleas/schema/oracle-webservices-10_0.xsd">
    <webservice-description name="CustomerLocatorService">
        <type-mappings xmlns:typens="urn:customer-example">
            <type-mapping java-class="examples.ox.model.Customer" xml-type="typens:customer-type">
                    <serializer class="examples.jaxrpc.jaxrpc11.CustomerSerializer"/>
            </type-mapping>
            <type-mapping java-class="examples.ox.model.Address" xml-type="typens:address-type">
                    <serializer class="examples.jaxrpc.jaxrpc11.CustomerSerializer"/>
            </type-mapping>
        </type-mappings>
    </webservice-description>
</oracle-webservices>

Here we see that no type classes are to be generated by the assembler for Customer or Address and that the CustomerSerializer is to be used for each of these classes.

Step 6: Assemble the JAX-RPC 1.1 Web Service

In this How-To, we will use the OC4J Web services assembler tool to create the necessary artifacts for deploying the Web service to OC4J. Change directories to the <DEMO_HOME> directory and run the tool by executing the following on the command line:

java -jar ${OC4J_HOME}/webservices/lib/wsa.jar –assemble –targetNamespace urn:customer-locator-service –typeNamespace urn:customer-locator-service –input <DEMO_HOME>/classes –classpath <DEMO_HOME>/classes –output ./ –ddFileName <DEMO_HOME>/custom_type_schema_pdd.xml –interfaceName examples.jaxrpc.jaxrpc11.service.CustomerLocatorService –className examples.jaxrpc.jaxrpc11.service.CustomerLocatorServiceImpl –serviceName CustomerLocatorService –appName customer-locator –schema <DEMO_HOME>/Customer.xsd

The options used in this command line are as follows:

• targetNamespace - specifies the target namespace to be used in the generated WSDL

• typeNamespace - specifies the type namespace to be used in the schema types in the generated WSDL

• input - a directory or JAR containing classes that should be copied to WEB-INF/classes

• classpath - classpath that contains any user-created classes

• output - location where generated files will be stored

• ddFileName - oracle-webservices.xml deployment descriptor that contains settings to assign to the Web service (for example, the custom serializer)

• interfaceName - path and name of a Java file that contains the Service Endpoint Interface

• className - the path and name (including the package name) of the implementation class for the Web service

• serviceName - in bottom up Web service assembly, this argument is used to name the generated WSDL and mapping files

• appName - base value for such things as context and uri; also used as the EAR and the WAR file name if not specified

• schema - relative path or URL to an XML Schema Document containing value types that are not to be generated by the WebServicesAssembler

The result of executing the above command will be a customer-locator.ear file in your <DEMO_HOME> folder.

Step 7: Deploy the Web Service

Start your OC4J server and deploy the customer-locator.ear file generated in "Step 6: Assemble the JAX-RPC 1.1 Web Service". Set the deployment name for the application to customer-locator. When binding the web app, set the application name to customer-locator and the default-web-site value to /jaxrpc-demo.

Step 8: Create the Oracle Web Services Type Mapping Configuration Client XML File

In the <DEMO_HOME> folder create a file called custom_type_schema_client_pdd.xml. The purpose of this file is to associate an XML type with a Java class and to specify a custom serializer to convert instances of the Java classes to/from XML. An entry should be added for each Java class that corresponds to a global XML type.

Example: The custom_type_schema_pdd.xml File shows the custom_type_schema_client_pdd.xml file for this How-To.

<oracle-webservices 
    <webservices-client> 
      <service-qname namespaceURI="http://oracle.com/ws/bottomup_customtype" localpart="CustomTypesService" />
      <type-mappings xmlns:typens="urn:customer-example">
            <type-mapping java-class="examples.ox.model.Customer" xml-type="typens:customer-type">
                  <serializer class="examples.jaxrpc.jaxrpc11.CustomerSerializer"/>
            </type-mapping>
            <type-mapping java-class="examples.ox.model.Address" xml-type="typens:address-type">
                  <serializer class="examples.jaxrpc.jaxrpc11.CustomerSerializer"/>
            </type-mapping>
        </type-mappings>
    </webservice-description>
    </webservices-client> 
</oracle-webservices>

Step 9: Generate the Client

In this How-To, we will use the OC4J Web services assembler tool to create the client proxy classes. Change directories to the <DEMO_HOME> directory and run the tool by executing the following on the command line:

java –jar ${OC4J_HOME}/webservices/lib/wsa.jar –genProxy –wsdl http://localhost:8888/jaxrpc-demo/customer-locator?WSDL –packageName examples.jaxrpc.jaxrpc11.client –output src –ddFileName custom_type_schema_client_pdd.xml –classpath custom_type_schema_pdd.xml;<DEMO_HOME>/classes

The options used in this command line are as follows:

• wsdl - specifies the absolute file path, relative file path, or URL to a WSDL document

• packageName - the package name that will be used for generated classes (if no package name is declared in the JAX-RPC mapping file)

• output - location where generated files will be stored

• ddFileName - oracle-webservices.xml deployment descriptor that contains settings to assign to the Web service (for example, the custom serializer)

• classpath - classpath that contains any user-created classes

The result of executing the above command will be client Java source files in your <DEMO_HOME>/src folder.

Step 10: Modify the Generated Client

In the <DEMO_HOME>/src folder, locate the generated file examples.jaxrpc.jaxrpc11.client.HttpSoap11Client.java. Locate the line in the main method that says //Add your code here and add the following lines of code:

System.out.println("[CLIENT] Requesting customer 'Jane Doe' from service...");
examples.ox.model.Customer result = myPort.findCustomer("Jane", "Doe");
System.out.println("[CLIENT] Customer returned from service: \n" + result.toString());

Before compiling the client classes, ensure that the following archives are on your classpath:

• <ORACLE_HOME>/toplink/jlib/toplink.jar

• <DEMO_HOME>/model.jar

• <OC4J_HOME>/lib/xml.jar

• <OC4J_HOME>/webservices/lib/saaj-api.jar

• <OC4J_HOME>/webservices/lib/wsclient.jar

• <OC4J_HOME>/webservices/lib/jaxrpc-api.jar

• <J2EE_HOME>/lib/activation.jar

Compile the client classes to the <DEMO_HOME>/classes folder.

Step 11: Build the Client JAR File

Create a JAR file named customer-locator-client.jar that includes the custom serializer class, generated proxy classes, binding XML, and deployment XML. For example:

• Customer.xml

• examples\jaxrpc\jaxrpc11\CustomerSerializer.class

• examples\jaxrpc\jaxrpc11\client\CustomerLocatorService_PortType.class

• examples\jaxrpc\jaxrpc11\client\CustomerLocatorService_Service.class

• examples\jaxrpc\jaxrpc11\client\HttpSoap11Client.class

• examples\jaxrpc\jaxrpc11\client\runtime\CustomerLocatorService_Service_Impl.class

• examples\jaxrpc\jaxrpc11\client\runtime\CustomerLocatorService_Service_SerializerRegistry12.class

• examples\jaxrpc\jaxrpc11\client\runtime\CustomerLocatorService_Service_SerializerRegistry.class

• examples\jaxrpc\jaxrpc11\client\runtime\HttpSoap11Binding_Stub.class

• examples\jaxrpc\jaxrpc11\client\runtime\HttpSoap11Binding_Stub.xml

• examples\jaxrpc\jaxrpc11\client\types\FindCustomer.class

• examples\jaxrpc\jaxrpc11\client\types\FindCustomerResponse.class

• examples\jaxrpc\jaxrpc11\client\types\runtime\FindCustomer_LiteralSerializer.class

• examples\jaxrpc\jaxrpc11\client\types\runtime\FindCustomerResponse_LiteralSerializer.class

Step 12: Run the Client

Before running the client, ensure that the following archives are on your classpath (in the order specified):

• <ORACLE_HOME>/toplink/jlib/toplink.jar

• <DEMO_HOME>/customer-locator-client.jar

• <DEMO_HOME>/model.jar

• <OC4J_HOME>/webservices/lib/wsa.jar

To run the client, run the examples.jaxrpc.jaxrpc11.client.HttpSoap11Client class.