edu.iris.Fissures.seed.container
Class SeedObjectContainer

java.lang.Object
  extended by edu.iris.Fissures.seed.container.SeedObjectContainer
All Implemented Interfaces:
ObjectContainer

public class SeedObjectContainer
extends java.lang.Object
implements ObjectContainer

Builder Container for Seed Blockettes.

Container that implements the interface of ObjectContainer and provides a facility for storing, retrieving, and cross-referencing blockettes. This container provides the implementer with the ability to ingest multiple SEED volumes and integrate the information in single location for merging and integration purposes. From this container, new SEED volumes (and even other formats) can be generated by creational classes, using it as a temporary database to retrieve all needed information. Note that this container is not meant for permanent storage, but the use of the disk persistence option allows you to re-load a previous container state from disk if so flagged.

Makes use of disk cache persistence in order to accomodate a large volume of Blockettes while minimizing memory consumption. Blockette's retrieved are placed in a Least Recently Used queue of some preconfigured size to accomodate repeated access of certain blockettes. All contents are persisted to disk as they are created and updated, and removed items are promtly eliminted. If so flagged, a new Container can access a previous session's persisted objects for immediate use.

Blockettes are stored in a parent/child heirarchy with regards to stations and channels, since their references to each other are positional in the SEED volume. Child blockettes are placed within a parent blockette to maintain this association. Stations are parents to Channels, and Channels are parents to response information. If this container has been flagged to indicate that a filter is being used by the Builder it is connected to, then the case of running into child blockettes with no parent, which had been filtered out, is treated as a normal condition, where the child blockettes are simply 'orphaned' and not stored in the container. If a filter is not being used, then this is considered an error condition, and an exception is thrown.

Version:
4/19/2006
Author:
Robert Casey, IRIS DMC

Constructor Summary
SeedObjectContainer()
          Default constructor that does not implement serialization
SeedObjectContainer(java.lang.String cacheDir)
          Contructor specifying a directory for disk cache persistence.
SeedObjectContainer(java.lang.String cacheDir, boolean loadPrevious)
          Constructor specifying a directory for disk cache persistence and bootstrap recall of previous session from disk if so flagged.
SeedObjectContainer(java.lang.String cacheDir, int capacity)
          Constructor specifying a directory for disk cache persistence.
SeedObjectContainer(java.lang.String cacheDir, int capacity, boolean loadPrevious)
          Constructor specifying a directory for disk cache persistence and bootstrap recall of previous session from disk if so flagged.
 
Method Summary
 void add(java.lang.Object addThis)
          Add a Blockette object to the container.
 void clear()
          Clear all contents in this container and start fresh.
 int findMatchingDictionary(java.lang.String blocketteString)
          Return an integer that represents the lookupId of the last added dictionary blockette to this container matching the provided blockette delimited string.
 void flushMemory()
          Flush all Blockettes from the memory cache.
 java.lang.Object get(int lookupId)
          Return blockette with the listed lookup ID.
 java.lang.String getCachePath()
          return the path to the base of the cache tree
static int getCategoryNumber(int lookupId)
          Return the category number encoded in the lookupId.
 Blockette getDictionaryBlockette(Blockette blk, int fieldNum)
          Get the referenced dictionary blockette.
 Blockette getDictionaryBlockette(Blockette blk, int fieldNum, int fieldIndex)
          Get the referenced dictionary blockette.
 Blockette getDictionaryBlockette(Blockette blk, int fieldNum, int fieldIndex, int listIndex)
          Get the referenced dictionary blockette.
 int getFiltered()
          Return the current filter rank value assigned to the container.
 java.lang.String getMetaEncoding(Blockette dataBlk)
          Return a string word representing the encoding type of data represented in the indicated data blockette.
 int getNewId(Blockette blk, boolean useRefNum)
          return an integer that represents a new lookupID number to be assigned to a new blockette, just before it is placed into the add() call.
 int getNewId(int category)
          DEPRECATED -- does not handle predictive numbering for dictionary blockettes Return a new lookupID number that is an incrementation of the previous one added to this container.
 java.lang.Object getNext()
          Get the next BlocketteDecorator in the established iterator, else return null.
 Blockette getTopParent(int lookupId)
          Get the top level parent Blockette for the indicated lookupID.
 int getVolumeNumber()
          Return the current volume number this container is set to
