Collaboration API Documentation

com.filenet.bso.api.util
Class BsoXMLUnmarshal

java.lang.Object
  |
  +--org.xml.sax.helpers.DefaultHandler
        |
        +--com.filenet.bso.api.util.BsoXMLUnmarshal
All Implemented Interfaces:
org.xml.sax.ContentHandler, org.xml.sax.DTDHandler, org.xml.sax.EntityResolver, org.xml.sax.ErrorHandler

public abstract class BsoXMLUnmarshal
extends org.xml.sax.helpers.DefaultHandler

The BsoXMLUnmarshal class supports the unmarshaling of XML content into Java classes. A Java class that is generated via unmarshaling XML content must be subclassed from this class.

See Also:
BsoGenericSAXHandler, BsoXMLBinder, BsoXMLMarshal, BsoXMLWriter, BsoXPathDef

Field Summary
protected  BsoXMLUnmarshal parent
          A BsoXMLUnmarshal object that holds the parent element for the current XML element.
protected  java.util.Map xmlElements
          A Map object that contains the elements and attributes extracted from XML content.
protected  BsoXPathDef xPathDef
          A BsoXPathDef object that holds the XPath definitions, which specify the XML elements to be unmarshaled and the classes that are created for the various elements in the XML.
 
Constructor Summary
BsoXMLUnmarshal()
           
BsoXMLUnmarshal(BsoXMLUnmarshal parent)
           
 
Method Summary
static java.lang.String decode(java.lang.String value)
          Decodes an encoded text element string.
static java.lang.String encode(java.lang.String value)
          Encodes a text element string that contains prohibited characters.
 void endElement(java.lang.String uri, java.lang.String name, java.lang.String qName)
          Override this method to provide class specific handling of the SAX DefaultHandler class's endElement method.
protected  boolean getBooleanValue(java.lang.String key)
          Returns the value of a text element or an attribute as a boolean.
protected  java.util.List getCollection(java.lang.String key)
          Returns a collection of objects unmarshaled from a homogenous sequence of XML elements.
protected  java.lang.Integer getIntValue(java.lang.String key)
          Returns an integer value from the text element or attribute.
 java.lang.Object getObject(java.lang.String name)
          Returns a Java Object, generated from the XML element, based on the given name.
protected  java.lang.Object getObjectValue(java.lang.String key, java.lang.Class objectClass)
          Returns an Object value that has been stored in the map, and validates the class of that object against the class that is passed in via the objectClass parameter.
 java.lang.String getString(java.lang.String name)
          Returns the string value of the element or attribute based on the given name.
protected  java.lang.String getStringValue(java.lang.String key)
          Returns an attribute or the raw value of a specified text element.
protected  java.lang.String getTextElement(java.lang.String key)
          Retrieves the text element value, decodes it if necessary, and returns the value as a String.
 BsoXPathDef getXPathDef()
          Returns the BsoXPathDef object that provides unmarshaling information for this class.
static boolean isEncoded(java.lang.String value)
          Returns a boolean that indicates if the parameter string is encoded.
static boolean isEncodingRequired(java.lang.String value)
          Returns a boolean that indicates if the parameter string contains prohibited characters and must be encoded.
protected  void remove(java.lang.String name)
          Removes the specified element from the map.
 void setObject(java.lang.String name, java.lang.Object value)
          Sets the object value of an element or attribute based on the given name.
 void setString(java.lang.String name, java.lang.String value)
          Sets the string value of an element or attribute based on the given name.
protected  void setTextElement(java.lang.String key, java.lang.String value)
          Sets the value of the text element, encoding the value if necessary.
protected  void setValue(java.lang.String key, boolean value)
          Sets a text element's or attribute's value after converting the value from a boolean into its XML representation.
protected  void setValue(java.lang.String key, java.lang.Integer value)
          Sets an integer value for a text element or an attribute.
protected  void setValue(java.lang.String key, java.lang.Object value)
          Sets an Object value for a text element or an attribute.
protected  void setValue(java.lang.String key, java.lang.String value)
          Sets a String value for a text element or an attribute.
 void startElement(java.lang.String uri, java.lang.String name, java.lang.String qName, org.xml.sax.Attributes atts)
          Override this method to provide class specific handling of the SAX DefaultHandler class's startElement method.
protected  void unmarshallAttributes(org.xml.sax.Attributes atts)
          Unmarshals the specified attributes from the XML content and places the name and value of each attribute into the map.
 void validate()
          Validates the XML state.
