org.bioquery.query
Class Query

java.lang.Object
  |
  +--java.util.Observable
        |
        +--org.bioquery.query.Query

All Implemented Interfaces:

java.io.Serializable

public class Query

extends java.util.Observable

implements java.io.Serializable

Query encapsulates a user-created search to a particular database. Query holds all information about a search, and is the centerpiece of the Query framework in the org.bioquery.query package.

This generalized class allows the building of multi-line searches based on Boolean operators. It does not contain any database-specific information. Database-specific information is loaded into this class dynamically at run-time by the QueryFactory class based on informations contained in the querys.xml file.

This class should not be instantiated directly, but should instead be created by the QueryFactory class based on the name of it's database. A list of available databases can be obtained by the static QueryFactory.getDatabaseList method.

Example:

       java.util.List databaseList = null;
       try { databaseList = QueryFactory.getDatabaseList(); }
       catch(IOException ex) { // error  }

       String databaseName = (String)databaseList.get(0);
       // (or ask user to pick a database from the list)

       // Create a query of the appropriate class from the queryType
       Query newQuery = null;
       try { newQuery = QueryFactory.createQuery(databaseName); }
       catch(IOException ex) { // error  }

       return newQuery;
  

A Query object can submit it's search to it's database using it's QuerySubmitter.

Example:

       QuerySubmitter submitter = theQuery.getQuerySubmitter();

       BufferedReader results = null;
       try { results = submitter.getQueryResults(); }
       catch (QueryException ex) { }

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

Each database a Query can search must be designated in the querys.xml file. Each database must also be assigned a custom subclass of QuerySubmitter. The QueryFactory will load the appropriate class name of the QuerySubmitter into the Query object during instantiation, based on the entry in querys.xml

Query objects can be written to, and read from text files (in xml format) via the QueryXmlConverter class.

Author:

James Brundege

See Also:

Serialized Form

Inner Class Summary

class

Query.QueryDescriptor Inner class holds data about the file this Query is saved in, and the details about automatic submission.

Field Summary

static int	AND Represents the Boolean command AND.
static int	NEAR Represents the Boolean command NEAR.
static int	NOT Represents the Boolean command NOT.
static int	OR Represents the Boolean command OR.

Method Summary

void	addField(java.lang.String commonName, java.lang.String submittedName) Add a field to the list of fields this query can search in it's database.
protected void	addFormat(java.lang.String commonName, java.lang.String extension, int maxNumDisplayable) Adds a format to the list of formats that this query can return it's resultset in.
QueryLine	addQueryLine() Add a new blank QueryLine at the next available position.
void	deleteQueryLine(int lineNum) Deletes the QueryLine at the designated line number.
java.util.Map	getAllFields() Returns a Map containing the names of all available fields for this query.
java.util.Map	getAllFormats() Returns a Map containing all available result formats for this Query, and the file extension for each format.
QueryLine[]	getAllQueryLines() Returns the entire query as an Array of QueryLine objects.
static java.lang.String[]	getBooleanOperators() Returns all available boolean operators as a String[].
java.lang.String	getCurrentFormat() Returns the currently chosen format for the results of this query.
java.lang.String	getDatabase() Get the name of this query's database.
int	getEndDisplayNum() Get the end display number (the end number in the set of results to be returned).
java.lang.String	getExtensionForFormat() Returns the file extension of the results based on this Query's current format.
java.lang.String	getFieldCode(java.lang.String fieldName) Returns the database-readable field code for the given human-readable field name.
java.lang.String	getFileExtension() The file extension used to save this Query as a file.
java.lang.String	getHelpURL() Get the URL of the help file explaining the structure and use of this query's database.
int	getMaxNumDisplayable() Returns the maximum number of items that can be returned in the current format.
java.lang.String	getName() Get the name of this individual query.
Query.QueryDescriptor	getQueryDescriptor() Returns the QueryDescriptor that holds information about the user, when to automatically submit the Query, and when it was last auto-submitted.
QueryLine	getQueryLine(int lineNum) Returns a single QueryLine from the query.
QuerySubmitter	getQuerySubmitter() Returns the QuerySubmitter that can submit this Query to it's database.
int	getStartDisplayNum() Get the start display number (the first number in the set of results to be returned).
QueryLine	getSubmitLine() returns the submitLine (the QueryLine designated as the one to be sent to the database).
int	getSubmitLineNumber() returns the line number of the submitLine (the QueryLine designated as the one to be sent to the database).
boolean	getUpdate(int queryLineNum) Indicates whether we need to update the ref count for the QueryLine the next time the Query is submitted.
void	insertQueryLine(int lineNum) Insert a blank QueryLine into the list of queryLines at the designated linenum.
void	setAllUpdates(boolean update) Sets the update needed value of every QueryLine in the Query to the given value.
protected void	setChanged() Notifies Observers that the Query has changed.
void	setCurrentFormat(java.lang.String aFormat) Designate the format for the results of this query.
protected void	setDatabase(java.lang.String name) Set the name of this query's database.
void	setEndDisplayNum(int endNum) Set the end display number (the end number in the set of results to be returned).
void	setFileExtension(java.lang.String fileExtension) The file extension used to save this Query as a file.
protected void	setHelpURL(java.lang.String helpURL) Set the URL of the help file explaining the structure and use of this query's database.
void	setName(java.lang.String name) Designate the name of this individual query.
void	setQueryLine(int lineNum, QueryLine queryLine) Assigns a QueryLine object to the designed line number.
protected void	setQuerySubmitter(QuerySubmitter newSubmitter) Sets the QuerySubmitter for this type of Query.
void	setStartDisplayNum(int startNum) Set the start display number (the first number in the set of results to be returned).
void	setSubmitLine(int lineNum) Sets which QueryLine should be submitted to the database.
void	setUpdate(int queryLineNum, boolean update) Set whether we need to update the ref count for the given QueryLine.
int	size() Returns the number of queryLines contained in this Query object.
void	summateQueryLines(java.lang.String bool) Combines all of the QueryLines into a new QueryLine, separated by the bool text.
java.lang.String	toString()

Methods inherited from class java.util.Observable

addObserver, clearChanged, countObservers, deleteObserver, deleteObservers, hasChanged, notifyObservers, notifyObservers

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

OR

public static final int OR

Represents the Boolean command OR.

AND

public static final int AND

Represents the Boolean command AND.

NOT

public static final int NOT

Represents the Boolean command NOT.

NEAR

public static final int NEAR

Represents the Boolean command NEAR.

Method Detail

getQueryDescriptor

public Query.QueryDescriptor getQueryDescriptor()

Returns the QueryDescriptor that holds information about the user, when to automatically submit the Query, and when it was last auto-submitted.

Returns:

A QueryDescriptor object holding submission data

addQueryLine

public QueryLine addQueryLine()

Add a new blank QueryLine at the next available position.

Returns:

The blank QueryLine added to the end of this Query.

setName

public void setName(java.lang.String name)

Designate the name of this individual query.

Parameters:

name - the name of this query.

getName

public java.lang.String getName()

Get the name of this individual query.

Returns:

the name given to this Query object.

getDatabase

public java.lang.String getDatabase()

Get the name of this query's database.

Returns:

the human-readable database name

setDatabase

protected void setDatabase(java.lang.String name)

Set the name of this query's database.

Parameters:

name - the name of the query's database.

getHelpURL

public java.lang.String getHelpURL()

Get the URL of the help file explaining the structure and use of this query's database.

Returns:

the URL where database help is located, in String format. The String should contain the full URL including protocol.

setHelpURL

protected void setHelpURL(java.lang.String helpURL)

Set the URL of the help file explaining the structure and use of this query's database.

Parameters:

helpURL - the URL for the documentation of this query's database, in String format. The String should contain the full URL including protocol.

getFileExtension

public java.lang.String getFileExtension()

The file extension used to save this Query as a file.

setFileExtension

public void setFileExtension(java.lang.String fileExtension)

The file extension used to save this Query as a file.

setQueryLine

public void setQueryLine(int lineNum,
                         QueryLine queryLine)
                  throws InvalidQueryLineException

Assigns a QueryLine object to the designed line number. Any existing QueryLine at that position will be overwritten.

Parameters:

lineNum - the line number. Note: starts at 1, not 0.

queryLine - the text representing one line of the query.

getQueryLine

public QueryLine getQueryLine(int lineNum)

Returns a single QueryLine from the query.

Parameters:

lineNum - the line number to be returned.

getAllQueryLines

public QueryLine[] getAllQueryLines()

Returns the entire query as an Array of QueryLine objects.

size

public int size()

Returns the number of queryLines contained in this Query object. Note that this number is also the next free index number available for a new QueryLine object.

setSubmitLine

public void setSubmitLine(int lineNum)
                   throws InvalidQueryLineException

Sets which QueryLine should be submitted to the database.

Parameters:

lineNum - The line number of the QueryLine that is set as the submitLine.

summateQueryLines

public void summateQueryLines(java.lang.String bool)

Combines all of the QueryLines into a new QueryLine, separated by the bool text. For example, if there are 4 QueryLines and you pass this method the String "OR" a new QueryLine is added at position 5 with this text:
#1 OR #2 OR #3 OR #4

getBooleanOperators

public static java.lang.String[] getBooleanOperators()

Returns all available boolean operators as a String[]. That is, OR, AND, NOT, NEAR

getSubmitLine

public QueryLine getSubmitLine()

returns the submitLine (the QueryLine designated as the one to be sent to the database).

getSubmitLineNumber

public int getSubmitLineNumber()

returns the line number of the submitLine (the QueryLine designated as the one to be sent to the database).

setUpdate

public void setUpdate(int queryLineNum,
                      boolean update)

Set whether we need to update the ref count for the given QueryLine. This is usually set to true whenever the text of a QueryLine is changed, or when the user explicitly chooses to update, and is reset to false whenever an update is performed.

Parameters:

queryLineNum - the number of the QueryLine that needs to be updated.

update - whether we need to update the ref count of the given QueryLine next time the Query is submitted.

getUpdate

public boolean getUpdate(int queryLineNum)

Indicates whether we need to update the ref count for the QueryLine the next time the Query is submitted. Returns false if there is no QueryLine at queryLineNum.

Parameters:

queryLineNum - the number of the QueryLine

Returns:

whether we need to update the ref count of this QueryLine next time the Query is submitted, or false if queryLineNum is invalid.

setAllUpdates

public void setAllUpdates(boolean update)

Sets the update needed value of every QueryLine in the Query to the given value.

setStartDisplayNum

public void setStartDisplayNum(int startNum)

Set the start display number (the first number in the set of results to be returned).

getStartDisplayNum

public int getStartDisplayNum()

Get the start display number (the first number in the set of results to be returned).

setEndDisplayNum

public void setEndDisplayNum(int endNum)

Set the end display number (the end number in the set of results to be returned). The total number of items returned is: getEndDisplayNum() - getStartDisplayNum()

getEndDisplayNum

public int getEndDisplayNum()

Get the end display number (the end number in the set of results to be returned). The total number of items returned is: getEndDisplayNum() - getStartDisplayNum()

addFormat

protected void addFormat(java.lang.String commonName,
                         java.lang.String extension,
                         int maxNumDisplayable)

Adds a format to the list of formats that this query can return it's resultset in. Also adds the file extension that indicates how the results should be displayed, and the max number of items to be displayed.

Some QuerySubmitters may return one format embedded in another. For example, if the Query is set to return XML, the xml text may come back inside an HTML document. The commonName of the format should be XML, but the file extension should be HTML, which tells us the program how to display the results.

This method is called by the QueryFactory when reading the querys.xml file. It is unlikely that it should be called directly. Instead, formats should be listed in query.xml.

Parameters:

commonName - the common (human readable) name of the resultset format.

extension - the file extension that indicates how the results should be displayed and saved.

maxNumDisplayable - the maximum number of items returned in this format per search

getExtensionForFormat

public java.lang.String getExtensionForFormat()

Returns the file extension of the results based on this Query's current format.

Some QuerySubmitters may return one format embedded in another. For example, if the Query is set to return XML, the xml text may come back inside an HTML document. The commonName of the format should be XML, but the file extension should be HTML, which tells us the program how to display the results.

Returns:

a file extension that indicative of how to display the results, such as txt or html. Note that no period (.) is included with this extension.

getMaxNumDisplayable

public int getMaxNumDisplayable()

Returns the maximum number of items that can be returned in the current format.

getAllFormats

public java.util.Map getAllFormats()

Returns a Map containing all available result formats for this Query, and the file extension for each format.

setCurrentFormat

public void setCurrentFormat(java.lang.String aFormat)

Designate the format for the results of this query.

Parameters:

format - the name of the preferred format.

getCurrentFormat

public java.lang.String getCurrentFormat()

Returns the currently chosen format for the results of this query.

addField

public void addField(java.lang.String commonName,
                     java.lang.String submittedName)

Add a field to the list of fields this query can search in it's database. The field names have 2 parts: a common (human readable) name and the (often abbreviated) form submitted to the database. If these are the same, two identical Strings should be added.

This method is called by the QueryFactory when reading the querys.xml file. It is unlikely that it should be called directly. Instead, fields should be listed in query.xml.

Parameters:

commonName - the common (human readable) name of the database field.

submittedName - the name of the field as passed to the database.

getAllFields

public java.util.Map getAllFields()

Returns a Map containing the names of all available fields for this query. The map contains pairs of Strings, with the first String being the common, human readable name of the query and the second String being the parameter name understood by the database which becomes part of the queryLine.

getFieldCode

public java.lang.String getFieldCode(java.lang.String fieldName)

Returns the database-readable field code for the given human-readable field name.

insertQueryLine

public void insertQueryLine(int lineNum)
                     throws InvalidQueryLineException

Insert a blank QueryLine into the list of queryLines at the designated linenum. This shifts all of the subsequent QueryLines down.

Parameters:

lineNum - The line number at which the new, blank query is inserted.

deleteQueryLine

public void deleteQueryLine(int lineNum)
                     throws InvalidQueryLineException

Deletes the QueryLine at the designated line number. This shifts all of the subsequent QueryLines up one line number.

Parameters:

lineNum - The line number of the QueryLine to be deleted.

setChanged

protected void setChanged()

Notifies Observers that the Query has changed.

Overrides:

setChanged in class java.util.Observable

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object

getQuerySubmitter

public QuerySubmitter getQuerySubmitter()

Returns the QuerySubmitter that can submit this Query to it's database. The QuerySubmitter returned depends on the database type of this Query, as designed in the querys.xml file.

setQuerySubmitter

protected void setQuerySubmitter(QuerySubmitter newSubmitter)

Sets the QuerySubmitter for this type of Query. This method is called by the QueryFactory when reading the querys.xml file. It is unlikely that it should be called directly. Instead, the QuerySubmitter class should be designated in query.xml.