static int getVolumeNumberFromId(int lookupId)
          utility to determine the volume number based on the provided lookupId.
 java.lang.Object improvedGet(int lookupId)
          Deprecated.
 boolean improvedLocate(int lookupId)
          Deprecated.
 boolean isCaching()
          return true if this container is caching objects to disk persistence.
 boolean isUsingSerialization()
          pseudonym for isCaching() -- deprecated
 int iterate()
          Set up an iterator for all parent Blockettes.
 int iterate(int catNum)
          Set up an iterator for all parent Blockettes of a specific category number, all volumes.
 int iterate(int volNum, int catNum)
          Set up Blockette interation.
 int iterate(java.util.Vector stations, java.util.Vector channels, int catNum)
          Set up an iterator for *Parent* Blockettes matching stations and channels.
 boolean locate(int lookupId)
          Find the blockette with the listed lookup ID and set a handle to it in locateRegister.
protected  Blockette lookup(int lookupId)
          Find the blockette in the hashmap that matches the blockette ID.
 java.lang.Object remove(int lookupId)
          Delete the blockette object matching to lookupId from the container Return that object upon removal.
 void setFiltered(Blockette blk)
          Notify the container that the indicated blockette has been filtered.
 void setFiltered(int value)
          Tell the container to assume that the indicated filter rank has been filtered.
 void setParent(int lookupId)
          Establish parent/child heirarchy for given lookup ID in the rank lattice.
 void setVolumeNumber(int volNum)
          force the current volume number of this container to be the indicated value -- this number can get changed via the add() command, which polls for the current volume.
 java.lang.String toString()
          Identify ourselves through this method.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

SeedObjectContainer

public SeedObjectContainer()
Default constructor that does not implement serialization


SeedObjectContainer

public SeedObjectContainer(java.lang.String cacheDir,
                           int capacity,
                           boolean loadPrevious)
                    throws java.lang.Exception
Constructor specifying a directory for disk cache persistence and bootstrap recall of previous session from disk if so flagged.

Parameters:
cacheDir - the base directory where the disk cache will reside
capacity - the maximum number of items to be cached in memory at one time
loadPrevious - true if previous disk persistence cache should be referenced.
Throws:
java.lang.Exception

SeedObjectContainer

public SeedObjectContainer(java.lang.String cacheDir,
                           int capacity)
                    throws java.lang.Exception
Constructor specifying a directory for disk cache persistence. All previous disk persistence entries are deleted upon startup.

Parameters:
cacheDir - the base directory where the disk cache will reside
capacity - the maximum number of items to be cached in memory at one time
Throws:
java.lang.Exception

SeedObjectContainer

public SeedObjectContainer(java.lang.String cacheDir,
                           boolean loadPrevious)
                    throws java.lang.Exception
Constructor specifying a directory for disk cache persistence and bootstrap recall of previous session from disk if so flagged. Uses the default cache capacity value.

Parameters:
cacheDir - the base directory where the disk cache will reside
loadPrevious - true if previous disk persistence cache should be referenced.
Throws:
java.lang.Exception

SeedObjectContainer

public SeedObjectContainer(java.lang.String cacheDir)
                    throws java.lang.Exception
Contructor specifying a directory for disk cache persistence. Uses default capacity specified in this class.

Parameters:
cacheDir - the base directory where the disk cache will reside
Throws:
java.lang.Exception
Method Detail

toString

public java.lang.String toString()
Identify ourselves through this method.

Overrides:
toString in class java.lang.Object

getCachePath

public java.lang.String getCachePath()
return the path to the base of the cache tree

Returns:
base pathname of the cache

clear

public void clear()
           throws ContainerException
Clear all contents in this container and start fresh. Use with caution, since this erases all previous entries, including the disk cache at cacheDir.

Throws:
ContainerException

add

public void add(java.lang.Object addThis)
         throws java.lang.Exception
