com.ibm.pvccommon.util
Class Database

java.lang.Object
  |
  +--java.util.Observable
        |
        +--com.ibm.pvccommon.util.Database
Direct Known Subclasses:
IniDatabase

public abstract class Database
extends java.util.Observable

Provides an abstract database to contain information about a Server, a Server Group, a User, or a User Group. In Orion terms, there is one database per resource context.

A Databased is organized into a set of DatabaseSections that can be loaded, saved, and accessed independently. DatabaseSection.

A Database can be implemented in a number of ways, including one that uses a set of local files for persistent storage and another that uses an Orion resource context in the Network Registry as persistent storage.

An explicit save or saveSection operation must be invoked to cause the database to write updates to persistent store.


Inner Class Summary
static class Database.ResourceType
          Indicator of resource type, and defined values.
 
Field Summary
static java.lang.String COPYRIGHT
          IBM copyright information.
static Database.ResourceType DEFAULT
           
protected static java.lang.String EMPTY_STRING
           
protected static java.lang.String ORIGINAL_VALUE
           
protected  java.lang.String purpose
          purpose is a string that is used in the construction of directories or property names to distinguish information from one application from the information stored by another application using the Database classes.
protected  java.util.Hashtable sections
           
static Database.ResourceType SERVER
           
static Database.ResourceType SERVER_GROUP
           
protected static java.lang.String SUBSET_ASSOCIATION
           
protected  java.util.Hashtable subsetList
          subsetList is a collection of vectors, each associated with a subset.
protected static java.lang.String[] typeNames
           
static Database.ResourceType USER
           
static Database.ResourceType USER_GROUP
           
 
Constructor Summary
protected Database(java.lang.String name)
          Opens the database without loading it for the default resource type and read/write access.
protected Database(java.lang.String name, boolean readOnly, Database.ResourceType type)
          Opens the database without loading it in read only mode for the given resource type.
protected Database(java.lang.String name, Database.ResourceType type)
          Opens the database without loading it for the given resource type and read/write access.
 
Method Summary
 void backoutChanges()
          This method allows an applet that configures the database to be written in two separate parts: the View that presents the values of the Database to the user in a visible GUI that allows the user to change them, and the Controller that creates the database, loads it from persistent storage, and stores it back to persistent storage.
 void commitChanges()
          This method allows an applet that configures the database to be written in two separate parts: the View that presents the values of the Database to the user in a visible GUI that allows the user to change them, and the Controller that creates the database, loads it from persistent storage, and stores it back to persistent storage.
 DatabaseSection createSection(java.lang.String sectionName, java.lang.String subsetName)
          Create a new DatabaseSection in the database, after checking to make sure that there is not already a section with the same name.
abstract  void deleteDatabase()
          Delete the database
 boolean exists(java.lang.String sectionName)
          Determines if the named DatabaseSection exists in the Database.
abstract  java.lang.String getDecodedName(java.lang.String name)
          Get the decoded name for the given encoded name
abstract  java.lang.String getEncodedName(java.lang.String name)
          Get the encoded name for the given key
protected  DatabaseSection getLoadedSection(java.lang.String sectionName)
          Get a section from the database.
 java.lang.String getName()
          Return a string giving gthe database name
 DatabaseSection getSection(java.lang.String sectionName)
          Get a section from the database.
 java.util.Enumeration getSections()
          Get an enumeration of all of the DatabaseSections of the database, including those that have been newly created, those that have been loaded from persistent storage, and those that have been removed from the active database.
 java.util.Enumeration getSections(java.lang.String subsetName)
          Get an enumeration of all of the DatabaseSections of the database that belong to a specific, named subset, including those that have been newly created, those that have been loaded from persistent storage, and those that have been removed from the active database.
 java.util.Enumeration getSubsetNames()
          Get an enumeration of all of the subsets of related sections that exist in the Database.
 int getType()
          Return the database type
 java.lang.String getTypeName()
          Return the database type name
 boolean getWhetherChangesPersist()
          Answers to an Observer whether the changes made in the Database should be made persistent or not.
abstract  boolean hasEncodedCharacters(java.lang.String name)
          Answer whether the given name has encoded characters or not
 boolean isCoalesced(DatabaseSection section, java.lang.String key)
          Answer whether the value for the given key is coalesced.
abstract  void loadDatabase()
          Load the database from persistent storage.
abstract  void loadDatabase(java.lang.String subsetName)
          Load the database from persistent storage given the subset name.
abstract  DatabaseSection loadSection(java.lang.String propertyName)
          Load the section given the section name.
 void prepareForInitialLoad()
          Prepare for the initial load of a database, when it is first being loaded.
 void removeSection(java.lang.String name)
          Remove a section from the active database.
 void saveDatabase()
          Save entire database.
