-----
 Castor
 -----
 XFire User's Guide
 -----

Castor

 Castor is a flexible XML binding tool that provides run-time marshalling and unmarshalling of XML and Java objects.
 One strength of Castor when compared to most (not all) other Java XML binding frameworks is that re-compilation of
 the Java code is not required if the mapping definition changes. Therefore, systems where the web service layer is
 being developed independently from the business layer can benefit from using Castor. XFire support for Castor is
 currently available in the latest XFire release. Two approaches to developing a Web service using Castor with XFire
 are presented below: top-down (schema first) and bottom-up (code first).  Before proceeding, check the Dependency
 Guide for required castor module dependencies.

* Assumptions about Reader

 * Competence with Java and XML

 * Basic knowledge of Castor XML binding framework

 * Experience configuring Java webapp and deploying

 * Nominal familiarity with Spring framework

 []

Top-down Approach (starting with XML schema):

 Firstly, the XML schema that defines the structure of your web service messages must be developed. For the purposes
 of this guide, we'll borrow a schema from http://www.webservicex.net/WeatherForecast.asmx?WSDL which defines a
 pre-existing weather forecast service.

 The borrowed schema below should be saved under META-INF/schema/ in the classpath:

+---------------------------------------------------------------------------------------------------------------------+
<s:schema elementFormDefault="qualified" targetNamespace="http://www.webservicex.net"
          xmlns:s="http://www.w3.org/2001/XMLSchema" xmlns:tns="http://www.webservicex.net">
      <s:element name="GetWeatherByZipCode">
        <s:complexType>
          <s:sequence>
            <s:element minOccurs="0" maxOccurs="1" name="ZipCode" type="s:string"/>
          </s:sequence>
        </s:complexType>
      </s:element>
      <s:element name="GetWeatherByZipCodeResponse">
        <s:complexType>
          <s:sequence>
            <s:element minOccurs="1" maxOccurs="1" name="GetWeatherByZipCodeResult" type="tns:WeatherForecasts"/>
          </s:sequence>
        </s:complexType>
      </s:element>
      <s:complexType name="WeatherForecasts">
        <s:sequence>
          <s:element minOccurs="1" maxOccurs="1" name="Latitude" type="s:float"/>
          <s:element minOccurs="1" maxOccurs="1" name="Longitude" type="s:float"/>
          <s:element minOccurs="1" maxOccurs="1" name="AllocationFactor" type="s:float"/>
          <s:element minOccurs="0" maxOccurs="1" name="FipsCode" type="s:string"/>
          <s:element minOccurs="0" maxOccurs="1" name="PlaceName" type="s:string"/>
          <s:element minOccurs="0" maxOccurs="1" name="StateCode" type="s:string"/>
          <s:element minOccurs="0" maxOccurs="1" name="Status" type="s:string"/>
          <s:element minOccurs="0" maxOccurs="1" name="Details" type="tns:ArrayOfWeatherData"/>
        </s:sequence>
      </s:complexType>
      <s:complexType name="ArrayOfWeatherData">
        <s:sequence>
          <s:element minOccurs="0" maxOccurs="unbounded" name="WeatherData" type="tns:WeatherData"/>
        </s:sequence>
      </s:complexType>
      <s:complexType name="WeatherData">
        <s:sequence>
          <s:element minOccurs="0" maxOccurs="1" name="Day" type="s:string"/>
          <s:element minOccurs="0" maxOccurs="1" name="WeatherImage" type="s:string"/>
          <s:element minOccurs="0" maxOccurs="1" name="MaxTemperatureF" type="s:string"/>
          <s:element minOccurs="0" maxOccurs="1" name="MinTemperatureF" type="s:string"/>
          <s:element minOccurs="0" maxOccurs="1" name="MaxTemperatureC" type="s:string"/>
          <s:element minOccurs="0" maxOccurs="1" name="MinTemperatureC" type="s:string"/>
        </s:sequence>
      </s:complexType>
</s:schema>
+---------------------------------------------------------------------------------------------------------------------+

 Next, we'll use castor to generate POJO classes from the service schema. First, define the source generator task and
 a goal for generation. The example below is for a maven 1.x configuration. Go to Using the Source Code Generator for
 a full reference on generating java classes from XML schema.

