net.rim.device.api.io.parser.xml
Class XMLHashtable

java.lang.Object
  java.util.Hashtable
      net.rim.device.api.io.parser.ObjectPathHashtableBase
          net.rim.device.api.io.parser.xml.XMLHashtable

All Implemented Interfaces:

ObjectPathHashtable, Persistable

public class XMLHashtable
extends ObjectPathHashtableBase
implements Persistable

This class converts an XML document into a hashtable that maps a String onto one or more Strings.

A hashtable key consists of a '/'-separated list of element names. If includeNamespaces is set to true, an element's name will be prefixed by the current namespace. This allows the caller to disambiguate between elements from different namespaces that have the same name.

If includeExplicitPaths is set to true, then an element's name will be suffixed by a ':' and an integer. This allows the caller to disambiguate between several elements with the same name under the same node in the XML tree. To determine the number of elements with the same name present under the same node in the XML tree, call getNumKeys() with the key for the element.

Attributes for an element can be retrived from the hashtable by appending "/@" + attributeName to the element's key.

For example, consider the following simple XML document:

  <ANS:Colours window="main" xmlns:ANS="A">
      <BNS:ForegroundColour xmlns:BNS="B">
          Blue
      </BNS:ForegroundColour>
      <BackgroundColour>
          White
      </BackgroundColour>
  </ANS:Colours>
 

With includeNamespaces == false and includeExplicitPaths == false, the hashtable would contain:

Key	Value
"/Colours"	""
"/Colours/@window"	"main"
"/Colours/ForegroundColour"	"Blue"
"/Colours/BackgroundColour"	"White"

With includeNamespaces == false and includeExplicitPaths == true, the hashtable would contain:

Key	Value
"/Colours:0"	""
"/Colours:0/@window:0"	"main"
"/Colours:0/ForegroundColour:0"	"Blue"
"/Colours:0/BackgroundColour:0"	"White"

Additionally

getNumKeys() parameter	Return Value
"/Colours"	1
"/Colours:0/ForegroundColour"	1

With includeNamespaces == true and includeExplicitPaths == false, the hashtable would contain:

Key	Value
"/A:Colours"	""
"/A:Colours/@A:window"	"main"
"/A:Colours/B:ForegroundColour"	"Blue"
"/A:Colours/A:BackgroundColour"	"White"

With includeNamespaces == true and includeExplicitPaths == true, the hashtable would contain:

Key	Value
"/A:Colours:0"	""
"/A:Colours:0/@A:window:0"	"main"
"/A:Colours:0/B:ForegroundColour:0"	"Blue"
"/A:Colours:0/A:BackgroundColour:0"	"White"

Additionally

getNumKeys() parameter	Return Value
"/A:Colours"	1
"/A:Colours:0/B:ForegroundColour"	1

Another example:

  <A:Colours window="main" xmlns:A="A">
      <B:ForegroundColour xmlns:B="B">
          Blue
      </B:ForegroundColour>
      <BackgroundColour>
          White
      </BackgroundColour>
  </A:Colours>
  <A:Colours window="dialog" xmlns:A="A">
      <B:ForegroundColour xmlns:B="B">
          Red
      </B:ForegroundColour>
      <BackgroundColour>
          Black
      </BackgroundColour>
  </A:Colours>
 

With includeNamespaces == false and includeExplicitPaths == false, the hashtable would contain:

Key	Value
"/Colours"	"",""
"/Colours/@window"	"main","dialog"
"/Colours/ForegroundColour"	"Blue","Red"
"/Colours/BackgroundColour"	"White","Black"

With includeNamespaces == false and includeExplicitPaths == true, the hashtable would contain:

Key	Value
"/Colours:0"	""
"/Colours:0/@window:0"	"main"
"/Colours:0/ForegroundColour:0"	"Blue"
"/Colours:0/BackgroundColour:0"	"White"
"/Colours:1"	""
"/Colours:1/@window:0"	"dialog"
"/Colours:1/ForegroundColour:0"	"Red"
"/Colours:1/BackgroundColour:0"	"Black"

Additionally

getNumKeys() parameter	Return Value
"/Colours"	2
"/Colours:0/ForegroundColour"	1

With includeNamespaces == true and includeExplicitPaths == false, the hashtable would contain:

Key	Value
"/A:Colours"	"",""
"/A:Colours/@A:window"	"main","dialog"
"/A:Colours/B:ForegroundColour"	"Blue","Red"
"/A:Colours/A:BackgroundColour"	"White","Black"

With includeNamespaces == true and includeExplicitPaths == true, the hashtable would contain:

Key	Value
"/A:Colours:0"	""
"/A:Colours:0/@A:window:0"	"main"
"/A:Colours:0/B:ForegroundColour:0"	"Blue"
"/A:Colours:0/A:BackgroundColour:0"	"White"
"/A:Colours:1"	""
"/A:Colours:1/@A:window:0"	"dialog"
"/A:Colours:1/B:ForegroundColour:0"	"Red"
"/A:Colours:1/A:BackgroundColour:0"	"Black"

Additionally

getNumKeys() parameter	Return Value
"/A:Colours"	2
"/A:Colours:0/B:ForegroundColour"	1

Elements containing text and subelements are handled.

Since:

BlackBerry API 6.0.0

Constructor Summary

XMLHashtable(InputStream input, boolean includeNamespaces, boolean includeExplicitPath)
Creates a new XMLHashtable for a given SAXParser and InputStream.

XMLHashtable(InputStream input, boolean includeNamespaces, boolean includeExplicitPath, String path)
Creates a new XMLHashtable for a given SAXParser and InputStream.

XMLHashtable(Node node)
Builds an XMLHashtable from an XML Document Object Model (DOM).

Method Summary
boolean	includesExplicitPaths() Indicates whether indexes are included in the paths for this Hashtable.
boolean	includesNamespaces() Indicates whether namespaces are included in the keys for this Hashtable.

Methods inherited from class net.rim.device.api.io.parser.ObjectPathHashtableBase

addString, getBoolean, getBoolean, getBooleanArray, getBooleanAt, getBooleanAt, getByte, getByte, getByteArray, getByteAt, getByteAt, getDouble, getDouble, getDoubleArray, getDoubleAt, getDoubleAt, getFloat, getFloat, getFloatArray, getFloatAt, getFloatAt, getInteger, getInteger, getInteger, getIntegerArray, getIntegerAt, getIntegerAt, getIntegerAt, getLong, getLong, getLongArray, getLongAt, getLongAt, getNumKeys, getNumValues, getShort, getShort, getShortArray, getShortAt, getShortAt, getString, getString, getStringArray, getStringAt, getStringAt

Methods inherited from class java.util.Hashtable

clear, contains, containsKey, elements, get, isEmpty, keys, put, rehash, remove, size, toString

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

XMLHashtable

public XMLHashtable(InputStream input,
                    boolean includeNamespaces,
                    boolean includeExplicitPath)
             throws SAXException,
                    IOException,
                    ParserConfigurationException

Creates a new XMLHashtable for a given SAXParser and InputStream.

Parameters:

parser - A SAX parser.

input - The XML input stream to parse.

includeNamespaces - Indicates whether the keys to the Hashtable should include namespace information to disambiguate element names.

includeExplicitPath - Indicates whether the keys to the Hashtable should include a number to disambiguate elements with the same name under the same branch in the XML tree.

Throws:

ParserConfigurationException - If there is a configuration issue that prevents the creation of the SAX Parser.

SAXException - If there is a problem creating the underlying SAX Parser.

IOException - If there is a problem reading the input from the InputStream.

Since:

BlackBerry API 6.0.0

XMLHashtable

public XMLHashtable(InputStream input,
                    boolean includeNamespaces,
                    boolean includeExplicitPath,
                    String path)
             throws SAXException,
                    IOException,
                    ParserConfigurationException

Creates a new XMLHashtable for a given SAXParser and InputStream.

Parameters:

input - The XML input stream to parse.

includeNamespaces - Indicates whether the keys to the Hashtable should include namespace information to disambiguate element names.

includeExplicitPath - Indicates whether the keys to the Hashtable should include a number to disambiguate elements with the same name under the same branch in the XML tree.

path - Instructs the XMLHashtable to include only elements in the Hashtable whose names begin with this prefix.

Throws:

ParserConfigurationException - If there is a configuration issue that prevents the creation of the SAX Parser.

SAXException - If there is a problem creating the underlying SAX Parser.

IOException - If there is a problem reading the input from the InputStream.

Since:

BlackBerry API 6.0.0

XMLHashtable

public XMLHashtable(Node node)

Builds an XMLHashtable from an XML Document Object Model (DOM).

Parameters:

node - The root node of the DOM.

Since:

BlackBerry API 6.0.0

Method Detail

includesNamespaces

public boolean includesNamespaces()

Indicates whether namespaces are included in the keys for this Hashtable.

Returns:

true if namespaces are included in the keys; otherwise false.

Since:

BlackBerry API 6.0.0

includesExplicitPaths

public boolean includesExplicitPaths()

Indicates whether indexes are included in the paths for this Hashtable.

Returns:

true if indexes are included in the paths; otherwise false.

Since:

BlackBerry API 6.0.0