Add a Blockette object to the container.

Specified by:
add in interface ObjectContainer
Throws:
java.lang.Exception

getDictionaryBlockette

public Blockette getDictionaryBlockette(Blockette blk,
                                        int fieldNum)
                                 throws java.lang.Exception
Get the referenced dictionary blockette. Utility method to allow the specified blockette to pull back the dictionary blockette referenced by the indicated field number. Returns null if dictionary not found.

Throws:
java.lang.Exception

getDictionaryBlockette

public Blockette getDictionaryBlockette(Blockette blk,
                                        int fieldNum,
                                        int fieldIndex)
                                 throws java.lang.Exception
Get the referenced dictionary blockette. Utility method to allow the specified blockette to pull back the dictionary blockette referenced by the indicated field number and repeat group field index. Does not work for List fields, such as Blockette 60, which requires multiple returns. Use the listIndex variant of this method for that. Returns null if dictionary not found.

Throws:
java.lang.Exception

getDictionaryBlockette

public Blockette getDictionaryBlockette(Blockette blk,
                                        int fieldNum,
                                        int fieldIndex,
                                        int listIndex)
                                 throws java.lang.Exception
Get the referenced dictionary blockette. This variant allows access to dictionary references in List fields, such as in blockette 60. The listIndex parameter is the index number, starting at 0, of the desired reference in that field's list.

Throws:
java.lang.Exception

get

public java.lang.Object get(int lookupId)
                     throws ContainerException
Return blockette with the listed lookup ID. Return object is actually a CachedBlocketteDecorator from locate().

Specified by:
get in interface ObjectContainer
Throws:
ContainerException

remove

public java.lang.Object remove(int lookupId)
                        throws ContainerException
Delete the blockette object matching to lookupId from the container Return that object upon removal. Remove all mapping entries. Remove its children as well as itself from its parent.

Specified by:
remove in interface ObjectContainer
Throws:
ContainerException

locate

public boolean locate(int lookupId)
               throws ContainerException
Find the blockette with the listed lookup ID and set a handle to it in locateRegister. Return true if successful, false if not. Returned Blockette is actually a CachedBlocketteDecorator, serving as the SeedObjectContainer's 'external face' for Blockettes.

Specified by:
locate in interface ObjectContainer
Throws:
ContainerException

iterate

public int iterate(int volNum,
                   int catNum)
Set up Blockette interation. Allows user to iterate through a set of *Parent* Blockettes for a particular category and volume. This method returns the number of Blockettes to be iterated over. getNext() will resolve lookups for the Blockettes encountered. Category numbers for SEED are 1 through 5. See SeedObjectBuilder for details.

Specified by:
iterate in interface ObjectContainer

iterate

public int iterate(int catNum)
Set up an iterator for all parent Blockettes of a specific category number, all volumes.

Specified by:
iterate in interface ObjectContainer

iterate

public int iterate()
Set up an iterator for all parent Blockettes.

Specified by:
iterate in interface ObjectContainer

iterate

public int iterate(java.util.Vector stations,
                   java.util.Vector channels,
                   int catNum)
            throws ContainerException
Set up an iterator for *Parent* Blockettes matching stations and channels. Also confines to a specific category number. Station and channel parameters are Vectors of string values. Each parameter can also be null. The null vector will simply be treated as 'all'. Returns the number of elements in the iterator.

Throws:
ContainerException

getNext

public java.lang.Object getNext()
                         throws ContainerException
Get the next BlocketteDecorator in the established iterator, else return null.

Specified by:
getNext in interface ObjectContainer
Throws:
ContainerException

setFiltered

public void setFiltered(Blockette blk)
                 throws java.lang.Exception
Notify the container that the indicated blockette has been filtered. Use this method to signal the container that the provided blockette has been filtered out by the builder. This will help indicate to the container what rank of Blockette was filtered out so that the child blockettes do not try to store into the Blockette rank lattice.

Throws:
java.lang.Exception

setFiltered

public void setFiltered(int value)
Tell the container to assume that the indicated filter rank has been filtered. Explicitly set the filterRank value with this method. Can be used to externally reset the filterRank to dormant by using a value of 0


