jade.db.AceObject

All Packages    This Package    Previous    Next

class jade.db.AceObject

java.lang.Object
   |
   +----jade.db.AceObject

AceObject mirrors, in Java, the hierarchical tree structure of objects in the ACEDB database. Ace objects are uniquely identified by two string identifiers:

class: The object's class. Some classes, such as "int", "date" and "float" are primitive, and others are constructed types. Examples of the latter include "Sequence", "Author", and "Gene".
name: The object's name. This can be any series of ascii characters, including spaces and control characters. However, names are usually limited to the rational set of alphanumeric characters.

To retrieve an AceObject from a networked ACE database, you request it from an AceAccessor. You can request a single object by class and name, or retrieve a set of objects using the ACE query language.

Java AceObjects, like native ACE objects, are structured as trees. At the "top" of the tree is the root, which contains the unique name and class of the object. To the "right" of the root is another node, and to the right of that possibly another. Each node has a "right" neighbor, corresponding roughly to subfields, and a "down" neighbor, which often corresponds roughly to records in a record-oriented database.

The organization of each object's tree depends on the ACEDB model. Fields are frequently identified by "tags". For example, in the model below, the terms "Full_name", "Laboratory", "Old_lab", "Address", "Paper", and "Sequence" are all tags. "?Laboratory" and "?Paper", distinguished by starting with an interrogation mark, correspond to constructed classes. These objects have internal data that can be retrieved using the so-called "pick" operation.

?Author Full_name Text
	Laboratory UNIQUE ?Laboratory XREF Staff
	Old_lab ?Laboratory
        Address Mail Text
                E_mail Text
                Phone Text
		Fax   Text
        Paper ?Paper
	Sequence ?Sequence XREF From_author

And here's the structure of a typical Author entry:

"Thierry-Mieg J" -> Full_name  -> Jean Thierry-Mieg
                      |
                    Laboratory -> FF
                      |
                    Address    -> Mail -> CRBM duCNRS
                      |                     |
                      |                   BP 5051
                      |                     |
                      |                   34033 Montpellier
                      |                     |
                      |                   FRANCE
                      |
                     E_mail    -> mieg@kaa.cnrs-mop.fr
                      |
                     Phone     -> 33-67-613324
                      |
                     Fax       -> 33-67-521559
                      |
                     Paper     -> The C. elegans genome sequencing project
                                             |
                                  Genome Project Database
                                             |
                                  Genome Sequencing
                                             |
                                  How to get ACEDB for your Sun
                                             |
                                  ACEDB is Hungry

The AceObject provides a number of methods for traversing the tree structure. You can retrieve the down and right pointers directly and traverse the tree on your own. You can search for tags and retrieve partial subtrees, or selectively "flatten" portions of the tree into Java arrays. There is also a method for "picking" an object in order to examine its internal structure.

Although every node is an AceObject, some are more useful when converted into other Java types. For examples, some AceObjects are best manipulated as integers, Strings or Date objects. AceObject has a number of casting routines to simplify this process.

AceObjects use a "lazy" style of allocation. When you first create them, all that's present is the name and class. Later, if you need their contents, they will automatically fill themselves from the database. The objects cache themselves locally in a most-recently-used fashion in order to minimize network traffic. In addition, all AceObject methods are thread-safe.

See Also:: AceTable,
AceAccessor
Version:: 1.0, 03.25.96
Author:: Lincoln Stein

There are no public constructors. AceObjects must be retrieved via requests to an AceAccessor.

Field Access

name()
Returns the object's name.
classe()
Returns the object's class.
down()
Returns the down pointer for this object.
right()
Returns the right pointer for this object.
accessor()
Returns the AceAccessor associated with this object.
Status Inquiries

status()
Indicates whether this object can be picked, and whether it is cached.
isClass()
Returns true if the object is an ACE class (potentially "pickable").
filled()
Returns the filled status for this object.
Tree Traversal and Lookup

