org.eclipse.persistence.oxm.XMLUnmarshallerHandler Maven / Gradle / Ivy

Show more of this group Show more artifacts with this name
Show all versions of org.eclipse.persistence.core Show documentation
EclipseLink build based upon Git transaction ecdf3c32c4
There is a newer version: 4.0.2
Show newest version
/*
 * Copyright (c) 1998, 2018 Oracle and/or its affiliates. All rights reserved.
 *
 * This program and the accompanying materials are made available under the
 * terms of the Eclipse Public License v. 2.0 which is available at
 * http://www.eclipse.org/legal/epl-2.0,
 * or the Eclipse Distribution License v. 1.0 which is available at
 * http://www.eclipse.org/org/documents/edl-v10.php.
 *
 * SPDX-License-Identifier: EPL-2.0 OR BSD-3-Clause
 */

// Contributors:
//     Oracle - initial API and implementation from Oracle TopLink
package org.eclipse.persistence.oxm;

import org.eclipse.persistence.exceptions.XMLMarshalException;
import org.eclipse.persistence.internal.oxm.UnmarshallerHandler;
import org.eclipse.persistence.oxm.XMLUnmarshaller;
import org.eclipse.persistence.platform.xml.SAXDocumentBuilder;
import org.w3c.dom.Document;
import org.xml.sax.SAXException;

/**
 * Class used to unmarshal SAX events to objects.
 *
 * 
Create an XMLUnmarshallerHandler from an XMLUnmarshaller.

 *  Code Sample

 *  
 *  XMLContext context = new XMLContext("mySessionName");

 *  XMLUnmarshaller unmarshaller = context.createUnmarshaller();

 *  XMLUnmarshallerHandler unmarshallerHandler = unmarshaller.getUnmarshallerHandler();

 *  
 *
 * 
Use the UnmarshallerHandler with an XMLReader

 *  Code Sample

 *  
 *  SAXParserFactory saxParserFactory = SAXParserFactory.newInstance();

 *  saxParserFactory.setNamespaceAware(true);

 *  SAXParser saxParser = saxParserFactory.newSAXParser();

 *  XMLReader xmlReader = saxParser.getXMLReader();

 *  xmlReader.setContentHandler(xmlUnmarshallerHandler);

 *  FileInputStream inputStream = new FileInputStream("MyFile.xml");

 *  InputSource inputSource = new InputSource(inputStream);

 *  xmlReader.parse(inputSource);

 *  Object result = xmlUnmarshallerHandler.getResult();

 *  
 *
 * XML that can be unmarshalled is XML which has a root tag that corresponds
 * to a default root element on an XMLDescriptor in the TopLink project associated
 * with the XMLContext.
 *
 * @see org.eclipse.persistence.oxm.XMLUnmarshaller
 */
public class XMLUnmarshallerHandler extends SAXDocumentBuilder implements UnmarshallerHandler {
    private XMLUnmarshaller xmlUnmarshaller;
    private boolean endDocumentTriggered;

    XMLUnmarshallerHandler(XMLUnmarshaller xmlUnmarshaller) {
        super();
        this.xmlUnmarshaller = xmlUnmarshaller;
    }

    public void endDocument() throws SAXException {
        endDocumentTriggered = true;
        super.endDocument();
    }

    public void startDocument() throws SAXException {
        endDocumentTriggered = false;
        super.startDocument();
    }

    /**
     * Returns the object that was unmarshalled from the SAX events.
     * @return the resulting object
     * @throws XMLMarshalException if an error occurred during unmarshalling
     */
    public Object getResult() {
        Document document = getDocument();

        if ((document == null) || !endDocumentTriggered) {
            throw XMLMarshalException.illegalStateXMLUnmarshallerHandler();
        }
        return xmlUnmarshaller.unmarshal(document);
    }
}