Package org.bioquery.query

A complete framework for modeling, storing, and submitting queries to mutliple different databases.

See:
Description

Class Summary

JdomUtils	Utilities that read and write JDOM Document objects to Streams and Files.
NCBIQuerySubmitter	The NCBIQuerySubmitter class handles the submission of 8 types of Querys associated with databases at the NCBI (National Center of Biotechnology Information) through their website at www.ncbi.nlm.nih.gov . Like all QuerySubmitter subclasses, this class should not be instantiated directly, but instead is returned when the getQuerySubmitter method is called on a Query object.
Query	Query encapsulates a user-created search to a particular database.
QueryFactory	QueryFactory has the job of returning a list of available databases, and returning an instance of Query that handles any specific database on the list.
QueryLine	This class models each individual line within a Query object.
QuerySubmitter	This is the abstract root class of the QuerySubmitter.
QueryXmlConverter	This class can write a Query object to XML and can read the XML and convert it back into a Query object.
ReaderUtils

Exception Summary

InvalidQueryException	Exception class thrown when data or methods within Query objects do not work as intended.
InvalidQueryLineException	Exception class thrown when the query text of a QueryLine object is not valid or contains an invalid line number reference to another QueryLine.
QueryException	Exception class thrown when data or methods within Query objects do not work as intended.

Package org.bioquery.query Description

A complete framework for modeling, storing, and submitting queries to mutliple different databases.

The query package provides a single conceptual model to represent queries to numerous different biomedical databases. This model builds queries as a series of text lines (QueryLines) that can be combined using Boolean operators. Each text line is itself made up of terms directed at specific fields of the database and separated by Boolean operators. Any line in the Query can be designated as the line to be submitted (the submitLine), and this one line controls what results are retrieved.

Each Query object is therefore composed of one or more QueryLine objects. Each Query object is also associated with one and only one QueryDescriptor object that is defined as an inner class of Query. This object holds metadata about when the Query should be submitted. It does not need to be extended or altered, and it's use is optional.

Query objects should not instantiated directly. Instead they should be created by calling the static method QueryFactory.createQuery(String database). A list of valid parameters for database can be obtained by calling QueryFactory.getDatabaseList.

Submission of a Query to it's database is the responsibility of it's QuerySubmitter object. Each Query is created with the appropriate subtype of QuerySubmitter for it's database. To submit a Query, one should first retrieve the correct QuerySubmitter by calling the getQuerySubmitter method. The QuerySubmitter object knows how to contact the Query's database, format the relevant QueryLine for submission, send it out, and receive and parse the results.

The query package models a generic database query. The database-specific details are contained in 2 places: in the querys.xml file (located in the META-INF directory of the base directory for the virtual machine i.e. ./META-INF/querys.xml) and in concrete subclasses of QuerySubmitter. To add the ability to search a new database one must add a new entry to querys.xml and create a new subclass of QuerySubmitter. The QueryFactory class will read querys.xml the first time it is invoked, and will dynamically find and instantiate the proper subclass of QuerySubmitter whenever a new Query is created. Subclasses of QuerySubmitter do not need to be part of the query package, and can be located anywhere where the virtual machine can find them.

If a Query stops returning correct results, it is likely due to a change in the interface of the external database. Some database specific details (such as the URL to submit the query to) are located in the querys.xml file and are very simple to correct. Most of the details about formating a query and parsing the results are found in the QuerySubmitter subclass for that database. If a Query stops working, it may be necessary to correct the QuerySubmitter subclass and recompile the class, or overwrite it with a new QuerySubmitter subclass that works correctly. The path to this new class can be associated with a database in the querys.xml file.

Here is an example of how to request information about the Query types available, and then instantiate a specific Query:

// make the package accessible to your class
import org.bioquery.query.*;

    try {
        // Get the list of available databases
        List databaseList = QueryFactory.getDatabaseList();
        Object[] databases = databaseList.toArray();

        // Ask the user to select one of the databases.
        String databaseName = (String)JOptionPane.showInputDialog(me,
                "Please choose the database for this Query.",
                "Choose Database", JOptionPane.QUESTION_MESSAGE,
                null, databases, databases[0]);

        // Ask the QueryFactory to return a subclass of Query based
        // on the database name chosen.
        Query q = QueryFactory.createQuery(databaseName);
    }
    catch (IOException ex) { ex.printStackTrace(); }

Here is a simple example of how to submit a Query object and get the results from the database:

    // Get the QuerySubmitter specific for this Query object.
    QuerySubmitter submitter = theQuery.getQuerySubmitter();

    // The results of the Query returned to the client.
    BufferedReader results = null;
    try { results = submitter.getQueryResults(); }
    catch (QueryException ex) { }

    if ( results != null ) {
       // Read the results
    }

The results come back as a BufferedReader containing the textual response from the database.