get(String)
Return the subtree anchored at the indicated tag. Traverses the tree searching for the tag in a depth-first manner.
at(String)
Return the subtree anchored at the indicated tag. Does not traverse the tree, but only searches the column immediately to the right of the root.
countKeys()
Returns the number of objects in the column immediately to the right of the root.
keys()
Returns an array consisting of all the objects in the column immediately to the right of the root.
pick()
Follows a class reference, returning a new AceObject from the database.
follow(String)
Find the subtree anchored at the indicated tag using get() semantics, and pick() them all, returning an array of AceObjects.
followOne(String)
As above, but only returns the first object found.
Casting and Type Conversion

stringOf()
Attempt to cast the root object to a String.
intOf()
Attempt to cast the root object to an int.
floatOf()
Attempt to cast the root object to a float.
doubleOf()
Attempt to cast the root object to a double.
dateOf()
Attempt to cast the root object to a Date.
node()
Use get() semantics to look up a tag by name and cast the node at this location its best type, returning an Object.
bestType()
Cast the root object into its best type and return it as an Object.
Tree pruning

row()
Flatten everything to the right of this object into an array of AceObject, returning the row.
col()
Flatten everything below this object into an array of AceObject, returning the column.
flatten()
A pseudonym for row().
Pretty Printing

dump()
Pretty-prints the object's contents.
toString()
Returns a string describing the object.

Field Access

name
public String name(): Returns the root object's name. An object can have any name, including "Sulston, JE", "[wp29421]", and "1.9237".
classe
public String classe(): Returns the root object's class (French spelling was used to avoid conflict with the Java keyword class. Class names are alphanumeric.
down
public AceObject down(): Returns a reference to the AceObject located at this object's down pointer, or null if there is no object at this location. The down pointer for the root of a tree is always null, but this is not true of subtrees to the right of the root.
right
public AceObject right(): Returns a reference to the AceObject located at this object's right pointer, or null if there is no object at this location. The root object's right pointer is almost always non-null, but this is not guaranteed.
accessor
public AceAccessor accessor(): Returns a reference to the AceAccessor database associated with this object, or null if no AceAccessor has been assigned (should never happen).

Status Inquiries

status
public int status()

