View source for EclipseLink/DesignDocs/350483

= Design Specification: Object-to-JSON Binding Layer =

[http://bugs.eclipse.org/350483 ER 350483]

== Document History ==
{|{{BMTableStyle}}
|-{{BMTHStyle}}
! Date
! Author
! Version Description & Notes
|- 
| ?
| Denise Smith
| ?
|-
| 2011/08/11
| Blaise Doughan
| ?
|}

== Project overview ==

This feature will add support for converting objects to/from JSON.  This is desirable when creating RESTful services as JAX-RS services often accept both XML (application/xml) and JSON (application/json) messages.

'''Goals:'''
* Offer the same flexibility as our object-to-XML mappings
* Where services offer both XML and JSON messages, support both with one set of mappings
* Not require additional compile time dependencies over the JAXB APIs
* Be easy to use with JAX-RS (i.e. MessageBodyReader and MessageBodyWriter)

== Concepts ==

See [http://www.json.org/ http://www.json.org/] for more JSON reference

== Requirements ==

'''1 - Same Flexibility as Our Object-to-XML Mapping'''

The new JSON binding will be compatible with all existing MOXy extensions.  This includes:
* External bindings file
* Dynamic JAXB
* Extensible models

'''2 - Where Services Offer Both XML and JSON Messages, Support Both with one set of mappings'''

If the XML representation is:

<source lang="xml">
<foo xmlns="urn:examle" id="123">
   <bar>Hello World</bar>
</foo>
</source>

And the JSON representation is:

<source lang="java">
{"foo" : {
    "id" : 123,
    "bar : "Hello World"
}}
</source>

The goal is to have this supported by one object model:

<source lang="java">
@XmlRootElement(namespace="urn:example")
public class Foo {

   @XmlAttribute
   private int id;

   @XmlElement(namespace="urn:example")
   private String bar;

}
</source>


'''3 - Not Require Additional Compile Time Dependencies over the JAXB APIs'''

Below is an example of a JSON binding that does not require any additional compile time dependencies above and beyond what is required for normal JAXB usage (which is none when using Java SE 6).

<source lang="java">
package blog.json.twitter;
 
import java.util.Date;
 
import javax.xml.bind.JAXBContext;
import javax.xml.bind.JAXBElement;
import javax.xml.bind.Marshaller;
import javax.xml.bind.Unmarshaller;
import javax.xml.transform.stream.StreamSource;
 
public class Demo {
 
    public static void main(String[] args) throws Exception {
        JAXBContext jc = JAXBContext.newInstance(SearchResults.class);
 
        Unmarshaller unmarshaller = jc.createUnmarshaller();
        unmarshaller.setProperty("eclipselink.media-type", "application/json");
        StreamSource source = new StreamSource("http://search.twitter.com/search.json?q=jaxb");
        JAXBElement<SearchResults> jaxbElement = unmarshaller.unmarshal(source, SearchResults.class);
 
        Result result = new Result();
        result.setCreatedAt(new Date());
        result.setFromUser("bdoughan");
        result.setText("You can now use EclipseLink JAXB (MOXy) with JSON :)");
        jaxbElement.getValue().getResults().add(result);
 
        Marshaller marshaller = jc.createMarshaller();
        marshaller.setProperty(Marshaller.JAXB_FORMATTED_OUTPUT, true);
        marshaller.setProperty("eclipselink.media-type", "application/json");
        marshaller.marshal(jaxbElement, System.out);
    }
 
}
</source>

'''4 - Easy to Use with JAX-RS (i.e. MessageBodyReader and MessageBodyWriter)''' 

The following two JAX-RS classes are one way that users could interact with MOXy's JSON binding.  Below is a demonstration of what the implementations could look like: 

'''''javax.ws.rs.ext.MessageBodyReader'''''

<source lang="java">
package org.example;
 
import java.io.*;
import java.lang.annotation.Annotation;
import java.lang.reflect.*;
import javax.xml.transform.stream.StreamSource;
 
import javax.ws.rs.*;
import javax.ws.rs.core.*;
import javax.ws.rs.ext.*;
import javax.xml.bind.*;
 
@Provider
@Produces(MediaType.APPLICATION_JSON)
@Consumes(MediaType.APPLICATION_JSON)
public class MOXyJSONProvider implements
    MessageBodyReader<Object>, MessageBodyWriter<Object>{
 
    @Context
    protected Providers providers;
 
    public boolean isReadable(Class<?> type, Type genericType,
        Annotation[] annotations, MediaType mediaType) {
        return true;
    }
 
    public Object readFrom(Class<Object> type, Type genericType,
            Annotation[] annotations, MediaType mediaType,
            MultivaluedMap<String, String> httpHeaders, InputStream entityStream)
            throws IOException, WebApplicationException {
            try {
                Class<?> domainClass = getDomainClass(genericType);
                Unmarshaller u = getJAXBContext(domainClass, mediaType).createUnmarshaller();
                u.setProperty("eclipselink.media-type", mediaType.toString());
                u.setProperty("eclipselink.json.include-root", false);
                return u.unmarshal(new StreamSource(entityStream), domainClass).getValue();
            } catch(JAXBException jaxbException) {
                throw new WebApplicationException(jaxbException);
            }
    }
 
    public boolean isWriteable(Class<?> type, Type genericType,
        Annotation[] annotations, MediaType mediaType) {
        return true;
    }
 
    public void writeTo(Object object, Class<?> type, Type genericType,
        Annotation[] annotations, MediaType mediaType,
        MultivaluedMap<String, Object> httpHeaders,
        OutputStream entityStream) throws IOException,
        WebApplicationException {
        try {
            Class<?> domainClass = getDomainClass(genericType);
            Marshaller m = getJAXBContext(domainClass, mediaType).createMarshaller();
            m.setProperty("eclipselink.media-type", mediaType.toString());
            m.setProperty("eclipselink.json.include-root", false);
            m.marshal(object, entityStream);
        } catch(JAXBException jaxbException) {
            throw new WebApplicationException(jaxbException);
        }
    }
 
    public long getSize(Object t, Class<?> type, Type genericType,
        Annotation[] annotations, MediaType mediaType) {
        return -1;
    }
 
    private JAXBContext getJAXBContext(Class<?> type, MediaType mediaType)
        throws JAXBException {
        ContextResolver<JAXBContext> resolver
            = providers.getContextResolver(JAXBContext.class, mediaType);
        JAXBContext jaxbContext;
        if(null == resolver || null == (jaxbContext = resolver.getContext(type))) {
            return JAXBContext.newInstance(type);
        } else {
            return jaxbContext;
        }
    }
 
    private Class<?> getDomainClass(Type genericType) {
        if(genericType instanceof Class) {
            return (Class<?>) genericType;
        } else if(genericType instanceof ParameterizedType) {
            return (Class<?>) ((ParameterizedType) genericType).getActualTypeArguments()[0];
        } else {
            return null;
        }
    }
 
}
</source>

== Design Constraints ==

=== JAXB Annotations ===

We will leverage the existing JAXB annotations to specify a JSON binding.  This will involve us coming up with JSON interpretations of the XML bindings.

'''Should Just Work'''

The following annotations should just work with our JSON binding layer, only requiring test cases to be written to confirm this.

{| border="1"
!Annotation
!Tested
|-
|XmlAccessorOrder
|Yes
|-
|XmlAccessorType 
|Yes
|-
|XmlJavaTypeAdapter 
|Yes
|-
|XmlJavaTypeAdapters 	
|Yes
|-
|XmlSeeAlso 	
|Yes
|-
|XmlTransient 	
|Yes
|-
|XmlType 	
|Yes
|}

'''Applicable to JSON but Require Work'''

The following annotations will require changes to the OXM layer in order to support.

{| border="1"
!Annotation
!Tested
|-
|XmlAnyAttribute 
|Yes
|-
|XmlAnyElement 
|Yes
|-
|XmlAttribute	
|Yes
|-
|XmlElement 
|Yes
|-
|XmlElementWrapper
|Yes
|-
|XmlID 	
|Yes
|-
|XmlIDREF 
|Yes
|-
|XmlList
|Yes
|-
|XmlRootElement
|Yes
|-
|XmlValue
|Yes
|}

'''Not Applicable to JSON'''

The following annotations are not applicable to JSON, but may still require some work so that they are ignored or throw exceptions appropriately.

{| border="1"
!Annotation
!Tested
|-
|XmlAttributeRef 
|No
|-
|XmlMimeType 	
|No
|-
|XmlMixed 
|No	
|-
|XmlNs 
|No
|-
|XmlNsForm
|No
|-
|XmlSchema 
|No	
|}

=== MOXy Annotations ===

'''Should Just Work'''

The following annotations should just work with our JSON binding layer, only requiring test cases to be written to confirm this. 

{| border="1"
!Annotation
!Tested
|-	
|XmlAccessMethods
|Yes
|-
|XmlContainerPolicy
|Yes
|-
|XmlCustomizer 
|Yes
|-
|XmlInverseReference
|Yes
|-
|XmlNameTransformer
|Yes
|-
|XmlProperties
|
|-
|XmlProperty
|
|-
|XmlReadOnly
|Yes
|-
|XmlReadTransformer
|Yes
|-
|XmlTransformation
|Yes
|-
|XmlVirtualAccessMethods
|
|-
|XmlVirtualAccessMethodsSchema
|
|-
|XmlWriteOnly
|Yes
|-
|XmlWriteTransformer
|Yes
|-
|XmlWriteTransformers
|Yes
|}

'''Applicable to JSON but Requires Work'''

The following annotations will require changes to the OXM layer in order to support. 

{| border="1"
!Annotation
!Tested
|-
|XmlClassExtractor
|Yes
|-
|XMLDiscriminatorNode
|Yes
|-
|XMLDiscriminatorValue
|Yes
|-
|XmlElementsJoinNodes
|Yes
|-
|XmlInlineBinaryData
|Yes
|-
|XmlIsSetNullPolicy
|
|-
|XmlJoinNode
|Yes
|-
|XmlJoinNodes
|
|-
|XmlKey
|Yes
|-
|XmlMashalNullRepresentation
|
|-
|XmlNullPolicy
|
|-
|XmlParameter
|
|-
|XmlPath
|
|-
|XmlPaths
|
|}

'''Not Applicable to JSON'''

The following annotations are not applicable to JSON, but may still require some work so that they are ignored or throw exceptions appropriately. 

{| border="1"
!Annotation
!Tested
|-
|XmlCDATA
|
|}

== Design / Functionality ==

=== High Level Design ===

'''Unmarshalling'''

We will implement a JSONReader that will convert JSON input (InputStream, Reader, System ID) into SAX events.

'''Marshalling'''

We will implement two new records JSONWriterRecord and JSONFormattedWriterRecord that will handle the JSON output.

=== Low Level Design ===

==== No "Root Element" Support ====

[https://bugs.eclipse.org/bugs/show_bug.cgi?id=353938 Bug 353938]

JSON supports documents with no root element:

<source lang="xml">
{"area-code":"613",
 "number":"1234567"}
</source>

Instead of the corresponding JSON with a root element "phone"
<source lang="xml">
{"phone":
   {"area-code":"613",
    "number":"1234567"}
}
</source>

'''Marshal'''
<p>
During marshal if there is no @XmlRootElement specified then the JSON document won't have a root element (as above).  If the object being marshalled does have an @XmlRootElement specified then there is the option of marshalling the root or not.   By default this is true and to change this behaviour the following property can be set on the marshaller
<source lang="java">
marshaller.setProperty(MarshallerProperties.JSON_INCLUDE_ROOT, false);
</source>
</p>

'''Unmarshal'''
<p>
During an unmarshal operation for the unmarshal operations that do no specify a class to unmarshal to we will always assume there is a root element in the document.  For unmarshal operations that specify a class to unmarshal to there is the option to unmarshal documents that have roots and documents that don`t have roots.  By default it will be assumed that the document has a root element.  This can be changed by setting the following property on the unmarshaller.

<source lang="java">
unmarshaller.setProperty(UnmarshallerProperties.JSON_INCLUDE_ROOT, false);
JAXBElement<SearchResults> jaxbElement = unmarshaller.unmarshal(source, SomeClass.class);
</source>
</p>

==== JSON Data Types [https://bugs.eclipse.org/bugs/show_bug.cgi?id=351119 Bug 351119] ====

XML has one datatype text, while JSON has: string, number, boolean.  The OXM layer will need to be enhanced to know the type of "text" being marshalled.

<source lang="xml">
{"address":
    "id":1,
    "city":"Ottawa",
    "isMailingAddress":true
}
</source>

==== Attributes ====
JSON doesn't have the concept as attributes so by default when marshaling anything mapped as an attribute will be marshalled as an element. During unmarshal elements will trigger both the attribute and element events to allow either the mapped attribute or element to handle the value.   If there is an element and attribute with the same name this will cause problems.  Additionally there would likely be issues if an AnyAttribute or Any existed as all items would probably be duplicated in the AnyAttribute mapping and the Any Mapping.

Users will be able to override the default behaviors by providing a prefix to marshal with attributes and to recognize during unmarshal.  In the example below the number attribute is mapped as an attribute.   The JSON_ATTRIBUTE_PREFIX could be pass in the map of properties during creation of the JAXBContext in which case Marshaller and Unmarshallers created from that context will use the specified prefix.  If the JSON_ATTRIBUTE_PREFIX is set on both the properties used during context creation and marshaller/unmarshaller the one specified on the marshaller/unmarshaller will be used.
<source lang="java">
 jsonUnmarshaller.setProperty(UnmarshallerProperties.JSON_ATTRIBUTE_PREFIX, "@");
 jsonMarshaller.setProperty(MarshallerProperties.JSON_ATTRIBUTE_PREFIX, "@") ;
</source>
<source lang="xml">
{"phone":{
  "area-code":"613",
  "@number":"1234567"
  }
}
</source>

==== Collections ====
By default in JSON empty collections are marshalled as []
<source lang="xml">
{"phone":{
  "myList":[],
  }
}
</source>

The following property can be set to false to change this behavior so that empty collections are not marshalled at all
<source lang="java">
 jsonMarshaller.setProperty(MarshallerProperties.JSON_MARSHAL_EMPTY_COLLECTIONS, Boolean.FALSE) ;
</source>
<source lang="xml">
{"phone":{
  }
}
</source>

'''Root Level Collections'''
JSON documents can have root level lists.     If a class Root.java has an @XmlRootElement(name="root") we could marshal as follows:

marshaller.marshal(myListOfRoots, System.out);
<source lang="xml">
[ {
   "root" : {
      "name" : "aaa"
   }
}, {
   "root" : {
      "name" : "bbb"
   }
} ]
</source>

Since the root element is present we can unmarshal with unmarshaller.unmarshal(json);

If Root.java does not have an @XmlRootElement or if jsonMarshaller.setProperty(MarshallerProperties.JSON_INCLUDE_ROO, Boolean.False) the marshal would give this output:
<source lang="xml">
[  
   { "name":"aaa"}, 
   { "name":"bbb"}
]
</source>
Since the root element is not present we need to provide the class to unmarshal to: unmarshaller.unmarshal(json, Root.class);

==== Namespaces ====

[https://bugs.eclipse.org/bugs/show_bug.cgi?id=351588 Bug 351588]
By default namespaces/prefixes will be ignored during marshal and unmarshal operations.  
This default behavior is a problem if there are multiple mappings with the same local name in different namespaces as there would be no way to distinguish between those mappings.
Users will be able to provide a Map of namespaces to customize the behavior.   In JAXB users can set a JAXBMarshaller.NAMESPACE_PREFIX_MAPPER.  If a NAMESPACE_PREFIX_MAPPER is set and the media type is application/json namespaces will be written out.  If a NAMESPACE_PREFIX_MAPPER is not set and the media type is application/json then namespaces will not be written.  To provide different behavior per media type separate jaxbmarshallers can be created.  When the mediatype is application/xml then this property is only used during marshal operations.  When the mediatype is application/json the NAMESPACE_PREFIX_MAPPER will also be used during unmarshal operations.

<source lang="java">
 Map namespaces = new HashMap<String, String>();
 namespaces.put("namespace1", "ns1");
 namespaces.put("namespace2", "ns2");
 jsonUnmarshaller.setProperty(UnmarshallerProperties.JSON_NAMESPACE_PREFIX_MAPPER, namespaces);
</source>

If the namespace map is set on the marshaller it will be used to prefix elements during the marshal operation.

<source lang="java">
 jsonMarshaller.setProperty(MarshallerProperties.NAMESPACE_PREFIX_MAPPER, namespaces);
</source>

The namespaces will be give the prefix from the map separated with a `.`
ie:
  {"ns0.employee:{
      "ns0.id":123
     }
  }

Design-To allow unmarshal to ignore namespaces XPathFragment will have an isNamespaceAware methods so that uris can be ignored during equals comparisons when in JSON unmarshal mode.  Additionally a new class that represents a QName will also be introduced (org.eclipse.persistence.internal.oxm.XPathQName) and it was also have an isNamespaceAware boolean.  XMLContext will store descriptors based on the new XPathQNames instead of the old QName.

==== Inheritance ====
Where XML would marshal an xsi:type="prefix:someChild" the following would be the equivalent JSON.
"type":"prefix.someChild"

==== Null support ====
[https://bugs.eclipse.org/bugs/show_bug.cgi?id=351587 Bug 351587]
When marshaling if the getMarshalNullRepresentation setting on nullpolicy is ABSENT_NODE we don't write that pair to JSON.  
If the getMarshalNullRepresentation is NIL we should write "null" 
If the getMarshalNullRepresentation is EMPTY_NODE we should write "null" 

Complex Object example employee.setAddress(null);
      {"emp":{
           "address":null
        }
Complex Object example employee.setAddress(new Address());
       {"emp":{
           "address":{}
        }

Simple example address.setCity(null);
        {"address":{
             "city":null
           }
        }


Null & Empty Lists

Given the following class:
<source lang="java">
@XmlRootElement
class Employee
  List addresses;  

  @XmlElementWrapper(name="phonenumbers")
  List numbers;

  @XmlElementWrapper(name="joblist", nillable = true)
  List jobs;
</source>

<source lang="java">
Employee emp = new Employee();

{"employee":{ 
   "joblist":null
}}
</source>

<source lang="java">
Employee emp = new Employee();
emp.numbers = new ArrayList();
emp.addresses= new ArrayList();
emp.jobs= new ArrayList();

{"employee":{
     "phonenumbers":{
         "numbers":[]
     },
     "joblist":{
        "jobs":[]
     }
   }
}
</source>

==== XmlValue ====
2 options for XmlValue behavior (need to choose which will be the default behavior).
If Phone.java has 1 field called number and it is marked with @XmlValue

Option1
<source lang="xml">
Single Case:
   {"employee":{
      {"phone":"123-4567"
   }}

List Case:
  {"employee":{
      "phone":["123-4567", "234-5678"]
   }}
</source>

Option2- use a customizable property that users can set to wrap the @XmlValue mappings.

jsonMarshaller.setProperty(MarshallerProperties.JSON_VALUE_WRAPPER, "value");
jsonUnmarshaller.setProperty(UnmarshallerProperties.JSON_VALUE_WRAPPER, "value");

The JSON_VALUE_WRAPPER could alternatively be put in the map of properties used during creation of the JAXBContext in which case Marshallers and Unmarshallers created from that context will use the specified JSON_VALUE_WRAPPER. 

<source lang="xml">
Single Case
   {"employee":{
      {"phone":{
          "value":"123-4567"
        }
   }}

List Case:
  {"employee":{
      {"phone":{
          "value":["123-4567", "234-5678"]
        }
   }}
</source>

==== XSI type attribute ====
ie:CompositeObjectMapping to Object.class
attributes of type java.lang.Object (or Collection of Objects).  
**Equivalent XML -   
   <responsibilities>
      <responsibility xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance' xmlns:xsd='http://www.w3.org/2001/XMLSchema' xsi:type="xsd:string">Fix Bugs</responsibility>

== Testing ==

'''Leveraging Existing Unit Tests'''

Where possible existing MOXy test cases will be used to test the new JSON support.  The majority of tests extend JAXBTestCases that ensures the test scenarios are run against all the supported XML sources and targets.  We will introduce a new class called JAXBWithJSONTestCases that will add test methods for all supported JSON sources and targets that we will convert existing test cases to extend as functionality is added.

'''New Unit Tests'''

New test cases will also be added, where possible these tests will extend JAXBWithJSONTestCases so that the equivalent XML use case is covered as well.

'''New Server Tests'''

New server tests will be added testing this functionality with JAX-RS frameworks.

== API ==


=== MediaType - New Enum ===
To marshal and unmarshal JSON instead of XML within JAXB the MediaType property as described below:

org.eclipse.persistence.oxm.MediaType will be added.  This class has been designed to align with the [[http://jsr311.java.net/nonav/javadoc/javax/ws/rs/core/MediaType.html JAX-RS (JSR-311) MediaType enum]]  The initial enum values are:
* APPLICATION_XML
* APPLICATION_JSON

'''New MOXy Specific JAXB Property ("eclipselink.media-type" - JAXBContextProperties.MEDIA_TYPE, MarshallerProperties.MEDIA_TYPE, UnmarshallerProperties.MEDIA_TYPE)'''

Standard JAXB APIs will be used to marshal and unmarshal.  Users will need to set a property on the JAXBContext, Marshaller and/or Unmarshaller to enable JSON mode:


'''JAXBContext'''

If the property is set when creating a JAXBContext then all Marshallers and Unmarshallers will start in JSON mode by default:

<source lang="java">
Map<String, Object> properties = new HashMap<String, Object>(1);
properties.put(JAXBContextProperties.MEDIA_TYPE, MediaType.APPLICATION_JSON);
JAXBContext jaxbContext = JAXBContext.newInstance(new Class[] {Root.class}, properties);
</source>

'''Unmarshaller'''

The following code will put the Unmarshaller in JSON mode.  The Unmarshaller can be set back to XML mode (default) using the the property value MediaType.APPLICATION_XML:

<source lang="java">
Unmarshaller jsonUnmarshaller = jaxbContext.createUnmarshaller();
jsonUnmarshaller.setProperty(UnmarshallerProperties.MEDIA_TYPE, MediaType.APPLICATION_JSON);
</source>

'''Marshaller'''

The following code will put the Marshaller in JSON mode.  The Marshaller can be set back to XML mode (default) using the the property value "application/xml":
  
<source lang="java">
Marshaller jsonMarshaller = jaxbContext.createMarshaller();
jsonMarshaller.setProperty(MarshallerProperties.MEDIA_TYPE, MediaType.APPLICATION_JSON);
</source>


== GUI ==

== Config files ==
* No changes are required to the current config files to support this feature.
* With the introduction of this feature we could support exposing our config files in JSON format.

== Documentation ==

== Open Issues ==

This section lists the open issues that are still pending that must be decided prior to fully implementing this project's requirements.

{|{{BMTableStyle}}
|-{{BMTHStyle}}
! Issue #
! Owner
! Description / Notes
|- 
|
|
|
|}

== Decisions ==

This section lists decisions made. These are intended to document the resolution of open issues or constraints added to the project that are important.

{|{{BMTableStyle}}
|-{{BMTHStyle}}
! Issue #
! Description / Notes
! Decision
|- 
| 1
| How should we parse JSON messages? 
| We have decided to use ANTLR to implement a JSON parser:  [https://bugs.eclipse.org/bugs/show_bug.cgi?id=351113 Bug 351113].   
|
|- 
| 2
| Any Mappings and Attributes
| Children are typically reported as both elements and attributes.  To avoid duplication issues a JAXBContext.JSON_ATTRIBUTE_PREFIX must be set for support with @XmlAnyAttribute, @XmlAnyElement
|
|- 
| 3
| ChoiceCollection and CollectionReference Mappings
| Need to sort the list before marshalling to group the like items together.
|}

== Future Considerations ==

During the research for this project the following items were identified as out of scope but are captured here as potential future enhancements. If agreed upon during the review process these should be logged in the bug system:

* When a standard parsing API for JSON becomes available the MOXy APIs should be extended to support this.

== Backlog ==

[https://bugs.eclipse.org/bugs/buglist.cgi?classification=RT&component=MOXy&product=EclipseLink&query_format=advanced&short_desc=JSON&short_desc_type=allwordssubstr&order=bug_status%2Ctarget_milestone%2Cpriority%2Cassigned_to%2Cbug_id&query_based_on= JSON Bugs]

{| border="1"
!Item
!Descripton
!Effort
|-
|4. Mapping collection to attribute
|CompositeDirectCollectionMapping to an attribute (ie: itmem/@type should work in JSON and look like  
{"test":{
    "item":{
         "type":["aaa", "bbb", "ccc"]
}}
|
|-
|Tests
|More tests with no root element. More tests with namespaces. Removed tests extending ExternalizedMetadataTestCases.  Tests that don't extend JAXBWithJSONTestCases. Test formatting
|
|-
|Test with "value" and "type" variables that could conflict with xsi:type and value wrapper properties.
|
|
|-
|Attribute on root with no include root set doesn`t work
|
|
|-
|Test cases for Bindings file
|Need to test mixing and matching of JSON and XML bindings files. [https://bugs.eclipse.org/bugs/show_bug.cgi?id=376618 Bug 376618]
|
|-
|Dynamic JAXB
|Need to create some Dynamic JAXB tests
|
|-
|Exception handling
|Unmarshal a JSON doc with media type = XML results in "[Fatal Error] :1:1: Content is not allowed in prolog." and Unmarshal an XML doc with media type = JSON results in line 1:0 no viable alternative at character '<'
|
|-
|Testcases with HashMap
|Our XML test cases have an ignoreOrder option so that when marshalling XML in different environments if elements from a map are returned in a different order the test still passes.   The JSON test cases are a string compare so we don't have an equivalent option.
|
|-
|Positional XPath iE: name[2]
|
|
|-
|XmlLocation
|Currently not supported in JSON
|
|-
|Malformed JSON - Quotes
| Currently our parser cannot handle if property names are not surrounded with double quotes (").  There are cases where inputs contain single (') or no quotes.  This may be something we want to handle.
|
|-
|Malformed JSON - Comments
| The JSON grammar does not allow for comments, however some documents contain them (C and HTML style comments).  This may be something we want to handle.
|
|}

== Completed==

{| border="1"
!Item
!Descripton
!Effort
|-
|Attributes 
|Current attribute support are just marshalled as elements but we should provide the option to provide a prefix ie: jsonMarshaller/jsonUnmarshaller.setProperty(JAXBContext.JSON_ATTRIBUTE_PREFIX, "@"); 
[https://bugs.eclipse.org/bugs/show_bug.cgi?id=356826 Bug 356826]
|
|-
|@XmlValue default behavior
|Support was added for @XmlValue but default behavior needs to be addressed [[https://bugs.eclipse.org/bugs/show_bug.cgi?id=360020 https://bugs.eclipse.org/bugs/show_bug.cgi?id=360020]]
|
|-
|Formatting
|Need to add tests? Sometimes closing brace is not in the right spot.  Non formatted output has spaces that we may want to remove.
|
|-
|TypeMappingInfoTests
|Ensure TypeMappingInfo tests are also converted to include JSON tests
|
|-
|1. Inheritance 
|For the type attribute should JSON marshal "type":"prefix:car-type" or "type":"car-type"   Also "type" is too common to use as the indicator vs. the @xsi:type in XML so needs to be able to be changed to something else.
|
|-
|2. Mappings to Object
|In XML we would write out xsi:type to preserve the actual type.
|
|-
|3. AnyAttribute/AnyObject mappings including Mixed
|Duplication will likely occur since during unmarshal everything is reported as both an attribute and an element.  Issues - anycollection with mixed =true. anycollection with collisions in list.  ANyAttributes will only worth with Attribute prefix turned on and we will only report explicitly marked attributes as attributes (instead of reporting as both attribute and element)
|
|-
|5. CharacterEscapeHandler
|
|
|-
|Object with no XmlRootElement should marshal/unmarshal even if include_root not set
|
|
|-
|Server Tests
|No current JAXB Server Tests exist
|
|-
|Include_root_element default behavior
|Default behavior for this setting needs to be discussed.
|
|-
|XmlValue and XmlPath("text()")
|No current support.  See [[http://wiki.eclipse.org/index.php?title=EclipseLink/DesignDocs/350483#XmlValue XmlValue]]
|
|-
|Namespaces 
|Current support ignores namespaces but we should add the option to allow the user to turn namespaces on and provide a map of prefix/uri pairs to the unmarshaller/marshaller.
|
|-
|Escape characters
|Test JSON escape characters are handled properly.  See [[http://www.json.org/ http://www.json.org/]]
|
|-
|Public properties
|Where should those public properties live
|
|-
|Root level array support
|JSON is allowed to have an array as the root level object but there is not currently support for this.  [https://bugs.eclipse.org/bugs/show_bug.cgi?id=371919 Bug 371919]
|
|-
|XmlPath('.')
|[[https://bugs.eclipse.org/bugs/show_bug.cgi?id=357142 https://bugs.eclipse.org/bugs/show_bug.cgi?id=357142]]
|
|-
|Formatting
|Confirm desired formatting and add some formatted tests.
|
|-
|@XmlElementWrapper?
|
|
|-
|XMLValue + Attribute + JSON with no value wrapper
|This should throw an exception.  XmlValue is allowed with XmlAttributes but if the mediatype is JSON then there must be a value wrapper specified
|-
|Number format
|Test JSON supported number formats.  See [[http://www.json.org/ http://www.json.org/]]
|
|-
|Test JAXB_FRAGMENT
|When marshalling a JAXB_FRAGMENT the doc should not have the outer open and close braces in JSON
|
|-
|CollectionReference and ChoiceCollection mappings
|Currently will marshal id:1,id:2 instead of id:[1,2]
|
|-
|Inline binary mappings
|Handled differently than direct mappings since direct mappings end in text() or are attributes but binary data mappings don't
|
|-
|Mapping XMLCollectionReferenceMapping - need to sort like choice collection
|org.eclipse.persistence.testing.jaxb.annotations.xmlelementsjoinnodes.collection.XmlElementsJoinNodeTestCases
|
|-
|Mappings to QName
|marshalled qname currently looks like "ns0:something" as value in JSON
|
|-
|WriterRecordContentHandler inner class of WriterRecord
|Currently writes XML ouptut... when is this called?
|
|-
|JSONWriterRecord element(XPathFragment frag) {
|Currently writes XML ouptut... when is this called?
|
|-
|BinaryDataColletionMappings
|org.eclipse.persistence.testing.jaxb.externalizedmetadata.mappings.binarydatacollection.BinaryDataCollectionMappingTestCases
|
|}