# 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" } }

- Interface Summary
  Interface | Description
  --- | ---
  JsonXMLConfig | Json XML factory configuration interface.

- Class Summary
  Class | Description
  --- | ---
  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.