[tmp/jakarta-migration.git] /

package org.collectionspace.services.common.xmljson;

import java.io.IOException;
import java.io.InputStream;
import java.io.OutputStream;
import java.util.Iterator;
import java.util.Stack;

import javax.xml.namespace.QName;
import javax.xml.stream.XMLEventReader;
import javax.xml.stream.XMLInputFactory;
import javax.xml.stream.XMLStreamConstants;
import javax.xml.stream.XMLStreamException;
import javax.xml.stream.events.Attribute;
import javax.xml.stream.events.Namespace;
import javax.xml.stream.events.StartElement;
import javax.xml.stream.events.XMLEvent;

import com.fasterxml.jackson.core.JsonGenerationException;
import com.fasterxml.jackson.databind.JsonMappingException;
import com.fasterxml.jackson.databind.ObjectMapper;

/**
 * Converts a CSpace XML payload to a JSON payload.
 *
 * This class is not intended to serve as a general purpose XML to JSON
 * translator. It is instead a lightweight processor tuned for the kinds
 * of XML generated by CSpace, and the particular transformations needed
 * to generate JSON for CSpace. The XML input is expected to conform to
 * conventions (described below) of CSpace XML payloads.
 * 
 * The conversion is performed as follows:
 * <ul>
 * <li>XML elements are converted to identically-named JSON fields.</li>
 * <li>XML attributes are converted to JSON fields prepended with "@".</li>
 * <li>XML namespace declarations are converted to JSON fields prepended with "@xmlns:".</li>
 * <li>Sibling XML elements that have the same name are converted to JSON arrays.</li>
 * </ul>
 *
 * This implementation is schema-unaware. It operates by examining only the input
 * document, without utilizing any XML schema information. This allows for speed
 * and simplicity, but has some consequences:
 *
 * <ul>
 * <li>Since type information is not available, all text content is converted to
 *     JSON strings.</li>
 * <li>Lists are inferred by the presence of multiple child elements with
 *     the same name. If an element contains only one child with a given name, it
 *     will not be converted to a JSON array, even if multiples are allowed by
 *     the XML schema.</li>
 * <li>Lists are not known ahead of time, and must be inferred by the presence of
 *     multiple identically-named children. This means that all children of an element
 *     must be known before JSON for that element can be generated. This makes it
 *     necessary to read the entire XML document into memory first, instead of
 *     doing a direct stream-to-stream conversion.</li>
 * </ul>
 *
 * Example:
 * 
 * XML
 * <pre>
 * <document name="collectionobjects">
 *   <ns2:collectionspace_core xmlns:ns2="http://collectionspace.org/collectionspace_core/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
 *     <createdBy>admin@core.collectionspace.org</createdBy>
 *     <createdAt>2016-07-27T04:31:38.290Z</createdAt>
 *   </ns2:collectionspace_core>
 *   <ns2:collectionobjects_common xmlns:ns2="http://collectionspace.org/services/collectionobject" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
 *     <objectNumber>2016.1.1</objectNumber>
 *     <objectNameList>
 *       <objectNameGroup>
 *         <objectNameCurrency/>
 *         <objectNameLanguage/>
 *         <objectName>Object name</objectName>
 *         <objectNameSystem/>
 *         <objectNameType/>
 *         <objectNameNote/>
 *         <objectNameLevel/>
 *       </objectNameGroup>
 *       <objectNameGroup>
 *         <objectNameCurrency/>
 *         <objectNameLanguage/>
 *         <objectName>Another name</objectName>
 *         <objectNameSystem/>
 *         <objectNameType/>
 *         <objectNameNote/>
 *         <objectNameLevel/>
 *       </objectNameGroup>
 *     </objectNameList>
 *     <comments>
 *       <comment>Some comment text</comment>
 *       <comment>Another comment</comment>
 *     </comments>
 *   </ns2:collectionobjects_common>
 * </document>
 * </pre>
 * 
 * JSON
 * <pre>
 * {
 *   "document": {
 *     "@name": "collectionobjects",
 *     "ns2:collectionspace_core": {
 *       "@xmlns:ns2": "http://collectionspace.org/collectionspace_core/",
 *       "@xmlns:xsi": "http://www.w3.org/2001/XMLSchema-instance",
 *       "createdBy": "admin@core.collectionspace.org",
 *       "createdAt": "2016-07-27T04:31:38.290Z"
 *     },
 *     "ns2:collectionobjects_common": {
 *       "@xmlns:ns2": "http://collectionspace.org/services/collectionobject",
 *       "@xmlns:xsi": "http://www.w3.org/2001/XMLSchema-instance",
 *       "objectNumber": "2016.1.1",
 *       "objectNameList": {
 *         "objectNameGroup": [
 *           {
 *             "objectNameCurrency": null,
 *             "objectNameLanguage": null,
 *             "objectName": "Object name",
 *             "objectNameSystem": null,
 *             "objectNameType": null,
 *             "objectNameNote": null,
 *             "objectNameLevel": null
 *           },
 *           {
 *             "objectNameCurrency": null,
 *             "objectNameLanguage": null,
 *             "objectName": "Another name",
 *             "objectNameSystem": null,
 *             "objectNameType": null,
 *             "objectNameNote": null,
 *             "objectNameLevel": null
 *           }
 *         ]
 *       },
 *       "comments": {
 *         "comment": [
 *           "Some comment text",
 *           "Another comment"
 *         ]
 *       }
 *     }
 *   }
 * }
 * </pre>
 * 
 * The conversion algorithm assumes that the input XML adheres to the following 
 * conventions:
 * 
 * <ul>
 * <li>The XML does not contain mixed-content elements. Elements may contain text
 *     or child elements, but not both. If an element contains child elements,
 *     any text adjacent to those child elements is discarded.</li>
 * <li>The XML does not have namespace declarations or attributes on text elements.
 *     If namespace declarations or attributes appear on elements containing
 *     only text, they are discarded.</li>
 * <li>The XML does not contain sequences of identically-named elements that are
 *     interrupted by other elements; or if it does, those interruptions are not
 *     important. For example, the parent node below contains a list of item
 *     elements, interrupted by an other element:
 *     
 *     <pre>
 *       <parent>
 *         <item>a</item>
 *         <item>b</item>
 *         <item>c</item>
 *         <other>uh oh</other>
 *         <item>d</item>
 *         <item>e</item>
 *       </parent>
 *     </pre>
 *     
 *     This is translated to:
 *     
 *     <pre>
 *       "parent": {
 *          "item": [
 *            "a",
 *            "b",
 *            "c",
 *            "d",
 *            "e"
 *          ],
 *          "other": "uh oh"
 *       }
 *     </pre>
 *     
 *     All of the item children of parent are converted into a single
 *     list, so the placement of the other element is not retained in
 *     JSON.
 * </li>
 * </ul>
 * 
 * This implementation uses a StAX parser to generate a lightweight 
 * representation of the input XML document in memory, performs the
 * necessary transformations, and outputs a JSON rendering of the
 * transformed document. A direct stream-to-stream conversion is
 * not possible because of the need to collect identically-named
 * XML elements for output as a JSON array; for any element, all children
 * must be known before JSON for that element may be written to the
 * output stream.
 */
