/* ========================================================================
* JCommon : a free general purpose class library for the Java(tm) platform
* ========================================================================
*
* (C) Copyright 2000-2005, by Object Refinery Limited and Contributors.
*
* Project Info: http://www.jfree.org/jcommon/index.html
*
* This library is free software; you can redistribute it and/or modify it
* under the terms of the GNU Lesser General Public License as published by
* the Free Software Foundation; either version 2.1 of the License, or
* (at your option) any later version.
*
* This library is distributed in the hope that it will be useful, but
* WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
* or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public
* License for more details.
*
* You should have received a copy of the GNU Lesser General Public
* License along with this library; if not, write to the Free Software
* Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301,
* USA.
*
* [Java is a trademark or registered trademark of Sun Microsystems, Inc.
* in the United States and other countries.]
*
* ------------------------
* AbstractModelReader.java
* ------------------------
* (C)opyright 2003-2005, by Thomas Morgner and Contributors.
*
* Original Author: Thomas Morgner;
* Contributor(s): David Gilbert (for Object Refinery Limited);
*
* $Id: AbstractModelReader.java,v 1.8 2005/10/18 13:33:53 mungady Exp $
*
* Changes
* -------
* 12-Nov-2003 : Initial version
* 25-Nov-2003 : Updated header (DG);
*
*/
package org.jfree.xml.util;
import java.io.BufferedInputStream;
import java.io.InputStream;
import java.net.URL;
import java.util.Stack;
import javax.xml.parsers.SAXParser;
import javax.xml.parsers.SAXParserFactory;
import org.jfree.util.Log;
import org.jfree.util.ObjectUtilities;
import org.jfree.xml.CommentHandler;
import org.jfree.xml.ElementDefinitionException;
import org.xml.sax.Attributes;
import org.xml.sax.InputSource;
import org.xml.sax.SAXException;
import org.xml.sax.XMLReader;
import org.xml.sax.helpers.DefaultHandler;
/**
* Loads the class model from an previously written xml file set.
* This class provides abstract methods which get called during the parsing
* (similiar to the SAX parsing, but slightly easier to code).
*
* This will need a rewrite in the future, when the structure is finished.
*/
public abstract class AbstractModelReader {
/** The 'START' state. */
private static final int STATE_START = 0;
/** The 'IN_OBJECT' state. */
private static final int IN_OBJECT = 1;
/** The 'IGNORE_OBJECT' state. */
private static final int IGNORE_OBJECT = 2;
/** The 'MAPPING' state. */
private static final int MAPPING_STATE = 3;
/** The 'CONSTRUCTOR' state. */
private static final int CONSTRUCTOR_STATE = 4;
/**
* The SAX2 callback implementation used for parsing the model xml files.
*/
private class SAXModelHandler extends DefaultHandler {
/** The resource URL. */
private URL resource;
/** The current state. */
private int state;
/** Open comments. */
private Stack openComments;
/** Flag to track includes. */
private boolean isInclude;
/**
* Creates a new SAX handler for parsing the model.
*
* @param resource the resource URL.
* @param isInclude an include?
*/
public SAXModelHandler(final URL resource, final boolean isInclude) {
if (resource == null) {
throw new NullPointerException();
}
this.resource = resource;
this.openComments = new Stack();
this.isInclude = isInclude;
}
/**
* Receive notification of the start of an element.
*
* @param uri The Namespace URI, or the empty string if the
* element has no Namespace URI or if Namespace
* processing is not being performed.
* @param localName The local name (without prefix), or the
* empty string if Namespace processing is not being
* performed.
* @param qName The qualified name (with prefix), or the
* empty string if qualified names are not available.
* @param attributes The attributes attached to the element. If
* there are no attributes, it shall be an empty
* Attributes object.
* @exception SAXException Any SAX exception, possibly
* wrapping another exception.
*
* @see org.xml.sax.ContentHandler#startElement
*/
public void startElement(final String uri, final String localName,
final String qName, final Attributes attributes)
throws SAXException {
setOpenComment(getCommentHandler().getComments());
this.openComments.push(getOpenComment());
setCloseComment(null);
try {
if (!this.isInclude && qName.equals(ClassModelTags.OBJECTS_TAG)) {
//Log.debug ("Open Comments: " + openComment);
startRootDocument();
return;
}
if (getState() == STATE_START) {
startRootElement(qName, attributes);
}
else if (getState() == IGNORE_OBJECT) {
return;
}
else if (getState() == IN_OBJECT) {
startObjectElement(qName, attributes);
}
else if (getState() == MAPPING_STATE) {
if (!qName.equals(ClassModelTags.TYPE_TAG)) {
throw new SAXException("Expected 'type' tag");
}
final String name = attributes.getValue(ClassModelTags.NAME_ATTR);
final String target = attributes.getValue(ClassModelTags.CLASS_ATTR);
handleMultiplexMapping(name, target);
}
else if (getState() == CONSTRUCTOR_STATE) {
if (!qName.equals(ClassModelTags.PARAMETER_TAG)) {
throw new SAXException("Expected 'parameter' tag");
}
final String parameterClass = attributes.getValue(ClassModelTags.CLASS_ATTR);
final String tagName = attributes.getValue(ClassModelTags.PROPERTY_ATTR); // optional
handleConstructorDefinition(tagName, parameterClass);
}
}
catch (ObjectDescriptionException e) {
throw new SAXException(e);
}
finally {
getCommentHandler().clearComments();
}
}
/**
* Receive notification of the end of an element.
*
* @param uri The Namespace URI, or the empty string if the
* element has no Namespace URI or if Namespace
* processing is not being performed.
* @param localName The local name (without prefix), or the
* empty string if Namespace processing is not being
* performed.
* @param qName The qualified name (with prefix), or the
* empty string if qualified names are not available.
* @exception SAXException Any SAX exception, possibly
* wrapping another exception.
* @see org.xml.sax.ContentHandler#endElement
*/
public void endElement(final String uri, final String localName, final String qName)
throws SAXException {
setOpenComment((String[]) this.openComments.pop());
setCloseComment(getCommentHandler().getComments());
try {
if (!this.isInclude && qName.equals(ClassModelTags.OBJECTS_TAG)) {
endRootDocument();
return;
}
if (qName.equals(ClassModelTags.OBJECT_TAG)) {
if (getState() != IGNORE_OBJECT) {
endObjectDefinition();
}
setState(STATE_START);
}
else if (qName.equals(ClassModelTags.MAPPING_TAG)) {
setState(STATE_START);
endMultiplexMapping();
}
else if (qName.equals(ClassModelTags.CONSTRUCTOR_TAG)) {
if (getState() != IGNORE_OBJECT) {
setState(IN_OBJECT);
}
}
}
catch (ObjectDescriptionException e) {
throw new SAXException(e);
}
finally {
getCommentHandler().clearComments();
}
}
/**
* Handles the start of an element within an object definition.
*
* @param qName The qualified name (with prefix), or the
* empty string if qualified names are not available.
* @param attributes The attributes attached to the element. If
* there are no attributes, it shall be an empty
* Attributes object.
* @throws ObjectDescriptionException if an error occured while
* handling this tag
*/
private void startObjectElement(final String qName, final Attributes attributes)
throws ObjectDescriptionException {
if (qName.equals(ClassModelTags.CONSTRUCTOR_TAG)) {
setState(CONSTRUCTOR_STATE);
}
else if (qName.equals(ClassModelTags.LOOKUP_PROPERTY_TAG)) {
final String name = attributes.getValue(ClassModelTags.NAME_ATTR);
final String lookupKey = attributes.getValue(ClassModelTags.LOOKUP_ATTR);
handleLookupDefinition(name, lookupKey);
}
else if (qName.equals(ClassModelTags.IGNORED_PROPERTY_TAG)) {
final String name = attributes.getValue(ClassModelTags.NAME_ATTR);
handleIgnoredProperty(name);
}
else if (qName.equals(ClassModelTags.ELEMENT_PROPERTY_TAG)) {
final String elementAtt = attributes.getValue(ClassModelTags.ELEMENT_ATTR);
final String name = attributes.getValue(ClassModelTags.NAME_ATTR);
handleElementDefinition(name, elementAtt);
}
else if (qName.equals(ClassModelTags.ATTRIBUTE_PROPERTY_TAG)) {
final String name = attributes.getValue(ClassModelTags.NAME_ATTR);
final String attribName = attributes.getValue(ClassModelTags.ATTRIBUTE_ATTR);
final String handler = attributes.getValue(ClassModelTags.ATTRIBUTE_HANDLER_ATTR);
handleAttributeDefinition(name, attribName, handler);
}
}
/**
* Handles the include or object tag.
*
* @param qName The qualified name (with prefix), or the
* empty string if qualified names are not available.
* @param attributes The attributes attached to the element. If
* there are no attributes, it shall be an empty
* Attributes object.
* @throws SAXException if an parser error occured
* @throws ObjectDescriptionException if an object model related
* error occured.
*/
private void startRootElement(final String qName, final Attributes attributes)
throws SAXException, ObjectDescriptionException {
if (qName.equals(ClassModelTags.INCLUDE_TAG)) {
if (this.isInclude) {
Log.warn("Ignored nested include tag.");
return;
}
final String src = attributes.getValue(ClassModelTags.SOURCE_ATTR);
try {
final URL url = new URL(this.resource, src);
startIncludeHandling(url);
parseXmlDocument(url, true);
endIncludeHandling();
}
catch (Exception ioe) {
throw new ElementDefinitionException
(ioe, "Unable to include file from " + src);
}
}
else if (qName.equals(ClassModelTags.OBJECT_TAG)) {
setState(IN_OBJECT);
final String className = attributes.getValue(ClassModelTags.CLASS_ATTR);
String register = attributes.getValue(ClassModelTags.REGISTER_NAMES_ATTR);
if (register != null && register.length() == 0) {
register = null;
}
final boolean ignored = "true".equals(attributes.getValue(ClassModelTags.IGNORE_ATTR));
if (!startObjectDefinition(className, register, ignored)) {
setState(IGNORE_OBJECT);
}
}
else if (qName.equals(ClassModelTags.MANUAL_TAG)) {
final String className = attributes.getValue(ClassModelTags.CLASS_ATTR);
final String readHandler = attributes.getValue(ClassModelTags.READ_HANDLER_ATTR);
final String writeHandler = attributes.getValue(ClassModelTags.WRITE_HANDLER_ATTR);
handleManualMapping(className, readHandler, writeHandler);
}
else if (qName.equals(ClassModelTags.MAPPING_TAG)) {
setState(MAPPING_STATE);
final String typeAttr = attributes.getValue(ClassModelTags.TYPE_ATTR);
final String baseClass = attributes.getValue(ClassModelTags.BASE_CLASS_ATTR);
startMultiplexMapping(baseClass, typeAttr);
}
}
/**
* Returns the current state.
*
* @return the state.
*/
private int getState() {
return this.state;
}
/**
* Sets the current state.
*
* @param state the state.
*/
private void setState(final int state) {
this.state = state;
}
}
/** The comment handler. */
private CommentHandler commentHandler;
/** The close comments. */
private String[] closeComment;
/** The open comments. */
private String[] openComment;
/**
* Default Constructor.
*/
public AbstractModelReader() {
this.commentHandler = new CommentHandler();
}
/**
* Returns the comment handler.
*
* @return The comment handler.
*/
protected CommentHandler getCommentHandler() {
return this.commentHandler;
}
/**
* Returns the close comment.
*
* @return The close comment.
*/
protected String[] getCloseComment() {
return this.closeComment;
}
/**
* Returns the open comment.
*
* @return The open comment.
*/
protected String[] getOpenComment() {
return this.openComment;
}
/**
* Sets the close comment.
*
* @param closeComment the close comment.
*/
protected void setCloseComment(final String[] closeComment) {
this.closeComment = closeComment;
}
/**
* Sets the open comment.
*
* @param openComment the open comment.
*/
protected void setOpenComment(final String[] openComment) {
this.openComment = openComment;
}
/**
* Parses an XML document at the given URL.
*
* @param resource the document URL.
*
* @throws ObjectDescriptionException ??
*/
protected void parseXml(final URL resource) throws ObjectDescriptionException {
parseXmlDocument(resource, false);
}
/**
* Parses the given specification and loads all includes specified in the files.
* This implementation does not check for loops in the include files.
*
* @param resource the url of the xml specification.
* @param isInclude an include?
*
* @throws org.jfree.xml.util.ObjectDescriptionException if an error occured which prevented the
* loading of the specifications.
*/
protected void parseXmlDocument(final URL resource, final boolean isInclude)
throws ObjectDescriptionException {
try {
final InputStream in = new BufferedInputStream(resource.openStream());
final SAXParserFactory factory = SAXParserFactory.newInstance();
final SAXParser saxParser = factory.newSAXParser();
final XMLReader reader = saxParser.getXMLReader();
final SAXModelHandler handler = new SAXModelHandler(resource, isInclude);
try {
reader.setProperty
("http://xml.org/sax/properties/lexical-handler",
getCommentHandler());
}
catch (SAXException se) {
Log.debug("Comments are not supported by this SAX implementation.");
}
reader.setContentHandler(handler);
reader.setDTDHandler(handler);
reader.setErrorHandler(handler);
reader.parse(new InputSource(in));
in.close();
}
catch (Exception e) {
// unable to init
Log.warn("Unable to load factory specifications", e);
throw new ObjectDescriptionException("Unable to load object factory specs.", e);
}
}
/**
* Start the root document.
*/
protected void startRootDocument() {
// nothing required
}
/**
* End the root document.
*/
protected void endRootDocument() {
// nothing required
}
/**
* Start handling an include.
*
* @param resource the URL.
*/
protected void startIncludeHandling(final URL resource) {
// nothing required
}
/**
* End handling an include.
*/
protected void endIncludeHandling() {
// nothing required
}
/**
* Callback method for ignored properties. Such properties get marked so that
* the information regarding these properties won't get lost.
*
* @param name the name of the ignored property.
*/
protected void handleIgnoredProperty(final String name) {
// nothing required
}
/**
* Handles a manual mapping definition. The manual mapping maps specific
* read and write handlers to a given base class. Manual mappings always
* override any other definition.
*
* @param className the base class name
* @param readHandler the class name of the read handler
* @param writeHandler the class name of the write handler
* @return true, if the mapping was accepted, false otherwise.
* @throws ObjectDescriptionException if an unexpected error occured.
*/
protected abstract boolean handleManualMapping(String className, String readHandler,
String writeHandler) throws ObjectDescriptionException;
/**
* Starts a object definition. The object definition collects all properties of
* an bean-class and defines, which constructor should be used when creating the
* class.
*
* @param className the class name of the defined object
* @param register the (optional) register name, to lookup and reference the object
* later.
* @param ignored ??.
*
* @return true, if the definition was accepted, false otherwise.
* @throws ObjectDescriptionException if an unexpected error occured.
*/
protected abstract boolean startObjectDefinition(String className, String register,
boolean ignored) throws ObjectDescriptionException;
/**
* Handles an attribute definition. This method gets called after the object definition
* was started. The method will be called for every defined attribute property.
*
* @param name the name of the property
* @param attribName the xml-attribute name to use later.
* @param handlerClass the attribute handler class.
* @throws ObjectDescriptionException if an error occured.
*/
protected abstract void handleAttributeDefinition(String name, String attribName,
String handlerClass)
throws ObjectDescriptionException;
/**
* Handles an element definition. This method gets called after the object definition
* was started. The method will be called for every defined element property. Element
* properties are used to describe complex objects.
*
* @param name the name of the property
* @param element the xml-tag name for the child element.
* @throws ObjectDescriptionException if an error occurs.
*/
protected abstract void handleElementDefinition(String name, String element)
throws ObjectDescriptionException;
/**
* Handles an lookup definition. This method gets called after the object definition
* was started. The method will be called for every defined lookup property. Lookup properties
* reference previously created object using the object's registry name.
*
* @param name the property name of the base object
* @param lookupKey the register key of the referenced object
* @throws ObjectDescriptionException if an error occured.
*/
protected abstract void handleLookupDefinition(String name, String lookupKey)
throws ObjectDescriptionException;
/**
* Finializes the object definition.
*
* @throws ObjectDescriptionException if an error occures.
*/
protected abstract void endObjectDefinition() throws ObjectDescriptionException;
/**
* Starts a multiplex mapping. Multiplex mappings are used to define polymorphic
* argument handlers. The mapper will collect all derived classes of the given
* base class and will select the corresponding mapping based on the given type
* attribute.
*
* @param className the base class name
* @param typeAttr the xml-attribute name containing the mapping key
*/
protected abstract void startMultiplexMapping(String className, String typeAttr);
/**
* Defines an entry for the multiplex mapping. The new entry will be activated
* when the base mappers type attribute contains this <code>typename</code> and
* will resolve to the handler for the given classname.
*
* @param typeName the type value for this mapping.
* @param className the class name to which this mapping resolves.
* @throws ObjectDescriptionException if an error occurs.
*/
protected abstract void handleMultiplexMapping(String typeName, String className)
throws ObjectDescriptionException;
/**
* Finializes the multiplexer mapping.
*
* @throws ObjectDescriptionException if an error occurs.
*/
protected abstract void endMultiplexMapping() throws ObjectDescriptionException;
/**
* Handles a constructor definition. Only one constructor can be defined for
* a certain object type. The constructor will be filled using the given properties.
*
* @param propertyName the property name of the referenced local property
* @param parameterClass the parameter class for the parameter.
* @throws ObjectDescriptionException if an error occured.
*/
protected abstract void handleConstructorDefinition(String propertyName, String parameterClass)
throws ObjectDescriptionException;
/**
* Loads the given class, and ignores all exceptions which may occur
* during the loading. If the class was invalid, null is returned instead.
*
* @param className the name of the class to be loaded.
* @return the class or null.
*/
protected Class loadClass(final String className) {
if (className == null) {
return null;
}
if (className.startsWith("::")) {
return BasicTypeSupport.getClassRepresentation(className);
}
try {
return ObjectUtilities.getClassLoader(getClass()).loadClass(className);
}
catch (Exception e) {
// ignore buggy classes for now ..
Log.warn("Unable to load class", e);
return null;
}
}
}