java.fedora.server.journal.xmlhelpers.AbstractXmlReader Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of fcrepo-client Show documentation
The Fedora Client is a Java Library that allows API access to a Fedora Repository. The client is typically one part of a full Fedora installation.
The newest version!
/*
 * -----------------------------------------------------------------------------
 *
 * License and Copyright: The contents of this file are subject to the
 * Apache License, Version 2.0 (the "License"); you may not use 
 * this file except in compliance with the License. You may obtain a copy of 
 * the License at 
 * http://www.fedora-commons.org/licenses.
 *
 * Software distributed under the License is distributed on an "AS IS" basis,
 * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License for
 * the specific language governing rights and limitations under the License.
 *
 * The entire file consists of original code.
 * Copyright © 2008 Fedora Commons, Inc.

 * 
Copyright © 2002-2007 The Rector and Visitors of the University of 
 * Virginia and Cornell University
 
 * All rights reserved.
 *
 * -----------------------------------------------------------------------------
 */

package fedora.server.journal.xmlhelpers;

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

import fedora.server.journal.JournalConstants;
import fedora.server.journal.JournalException;

/**
 * 
 * Title: AbstractXmlReader
 * 
 * 
 * Description: An abstract base class that provides some useful methods
 * for the XML reader classes.
 * 
 * 
 * @author [email protected]
 * @version $Id: AbstractXmlReader.java 5025 2006-09-01 22:08:17 +0000 (Fri, 01
 *          Sep 2006) cwilper $
 */

public abstract class AbstractXmlReader
        implements JournalConstants {

    /**
     * Advance past any white space. Leave the reader positioned before the next
     * tag (or non-white-space event).
     */
    protected void advancePastWhitespace(XMLEventReader reader)
            throws XMLStreamException {
        XMLEvent next = reader.peek();
        while (next.isCharacters() && next.asCharacters().isWhiteSpace()) {
            reader.nextEvent();
            next = reader.peek();
        }
    }

    /**
     * Read the next event and complain if it is not the Start Tag that we
     * expected.
     */
    protected XMLEvent readStartTag(XMLEventReader reader, QName tagName)
            throws XMLStreamException, JournalException {
        XMLEvent event = reader.nextTag();
        if (!isStartTagEvent(event, tagName)) {
            throw getNotStartTagException(tagName, event);
        }
        return event;
    }

    /**
     * Test an event to see whether it is an start tag with the expected name.
     */
    protected boolean isStartTagEvent(XMLEvent event, QName tagName) {
        return event.isStartElement()
                && event.asStartElement().getName().equals(tagName);
    }

    /**
     * Test an event to see whether it is an end tag with the expected name.
     */
    protected boolean isEndTagEvent(XMLEvent event, QName tagName) {
        return event.isEndElement()
                && event.asEndElement().getName().equals(tagName);
    }

    /**
     * Get the value of a given attribute from this start tag, or complain if
     * it's not there.
     */
    protected String getRequiredAttributeValue(StartElement start,
                                               QName attributeName)
            throws JournalException {
        Attribute mapNameAttribute = start.getAttributeByName(attributeName);
        if (mapNameAttribute == null) {
            throw new JournalException("Start tag '" + start
                    + "' must contain a '" + attributeName + "' attribute.");
        }
        return mapNameAttribute.getValue();
    }

    /**
     * Get the value of a given attribute from this start tag, or null if the
     * attribute is not there.
     */
    protected String getOptionalAttributeValue(StartElement start,
                                               QName attributeName) {
        Attribute mapNameAttribute = start.getAttributeByName(attributeName);
        if (mapNameAttribute == null) {
            return null;
        } else {
            return mapNameAttribute.getValue();
        }
    }

    /**
     * Loop through a series of character events, accumulating the data into a
     * String. The character events should be terminated by an EndTagEvent with
     * the expected tag name.
     */
    protected String readCharactersUntilEndTag(XMLEventReader reader,
                                               QName tagName)
            throws XMLStreamException, JournalException {
        StringBuffer stringValue = new StringBuffer();
        while (true) {
            XMLEvent event = reader.nextEvent();
            if (event.isCharacters()) {
                stringValue.append(event.asCharacters().getData());
            } else if (isEndTagEvent(event, tagName)) {
                break;
            } else {
                throw getNotCharactersException(tagName, event);
            }
        }
        return stringValue.toString();
    }

    /**
     * Complain when we were expecting a start tag, and didn't find it.
     */
    protected JournalException getNotStartTagException(QName tagName,
                                                       XMLEvent event) {
        return new JournalException("Expecting '" + tagName
                + "' start tag, but event was '" + event + "'");

    }

    /**
     * Complain when we were expecting a end tag, and didn't find it.
     */
    protected JournalException getNotEndTagException(QName tagName,
                                                     XMLEvent event) {
        return new JournalException("Expecting '" + tagName
                + "' end tag, but event was '" + event + "'");

    }

    /**
     * If we encounter an unexpected event when reading the journal file, create
     * an exception with all of the pertinent information.
     */
    protected JournalException getNotCharactersException(QName tagName,
                                                         XMLEvent event) {
        return new JournalException("Expecting characters or '" + tagName
                + "' end tag, but event was '" + event + "'");
    }

    /**
     * While traversing a group of member tags, we expected either the start of
     * another member tag, or the end of the group.
     */
    protected JournalException getNotNextMemberOrEndOfGroupException(QName groupTagName,
                                                                     QName memberTagName,
                                                                     XMLEvent event) {
        return new JournalException("Expecting either '" + memberTagName
                + "' start tag, or '" + groupTagName
                + "' end tag, but event was '" + event + "'");
    }
}