All Packages    This Package    Next

class jade.db.AceAccessor

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

AceAccessor is multithreaded and takes advantage of net-ACE's ability to handle multiple concurrent sessions. This allows several large queries to run simultaneously.

Typical examples of usage:

1. Obtain a connection to the server on host alpha, port 20100:

         try {
           AceAccessor wormdb=new AceAccessor("alpha",20100);
         } catch (IOException e) {
           System.err.println(e);
         }
         

2. Fetch information about the gene "unc-6" from the database:

         AceObject unc6=wormdb.fetch("Gene","unc-6");
         

3. Retrieve all genes that match the pattern "ace*":

         AceObject[] aces=wormdb.find("Gene","ace*");
         

4. Retrieve an enumeration over all sequences in the database:

         Enumeration sequences = wormdb.find_many("Sequence","*");
         while (sequences.hasMoreElements()) {
            AceObject next = (AceObject)sequences.nextElement());
            ...
         }
         

5. Retrieve an enumeration over all papers published between 1986 and 1989:

         String query = "find Paper Year >= 1986 AND Year <= 1989";
         Enumeration papers = wormdb.query_many(query);
         while (papers,hasMoreElements()) { ...
         

See Also:

AceAccessor
AceTable

Version:

1.0, 03.25.96

Author:

Lincoln Stein

AceAccessor(String,int)

Create a new AceAccessor connected to the ACE database at the specified host and port.

• Fetching Objects

  fetch(String,String)

  Fetch the object matching the provided class and name.

  find(String,String)

  Find a set of AceObjects matching the given class and name pattern and return an AceObject array.

  find(String,String,int)

  As above, but with a size limit to the returned array.

  find_many(String,String)

  Find a set of AceObjects matching the given class and name pattern and return an Enumeration over the set.

  find_one(String,String)

  Find an AceObjects matching the given class and name pattern. If more than one objects match, return the first one.

  query(String)

  Send a query using ACE query language and return a set of AceObjects.

  query(String,int)

  Send a query using ACE query language and return a set of AceObjects, up to a specified size limit.

  query_many(String)

  Send a query using ACE query language and return an enumerator over a (potentially large) set of AceObjects.

• Getting information about Objects

  count(String,String)

  Count the number of objects that match the provided ACE class and name pattern.

  count(String)

  Count the number of objects that match the provided ACE class and name pattern.

  follow(String,String,String)

  Retrieve a set of AceObjects and immediately "follow" a tag.

• Table Queries

  tableQuery(String[])

  Return an AceTable based on a table-style query.

  tableQuery(String,String[])

  Return an AceTable based on the named table query and provided runtime parameters.

  tableQuery(AceObject,String[])

  Return an AceTable based on the ACE table contained within the AceObject and the provided runtime parameters.

• Miscellaneous

  dup()

  Make a duplicate of the AceAccessor, connected to the same ACE database as the original. This is useful for multithreading and is used extensively by procedures internal to AceObject.

• Deprecated methods

  list()

  List the currently active objects (deprecated).

  fetch(String,String,boolean)

  Fetch the object matching the provided class and name, with control over whether the fetch should be from the in-memory cache only (deprecated).

  fetch(String,String,boolean,boolean)

  Fetch the object matching the provided class and name, with control over both the cache and the filling status of the object (deprecated).

MAX_CONN(String,int)

The maximum number of simultaneous connections allowed to a single server.

CACHE_MIN(String,int)

The minimum size of the object cache.

CACHE_MAX(String,int)

The maximum size of the object cache.

AceAccessor

  public AceAccessor(String host, int port) throws IOException

Constructs an AceAccessor on the given host and port. Host names must be in domain name format (version 1.0 does not recognize numeric IP addresses). A ACEDB netclient process must be listening to the designated port in order for the connection to succeed. If the connection attempt is unsuccessful, this constructor willl throw an IOException

AceAccessor

  public AceAccessor(String host, int port, boolean debug) throws IOException

As above, but allows you to pass a flag that enables copious amounts of debug information.

Fetching Objects

fetch

  public AceObject fetch(String class, String name)

Fetches a single AceObject from the database using the provided ACE class and name. If no matching object exists, this procedure returns null. It will also return null if more than one object matches the provided name (this can only happen if you inadvertently use wild card characters in the name). Example:

      AceObject unc6 = wormdb.fetch("Gene","unc-6")

find

  public AceObject[] find(String class, String namePattern)

Does a database search for all objects of the specified class that match the name pattern. As explained in the ACEDB query language manual, name patterns can contain the Unix shell-style * and ? wildcards. The first matches any sequence of 0 or more characters, while the second matches any single character.

find

  public AceObject[] find(String class, String namePattern, int max)

As above, but limits the number of objects returned to max. See also find_many()

find_many

  public Enumeration find_many(String class, String namePattern)

Performs a find() query on the database for AceObjects matching the given class and name pattern, and returns an Enumeration over them. Objects will be returned from the server in a manner that conserves network bandwidth and memory. See the introduction at the top of this document for some examples of how to iterate through the returned enumeration.

find_one

  public AceObject find_one(String class, String namePattern)

Uses a find() query to fetch objects matching the given class and name pattern. Returns the first AceObject found, or null if no objects match.

query

  public AceObject[] query(String query)

Passes a general query (or set of queries) to the ACE query parser and returns an array containing all the AceObjects returned from the query. Multiple query commands can be passed to the server by separating them with the semicolon (;) character. If no objects are retrieved from the query a value of null is returned.

query

  public AceObject[] query(String query, int max)

As above, but with a maximum limit on the number of objects that can be retrieved.

query_many

  public Enumeration query(String query)

As in query(), but returns an Enumeration of AceObjects so that you can iterate over large sets of objects in a network- and memory-efficient manner.

Getting Information about Objects

count

  public int count(String class, String namePattern)

Return the number of objects that match the given class and name pattern. See find() for the pattern matching rules.

count

  public int count(String query)

Pose a general ACE query to the database and return the number of objects that match. See query().

follow

  public AceObject[] follow(String class, String name, String tag)

Perform a fetch() query to get the object indicated by the specified class and name followed immediately by an ACE query language follow command to retrieve the set of objects pointed to by the indicated tag. This is a shortcut procedure. These two examples are equivalent:

1. 	    String query = "find Gene unc-16; follow Sequence";
   	    AceObject[] result = wormdb.query(query);
   	    

2. 	    AceObject[] result = wormdb.follow("Gene","unc-16","Sequence");
   	    

Table Queries

Table queries can (and usually do) contain parameters assigned at run time, allowing useful queries to be reused many times. For example, the Table named "Map" in the C. elegans database takes one parameter: the name of the chromosome to display. This table returns a two column list consisting of genetic loci and their position on the C. elegans genetic map.

All these queries return an AceTable object, which is a version of AceObject specialized to take advantage of the predictable tabular nature of the data.

There are three ways to perform table queries:

1. Access a named table already stored in the database, and pass runtime parameters to it. Example:

         String parameters[] = {"X"};
         AceTable result = wormdb.tableQuery("Map",parameters);
         

2. Fetch the table as an AceObject first. This allows you to examine its contents before submitting the query (however you cannot yet change the contents due to a oversight in the implementation). The AceObject containing the table can then be evaluated as a query using runtime parameters:

         AceObject theTableQ = wormdb.fetch("Table","Map");
         String parameters[] = {"X"};
         AceTable result = wormdb.tableQuery(theTableQ,parameters);
         

3. Create the table yourself as an array of String. The format of table queries is currently undocumented but can be inferred from the queries built by the Xace table-builder.

         String theQuery[] = { (long & complex list of strings) }
         AceTable result = wormdb.tableQuery(theQuery);
         

tableQuery

  public AceTable tableQuery(String[] query)

Creates an ACE table query on the fly, submits it to the database, and returns the result as an AceTable object.

tableQuery

  public AceTable tableQuery(String name, String[] parameters)

Looks up the Table object named name, substitutes parameters %1, %2, %3... from the provided parameter list, and evaluates the query, returning an AceTable object. If no Table matching the provided name is found, this method returns null. If the query evaluates to empty, you will receive an empty AceTable.

tableQuery

  public AceTable tableQuery(AceObject query, String[] parameters)

Returns an AceTable using the provided AceObject as the Table object and substituting the provided runtime parameters for the formal parameters %1, %2, %3.... If the AceObject does not correspond to a member of the ACE Table class, this method returns null. An empty AceTable is returned if the query returns an empty result.

Miscellaneous

dup

  public AceAccessor dup()

Returns a copy of the current AceAccessor from a pool of AceAccessors maintained internally (the size of the pool is controlled by the class static variable MAX_CONNECTIONS). Using dup() is useful when launching a concurrent thread. If possible, dup() will provide an AceAccessor that is currently unused, allowing multiple threads to run concurrent queries.

dup() is used internally by the AceObject pick() method. When you follow an object reference in the database, the database access will occur in a way that allows for threading. See the example code for usage.

Deprecated Methods

list

  public AceObject[] list()

Return the currently active list of AceObjects maintained on the remote server. This method is not multithreaded. If you are running a multithreaded application you are not guaranteed to retrieve your own thread's active list rather than some other thread's.

fetch

  public AceObject fetch(String class, String name, boolean cacheOnly)

Perform a fetch() operation with control over the object cache. Ordinarily an object will be fetched from the in-memory cache if possible, otherwise from the database. If a value of true is given for cacheOnly, null will be returned if the object is not in the cache.

fetch

  public AceObject fetch(String class, String name, boolean cacheOnly, boolean fill)

Ordinarily fetch() will return an "unfilled" object from the database. Its name and class will be present, but the rest of the tree structure will only be fleshed out in when needed. You can override this behavior by providing a value of true in the fill parameter. This will force the object to be filled immediately.

MAX_CONN

  public static int MAX_CONN

Each jade.db.AceAccessor maintains a pool of socket connections to the server, up to the limit specified by MAX_CONN. You are free to adjust this static class variable prior to creating a new AceAccessor object. Note that some versions of Java 1.0 have problems opening more than 5 simultaneous TCP/IP connections.

CACHE_MIN

  public static int CACHE_MIN

The in-memory object cache maintains a list of AceObjects sorted by their time of last access. If the number of objects exceeds CACHE_MIN, the cache will instruct objects below this position on the list to begin to "unfill" themselves (discard their internal structure) in order to recover memory. The objects will be automatically refilled if you again access them.

CACHE_MAX

  public static int CACHE_MAX

If the number of objects in the cache exceeds the value of CACHE_MAX, objects beyond this point in the list will be removed from the cache. This does not mean that they will be deleted from Java memory: the object will persist until the last reference to it is deleted and garbage collection occurs. However, subsequent attempts to retrieve this object from the database will result in a new object rather than a cached one.

---

All Packages    This Package    Next