public class XmlToJsonStreamConverter {
    /**
     * The StAX event reader used to parse the XML input stream.
     */
    protected XMLEventReader xmlEventReader;
    
    
    /**
     * The JSON output stream.
     */
    protected OutputStream jsonStream;
    
    /**
     * A stack used to track the current state of XML parsing.
     * XmlNode instances are pushed onto the stack as elements
     * are entered, and popped off as elements are exited.
     */
    protected Stack<XmlNode> stack = new Stack<XmlNode>();
    
    /**
     * The result of parsing the XML.
     */
    protected XmlNode parseResult = null;
    
    /**
     * Creates an XmlToJsonStreamConverter that reads XML from an input stream,
     * and writes JSON to an output stream.
     * 
     * @param in the XML input stream
     * @param out the JSON output stream
     * @throws XMLStreamException
     */
    public XmlToJsonStreamConverter(InputStream in, OutputStream out) throws XMLStreamException {
        XMLInputFactory factory = XMLInputFactory.newInstance();
        
        xmlEventReader = factory.createXMLEventReader(in);
        jsonStream = out;
    }
    
    /**
     * Performs the conversion.
     * 
     * @throws XMLStreamException
     * @throws JsonGenerationException
     * @throws JsonMappingException
     * @throws IOException
     */
    public void convert() throws XMLStreamException, JsonGenerationException, JsonMappingException, IOException {
        // Read in the XML stream.
        
        while(xmlEventReader.hasNext()) {
            XMLEvent event = xmlEventReader.nextEvent();
            
            switch(event.getEventType()) {
                case XMLStreamConstants.CHARACTERS:
                    onCharacters(event);
                    break;
                case XMLStreamConstants.START_ELEMENT:
                    onStartElement(event);
                    break;
                case XMLStreamConstants.END_ELEMENT:
                    onEndElement(event);
                    break;
                case XMLStreamConstants.START_DOCUMENT:
                    onStartDocument(event);
                    break;
                case XMLStreamConstants.END_DOCUMENT:
                    onEndDocument(event);
                    break;
            }
        }
        
        // The XML has been parsed into parseResult.
        // Write it out as JSON.
        
        ObjectMapper objectMapper = new ObjectMapper();
        objectMapper.writeValue(jsonStream, parseResult);
        
        jsonStream.flush();
    }
    