protected  void validateThis(java.lang.String element, java.lang.String fieldName, java.lang.Object fieldValue)
          Validates that this text element or attribute has a value.
 
Methods inherited from class org.xml.sax.helpers.DefaultHandler
characters, endDocument, endPrefixMapping, error, fatalError, ignorableWhitespace, notationDecl, processingInstruction, resolveEntity, setDocumentLocator, skippedEntity, startDocument, startPrefixMapping, unparsedEntityDecl, warning
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

xmlElements

protected java.util.Map xmlElements
A Map object that contains the elements and attributes extracted from XML content.

parent

protected BsoXMLUnmarshal parent
A BsoXMLUnmarshal object that holds the parent element for the current XML element.

xPathDef

protected BsoXPathDef xPathDef
A BsoXPathDef object that holds the XPath definitions, which specify the XML elements to be unmarshaled and the classes that are created for the various elements in the XML.
Constructor Detail

BsoXMLUnmarshal

public BsoXMLUnmarshal()

BsoXMLUnmarshal

public BsoXMLUnmarshal(BsoXMLUnmarshal parent)
Method Detail

encode

public static java.lang.String encode(java.lang.String value)
Encodes a text element string that contains prohibited characters. The string will be enclosed in a CDATA section and if the string contains any CDATA suffix strings, those will be encoded.

Parameters:
value - A text element string to encode.

Returns:
The encoded string.

See Also:
isEncoded(String)

isEncoded

public static boolean isEncoded(java.lang.String value)
Returns a boolean that indicates if the parameter string is encoded.

Parameters:
value - A text element string.

Returns:
true if the string is encoded; otherwise, returns false.

isEncodingRequired

public static boolean isEncodingRequired(java.lang.String value)
Returns a boolean that indicates if the parameter string contains prohibited characters and must be encoded.

Parameters:
value - A text element string.

Returns:
true if the string must be encoded; otherwise, returns false.

decode

public static java.lang.String decode(java.lang.String value)
Decodes an encoded text element string.

Parameters:
value - A text element string to decode.

Returns:
A decoded string.

getXPathDef

public BsoXPathDef getXPathDef()
Returns the BsoXPathDef object that provides unmarshaling information for this class.

Returns:
A BsoXPathDef object.

validate

public void validate()
Validates the XML state. This method is called by the BsoGenericSAXHandler class during parsing of XML content to validate the XML state that was used to generate this class. The default implementation of this method does nothing. Derived classes should override this method to perform validation of the state of the object after unmarshaling.

getString

public java.lang.String getString(java.lang.String name)
Returns the string value of the element or attribute based on the given name.

Parameters:
name - A String containing the name of the element or attribute.

Returns:
A String containing the value of the element or attribute.

setString

public void setString(java.lang.String name,
                      java.lang.String value)
Sets the string value of an element or attribute based on the given name.

Parameters:
name - The name of the element or attribute.

value - The value of the element or attribute.

getObject

public java.lang.Object getObject(java.lang.String name)
Returns a Java Object, generated from the XML element, based on the given name.

Parameters:
name - The name of the XML-based Java object.

Returns:
An XML-based Java Object.

setObject

public void setObject(java.lang.String name,
                      java.lang.Object value)
Sets the object value of an element or attribute based on the given name.

Parameters:
name - The name of the XML-based object.

value - An XML-based Object.

startElement

public void startElement(java.lang.String uri,
                         java.lang.String name,
                         java.lang.String qName,
                         org.xml.sax.Attributes atts)
Override this method to provide class specific handling of the SAX DefaultHandler class's startElement method.

This method is called by the BsoGenericSAXHandler class.

Overrides:
startElement in class org.xml.sax.helpers.DefaultHandler
Parameters:
uri - The URI (Universal Resource Identifier) for the namespace of this element.

name - The element type name.

qName - The qualified name of this element or an empty string if qualified names are not present. A qualified name will include the prefix plus the localName.

atts - The specified or default attributes.

endElement

public void endElement(java.lang.String uri,
                       java.lang.String name,
                       java.lang.String qName)
                throws org.xml.sax.SAXException
Override this method to provide class specific handling of the SAX DefaultHandler class's endElement method.

This method is called by the BsoGenericSAXHandler class.

Overrides:
endElement in class org.xml.sax.helpers.DefaultHandler
Parameters:
uri - The URI (Universal Resource Identifier) for the namespace of this element.