getFiltered

public int getFiltered()
Return the current filter rank value assigned to the container. Return the filterRank value, which if non-zero, indicates the rank value and higher of blockette types that are to be rejected until filterRank is later reset to 0.


flushMemory

public void flushMemory()
Flush all Blockettes from the memory cache. This is typically called when attempting to preserve all memory contents to disk before closing the container.


getMetaEncoding

public java.lang.String getMetaEncoding(Blockette dataBlk)
                                 throws java.lang.Exception
Return a string word representing the encoding type of data represented in the indicated data blockette. Does NOT resolve Blockette 1000 indicator, ONLY METADATA REFERENCES. Returns UNKNOWN if no match found.

Throws:
java.lang.Exception

setParent

public void setParent(int lookupId)
               throws ContainerException
Establish parent/child heirarchy for given lookup ID in the rank lattice. Used typically for add() context.

Parameters:
lookupId - the parent we want to establish in the rank lattice
Throws:
ContainerException

getTopParent

public Blockette getTopParent(int lookupId)
Get the top level parent Blockette for the indicated lookupID. Return a null if no such parent is found. A top level parent ID will simply return itself. This sets the global rankLattice vector to the current lookupID parent/child relationship.


improvedLocate

public boolean improvedLocate(int lookupId)
                       throws ContainerException
Deprecated. Use locate() instead.

Throws:
ContainerException

improvedGet

public java.lang.Object improvedGet(int lookupId)
                             throws ContainerException
Deprecated. Use get() instead.

Throws:
ContainerException

getNewId

public int getNewId(Blockette blk,
                    boolean useRefNum)
             throws java.lang.Exception
return an integer that represents a new lookupID number to be assigned to a new blockette, just before it is placed into the add() call. Note that the id returned might will contain a volume number that is either from that last id, or derived from the current volume number. If the current volume number is 0, it will ask the BlocketteDecoratorFactory for a new value. Flag true for useRefNum to use already provided dictionary reference numbers when the source of data is an internally consistent source such as a SEED file.

Throws:
java.lang.Exception

getNewId

public int getNewId(int category)
             throws java.lang.Exception
DEPRECATED -- does not handle predictive numbering for dictionary blockettes Return a new lookupID number that is an incrementation of the previous one added to this container. Each category has its own series.

Throws:
java.lang.Exception

findMatchingDictionary

public int findMatchingDictionary(java.lang.String blocketteString)
Return an integer that represents the lookupId of the last added dictionary blockette to this container matching the provided blockette delimited string. Return -1 if there is no matching lookupId...which means that this dictionary reference has not been added yet. This check can be used to prevent writing identical dictionary blockettes to the container, and consolidating other blockettes pointing to the same information around one dictionary blockette. NOTE: doesn't take into account multiple volumes, but treats all volumes as being in the same dictionary pool, so be aware of this when checking for duplicates.


isCaching

public boolean isCaching()
return true if this container is caching objects to disk persistence.


isUsingSerialization

public boolean isUsingSerialization()
pseudonym for isCaching() -- deprecated


setVolumeNumber

public void setVolumeNumber(int volNum)
force the current volume number of this container to be the indicated value -- this number can get changed via the add() command, which polls for the current volume. Note that the volume number is always assigned externally, either by an ObjectBuilder or other class. New volume numbers can be grabbed from the BlocketteDecoratorFactory to prevent duplication.

Parameters:
volNum - volume number to assign to this container

getVolumeNumber

public int getVolumeNumber()
Return the current volume number this container is set to


getVolumeNumberFromId

public static int getVolumeNumberFromId(int lookupId)
utility to determine the volume number based on the provided lookupId.

Parameters:
lookupId -
Returns:
value representing the volume number of this id

getCategoryNumber

public static int getCategoryNumber(int lookupId)
Return the category number encoded in the lookupId.


lookup

protected Blockette lookup(int lookupId)
Find the blockette in the hashmap that matches the blockette ID. Returns an undecorated Blockette, the raw data object that is stored to the CachedHashMap.