    /**
     * Event handler executed when the start of the XML document is
     * encountered in the input stream.
     * 
     * @param event the event
     */
    protected void onStartDocument(XMLEvent event) {
        // Push an unnamed node on the stack to represent the
        // document.
        
        stack.push(new XmlNode());
    }

    /**
     * Event handler executed when the end of the XML document is
     * encountered in the input stream.
     * 
     * @param event the event
     */
    protected void onEndDocument(XMLEvent event) {
        // The last remaining node on the stack should be
        // the one representing the document. Pop it and
        // store it in parseResult.
        
        parseResult = stack.pop();
    }
    
    /**
     * Event handler executed when the start of an XML element is
     * encountered in the input stream.
     * 
     * @param event the event
     */
    @SuppressWarnings("unchecked")
    protected void onStartElement(XMLEvent event) {
        // Create a node to represent the element.
        
        StartElement element = event.asStartElement();
        QName name = element.getName();

        XmlNode node = new XmlNode(ConversionUtils.jsonFieldNameFromXMLQName(name));

        // Add namespace declarations, if any.
        
        Iterator<Namespace> nsIter = element.getNamespaces();
        
        while(nsIter.hasNext()) {
            Namespace ns = nsIter.next();
            
            node.addNamespace(ns.getPrefix(), ns.getNamespaceURI());
        }

        // Add attributes, if any.
        
        Iterator<Attribute> attrIter = element.getAttributes();
        
        while(attrIter.hasNext()) {
            Attribute attr = attrIter.next();
            
            node.addAttribute(attr.getName().toString(), attr.getValue());
        }
        
        // Push the node onto the stack.
        
        stack.push(node);
    }

    /**
     * Event handler executed when the end of an XML element is
     * encountered in the input stream.
     * 
     * @param event the event
     */
    protected void onEndElement(XMLEvent event) {
        // Pop the node corresponding to this element off the stack.
        
        XmlNode node = stack.pop();
        XmlNode parent = stack.peek();
        
        // Add the node to its parent. This is done here instead of
        // in onStartElement(), because we now know the entire contents
        // of the element. This gives us the possibility to prevent
        // adding elements that are empty. In onStartElement(), we don't
        // yet know if the element is going to be empty.
        
        parent.addChild(node);
    }

    /**
     * Event handler executed when character content is
     * encountered in the input stream.
     * 
     * @param event the event
     */
    protected void onCharacters(XMLEvent event) {
        // Add the text to the parent element.
        
        String text = event.asCharacters().getData();
        XmlNode parent = stack.peek();
        
        parent.addText(text);
    }
}