com.ibm.wbi.persistent
Class Section

java.lang.Object
  |
  +--com.ibm.wbi.persistent.Section

public class Section
extends java.lang.Object

Persistent store mechanism. A Section is the unified interface for persistent storage in WBI. A Section contains arbitrary key/value pairs accessed by the getValue(...) methods, and other named subsections accessed by the getSection(...) methods. In other words, the Section persistence mechanism is a hierarchical database much like a filesystem. It can be mapped onto different backends including a filesystem and LDAP.


Field Summary
static java.lang.String COPYRIGHT
           
 
Method Summary
 Section createSection(java.lang.String pathstr)
          Creates the named Section and returns it.
 Section createSection(java.lang.String pathstr, java.lang.ClassLoader loader)
           
 void disposeSection(java.lang.String pathstr)
          The Section system maintains references to Sections that have already been opened to ensure that when a section is asked for by name twice, the same Section is returned each time.
 boolean getBooleanValue(java.lang.String key)
           
 boolean getBooleanValue(java.lang.String key, boolean def)
           
 byte getByteValue(java.lang.String key)
           
 byte getByteValue(java.lang.String key, byte def)
           
 char getCharacterValue(java.lang.String key)
           
 char getCharacterValue(java.lang.String key, char def)
           
 double getDoubleValue(java.lang.String key)
           
 double getDoubleValue(java.lang.String key, double def)
           
 float getFloatValue(java.lang.String key)
           
 float getFloatValue(java.lang.String key, float def)
           
 int getIntegerValue(java.lang.String key)
           
 int getIntegerValue(java.lang.String key, int def)
           
 long getLongValue(java.lang.String key)
           
 long getLongValue(java.lang.String key, long def)
           
 java.lang.String getName()
          Get the name, or last component of the path, for this section.
 java.io.Serializable getObjectValue(java.lang.String key)
           
 java.io.Serializable getObjectValue(java.lang.String key, java.io.Serializable def)
           
 Section getParentSection()
          Get the parent of this section.
 java.lang.String getPath()
          Get the fully-qualified path of this section.
 Section getSection(java.lang.String pathstr)
          Get the Section specified by the path.
 Section getSection(java.lang.String pathstr, java.lang.ClassLoader loader)
           
 short getShortValue(java.lang.String key)
           
 short getShortValue(java.lang.String key, short def)
           
 java.lang.String getValue(java.lang.String key)
          Get the value associated with the given key.
 java.lang.String getValue(java.lang.String key, java.lang.String def)
          Get the value associated with this key or the default.
 boolean isContainer()
           
 boolean isEmpty()
          Return whether or not the section is empty (no keys or children).
 boolean keyExists(java.lang.String key)
          Tell whether a key exists in this section
 java.util.Enumeration keys()
          Get the keys associated with this section.
 int keysSize()
          Return the number of keys associated with this section
static void main(java.lang.String[] args)
          Internal-use testing suite
 void removeKey(java.lang.String key)
          Remove a key from this section
 void removeSection(java.lang.String pathstr)
          Removes the named section.
 boolean revert()
          Revert the Section to the last saved state.
 void save()
          Save the current state.
 void save(boolean force)
          Save the current state.
 boolean saveWithStatus()
          Save the current state.
 boolean saveWithStatus(boolean force)
          Save the current state.
 boolean sectionExists(java.lang.String pathstr)
          Tell whether the named section exists (not recursive)
 java.util.Enumeration sections()
          Get an enumeration of immediately contained sections.
 java.util.Enumeration sections(java.lang.ClassLoader loader)
           
 java.util.Enumeration sectionsRecursively()
          Get an enumeration of all contained sections, recursively.
 java.util.Enumeration sectionsRecursively(java.lang.ClassLoader loader)
           
 int sectionsSize()
          Return the number of sections contained in this section
 void setAutoSave(boolean enabled)
          Enable/disable autosave.
 void setDefaultClassLoader(java.lang.ClassLoader defloader)
           
 void setValue(java.lang.String key, boolean value)
           
 void setValue(java.lang.String key, byte value)
           
 void setValue(java.lang.String key, char value)
           
 void setValue(java.lang.String key, double value)
           
 void setValue(java.lang.String key, float value)
           
 void setValue(java.lang.String key, int value)
           
 void setValue(java.lang.String key, long value)
           
 void setValue(java.lang.String key, java.io.Serializable value)
          Set the value associated with the given key.
 void setValue(java.lang.String key, short value)
           
 java.lang.String toString()
          Give a string representation of this section.
 java.util.Enumeration values()
          Get the values associated with this section.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

COPYRIGHT

public static final java.lang.String COPYRIGHT
Method Detail

setDefaultClassLoader

public void setDefaultClassLoader(java.lang.ClassLoader defloader)

setAutoSave

