org.dvb.tvanytime.metadata
Class DatabaseQuery

java.lang.Object
  extended by org.dvb.tvanytime.metadata.DatabaseQuery

public abstract class DatabaseQuery
extends java.lang.Object

Class representing 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.

See Also:
Database, DatabaseQueryResult

Field Summary
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 See rules for GREATER_THAN and EQUALS for how non-numeric fields are compared.
static int LESS_THAN
          Operator to specify less than .
static 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.
static int NOT_EQUALS
          Operator to check for in-equality.
 
Constructor Summary
DatabaseQuery()
           
 
Method Summary
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, java.lang.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(java.lang.String fieldID, int comparison, java.lang.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 java.lang.Object
equals, 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-insentitive 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(java.lang.String fieldID,
                                        int comparison,
                                        java.lang.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, "urn:tva:metadata:cs:ContentCS:2004:3.4.11"); 
 DatabaseQuery the_query = q1.and(q2); 

Parameters:
fieldID - the name of the field to compare. This must be the name of a known fieldID, i.e. the containsKey(fieldID) method of the appropriate FieldIDDefinitionList 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), a reference to a controlled term must be used (e.g. "urn:tva:metadata:cs:ContentCS:2004:3.4.11"). For comparison==DatabaseQuery.EXISTS, this parameter is not used (it is safe to pass null in this case).
Returns:
a DatabaseQuery object
Throws:
DatabaseException - is 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
Returns:
a DatabaseQuery object
Throws:
DatabaseException - if the AND of these two queries is known to be invalid

and

public abstract DatabaseQuery and(DatabaseQuery query,
                                  java.lang.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("Title",DatabaseQuery.CONTAINS,"grave"); DatabaseQuery 
 b("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:
 <tva:ShortTitle xml:lang="fr">Dilemme Grave</tva:ShortTitle>
 <tva:ShortTitle xml:lang="en">Serious Dilemma</tva:ShortTitle> 
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 a known fieldID, (i.e. the containsKey(fieldID) method of the appropriate FieldIDDefinitionList must return true) and must be a node that is at least the heighest level element represented by the two predicates (i.e. the context node is not a child node of either predicate).
Returns:
a DatabaseQuery object
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
Returns:
a DatabaseQuery object
Throws:
DatabaseException - if the AND 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.