# MOXy Example

## What is MOXy

This example demonstrates that you can utilize MOXy extensions when dealing with XML representation when developing a Jersey based RESTful Web application

MOXy is EclipseLink's Object to XML Mapping services. MOXy allows for a POJO object model to be mapped to an XML schema. The Java Architecture for XML Binding (JAXB) provides a Java standard for object XML mapping (OXM). MOXy supports JAXB, as well as providing its' own native API and integration with Web Services.

## MOXy XML Path Mapping Extension

The MOXy extension shown in this example is described on the Eclipse Wiki site at http://wiki.eclipse.org/EclipseLink/Examples/MOXy/GettingStarted/MOXyExtensions. It allows you to specify path based mapping via @XmlPath annotation.

If the MOXy extension was not used, the XML represenation of the customer data would look like follows:

    <customer>
      <name>Jane Doe</name>
      <address>
        <city>My Town</city>
        <street>123 Any Street</street>
      </address>
      <phoneNumbers type="work">613-555-1111</phoneNumbers>
      <phoneNumbers type="cell">613-555-2222</phoneNumbers>
    </customer>

By adding `@org.eclipse.persistence.oxm.annotations.XmlPath` annotation to the bean definition classes, you will get the following XML representation instead:

    <customer>
      <personal-info>
        <name>Jane Doe</name>
      </personal-info>
      <contact-info>
        <address>
          <city>My Town</city>
          <street>123 Any Street</street>
        </address>
        <phone-number type="work">613-555-1111</phone-number>
        <phone-number type="cell">613-555-2222</phone-number>
      </contact-info>
    </customer>

XML Path expressions used are:

- personal-info/name/text()
- contact-info/address
- contact-info/phone-number

Please check out the source code and the wiki page linked above for the detailed information on the XML Path mapping feature.

## Replacing Implicit JAXB Runtime With MOXy

Since MOXy is a JAXB implementation, the example still utilizes the standard Jersey JAXB message body reader/writer providers. To make Jersey use MOXy runtime, you just need to put a `jaxb.properties` file into the Java package containing your JAXB beans. The file should have the following content:

    javax.xml.bind.context.factory=org.eclipse.persistence.jaxb.JAXBContextFactory

Concrete file used in this example is placed under `src/main/resources/com/sun/jersey/samples/moxy/beans/jaxb.properties`

## REST Resources

The example consists of a single REST Resource represented by the following Java class:

`com.sun.jersey.samples.moxy.CustomerResource`
  A resource class that maintains a single customer data.

The mapping of the URI path space is presented in the following table:

URI path | Resource class | HTTP methods
--- | --- | ---
/customer | CustomerResource | GET
/customer | CustomerResource | PUT

## Running the Example

If you are working with Jersey GlassFish update center module installed into your existing GlassFish instance, you will need to follow instructions at the module README file in order to deploy the example.

Otherwise, you can run the example using embedded GlassFish as follows:

> `mvn clean package embedded-glassfish:run`

or you can run the example using Jetty as follows:

> `mvn clean package jetty:run`

From a web browser, visit:

> `http://localhost:8080/moxy/customer`