+---------------------------------------------------------------------------------------------------------------------+
<ant:path id="castor.class.path">
        <ant:path refid="maven.dependency.classpath"/>
        <ant:pathelement path="${maven.build.dest}"/>
        <ant:pathelement path="${maven.test.dest}"/>
</ant:path>

<ant:taskdef name="castor-srcgen"
                classname="org.exolab.castor.tools.ant.taskdefs.CastorSourceGenTask"
                classpathref="castor.class.path"/>

<goal name="generate-source">
        <ant:delete dir="${maven.build.dir}/generated-src"/>
        <ant:mkdir dir="${maven.build.dir}/generated-src"/>
        <castor-srcgen file="src/main/META-INF/schema/WeatherForecast.xsd"
                      package="net.webservicex"
                      todir="${maven.build.dir}/generated-src"
                      types="j2"
                      warnings="false" />
</goal>
+---------------------------------------------------------------------------------------------------------------------+

 After running the generate-source goal, the supporting classes will be in the generated-src directory under the
 net.webservicex package.  Along with each class is an accompanying Descriptor class file (e.g.
 WeatherDataDescriptor.java) that contains XML binding information.

 Next, write a Web service with the support of the generated classes.  Note, the example below is a trivial
 implementation.

+---------------------------------------------------------------------------------------------------------------------+
package foo.bar;

import net.webservicex.*;

public class WeatherService
{

    public GetWeatherByZipCodeResponse GetWeatherByZipCode(GetWeatherByZipCode body)
    {
        GetWeatherByZipCodeResponse res = new GetWeatherByZipCodeResponse();
        String zipCode = body.getZipCode();
        if (!zipCode.equals("1050"))
            throw new RuntimeException("Parameter isnt passed correctly. expected: 1050, got "
                    + zipCode);
        GetWeatherByZipCodeResult weather = new GetWeatherByZipCodeResult();

        weather.setLatitude(1);
        weather.setLongitude(1);
        weather.setPlaceName("Vienna, AT");
        weather.setAllocationFactor(1);

        res.setGetWeatherByZipCodeResult(weather);

        return res;
    }

}
+---------------------------------------------------------------------------------------------------------------------+

 After this, configure the service in Xfire. The example below takes the XML configuration approach (which uses Spring
 integration). In addition, XFire supports integration of configuration into containers such as Plexus and
 PicoContainer. For more control over the Web service definition, JSR 181 Annotations should be used in the service
 code.

 The configuration goes in the services.xml descriptor. This file goes in META-INF/xfire/ on the classpath:

+---------------------------------------------------------------------------------------------------------------------+
<beans xmlns="http://xfire.codehaus.org/config/1.0">

  <service>
    <serviceClass>foo.bar.WeatherService</serviceBean>
    <schemas>
      <schema>META-INF/schema/WeatherForecast.xsd</schema>
    </schemas>
    <style>document</style>
    <serviceFactory>#castorServiceFactory</serviceFactory>
  </service>

  <bean id="castorTypeRegistry" class="org.codehaus.xfire.castor.CastorTypeMappingRegistry" />

  <bean id="bindingProvider" class="org.codehaus.xfire.aegis.AegisBindingProvider">
        <constructor-arg ref="castorTypeRegistry" />
  </bean

  <bean id="castorServiceFactory" class="org.codehaus.xfire.service.binding.ObjectServiceFactory">
    <constructor-arg index="0" ref="xfire.transportManager" />
    <constructor-arg index="1" ref="bindingProvider" />
   </bean>

</beans>
+---------------------------------------------------------------------------------------------------------------------+

 The service definition specifies the web service implementation class with the <serviceClass> property. A list of
 <<< <schemas> >>> can be provided to be included in WSDL generation. In this case, the borrowed schema definition in
 the classpath at META-INF/schema/WeatherForecast.xsd has been included.

 The request and response messages were defined in our schema and were included as a single parameter and return type,
 respectively, in our service method. This lends itself to a bare (or unwrapped) parameter-style.  The service
 definition specifies a bare parameter-style by setting the <style> property as 'document'.  If a wrapped
 parameter-style is preferable, the request and response schema definitions and generated classes would not be needed,
 as the operation name would wrap any request parameters and return type. The style property in the service definition
 would not be needed as service factories create services as wrapped style by default. The service method signature
 for a wrapped style service would be:

+---------------------------------------------------------------------------------------------------------------------+
public WeatherForecasts GetWeatherByZipCode(String zipCode)
+---------------------------------------------------------------------------------------------------------------------+

 Service factories are responsible for creating the service inside of XFire. In this case, we want to use an
 ObjectServiceFactory with Castor binding, so the beans 'castorTypeRegistry', 'bindingProvider' and
 'castorServiceFactory' are defined. Notice that these beans are using spring-style bean definitions (e.g. <bean id=...>)
 since XML Configuration uses Spring to build its services. We reference this service factory in the <serviceFactory>
 property of the service definition as #castorServiceFactory. The '#' denotes a reference to another defined bean. Read
 the Bindings section to learn more about setting up service factories with different xml binding mechanisms.

 After configuring the service within XFire, the service needs to be exposed so it can be reached by client-proxies.
 This can be done over HTTP by defining a servlet in the web.xml. Since we have taken the XML Configuration approach,
 it is best to set up the XFireConfigurableServlet in our web.xml. XFireConfigurableServlet will load the services.xml
 along with the included org.codehaus.xfire.spring.xfire.xml files upon initialization. Reference the XML
 Configuration for how to write the web.xml file.

 Finally, deploy the web application to your favorite servlet container, and the service should be visible at
 /services/WeatherService?wsdl under the deployed webapp context path.

Bottom-up Approach (starting with Java classes):

 Let's say you want to leverage your pre-existing business code by exposing certain methods with a Web Service. That's
 not too hard to do with Castor binding and XFire, but it's a different approach that involves mapping Java to XML
 rather than generating Java classes from schema. Service-oriented architecture discourages simply exposing the
 domain model, but in this example we're going to be rebellious and not insulate it. This doesn't mean that the
 bottom-up approach can't follow SOA best practices, altogether.

 Below is a Book class that's part of the domain:

+---------------------------------------------------------------------------------------------------------------------+
package foo.bar;

public class Book
{
    private String title;

    private String isbn;

    private String author;

    public String getIsbn()
    {
        return isbn;
    }

    public void setIsbn(String isbn)
    {
        this.isbn = isbn;
    }

    public String getTitle()
    {
        return title;
    }

    public void setTitle(String title)
    {
        this.title = title;
    }

    public String getAuthor()
    {
        return author;
    }

    public void setAuthor(String author)
    {
        this.author = author;
    }
}
+---------------------------------------------------------------------------------------------------------------------+

 Next, is a service class that has a couple methods we want to expose as a web service. Note: This service class could
 have existed already as a business service, or could have been written specifically to be a web service. As you might
 have noticed, the implementation is quite trivial (ie. stoopid).

+---------------------------------------------------------------------------------------------------------------------+
package foo.bar;

public class BookService
{
    private Book onlyBook;

    public BookService()
    {
        onlyBook = new Book();
        onlyBook.setAuthor("Steve Ballmer");
        onlyBook.setTitle("How to Yell Real Loud and Look Like You Might Have a Heart Attack");
        onlyBook.setIsbn("012924828");
    }

    public String addBook(Book book)
    {
        return onlyBook.getIsbn();
    }

    public Book findBook(String isbn)
    {
        return onlyBook;
    }
}
+---------------------------------------------------------------------------------------------------------------------+

 Let's create an XSD that matches the Book class, so that we know what the XML element for the Book class should look
 like. The Book.xsd schema below should be saved under META-INF/schema/ in the classpath:

+---------------------------------------------------------------------------------------------------------------------+
<xsd:schema elementFormDefault="qualified" targetNamespace="http://xfire.codehaus.org"
          xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:tns="http://xfire.codehaus.org">
    <xsd:complexType name="Book">
        <xsd:sequence>
            <xsd:element name="title" type="xsd:string"/>
            <xsd:element name="isbn" type="xsd:string"/>
            <xsd:element name="author" type="xsd:string"/>
        </xsd:sequence>
    </xsd:complexType>
