wyvern.kernel.properties
Class PropertyParser

java.lang.Object
  wyvern.kernel.properties.PropertyParser

public final class PropertyParser

extends java.lang.Object

This class provides methods for parsing properties. It's used primarily by the Archetype.parseProperties() for obtaining the properties and values to set on an object.

Version:

1.0, Jan 27, 1998

Author:

Steve Yegge

Constructor Summary

PropertyParser()

Method Summary

java.lang.Object	createBeanValue(java.lang.String classname) Attempts to load and instantiate the specified class.
static java.lang.Object	createPythonBeanValue(java.lang.String path, java.lang.Class type) Attempts to load and instantiate the specified python class.
static java.beans.BeanInfo	getBeanvalInfo(java.lang.Object value) Gets a BeanInfo object that will stop looking when it reaches the top of the wyvern class heirarchy.
static PropertyParser	getInstance()
static int	getIntAttribute(org.w3c.dom.Element node, java.lang.String name) Retrieves an attribute whose value is an int.
static java.util.HashMap	getPropNames(java.lang.Object value) Returns a list of the sub-properties that this value possesses.
java.lang.Object	instantiateObject(java.lang.Class c) Creates an instance of the passed class.
static Property	parseAppearance(org.w3c.dom.Element node) Creates an Appearance bean from the shorthand wyvern-XML "image" element.
java.lang.Object	parseBeanProperty(org.w3c.dom.Element node) Initializes a Bean property from its externalized representation.
void	parseBeanSubProps(org.w3c.dom.Element node, java.lang.Object bean) Parses an externalized bean property value (a "bean").
static Property	parseMusic(org.w3c.dom.Element node) Creates an Soundtrack bean from the shorthand wyvern-XML "music" element.
static Property	parsePoint(java.lang.String name, org.w3c.dom.Element node) Shortcut for properties whose value is a Point.
Property	parseProperty(org.w3c.dom.Node node) Parses a single property from an element list.
java.util.List	parsePropertyList(org.w3c.dom.Element node) Parses a list of externalized properties.
Property	parsePropertyNode(org.w3c.dom.Element child) Exact same thing as parseProperty(), except it doesn't get the first child element of the node and parse that.
static Property	parseSize(java.lang.String size) This allows the user to specify a (rectangular) size for an object, rather than a location list.
void	readBeanProp(java.lang.Object bean, java.beans.PropertyDescriptor desc, org.w3c.dom.Element node, java.lang.String name) Reads the value of a sub-property and initializes that sub-property on the passed object.
void	setContinueOnError(boolean continueOnError) Tells this PropertyParser to keep going if we encounter an error, such as a property that can't be instantiated.
static void	setSubProperty(java.lang.Object beanval, java.beans.PropertyDescriptor desc, java.lang.Object pval) Sets a sub-property on a bean-value object.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

PropertyParser

public PropertyParser()

Method Detail

getInstance

public static PropertyParser getInstance()

setContinueOnError

public void setContinueOnError(boolean continueOnError)

Tells this PropertyParser to keep going if we encounter an error, such as a property that can't be instantiated. By default, it stops when it encounters an error.

parsePropertyList

public java.util.List parsePropertyList(org.w3c.dom.Element node)
                                 throws java.lang.Exception

Parses a list of externalized properties.

Parameters:

node - a DOM tree containing the properties

Returns:

a List containing one Property object for each property that was parsed.

Throws:

ParseException - if there was a parse error in the list, unless continueOnError() was set.

java.lang.Exception

parseProperty

public Property parseProperty(org.w3c.dom.Node node)
                       throws java.lang.Exception

Parses a single property from an element list. A property consists of a name and a value. If the value starts with the keyword "class" or "arch", then it may be followed by a block statement consisting of a list of sub-properties to add to the class or archetype.

The parser has a number of special-cased properties (such as "size" and "weight") that occur so frequently that we felt justified in having special syntax available for them.

Parameters:

node - a DOM Node object containing at least one child node. The child node needn't necessarily be a property element - this method will strip childen from the node until it finds an element or the node is empty.

Returns:

a Property containing the property name and its value, or null if no property was found.

Throws:

a - ParseException if we found a malformed property element definition.

java.lang.Exception

parsePropertyNode

public Property parsePropertyNode(org.w3c.dom.Element child)
                           throws java.lang.Exception

Exact same thing as parseProperty(), except it doesn't get the first child element of the node and parse that. It just starts parsing with the passed node.

Throws:

java.lang.Exception

parseSize

public static Property parseSize(java.lang.String size)
                          throws java.lang.Exception

This allows the user to specify a (rectangular) size for an object, rather than a location list. It's syntactic sugar, but it also makes map loading faster, since you don't have to read in a point list for every object larger than 1x1.

Parameters:

size - a size specifier, such as 1x2

Returns:

a Property containing the "locs" property as a PointList

Throws:

java.lang.Exception

parsePoint

public static Property parsePoint(java.lang.String name,
                                  org.w3c.dom.Element node)
                           throws java.lang.Exception

Shortcut for properties whose value is a Point.

Parameters:

name - the property name

node - an Element of of type "point"; requires x, y attrs

Returns:

a Property containing the Point value

Throws:

java.lang.Exception

parseAppearance

public static Property parseAppearance(org.w3c.dom.Element node)
                                throws java.lang.Exception

Creates an Appearance bean from the shorthand wyvern-XML "image" element.

Parameters:

node - an Element of type "image"

Returns:

a property named "image" whose value is the bean

Throws:

java.lang.Exception

getIntAttribute

public static int getIntAttribute(org.w3c.dom.Element node,
                                  java.lang.String name)

Retrieves an attribute whose value is an int.

Parameters:

node - the Element node to get the attribute from

name - the name of the attribute to get

Returns:

the int value of that attribute, or zero if not present

parseMusic

public static Property parseMusic(org.w3c.dom.Element node)
                           throws java.lang.Exception

Creates an Soundtrack bean from the shorthand wyvern-XML "music" element.

Parameters:

node - an Element of type "music"

Returns:

a property named "music" whose value is the bean object

Throws:

java.lang.Exception

parseBeanProperty

public java.lang.Object parseBeanProperty(org.w3c.dom.Element node)
                                   throws java.lang.Exception

Initializes a Bean property from its externalized representation.

Parameters:

node - the DOM Element representing the bean property

Returns:

an initialized object of the specified value class

Throws:

ParseException - if it couldn't parse the bean value

java.lang.Exception

createBeanValue

public java.lang.Object createBeanValue(java.lang.String classname)
                                 throws java.lang.Exception

Attempts to load and instantiate the specified class.

Parameters:

classname - the name of the class to instantiate

Returns:

an object of that class. If the class implements the Singleton interface, it invokes getInstance() on the class instead of instantiating it.

Throws:

a - ParseException if the class couldn't be loaded or instantiated, with an appropriate detail message. If setContinueOnError() was called first, then no Exception will be thrown - it'l; return null instead.

java.lang.Exception

createPythonBeanValue

public static java.lang.Object createPythonBeanValue(java.lang.String path,
                                                     java.lang.Class type)
                                              throws java.lang.Exception

Attempts to load and instantiate the specified python class.

Parameters:

path - the (relative) path of the python file to instantiate, such as "wiz/wyvern/moonquest/moon_crystal".

Returns:

an object of that class

Throws:

an - InstantiationException if we couldn't create it

java.lang.Exception

instantiateObject

public java.lang.Object instantiateObject(java.lang.Class c)
                                   throws java.lang.Exception

Creates an instance of the passed class. If the class implements wyvern.lib.properties.Singleton, the method looks for a getInstance() method on the class and invokes that.

Parameters:

c - the class to check

Returns:

the new object or Singleton instance. Null if we couldn't instantiate it, and continueOnError() was called.

Throws:

any - Exception, unless setContinueOnError() is set. Don't count on it throwing an exception, though - it may simply log an error on the PropertyParser logger.

java.lang.Exception

parseBeanSubProps

public void parseBeanSubProps(org.w3c.dom.Element node,
                              java.lang.Object bean)
                       throws java.lang.Exception

Parses an externalized bean property value (a "bean").

Parameters:

node - the DOM Element representing the bean

bean - the Bean object to add the properties to

Returns:

nothing, but sets the properties on beanval as it reads them. The method may be invoked recursively if it finds a nested beanval definition.

Throws:

ParseException - if the Bean couldn't be parsed, with an appropriate detail message.

java.lang.Exception

readBeanProp

public void readBeanProp(java.lang.Object bean,
                         java.beans.PropertyDescriptor desc,
                         org.w3c.dom.Element node,
                         java.lang.String name)

Reads the value of a sub-property and initializes that sub-property on the passed object.

Parameters:

bean - the bean to add the property to

desc - a PropertyDescriptor for the sub-property we're parsing

node - the Element containing the property to add to the bean

name - the name of the property to set on the bean. E.g. if the name is "layer", we'll look for a "setLayer" bean method.

setSubProperty

public static void setSubProperty(java.lang.Object beanval,
                                  java.beans.PropertyDescriptor desc,
                                  java.lang.Object pval)
                           throws java.lang.Exception

Sets a sub-property on a bean-value object.

Parameters:

beanval - the bean-value object to operate on

desc - the PropertyDescriptor for the sub-property we're setting

pval - the actual value for the sub-property we're setting

Throws:

java.lang.Exception

getPropNames

public static java.util.HashMap getPropNames(java.lang.Object value)

Returns a list of the sub-properties that this value possesses.

Parameters:

value - the value object of the BeanProperty we're parsing

Returns:

a HashMap containing descriptors for all settable properties for the value, keyed under their names.

getBeanvalInfo

public static java.beans.BeanInfo getBeanvalInfo(java.lang.Object value)
                                          throws java.beans.IntrospectionException

Gets a BeanInfo object that will stop looking when it reaches the top of the wyvern class heirarchy.

Parameters:

value - the value object of the BeanProperty we're parsing

Returns:

a BeanInfo containing information about the class

Throws:

java.beans.IntrospectionException