public void setAutoSave(boolean enabled)
Enable/disable autosave. When autosave is enabled save() is called internally each time setValue() or removeKey() is called. Note that performance might be degraded when this option is available (precisely b/c save() is called more often) and revert() will not work. This option is disabled by default.
Parameters:
enabled - enable this feature

keysSize

public int keysSize()
Return the number of keys associated with this section
Returns:
number of keys

sectionsSize

public int sectionsSize()
Return the number of sections contained in this section
Returns:
number of sections

isEmpty

public boolean isEmpty()
Return whether or not the section is empty (no keys or children).
Returns:
true if empty

revert

public boolean revert()
Revert the Section to the last saved state. Only changes in key/value pairs are reverted. Adding/removing child sections is not.
Returns:
success of operation

removeSection

public void removeSection(java.lang.String pathstr)
Removes the named section.
Parameters:
pathstr - name of section to remove, e.g., "a/b/c"
See Also:
getSection(String)

disposeSection

public void disposeSection(java.lang.String pathstr)
The Section system maintains references to Sections that have already been opened to ensure that when a section is asked for by name twice, the same Section is returned each time. The problem with this approach is that it might appear to leak, since references are held to Sections indefinitely once opened. This method removes the internal reference to the named Section, allowing it (and its children) to be garbage collected. This method reverts the internal tree to the state before that section was initially requested; unsaved data is lost. The programmer needs to be careful that a reference to the disposed section is not held elsewhere, otherwise it is possible for multiple instances of sections representing the same data to come into existence.
Parameters:
pathstr - The path name for the section
See Also:
getSection(String)

createSection

public Section createSection(java.lang.String pathstr)
Creates the named Section and returns it. If the Section already exists, then it just returns it. It is safe to use this method if you are unsure of whether the Section already exists or not rather then checking for the existence of the Section first.
Parameters:
pathstr - path of the newly created Section
Returns:
the new Section, or null if failure
See Also:
getSection(String)

createSection

public Section createSection(java.lang.String pathstr,
                             java.lang.ClassLoader loader)

getSection

public Section getSection(java.lang.String pathstr)
Get the Section specified by the path. The parsing of the path is similar to how "cd" in DOS/UNIX work. If the path begins with a "/" then it is "absolute", otherwise it is relative to the current Section. So "/a/b/c" called from any Section would return the same Section as "b/c" called from Section "/a" or "c" called from Section "/a/b". Likewise, "." and ".." are interpreted as the current Section and the parent Section, respectively.
Parameters:
pathstr - The path of the section to get
Returns:
the named Section, or null if it doesn't exist

getSection

public Section getSection(java.lang.String pathstr,
                          java.lang.ClassLoader loader)

getParentSection

public Section getParentSection()
Get the parent of this section. This is has the same effect as calling getSection("..").
Returns:
the parent of this Section.

sections