Returns a status code for the object, indicating whether it can be picked() or not. (A pick operation follows the node into the database and returns a new AceObject that displays the node's internal structure). The status code is one of four static class constants:

AceObject.INERT: This object is an atomic object (such as an integer, date or string) that cannot be picked.
AceObject.POTENTIAL: This object is an instance of a constructed ACE class and can potentially be picked. However, the success of a pick operation is not guaranteed, as ACE may have no further information about the object beyond its name.
AceObject.LIVE: Object has been successfully picked in the past and can be picked again in the future. Its internal structure is likely to be in the cache, but this is not guaranteed.
AceObject.DEAD: An attempt was made to pick the object in the past and the attempt failed. Further attempts to pick this object will probably fail as well.

isClass
public boolean isClass()

Returns true if the object corresponds to a constructed ACE class.

filled
public boolean filled()

Returns true if the object's contents have been filled from the database. Ordinarily you won't have to worry about this because filling happens automatically as needed. However, when retrieving large objects (such as heavily-annotated sequences), there may be a perceptible delay while the object is recovered from the database. You can use this method to ascertain whether a database access will occur.

Tree Traversal and Lookup

An AceObject can be treated as an associative array in which the tags correspond to keys and the subtrees anchored on the right of the tags correspond to values. Two types of lookup semantic are supported:

at() semantics do not traverse the tree searching for a named tag, but step through the column of tags to the immediate right of the root.
get() semantics do a full traversal of the tree searching for the indicated key.

In the Author entry example given at the top of this manual page, a call to myObj.at("Address") will retrieve the partial tree rooted at the tag "Address". However a call to myObj.at("Phone") will fail because it is too deeply nested in the tree. A call to myObj.get("Phone") succeeds, however, because it traverses the tree looking for the key, at the cost of some execution speed.. (You could avoid the speed penalty by specifying the complete path with myObj.at("Address").at("Phone")).

Key lookups are always case insensitive.

get
public AceObject get(String key): Returns the partial AceObject tree anchored at the tag matching the provided key, traversing the tree, if necessary, to find the tag. If no matching key is found, returns null.
at public AceObject at(String key): Returns the partial AceObject tree anchored at the tag matching the provided key. No tree traversal is performed: only tags in the column to the immediate right of the root are examined. If no matching key is found, returns null.
countKeys
public int countKeys(): Returns the number of keys in the column to the right of the root. In the Author entry example above, countKeys() will return a count of 6.
keys
public String[] keys(): Returns an array containing all the keys in the column to the right of the root. In the Author entry example above, countKeys() will return the array {"Full_name","Laboratory","Address","E-Mail","Phone","Fax","Paper"}.
pick
public AceObject pick(): Does a database access to create a new AceObject representing the internal structure of the current object. A pick() on the root of an AceObject will return a reference to the same object. A pick() on one of its nodes will potentially return a new AceObject if the node is a member of one of the constructed ACE classes (see isClass()). pick() will return null if the node you attempt to pick is not a constructed class or if the database access fails.
follow
public AceObject[] follow(String key): Finds the subtree anchored at the matching tag using get() semantics, and performs a pick() on all the objects immediately adjacent to tag, returning an array of AceObject. In the Author example, calling follow() with a key of "Paper" will return an array of five Paper objects.
followOne
public AceObject followOne(String key): As above, but only follows the first object (i.e. does a pick() on the object immediately right of the specified tag). This is useful for tags that you know are single-valued.

Casting and Type Conversion

stringOf
public String stringOf()

Return a string representation of the root object into a string. This is usually equivalent to the name().

intOf
public int intOf()

Returns an integer representation of the root object. Returns 0 if the object is not representable as a number (this is in deference to Perl's behavior). Usage example:

        int distance = myGene.get("position").intOf()

floatOf
public float floatOf()

Returns a float representation of the root object. Returns 0.0 if the object is not representable as a number.

doubleOf
public double doubleOf()

Returns a double representation of the root object. Returns 0.0 if the object is not representable as a number.

dateOf
public Date dateOf()

Returns a date representation of the root object. Returns January 1, 1970 if the object is not representable as a Date. Example:

        Date birthday = lstein.get("birthday").dateOf()

node
public Object node(String key)

Use get() semantics to look up the indicated key and return an Object representing the "best" type for the node to the right of the key. This function returns an Object which will have to be downcast to the appropriate type: see

bestType
public Object bestType()

Return an Object representing the "best" Java type for the root of this object. This call will return one of the following types of object:

Float
Integer
Date
String

You are responsible for downcasting the returned Object into the correct type. For example:

Date birthday = (Date)lstein.get("birthday").bestType();

Tree Pruning

row
public Object[] row(): Flatten everything to the right of the root node and return it as an array of Object. The bestType() method is used to determine the most appropriate representation for the objects. In the Author example above, the call myObject.at("Address").row() will return the array of String {"Mail","CRBM duCNRS"}
col
public Object[] col(): Flatten everything in the column to the right of the root node and return it as an array of Object. The bestType() method is used to determine the most appropriate representation for the objects. In the Author example above, the call myObject.get("Mail").col() will return the array of String {"CRBM duCNRS","BP 5051","34033 Montpellier","FRANCE"}.
flatten
public Object[] flatten(): This is an alias for row().

Pretty Printing

dump
public String dump(): This returns a pretty-printed string representing the object and its contents. It uses tabs rather than spaces to indent the fields and may not look entirely correct on all displays. It's intended primarily as a debugging tool.
toString
public String toString(): Returns a string representation of the object consisting of the object's name and class.

All Packages    This Package    Previous    Next