</xsd:schema>
+---------------------------------------------------------------------------------------------------------------------+

 The schema outlines a complex type that has three string elements. It is important to note that the namespace prefix
 for XML schema namespace is 'xsd' and the namespace prefix for the target namespace is 'tns'. These are the prefixes
 used by the XFire WSDL builder when creating the schema section, and this schema will actually be inserted inline
 into the schema section of the WSDL.

 Now we need to specify how to transform our Book class to an XML element that conforms to the XSD, and vice versa.
 This is done with a castor mapping file. More information on writing castor mappings is available at
 http://www.castor.org/xml-mapping.html

 The castor.xml mapping file below should be saved under the foo.bar package:

+---------------------------------------------------------------------------------------------------------------------+
<?xml version="1.0" encoding="UTF-8"?>
<mapping>
  <class name="org.codehaus.xfire.castor.Book">
    <map-to xml="Book" ns-uri="http://xfire.codehaus.org" ns-prefix="tns" element-definition="false"/>
    <field name="title" type="string"/>
    <field name="isbn" type="string"/>
    <field name="author" type="string"/>
  </class>
</mapping>
+---------------------------------------------------------------------------------------------------------------------+

 Note again, the target namespace and tns prefix are the same as in the XSD. The element-defintion attribute denotes
 whether the XSD definition is a concrete element or an abstract complex type. In this case, it is a complex type so
 element-definition is false (which is actually is default value).

 All the distinct parts are there, time to configure the service in Xfire. The example below takes the XML
 configuration approach (which uses Spring integration).

 The configuration goes in the services.xml descriptor. This file goes in META-INF/xfire/ on the classpath:

+---------------------------------------------------------------------------------------------------------------------+
<beans xmlns="http://xfire.codehaus.org/config/1.0">

  <service>
    <serviceClass>foo.bar.BookService</serviceBean>
    <namespace>http://xfire.codehaus.org</namespace>
    <schemas>
      <schema>META-INF/schema/Book.xsd</schema>
    </schemas>
    <serviceFactory>#castorServiceFactory</serviceFactory>
  </service>

  <bean id="castorTypeRegistry" class="org.codehaus.xfire.castor.CastorTypeMappingRegistry">
      <property name="mappingFile" value="foo/bar/castor.xml" />
  </bean>

  <bean id="bindingProvider" class="org.codehaus.xfire.aegis.AegisBindingProvider">
        <constructor-arg ref="castorTypeRegistry" />
  </bean

  <bean id="castorServiceFactory" class="org.codehaus.xfire.service.binding.ObjectServiceFactory">
    <constructor-arg index="0" ref="xfire.transportManager" />
    <constructor-arg index="1" ref="bindingProvider" />
   </bean>

</beans>
+---------------------------------------------------------------------------------------------------------------------+

 The service definition specifies the web service implementation class with the <serviceClass> property. A list of
 <schemas> can be provided to be included in WSDL generation. In this case, the schema definition in the classpath at
 META-INF/schema/Book.xsd has been included. Our service is of parameter style 'wrapped', as the method names in the
 service will wrap our request and response messages (e.g. <findBook>). The style property in the service definition
 is not be needed as service factories create services as wrapped style by default.

 Service factories are responsible for creating the service inside of XFire. In this case, we want to use an
 ObjectServiceFactory with Castor binding, so the beans 'castorTypeRegistry', 'bindingProvider' and
 'castorServiceFactory' are defined. Notice that these beans are using spring-style bean definitions
 (e.g. <bean id=...>) since XML Configuration uses Spring to build its services. We reference this service factory in
 the <serviceFactory> property of the service definition as #castorServiceFactory. The '#' denotes a reference to
 another defined bean. The 'castorTypeRegistry' definition sets the 'mappingFile' property to point to the castor.xml
 mapping file in the classpath.

 After configuring the service within XFire, the service needs to be exposed so it can be reached by client-proxies.
 This can be done over HTTP by defining a servlet in the web.xml. Reference the XML Configuration for how to write the
 web.xml file.

 After configuring the service and web application, deploy it to your favorite servlet container, and the service
 should be visible at /services/BookService?wsdl under the deployed webapp context path.