org.ocap.hn.content.navigation

Class DatabaseQuery

java.lang.Object

org.ocap.hn.content.navigation.ContentDatabaseFilter

org.ocap.hn.content.navigation.DatabaseQuery

public abstract class DatabaseQuery
extends ContentDatabaseFilter

DatabaseQuery class. This class represents a query of the metadata database. Methods are provided so that complex AND, OR, NOT expressions can be created.

Note that this object is immutable; the and(), or() and negate() methods do not affect this object but return references to a new query.

For example:

 
 DatabaseQuery qa = DatabaseQuery.newInstance("Genre", DatabaseQuery.EQUALS, "3.4.11"); 
 DatabaseQuery qb = DatabaseQuery.newInstance ("SpokenLanguage", DatabaseQuery.EQUALS,"fr-CA"); 
 DatabaseQuery qc = qb.and(qa.negate()); 
 

So the final statement has no effect on the state of qa or qb objects, which still represent non-negated, root predicates.

Version:

1.3

Author:

Alex Ashley, Alexander.Kobzhev, Andrew Hickman

Field Summary

Fields

Modifier and Type	Field and Description
static int	CONTAINS Operator to check for a String being contained within the field The comparison is case insensitive, non whole word.
static int	EQUALS Used to specify a test for equality.
static int	EXISTS Operator to check to see if a field exists
static int	GREATER_THAN Operator to specify greater than .
static int	GREATER_THAN_OR_EQUALS Operator to specify greater than or equals.
static int	LESS_THAN Operator to specify less than .
static int	LESS_THAN_OR_EQUALS Operator to specify less than or equals.
static int	NOT_EQUALS Operator to check for in-equality.

Constructor Summary

Constructors

Constructor and Description
DatabaseQuery()

Method Summary

Methods

Modifier and Type	Method and Description
abstract DatabaseQuery	and(DatabaseQuery query) Create a new DatabaseQuery based upon the logical AND of the predicates represented by this query and the argument query.
abstract DatabaseQuery	and(DatabaseQuery query, String contextNode) Create a new DatabaseQuery object based upon the logical AND of the predicates represented by this query and the argument query.
abstract DatabaseQuery	negate() Create a new DatabaseQuery, which is the logical NOT of this query.
static DatabaseQuery	newInstance(String fieldName, int comparison, String value) Make a new DatabaseQuery for a specific value in a specific field.
abstract DatabaseQuery	or(DatabaseQuery query) Create a new DatabaseQuery based upon the logical OR of the predicates represented by this query and the argument query.

Methods inherited from class org.ocap.hn.content.navigation.ContentDatabaseFilter

accept

Methods inherited from class java.lang.Object

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

Field Detail

EQUALS

public static final int EQUALS

Used to specify a test for equality. For numbers and dates, an exact match is made. For strings, a case-insensitive comparison is made

See Also:

Constant Field Values

GREATER_THAN

public static final int GREATER_THAN

Operator to specify greater than . For numbers the test is "a>b". For Date fields, the test is "a is after b". For strings, the comparison is based on case-insensitive dictionary ordering (i.e. which value occurs first when sorted in alphabetical order). E.g. "dog" > "cat" == true, "Chimp" > "dog" == false

See Also:

Constant Field Values

LESS_THAN

public static final int LESS_THAN

Operator to specify less than . For numbers the test is "a<b". For Date fields, the test is "a is before b". For strings, the comparison is based on case-insensitive dictionary ordering (i.e. which one occurs first when sorted in alphabetical order).

See Also:

Constant Field Values

GREATER_THAN_OR_EQUALS

public static final int GREATER_THAN_OR_EQUALS

Operator to specify greater than or equals. See rules for GREATER_THAN and EQUALS for how non-numeric fields are compared.

See Also:

Constant Field Values

LESS_THAN_OR_EQUALS

public static final int LESS_THAN_OR_EQUALS

Operator to specify less than or equals. See rules for LESS_THAN and EQUALS for how non-numeric fields are compared.

See Also:

Constant Field Values

CONTAINS

public static final int CONTAINS

Operator to check for a String being contained within the field The comparison is case insensitive, non whole word.

See Also:

Constant Field Values

NOT_EQUALS

public static final int NOT_EQUALS

Operator to check for in-equality. NOT_EQUALS follows the same equality checking rules as EQUALS

See Also:

Constant Field Values

EXISTS

public static final int EXISTS

Operator to check to see if a field exists

See Also:

Constant Field Values

Constructor Detail

DatabaseQuery

public DatabaseQuery()

Method Detail

newInstance

public static DatabaseQuery newInstance(String fieldName,
                        int comparison,
                        String value)
                                 throws DatabaseException

Make a new DatabaseQuery for a specific value in a specific field. This is how the root predicates of a query is formed. For example:

 
 DatabaseQuery q1 = DatabaseQuery.newInstance("Title", DatabaseQuery.CONTAINS, "Foxes"); 
 DatabaseQuery q2 = DatabaseQuery.newInstance("Genre", DatabaseQuery.CONTAINS, "3.4.11"); 
 DatabaseQuery the_query = q1.and(q2); 
 

Parameters:

fieldName - The name of the field to compare. This field must be the name of known field ID, i.e. FieldID.getInstance().hasKey(fieldName) must return true.

comparison - The type of comparison to make (CONTAINS, EXISTS, LESS_THAN, etc)

value - The value to check. For numeric fields, the value must be a string that contains a number. For date fields, the value must be a date in an ISO 8601 compliant format (e.g. of the form "2001-01-05T14:30:00Z" or "2001-01-05T15:30:00+01:00"). For fields that contain an item from a classification scheme (e.g. the "Genre" field), the ID of the controlled term must be used (e.g. "3.4.11"). For comparison==DatabaseQuery.EXISTS, this parameter is not used (it is safe to pass null in this case).

Throws:

DatabaseException - if the specified fieldName is unknown, if the comparison is unknown or value is invalid.

and

public abstract DatabaseQuery and(DatabaseQuery query)
                           throws DatabaseException

Create a new DatabaseQuery based upon the logical AND of the predicates represented by this query and the argument query.

Parameters:

query - The second predicate for the AND

Throws:

DatabaseException - if the AND of these two queries is known to be invalid

and

public abstract DatabaseQuery and(DatabaseQuery query,
                String contextNode)
                           throws DatabaseException

Create a new DatabaseQuery object based upon the logical AND of the predicates represented by this query and the argument query. The resulting predicate will only match within the scope of the specified node. For example:

 
 DatabaseQuery a = DatabaseQuery.newInstance("Title",DatabaseQuery.CONTAINS,"grave"); 
 DatabaseQuery b = DatabaseQuery.newInstance("TitleLanguage",DatabaseQuery.EQUALS,"en"); 
 DatabaseQuery query = a.and(b,"Title"); 
 

will cause a search for a title that contains the name "grave" and has an English language title, within the same title node. Without the context node, a valid match would be found for:

 Dilemme 
 Grave Serious 
 Dilemma 

because there is a title with lang="en" and a title which contains "grave".

Parameters:

query - The second predicate for the AND

contextNode - The node within which all of the AND must be satisfied. This node must be the name of known field ID, (i.e. FieldID.getInstance().hasKey(fieldName) must return true) and must be a node that is at least the highest level element represented by the two predicates (i.e. the context node is not a child node of either predicate).

Throws:

DatabaseException - if the AND of these two queries is known to be invalid, or the contextNode is invalid

or

public abstract DatabaseQuery or(DatabaseQuery query)
                          throws DatabaseException

Create a new DatabaseQuery based upon the logical OR of the predicates represented by this query and the argument query.

Parameters:

query - The second predicate for the OR

Throws:

DatabaseException - if the OR of these two queries is known to be invalid

negate

public abstract DatabaseQuery negate()

Create a new DatabaseQuery, which is the logical NOT of this query.

Returns:

a new DatabaseQuery object that is the logical negative of this object.