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

Go to download
Show more of this group Show more artifacts with this name
Show all versions of eclipselink Show documentation
EclipseLink build based upon Git transaction f2b9fc5
There is a newer version: 5.0.0-B03
/*
 * Copyright (c) 1998, 2023 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.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;
    }

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

    @Override
    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
     */
    @Override
    public Object getResult() {
        Document document = getDocument();

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