name - The element type name.

qName - The qualified name of this element or an empty string if qualified names are not present. A qualified name will include the prefix plus the localName.

Throws:
org.xml.sax.SAXException - Any SAXException.

remove

protected void remove(java.lang.String name)
Removes the specified element from the map.

Parameters:
name - A String containing the name of the element to remove from the map.

unmarshallAttributes

protected void unmarshallAttributes(org.xml.sax.Attributes atts)
Unmarshals the specified attributes from the XML content and places the name and value of each attribute into the map.

Parameters:
atts - A collection of attributes to be unmarshaled.

getTextElement

protected java.lang.String getTextElement(java.lang.String key)
Retrieves the text element value, decodes it if necessary, and returns the value as a String.

Parameters:
key - A String that contains the key for the text element to be retrieved.

Returns:
A String that represents the value of the text element.

setTextElement

protected void setTextElement(java.lang.String key,
                              java.lang.String value)
Sets the value of the text element, encoding the value if necessary.

Parameters:
key - A String that contains the key for the text element to be set.

value - A String that contains the value to be set for the specified text element.

getStringValue

protected java.lang.String getStringValue(java.lang.String key)
Returns an attribute or the raw value of a specified text element. This method does not perform any decoding of the XML.

Parameters:
key - A String that contains the name of the text element or attribute.

Returns:
A String that represents the value of the text element or attribute.

getBooleanValue

protected boolean getBooleanValue(java.lang.String key)
Returns the value of a text element or an attribute as a boolean. This method evaluates the value for "true" or "1", or "false" or "0", converts the value to a boolean, and returns it. If the value is not one of the four above, this method presents a validation error.

Parameters:
key - A String that contains the name of the text element or attribute.

Returns:
true if the value of the text element or attribute is "true" or "1"; returns false if the value is "false" or "0".

setValue

protected void setValue(java.lang.String key,
                        boolean value)
Sets a text element's or attribute's value after converting the value from a boolean into its XML representation. For example, an input value of true is converted to "true".

Parameters:
key - A String that contains the name of the text element or attribute.

value - true or false.

setValue

protected void setValue(java.lang.String key,
                        java.lang.String value)
Sets a String value for a text element or an attribute. This method performs no encoding on the input value.

Parameters:
key - A String that contains the name of the text element or attribute.

value - A String that contains the value to be set.

setValue

protected void setValue(java.lang.String key,
                        java.lang.Integer value)
Sets an integer value for a text element or an attribute.

Parameters:
key - A String that contains the name of the text element or attribute.

value - The integer value to be set.

getIntValue

protected java.lang.Integer getIntValue(java.lang.String key)
Returns an integer value from the text element or attribute.

Parameters:
key - A String that contains the name of the text element or attribute.

Returns:
The text element's or attributes integer value, or returns -9999 (INT_VALUE_NOT_PRESENT) if the element or attribute has no assigned value.

getCollection

protected java.util.List getCollection(java.lang.String key)
Returns a collection of objects unmarshaled from a homogenous sequence of XML elements.

Parameters:
key - A String that contains the name used as a lookup into the map.

Returns:
A List of objects.

setValue

protected void setValue(java.lang.String key,
                        java.lang.Object value)
Sets an Object value for a text element or an attribute.

Parameters:
key - A String that contains the name of the text element or attribute.

value - The Object to which the value is set.

getObjectValue

protected java.lang.Object getObjectValue(java.lang.String key,
                                          java.lang.Class objectClass)
Returns an Object value that has been stored in the map, and validates the class of that object against the class that is passed in via the objectClass parameter. This method throws a BsoRuntimeException if the classes do not match.

Parameters:
key - A String that contains the name used as a lookup into the map.

objectClass - The Java Class to validate against.

Returns:
An object unmarshaled from an XML element; must be cast to the appropriate class.

validateThis

protected void validateThis(java.lang.String element,
                            java.lang.String fieldName,
                            java.lang.Object fieldValue)
Validates that this text element or attribute has a value. This method is typically called from within the validate() method in classes that derive from BsoXMLUnmarshal.

This method throws a BsoRuntimeException if the text element's or attribute's value is invalid is null.

Parameters:
element - A String containing the name of the text element or attribute.

fieldname - A String containing the field name to validate against.

fieldValue - A Java Object that represents the value of the field to validate.

Collaboration API Documentation

Copyright © 2002 - 2004 FileNet Corporation. All rights reserved.