edu.ucsb.adl.middleware
Class Query

java.lang.Object
  |
  +--edu.ucsb.adl.middleware.Query

All Implemented Interfaces:

XmlHandler

public final class Query

extends java.lang.Object

implements XmlHandler

A query. A query stores:

• one or more collection names, e.g., "adl_catalog";
• a constraint, represented as a tree of one or more Query.Constraint objects;
• optionally, the descriptive name of a ranking method, e.g., "by date, most recent first";
• optionally, a nonnegative maximum number of results to return.

Version:

$Header: /export/home/gjanee/middleware/edu/ucsb/adl/middleware/RCS/Query.java,v 1.7 2004/09/22 03:00:26 gjanee Exp $

$Log: Query.java,v $ Revision 1.7 2004/09/22 03:00:26 gjanee
Rewrite to use new, centralized XML/HTML encoding functions.

Revision 1.6 2004/03/15 20:18:04 gjanee
Minor change: we now remove any encoding declaration from the original XML query.

Revision 1.5 2004/02/24 05:04:32 gjanee
Significantly rewritten to employ the new validating XML parser. Also, added support for spatial fallback: in inner class SpatialConstraint, polygonal spatial constraints are now required to have bounding boxes. Added support for relational constraints; added inner class RelationalConstraint. Added a constructor that constructs a Query from its constituent components. Added the toXML method. (The getOriginal method calls toXML if the Query was constructed from components.)

Revision 1.4 2003/06/12 21:17:14 gjanee
Minor documentation clarification.

Revision 1.3 2002/09/05 03:31:41 gjanee
Added support for field-level constraints. Added inner classes Query.Field and Query.IdentificationConstraint.

Revision 1.2 2000/05/02 13:22:03 gjanee
Added method getOriginal.

Revision 1.1 2000/04/03 20:11:23 gjanee
Initial revision

Author:

Greg Janée
Alexandria Digital Library

Nested Class Summary

static class	Query.BooleanConstraint A boolean combination of two or more subconstraints.
static class	Query.Constraint Abstract base class for constraints.
static class	Query.Field Identifies a metadata field.
static class	Query.HierarchicalConstraint A hierarchical categorization constraint.
static class	Query.IdentificationConstraint An identification constraint.
static class	Query.NumericConstraint A numeric constraint.
static class	Query.RelationalConstraint A relational constraint.
static class	Query.SimpleConstraint Abstract base class for simple (non-boolean) constraints.
static class	Query.SpatialConstraint A spatial (i.e., geographic) constraint.
static class	Query.TemporalConstraint A temporal constraint.
static class	Query.TextualConstraint A textual constraint.

Constructor Summary

Query(java.lang.String query)
Constructs a Query.

Query(java.lang.String[] collections, Query.Constraint constraint, java.lang.String rankingMethod, int maximumResults)
Constructs a Query from its constituent components.

Method Summary

void	characters(char[] string, int start, int length) For use by ValidatingXmlParser only.
void	endElement(int elementCode) For use by ValidatingXmlParser only.
java.lang.String[]	getCollections() Returns the collection names.
Query.Constraint	getConstraint() Returns the constraint.
int	getMaximumResults() Returns the maximum number of results.
java.lang.String	getOriginal() Returns the original, XML query.
java.lang.String	getRankingMethod() Returns the ranking method.
void	startElement(int elementCode, java.lang.String[] attributes) For use by ValidatingXmlParser only.
java.lang.String	toHTML(java.lang.String mapServerURL) Converts the query to HTML.
java.lang.String	toXML() Converts the query to XML.

Methods inherited from class java.lang.Object

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

Constructor Detail

Query

public Query(java.lang.String query)
      throws InternalErrorException

Constructs a Query.

Parameters:

query - The query, expressed in XML according to the ADL-query DTD.

Throws:

InternalErrorException - If the query is invalid.

Query

public Query(java.lang.String[] collections,
             Query.Constraint constraint,
             java.lang.String rankingMethod,
             int maximumResults)

Constructs a Query from its constituent components.

Parameters:

collections - An array of one or more collection names. This class assumes ownership of the array, and thus the array should not be referenced by the caller after calling this method.

constraint - The root node of a constraint tree. This class assumes ownership of the constraint tree, and thus the tree should not be referenced by the caller after calling this method.

rankingMethod - The descriptive name of a ranking method, or null.

maximumResults - The maximum number of results, or a negative value indicating no limit.

Throws:

java.lang.IllegalArgumentException - If zero collections are specified.

java.lang.NullPointerException - If collections, any element of collections, or constraint is null.

Method Detail

startElement

public void startElement(int elementCode,
                         java.lang.String[] attributes)

For use by ValidatingXmlParser only.

Specified by:

startElement in interface XmlHandler

Parameters:

elementCode - The element's code.

attributes - Element attribute values, indexed by attribute code. All of the element's declared attributes are represented in the array; attributes for which a value is specified in the document or for which there is a DTD-specified default have non-null values. The handler should reference the array for the duration of the call only, as it is reused by the parser. Also, the array may be longer than necessary.

endElement

public void endElement(int elementCode)
                throws XmlException

For use by ValidatingXmlParser only.

Specified by:

endElement in interface XmlHandler

Parameters:

elementCode - The element's code.

Throws:

XmlException - If any error occurs.

characters

public void characters(char[] string,
                       int start,
                       int length)

For use by ValidatingXmlParser only.

Specified by:

characters in interface XmlHandler

Parameters:

string - The textual content.

start - The index in string at which the textual content starts.

length - The length of the content.

toHTML

public java.lang.String toHTML(java.lang.String mapServerURL)

Converts the query to HTML.

Parameters:

mapServerURL - The template URL of a map server or null. If a URL is specified, it should refer to a service that returns, in the form of a small, inline image, a map depicting a bounding box given the boundary coordinates of the box. The URL should contain four tokens, $N, $S, $E, and $W, that will be replaced by the coordinates of the box. Coordinates are expressed in signed decimal degrees north of the equator and east of the Greenwich meridian. The service can assume that the coordinates are valid. Note that the east boundary will be less than the west boundary if the bounding box crosses the +/-180 meridian. An example of a template:

http://maps-r-us.com/map?width=300&height=150&north=$N&south=$S&east=$E&west=$W&format=gif

Returns:

An HTML fragment consisting of a single <ul> element. The fragment references the following style classes:

<ul class=query>

Identifies the entire query.

<span class=query-bucket>

Identifies a bucket name in a constraint.

<span class=query-field>

Identifies a field name in a constraint.

<span class=query-keyword>

Identifies a boolean keyword in a constraint.

<span class=query-label>

Identifies a label.

<span class=query-operator>

Identifies an operator in a constraint.

<span class=query-value>

Identifies a target value in a constraint.

toXML

public java.lang.String toXML()

Converts the query to XML.

Returns:

A complete XML document.

getCollections

public java.lang.String[] getCollections()

Returns the collection names.

Returns:

The collection names, which should not be modified.

getConstraint

public Query.Constraint getConstraint()

Returns the constraint.

Returns:

The root node of the constraint tree.

getRankingMethod

public java.lang.String getRankingMethod()

Returns the ranking method.

Returns:

The descriptive name of the ranking method or null.

getMaximumResults

public int getMaximumResults()

Returns the maximum number of results.

Returns:

The maximum number of results, or a negative value indicating no limit.

getOriginal

public java.lang.String getOriginal()

Returns the original, XML query.

Returns:

The original query.