# Package org.apache.synapse.commons.staxon.core.json

package org.apache.synapse.commons.staxon.core.json

Classes to read and write JSON via StAX.

The writer consumes processing instructions `<?xml-multiple element-name?>` to properly insert JSON array tokens (`'['` and `']'`). The client must provide this instruction through the `XMLStreamWriter.writeProcessingInstruction(String, String)` method, passing the (possibly prefixed) field name as data e.g.

       ...
       writer.writeProcessingInstruction("xml-multiple", "item");
       for (Item item : items) {
         writer.writeStartElement("item");
         ...
         writer.writeEndElement();
       }
       ...

The element name passed as processing instruction data is optional. If omitted, the next element within the current scope will start an array. Note, that this method does not allow to create empty arrays (in fact, the above code sample could create unexpected results, if the name would have been omitted and collection were empty).

Likewise, the reader produces the processing instruction as XML events.

The purpose of the used mapping convention is to generate a more compact `JSON`. It borrows the `"$"` syntax for text elements from the BadgerFish convention but attempts to avoid needless text-only `JSON` properties. The rules are:

1. Element names become object properties.

2. Text content of elements goes directly in the value of an object.

       <alice>bob</alice>

   becomes

       { "alice": "bob" }

3. Nested elements become nested properties.

       <alice><bob>charlie</bob><david>edgar</david></alice>

   becomes

       { "alice": { "bob": "charlie", "david": "edgar" } }

4. Multiple elements with the same name and at the same level become array elements.

       <alice><bob>charlie</bob><bob>david</bob></alice>

   becomes

       { "alice": { "bob": [ "charlie", "david" ] } }

5. Attributes go in properties whose name begin with `"@"`.

       <alice charlie="david">bob</alice>

   becomes

       { "alice": { "@charlie": "david", "$": "bob" } }

6. A default namespace declaration goes in the element's `"@xmlns"` property.

       <alice xmlns="http://some-namespace">bob</alice>

   becomes

       { "alice": { "@xmlns": "http://some-namespace", "$": "bob" } }

7. A prefixed namespace declaration goes in the element's `"@xmlns:<prefix>"` property.

       <alice xmlns:edgar="http://some-other-namespace">bob</alice>

   becomes

       { "alice": { "@xmlns:edgar": "http://some-other-namespace", "$": "bob" } }

- Related Packages
  Package
  Description
  org.apache.synapse.commons.staxon.core.json.jaxb
  JAXB support for JSON.
  org.apache.synapse.commons.staxon.core.json.stream
  JSON streaming backend API.
  org.apache.synapse.commons.staxon.core.json.util
  JSON-specific StAX utility classes.
- Class
  Description
  JsonXMLConfig
  Json XML factory configuration interface.
  JsonXMLConfigBuilder
  Configuration builder with "fluid" interface.
  JsonXMLConfigImpl
  Simple JSON XML configuration.
  JsonXMLInputFactory
  XML input factory for streaming from JSON.
  JsonXMLOutputFactory
  XML output factory for streaming to JSON.
  JsonXMLStreamConstants
  Constants used by reader and writer classes.
  JsonXMLStreamReader
  JSON XML stream reader.
  JsonXMLStreamWriter
  JSON XML stream writer.