org.bioquery.query
Class QuerySubmitter

java.lang.Object
  |
  +--org.bioquery.query.QuerySubmitter

Direct Known Subclasses:

NCBIQuerySubmitter

public abstract class QuerySubmitter

extends java.lang.Object

This is the abstract root class of the QuerySubmitter. Every database type should have a custom QuerySubmitter subclass that is returned by the getQuerySubmitter method. A QuerySubmitter should never be directly instantiated, but should rather be returned by a call to the getQuerySubmitter method of a Query object.

A QuerySubmitter has 5 main responsibilities:

1. Convert the List of queryLines contained in it's Query into a format understood by the database.
2. Contact the remote database over the internet, and submit the Query to it.
3. Submit the Query to retrieve the full results of that Query in any available format.
4. Submit the Query to determine the number of items returned by that Query.
5. Limit the items returned by a Query to those items modified in a specific range of dates.

Depending on the nature of the application, items 4 and 5 may not be fully implemented.

A QuerySubmitter's relationship with it's Query is determined by the querys.xml file, where the subclass of QuerySubmitter appropriate for each database is listed. When a Query for a specific database is created by the QueryFactory, it is told the class of it's QuerySubmitter, which it can then instantiate from it's getQuerySubmitter method.

Author:

James Brundege

Field Summary

protected java.util.Date	endDate
protected Query	myQuery
protected java.util.Date	startDate

Constructor Summary

QuerySubmitter()

Method Summary

static java.lang.String	convertOperatorCase(java.lang.String initialText, boolean toUpperCase) Finds the textual Boolean operators AND, OR, NOT and NEAR surrounded by spaces and converts them to either uppercase or lowercase.
abstract java.io.BufferedReader	getQueryData() Finds the number of references returned by each line of the Query.
abstract java.io.BufferedReader	getQueryResults() Submits this QuerySubmitter's Query object to the appropriate database and returns a BufferedReader containing the text results.
static java.lang.String	parseQueryLine(QueryLine queryLine) Takes a QueryLine object and returns the queryText for that object with any references to other QueryLines fully expanded into the raw fields and boolean commands that make up the Query.
void	resetEndDate() This method undoes the effects of calling setEndDate.
void	resetStartDate() This method undoes the effects of calling setStartDate.
boolean	setEndDate(java.util.Date end) Sets the ending date for the search.
protected void	setInitParams(java.util.HashMap parameters) Empty method should be overridden in subclasses if custom parameters are used.
protected void	setQuery(Query myQuery) Sets the Query object for this QuerySubmitter.
boolean	setStartDate(java.util.Date start) Sets the starting date for the search.

Methods inherited from class java.lang.Object

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

Field Detail

myQuery

protected Query myQuery

startDate

protected java.util.Date startDate

endDate

protected java.util.Date endDate

Constructor Detail

QuerySubmitter

public QuerySubmitter()

Method Detail

setQuery

protected void setQuery(Query myQuery)

Sets the Query object for this QuerySubmitter. The QuerySubmitter should be passed a reference to the Query object that created it immediately after it is instantiated, and this should never change.

Parameters:

myQuery - The Query object that created this QuerySubmitter.

setInitParams

protected void setInitParams(java.util.HashMap parameters)

Empty method should be overridden in subclasses if custom parameters are used. This method is called by the QueryFactory, which passes a Map containing each listed in the tags of querys.xml Fragile items that may need to be updated, such as URLs and strings used to parse web pages, should be placed as new elements in the section of querys.xml They can then be retrieved by subclasses from this method and placed into class parameters.

parseQueryLine

public static java.lang.String parseQueryLine(QueryLine queryLine)
                                       throws InvalidQueryLineException

Takes a QueryLine object and returns the queryText for that object with any references to other QueryLines fully expanded into the raw fields and boolean commands that make up the Query. Processing a QueryLine with this method is a prerequisite to submitting that QueryLine to a database. This method also throws an InvalidQueryLineException if there is an invalid reference to another QueryLine in the Query. Hence it can serve as a simple check to see whether the line references in a QueryLine are all valid.