public java.util.Enumeration sections()
Get an enumeration of immediately contained sections. The order of the result is undefined. This method does not recurse down the tree.
Returns:
Enumeration of Sections (you'll need to cast)
See Also:
sectionsRecursively()

sections

public java.util.Enumeration sections(java.lang.ClassLoader loader)

sectionsRecursively

public java.util.Enumeration sectionsRecursively()
Get an enumeration of all contained sections, recursively. The order of the result is undefined. In general, to preserve the tree structure, you'll want to walk the tree using the sections() method.
Returns:
Enumeration of Sections (you'll need to cast)
See Also:
sections()

sectionsRecursively

public java.util.Enumeration sectionsRecursively(java.lang.ClassLoader loader)

sectionExists

public boolean sectionExists(java.lang.String pathstr)
Tell whether the named section exists (not recursive)
Parameters:
pathstr - The path to the tested Section
Returns:
whether it exists

save

public void save()
Save the current state. By default the force flag is disabled and save will only happen if the dirty flag has been set. The dirty flag is set whenever setValue() or removeKey() are called.
See Also:
save(boolean force)

saveWithStatus

public boolean saveWithStatus()
Save the current state. By default the force flag is disabled and save will only happen if the dirty flag has been set. The dirty flag is set whenever setValue() or removeKey() are called.
See Also:
saveWithStatus(boolean force)

save

public void save(boolean force)
Save the current state. Ignore any errors that are returned.
Parameters:
force - disregard the dirty flag; save always
See Also:
saveWithStatus()

saveWithStatus

public boolean saveWithStatus(boolean force)
Save the current state. A dirty flag is employed, which is set whenever setValue() or removeKey() are called. Since it is possible to save an object with nested values, the dirty flag might not be maintained correctly. In this case the force flag should be used. Typically save(), which sets the force flag to false, is appropriate.

If the save is successful, true is returned. Otherwise, false is returned.

Parameters:
force - disregard the dirty flag; save always
Returns:
true if save succeeds, false otherwise.
See Also:
save()

getPath

public java.lang.String getPath()
Get the fully-qualified path of this section. This string is guaranteed to be unique in this database.
Returns:
fully-qualified path

getName

public java.lang.String getName()
Get the name, or last component of the path, for this section. This string is not guaranteed to be unique. E.g., the section with path "/prefs/network/default" and the section with path "/prefs/device/default" will have the same name. If these strings need to be distinguished, then getPath() should be used.
Returns:
last component of path

toString

public java.lang.String toString()
Give a string representation of this section. Useful for debugging purposes
Overrides:
toString in class java.lang.Object
Returns:
the string representation

keys

public java.util.Enumeration keys()
Get the keys associated with this section. The order of the result is undefined.
Returns:
Enumertion of Strings

values

public java.util.Enumeration values()
Get the values associated with this section. The order of the result is undefined.
Returns:
Enumeration of Serializable (Object)

keyExists

public boolean keyExists(java.lang.String key)
Tell whether a key exists in this section
Parameters:
key - The key to test
Returns:
whether the key exists

removeKey

public void removeKey(java.lang.String key)
Remove a key from this section
Parameters:
key - The key to remove

getValue

public java.lang.String getValue(java.lang.String key)
Get the value associated with the given key. There is a method for each type of value that can be returned. Note that getValue() returns a String; to get an arbitrary Serializable Object, use getObjectValue().
Parameters:
key - Which key to get the value for
Returns:
The value associated with the key

getValue

public java.lang.String getValue(java.lang.String key,
                                 java.lang.String def)
Get the value associated with this key or the default. The default value is never added to the persistent store, it is soley for programmatic convenience.
Parameters:
key - Which key to get the value for
def - Default value if key does not exist
See Also:
getValue(String)

getObjectValue

public java.io.Serializable getObjectValue(java.lang.String key)
See Also:
getValue(String)

getObjectValue

public java.io.Serializable getObjectValue(java.lang.String key,
                                           java.io.Serializable def)
See Also:
getValue(String, String)

getIntegerValue

public int getIntegerValue(java.lang.String key)
See Also:
getValue(String)

getIntegerValue

public int getIntegerValue(java.lang.String key,
                           int def)
See Also:
getValue(String, String)

getShortValue

public short getShortValue(java.lang.String key)
See Also:
getValue(String)

getShortValue

public short getShortValue(java.lang.String key,
                           short def)
See Also:
getValue(String, String)

getLongValue

public long getLongValue(java.lang.String key)
See Also:
getValue(String)

getLongValue

public long getLongValue(java.lang.String key,
                         long def)
See Also:
getValue(String, String)

getDoubleValue

public double getDoubleValue(java.lang.String key)
See Also:
getValue(String)

getDoubleValue

public double getDoubleValue(java.lang.String key,
                             double def)
See Also:
getValue(String, String)

getFloatValue

public float getFloatValue(java.lang.String key)
See Also:
getValue(String)

getFloatValue

public float getFloatValue(java.lang.String key,
                           float def)
See Also:
getValue(String, String)

getBooleanValue

public boolean getBooleanValue(java.lang.String key)
See Also:
getValue(String)

getBooleanValue

public boolean getBooleanValue(java.lang.String key,
                               boolean def)
See Also:
getValue(String, String)

getCharacterValue

public char getCharacterValue(java.lang.String key)
See Also:
getValue(String)

getCharacterValue

public char getCharacterValue(java.lang.String key,
                              char def)
See Also:
getValue(String, String)

getByteValue

public byte getByteValue(java.lang.String key)
See Also:
getValue(String)

getByteValue

public byte getByteValue(java.lang.String key,
                         byte def)
See Also:
getValue(String, String)

setValue

public void setValue(java.lang.String key,
                     java.io.Serializable value)
Set the value associated with the given key. This method is overloaded for all java types which implement Serializable or are primitive (int, boolean, etc).
Parameters:
key - The key to bind the value to
value - The value to bind to the key

setValue

public void setValue(java.lang.String key,
                     short value)
See Also:
setValue(String, Serializable)

setValue

public void setValue(java.lang.String key,
                     int value)
See Also:
setValue(String, Serializable)

setValue

public void setValue(java.lang.String key,
                     long value)
See Also:
setValue(String, Serializable)

setValue

public void setValue(java.lang.String key,
                     float value)
See Also:
setValue(String, Serializable)

setValue

public void setValue(java.lang.String key,
                     double value)
See Also:
setValue(String, Serializable)

setValue

public void setValue(java.lang.String key,
                     boolean value)
See Also:
setValue(String, Serializable)

setValue

public void setValue(java.lang.String key,
                     char value)
See Also:
setValue(String, Serializable)

setValue

public void setValue(java.lang.String key,
                     byte value)
See Also:
setValue(String, Serializable)

isContainer

public boolean isContainer()

main

public static void main(java.lang.String[] args)
Internal-use testing suite