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

java.lang.Object
  extended by java.util.Hashtable
      extended by net.rim.device.api.io.parser.ObjectPathHashtableBase
          extended by 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





Copyright 1999-2010 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Copyright 1993-2003 Sun Microsystems, Inc. 901 San Antonio Road, Palo Alto, California, 94303, U.S.A. All Rights Reserved.
Copyright 2002-2003 Nokia Corporation All Rights Reserved.
Java is a trademark of Sun Microsystems, Inc.