org.jboss.mq.xml
Class XElement

java.lang.Object
  org.jboss.mq.xml.XElement

public class XElement

extends java.lang.Object

XElement provides an interface to an XML element. An XElement represents an XML element which contains:

• Name (required)
• Attributes (optional)
• character data (optional)
• other elements (optional)

It is important to understand the diffrence between an "field" XElement and a non "field" XElement. If an XElement does not contain any sub elements, it is considered a "field" XElement. The getField(String) and getValue() functions will throw an XElementException if they are used on non "attribute" objects. This give you a little bit type checking (You'll get an exception if you try to access the character data of an element that has sub elements).

If XElement is not an field, then it contains other XElements and optionaly some text. The text data can be accessed with the getText() method and the sub elements with the iterator() or with getElementXXX() fuctions. Since XML and thus XElements provide a tree type data structure, traversing the tree to access leaf data can be cumbersom if you have a 'deep' tree. For example, you may have to do: element.getElement("tree").getElement("branch").getElement("leaf") access a XElement 3 levels deep in the tree. To access deep elements easier, XElements lets you use 'reletive' names to access deep elements. Using reletive names, you could access the same element in previous example doing: element.getElement("tree/branch/leaf") When using relative names, keep in mind that "." will get the current XElement, and ".." will get parent XElement. Very similar to how URLs work.

XElement

public XElement(java.lang.String objectName)

Constructs an empty object.

Parameters:

objectName - the tag or element name that this object represents.

XElement

public XElement(java.lang.String objectName,
                org.xml.sax.Attributes atts)

Constructs an XElement with it's parent and metatags set.

Parameters:

objectName - the tag or element name that this object represents.

atts - Description of Parameter

setAttribute

public void setAttribute(java.lang.String key,
                         java.lang.String value)

Sets/Adds a metatag value Only metatags whose value is not empty will display when the toString() methods is called.

Parameters:

key - the name of the metatag

value - the value to set the metatag to.

setName

public void setName(java.lang.String newName)

Sets the object name

Parameters:

newName -

setValue

public void setValue(java.lang.String value)
              throws XElementException (src) 

Gets the character data that was within this object. This fuction can only be used on objects that are attributes.

Parameters:

value - The new Value value

Throws:

XElementException (src) - if the object was not an attribute object

setField

public void setField(java.lang.String key,
                     java.lang.String value)
              throws XElementException (src) 

Sets/Adds a attribute

Parameters:

key - the name of the attribute element

value - the value to set the attribute to.

Throws:

XElementException (src) - Description of Exception

getAttribute

public java.lang.String getAttribute(java.lang.String key)

Returns the value of a meta data value.

Parameters:

key - Description of Parameter

Returns:

The Attribute value

getName

public java.lang.String getName()

Returns the element name (tag name) of this XElement

Returns:

The Name value

getParent

public XElement (src)  getParent()

Get the parent of this object, or the object the contains this one.

Returns:

The Parent value

getText

public java.lang.String getText()

Gets the TRIMMED character data that was within this object. This differs from getValue() in that:

• this fuction will work on attribute and non attribute XElements
• it will trim both ends of the character data before returning it.

Returns:

The Text value

getValue

public java.lang.String getValue()
                          throws XElementException (src) 

Gets the character data that was within this object. This fuction can only be used on objects that are attributes.

Returns:

The Value value

Throws:

XElementException (src) - if the object was not an attribute object

getElement

public XElement (src)  getElement(java.lang.String relativeName)
                    throws XElementException (src) 

Returns the first object contained in this object named relativeName.

Parameters:

relativeName - The name of the object to find

Returns:

The Element value

Throws:

XElementException (src) - if the object could not be found.

getField

public java.lang.String getField(java.lang.String objectName)
                          throws XElementException (src) 

Gets the value of a contained attribute object.

Parameters:

objectName - The name of the attribute object.

Returns:

The Field value

Throws:

XElementException (src) - if the object does not exist or if its not an attribute object.

isField

public boolean isField()

Returns true if the object is an attribute object. An object is an attribute object if it does not contain any other objects.

Returns:

The Field value

getElementsNamed

public java.util.Enumeration getElementsNamed(java.lang.String relativeName)

Returns all the contained objects with the specified name.

Parameters:

relativeName - The name of the objects

Returns:

The ElementsNamed value

add

public void add(java.lang.String data)

Adds and appends string data to the objects text.

Parameters:

data - Description of Parameter

toString

public java.lang.String toString()

Serializes this object into a string.

Returns:

Description of the Returned Value

addElement

public void addElement(XElement (src)  subObject)

Adds an XElement to the set of XElements that are contained by this object.

Parameters:

subObject -

addField

public void addField(java.lang.String key,
                     java.lang.String value)

Adds an XElement to the set of XElements that are contained by this object.

Parameters:

key - The feature to be added to the Field attribute

value - The feature to be added to the Field attribute

containsElement

public boolean containsElement(java.lang.String objectName)

Tests to see if this object contains the specified object.

Parameters:

objectName - The name of the object.

Returns:

Description of the Returned Value

containsField

public boolean containsField(java.lang.String objectName)

Tests to see if this object contains the specified attribute object.

Parameters:

objectName - The name of the attribute object.

Returns:

Description of the Returned Value

toString

public java.lang.String toString(int nestingLevel,
                                 boolean indent)

Serializes this object into a string.

Parameters:

nestingLevel - how many tabs to prepend to output

indent - Description of Parameter

Returns:

Description of the Returned Value

toXML

public java.lang.String toXML(boolean indent)

Serializes this object into a XML document String.

Parameters:

indent - Description of Parameter

Returns:

Description of the Returned Value

removeFromParent

public void removeFromParent()
                      throws XElementException (src) 

Removes this XElement from the parent.

Throws:

XElementException (src) - if the object did not have a parent

elements

public java.util.Enumeration elements()

Returns:

Description of the Returned Value

createFrom

public static XElement (src)  createFrom(java.io.InputStream is)
                           throws XElementException (src) ,
                                  java.io.IOException

Constructs an empty object.

Parameters:

is - Description of Parameter

Returns:

Description of the Returned Value

Throws:

XElementException (src) - Description of Exception

java.io.IOException - Description of Exception

createFrom

public static XElement (src)  createFrom(java.net.URL url)
                           throws XElementException (src) ,
                                  java.io.IOException

Constructs an empty object.

Parameters:

url - Description of Parameter

Returns:

Description of the Returned Value

Throws:

XElementException (src) - Description of Exception

java.io.IOException - Description of Exception

getOptionalField

public java.lang.String getOptionalField(java.lang.String field)
                                  throws XElementException (src) 

Throws:

XElementException (src)

setOptionalField

public void setOptionalField(java.lang.String field,
                             java.lang.String value)
                      throws XElementException (src) 

Throws:

XElementException (src)