abstract  void saveDatabase(java.lang.String subsetName)
          Save the database given the subsetName.
 void saveSection(DatabaseSection section)
          Save a section, specified by reference to a specific section object.
abstract  void saveSection(java.lang.String sectionName)
          Save the given section specified by section name.
 void setPurpose(java.lang.String dbPurpose)
          Set the purpose of this Database.
 int size()
          Return the database size, which is the number of sections
 java.lang.String toString()
          Return a string that can be used in debugging to represent the current state of the Database.
 
Methods inherited from class java.util.Observable
addObserver, clearChanged, countObservers, deleteObserver, deleteObservers, hasChanged, notifyObservers, notifyObservers, setChanged
 
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
IBM copyright information.

typeNames

protected static final java.lang.String[] typeNames

DEFAULT

public static final Database.ResourceType DEFAULT

USER

public static final Database.ResourceType USER

USER_GROUP

public static final Database.ResourceType USER_GROUP

SERVER

public static final Database.ResourceType SERVER

SERVER_GROUP

public static final Database.ResourceType SERVER_GROUP

SUBSET_ASSOCIATION

protected static final java.lang.String SUBSET_ASSOCIATION

EMPTY_STRING

protected static final java.lang.String EMPTY_STRING

ORIGINAL_VALUE

protected static final java.lang.String ORIGINAL_VALUE

purpose

protected java.lang.String purpose
purpose is a string that is used in the construction of directories or property names to distinguish information from one application from the information stored by another application using the Database classes. Thus, the default purpose is "transform" for the TransProxy. The Pervader project can use this field to interject an alternative string into the property or directory names. See specific Database implementations for information about how this value is specifically used.

sections

protected java.util.Hashtable sections

subsetList

protected java.util.Hashtable subsetList
subsetList is a collection of vectors, each associated with a subset. The subset name is the key for the hash table. Each vector includes references to the set of DatabaseSections that are in that database subset. The set of sections that are not in a subset are included in this data structure in the Vector retrieved with the key that is the empty string.
Constructor Detail

Database

protected Database(java.lang.String name)
Opens the database without loading it for the default resource type and read/write access.
Parameters:
name - Descriptiove name to be associated with the database.

Database

protected Database(java.lang.String name,
                   Database.ResourceType type)
Opens the database without loading it for the given resource type and read/write access.
Parameters:
name - Descriptiove name to be associated with the database.
type - An identifier of the resource type

Database

protected Database(java.lang.String name,
                   boolean readOnly,
                   Database.ResourceType type)
Opens the database without loading it in read only mode for the given resource type.
Parameters:
name - Descriptiove name to be associated with the database.
readOnly - true if read-only access (any updates are transient). false for read-write access.
type - An identifier of the Resource type
Method Detail

exists

public boolean exists(java.lang.String sectionName)
Determines if the named DatabaseSection exists in the Database.
Parameters:
sectionName - The DatabaseSection name
Returns:
true if section exists in the database; false if doesn't exist in the database.

setPurpose

public void setPurpose(java.lang.String dbPurpose)
Set the purpose of this Database. This is used in creating a unique name
Parameters:
dbPurpose - A simple string (usually a word) giving a purpose (like "pdadeploy")

isCoalesced

public boolean isCoalesced(DatabaseSection section,
                           java.lang.String key)
Answer whether the value for the given key is coalesced. Defaults to false, but specific database types that support coalescing can respond differently.
Parameters:
section - the database section
key - preference name
Returns:
true if coalesced, false otherwise

getSections

public java.util.Enumeration getSections()
Get an enumeration of all of the DatabaseSections of the database, including those that have been newly created, those that have been loaded from persistent storage, and those that have been removed from the active database.
Returns:
The enumeration of the DatabaseSections

getSections

public java.util.Enumeration getSections(java.lang.String subsetName)
Get an enumeration of all of the DatabaseSections of the database that belong to a specific, named subset, including those that have been newly created, those that have been loaded from persistent storage, and those that have been removed from the active database.

Generally a database subset consists of a collection of DatabaseSections that serve a particular purpose, such as all the DatabaseSections that individually define the characteristics of a particular kind of plugin. This allows the application to request all the sections for a particular purpose without having to iterate through all the sections to discover which are relevant.

Parameters:
The - name of the subset whose sections are being requested
Returns:
The enumeration of the DatabaseSections

getSubsetNames

public java.util.Enumeration getSubsetNames()
Get an enumeration of all of the subsets of related sections that exist in the Database.
Returns:
The enumeration of the subset names

getSection