Parameters:

queryLine - the QueryLine object whose query text should be expanded.

Returns:

the text of the QueryLine with each reference to another QueryLine number within the same Query expanded to include that QueryLine's text.

convertOperatorCase

public static java.lang.String convertOperatorCase(java.lang.String initialText,
                                                   boolean toUpperCase)

Finds the textual Boolean operators AND, OR, NOT and NEAR surrounded by spaces and converts them to either uppercase or lowercase. This utility lets subclasses of QuerySubmitter easily convert operators to the case understood by the database for that subclass. This method only finds the operators if they have spaces on both sides, and if they are in the same case. It does not find mixed-case operators.

Parameters:

initialText - The search text in which all boolean operators should be converted to the same case.

toUpperCase - true if all operators should be converted to uppercase. false if all operators should be converted to lowercase.

Returns:

The initialText with the operators converted to the correct case.

getQueryResults

public abstract java.io.BufferedReader getQueryResults()
                                                throws InvalidQueryException,
                                                       InvalidQueryLineException

Submits this QuerySubmitter's Query object to the appropriate database and returns a BufferedReader containing the text results. A null BufferedReader may be returned if there was a problem connecting to Entrez.

Returns:

a BufferedReader containing the complete list of references returned by the Query's submitLine, formated according to the settings in the Query.

getQueryData

public abstract java.io.BufferedReader getQueryData()
                                             throws InvalidQueryException,
                                                    InvalidQueryLineException

Finds the number of references returned by each line of the Query. This method must do the following:

• Iterate through each QueryLine in the Query.
• If the QueryLine getUpdateNeeded method returns true:
• submit the QueryLine and get the result count.
• put the results into the BufferedReader in the following format:
• QueryLineNumber BQProtocol.DELIMITER ItemsReturned

Each entry should constitute one line (that is, separated by a newLine character).

Note: It is not required to fully implement this method in subclasses of QuerySubmitter. The method can be overriden with the following single-line method:

  public BufferedReader getQueryDate() {
      return null;
  }

This will have the effect of selectively disabling the ability of the user to see the item count for each line of their query for that Query type. Other Query types will not be affected.

Returns:

a BufferedReader containing ASCII text in which each line contains data for one QueryLine in the format
QueryLineNumber BQProtocol.DELIMITER ItemsReturned.

setStartDate

public boolean setStartDate(java.util.Date start)

Sets the starting date for the search. Results that are "dated" (or were entered) prior to this date should not be returned when this submitter runs the getQueryResults method. This method is typically only used by the AutoSubmitEngine to retrieve the latest update since the last automated search. Users can directly control the search dates by entering the appropriate fields in their queryLines

.

By default (until this method is called) there is no start date and results with any entry date may be returned. This state can be restored with the resetStartDate() method.

If a concrete implementation of QuerySubmitter cannot utilize these dates in its getQueryResults and getQueryData methods, it should override this method to return false.

Parameters:

start - A Date representing the earliest (or oldest) items that should be returned by any search.

Returns:

true if the start date was successfully set, false otherwise.

resetStartDate

public void resetStartDate()

This method undoes the effects of calling setStartDate. Resets the start date to null, thus having no start date so results with any entry date may be returned.

setEndDate

public boolean setEndDate(java.util.Date end)

Sets the ending date for the search. Results that are "dated" (or were entered) after this date should not be returned when this submitter runs either the getQueryResults method.

.

By default (until this method is called) there is no end date and results with any entry date may be returned. This state can be restored with the resetEndDate() method.

If a concrete implementation of QuerySubmitter cannot utilize these dates in its getQueryResults and getQueryData methods, it should override this method to return false.

Parameters:

end - A Date representing the latest (or youngest) items that should be returned by any search.

Returns:

true if the end date was successfully set, false otherwise.

resetEndDate

public void resetEndDate()

This method undoes the effects of calling setEndDate. Resets the end date to null, thus having no end date so results with any entry date may be returned.