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