public DatabaseSection getSection(java.lang.String sectionName)
Get a section from the database. Only DatabaseSections that have not been removed in previous actions can be returned. Loads section from persistent storage if not already loaded
Parameters:
sectionName - The name of the section.
Returns:
The section or null if doesn't exist.

getLoadedSection

protected DatabaseSection getLoadedSection(java.lang.String sectionName)
Get a section from the database. Does not load from persistent storage
Parameters:
sectionName - The name of the section.
Returns:
The section or null if doesn't exist.

createSection

public DatabaseSection createSection(java.lang.String sectionName,
                                     java.lang.String subsetName)
Create a new DatabaseSection in the database, after checking to make sure that there is not already a section with the same name.
Parameters:
sectionName - The name of the section.
subsetName; - empty string if section is not in a subset
Returns:
The section.

removeSection

public void removeSection(java.lang.String name)
Remove a section from the active database. Specific database implementations should override this method to remove the section from persistent storage, but call this method in the superclass to remove the section from active use.
Parameters:
name - The name of the section.

loadDatabase

public abstract void loadDatabase()
Load the database from persistent storage.

loadDatabase

public abstract void loadDatabase(java.lang.String subsetName)
Load the database from persistent storage given the subset name.
Parameters:
subsetName - The name of the subset.

loadSection

public abstract DatabaseSection loadSection(java.lang.String propertyName)
Load the section given the section name.
Parameters:
propertyName - The name of the section to load
Returns:
The section.

saveDatabase

public void saveDatabase()
Save entire database. First the subsets and then the rest of the sections that are not associated with subsets (are held in the subset with the empty string for a name).

saveSection

public void saveSection(DatabaseSection section)
Save a section, specified by reference to a specific section object.
Parameters:
section - -- reference to section to be saved

saveSection

public abstract void saveSection(java.lang.String sectionName)
Save the given section specified by section name.
Parameters:
sectionName - The name of the section to save

saveDatabase

public abstract void saveDatabase(java.lang.String subsetName)
Save the database given the subsetName.
Parameters:
subsetName - the subset name

deleteDatabase

public abstract void deleteDatabase()
                             throws MissingRequiredResourceException
Delete the database
Throws:
MissingRequiredResourceException -  

getEncodedName

public abstract java.lang.String getEncodedName(java.lang.String name)
Get the encoded name for the given key
Parameters:
name - the name to get encoded name for
Returns:
the encoded value

getDecodedName

public abstract java.lang.String getDecodedName(java.lang.String name)
Get the decoded name for the given encoded name
Parameters:
name - the encoded name to get the decoded value of
Returns:
the decoded value

hasEncodedCharacters

public abstract boolean hasEncodedCharacters(java.lang.String name)
Answer whether the given name has encoded characters or not
Parameters:
name - the name to check
Returns:
true if has encoded characters, false otherwise

prepareForInitialLoad

public void prepareForInitialLoad()
Prepare for the initial load of a database, when it is first being loaded. Subsequent loads of the database may not invoke this method, if the database user wants the effects of loadDatabase() operations to be cumulative.

This method does the clearing associated with all implementations of the Database class.


toString

public java.lang.String toString()
Return a string that can be used in debugging to represent the current state of the Database.
Overrides:
toString in class java.lang.Object
Returns:
Display string for debugging purposes

getName

public java.lang.String getName()
Return a string giving gthe database name
Returns:
The name

getType

public int getType()
Return the database type
Returns:
The type value

getTypeName

public java.lang.String getTypeName()
Return the database type name
Returns:
The type name

size

public int size()
Return the database size, which is the number of sections
Returns:
The number of sections

commitChanges

public void commitChanges()
This method allows an applet that configures the database to be written in two separate parts: the View that presents the values of the Database to the user in a visible GUI that allows the user to change them, and the Controller that creates the database, loads it from persistent storage, and stores it back to persistent storage.

For example, a GUI could call this method when the user pushes the OK button, indicating a wish to have changes stored persistently. The controller can be implemented as an Observer on the Database. When its update() method is called as a result of this method being called by the GUI, it causes the database to be stored to persistent storage.


backoutChanges

public void backoutChanges()
This method allows an applet that configures the database to be written in two separate parts: the View that presents the values of the Database to the user in a visible GUI that allows the user to change them, and the Controller that creates the database, loads it from persistent storage, and stores it back to persistent storage.

For example, a GUI could call this method when the user pushes the CANCEL button, indicating a wish to have no changes stored persistently. The controller can be implemented as an Observer on the Database. When its update() method is called, it causes the database to be reload from persistent storage before it reinvokes the GUI.


getWhetherChangesPersist

public boolean getWhetherChangesPersist()
Answers to an Observer whether the changes made in the Database should be made persistent or not.
Returns:
Tells whether changes are persistent or not