com.kabira.platform

Class KeyQuery<T>

java.lang.Object

com.kabira.platform.KeyQuery<T>

public final class KeyQuery<T>
extends java.lang.Object

Class used to define a query and obtain results using keys.

Instances of this class are created by KeyManager, so it has no public constructors.

Once a query is defined, it may be executed multiple times.

Method Summary

Methods

Modifier and Type	Method and Description
int	cardinality() Returns the number of instances of the given key.
void	defineQuery(KeyFieldValueList keyFields) Defines the fields that form a key query.
void	defineQuery(KeyFieldValueRangeList keyFields) Defines the fields that form a range query.
T	getMaximumResult(LockMode objectLock) Returns the maximum value for the given ordered key.
T	getMinimumResult(LockMode objectLock) Returns the mininum value for the given ordered key.
T	getOrCreateSingleResult(LockMode objectLock, KeyFieldValueList additionalFields) Returns the instance for the given unique key.
java.lang.Iterable<T>	getResults(KeyOrderedBy orderBy, LockMode objectLock) Returns the results for a query using an ordered key.
java.lang.Iterable<T>	getResults(LockMode objectLock) Returns the results of a query.
T	getSingleResult(LockMode objectLock) Returns the instance matching the given unique key.
java.lang.String	toString() Creates a human readable query string.

Methods inherited from class java.lang.Object

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

Method Detail

getResults

public java.lang.Iterable<T> getResults(LockMode objectLock)
                                 throws KeyIncompleteError

Returns the results of a query.

Parameters:

objectLock - LockMode to apply to each instance returned.

Returns:

Iterable containing set.

Throws:

KeyIncompleteError - All the fields for the key have not been defined.

Executes the previously defined query and returns the resulting set. For ordered keys, the default orderBy of ASCENDING is used.

getResults

public java.lang.Iterable<T> getResults(KeyOrderedBy orderBy,
                               LockMode objectLock)
                                 throws KeyIncompleteError

Returns the results for a query using an ordered key.

Parameters:

orderBy -

objectLock -

Returns:

Iterable containing set.

Throws:

KeyIncompleteError - All the fields for the key have not been defined.

KeyIllegalKeyTypeError - The key is not ordered.

Executes the previously defined query and returns the resulting set.

getSingleResult

public T getSingleResult(LockMode objectLock)
                  throws KeyIncompleteError,
                         KeyIllegalKeyTypeError

Returns the instance matching the given unique key.

Parameters:

objectLock - The object lock applied if an instance is found.

Returns:

Object containing result, or null if key not found.

Throws:

KeyIncompleteError - The fields for the key have not been defined.

KeyIllegalKeyTypeError - The key is not unique.

Executes the previously defined query and returns an instance.

getMinimumResult

public T getMinimumResult(LockMode objectLock)
                   throws KeyMalformedQueryError,
                          KeyIllegalKeyTypeError

Returns the mininum value for the given ordered key.

Parameters:

objectLock - The object lock applied if an instance is found.

Returns:

Object containing result, or null if key not found.

Throws:

KeyIllegalKeyTypeError - The key is not ordered.

KeyMalformedQueryError - An illegal operator was used when defining the query.

Executes the previously defined query (if any) and returns an instance containing the minimum value. If no query was defined, the instance containing the minimum key is returned. If a query was defined, the instance containing the minimum key value that matches the given fields is returned.

getMaximumResult

public T getMaximumResult(LockMode objectLock)
                   throws KeyMalformedQueryError,
                          KeyIllegalKeyTypeError

Returns the maximum value for the given ordered key.

Parameters:

objectLock - The object lock applied if an instance is found.

Returns:

Object containing result, or null if key not found.

Throws:

KeyIllegalKeyTypeError - The key is not ordered.

KeyMalformedQueryError - An illegal operator was used when defining the query.

Executes the previously defined query (if any) and returns an instance containing the maximum value. If no query was defined, the instance containing the maximum key is returned. If a query was defined, the instance containing the maximum key value that matches the given fields is returned.

getOrCreateSingleResult

public T getOrCreateSingleResult(LockMode objectLock,
                        KeyFieldValueList additionalFields)
                          throws KeyIncompleteError,
                                 KeyIllegalKeyTypeError,
                                 KeyIllegalFieldError

Returns the instance for the given unique key.

Parameters:

objectLock - The object lock applied if a pre-existing instance is found.

additionalFields - Additional field values to use if an instance in created. These values are ignored if the instance already exists. null can be specified if no additional field values are needed.

Returns:

Object containing result.

Throws:

KeyIncompleteError - The fields for the key have not been defined.

KeyIllegalKeyTypeError - The key is not unique.

KeyIllegalFieldError - A field in the additionalFields list is not valid.

Executes the previously defined query and returns an instance. This method will atomically insure that an instance of the type will be created when searching for a instance by key. The additionalFields list passed in allows the programmer to populate secondary key fields if the instance is created. This should be used instead of doing:

KeyedObject ko = kq.getSingleResult(lockMode);
if (ko == null)
{
    ko = new KeyedObject(keys);
}

The above new can throw an ObjectNotUniqueError exception if another transaction creates the instance between the getSingleResult() and the new call.

cardinality

public int cardinality()
                throws KeyIncompleteError

Returns the number of instances of the given key.

Returns:

Number of instances.

Throws:

KeyIncompleteError - All the fields for the key have not been defined.

Executes the previously defined query and returns the number of instances that would result.

No transaction locks are take when this method executes. This means the number returned by cardinality() may change even if called multiple times within a single transaction.

defineQuery

public void defineQuery(KeyFieldValueList keyFields)
                 throws KeyIllegalFieldError,
                        KeyMalformedQueryError

Defines the fields that form a key query.

Parameters:

keyFields - The fields to use.

Throws:

KeyIncompleteError - All the fields for the key have not been defined.

KeyIllegalFieldError - A given field is not part of the key.

KeyMalformedQueryError - The resulting key lookup cannot perform a range query on an ordered key, or duplicate fields exist for a non-ordered key.

When executed, this defines the values used for a key lookup. Any previous query is overwritten.

defineQuery

public void defineQuery(KeyFieldValueRangeList keyFields)
                 throws KeyIllegalFieldError,
                        KeyMalformedQueryError

Defines the fields that form a range query.

Parameters:

keyFields - The fields to use.

Throws:

KeyIllegalFieldError - A given field is not part of the key.

KeyMalformedQueryError - The resulting key lookup cannot perform a range query on an ordered key, duplicate fields are defined for a non-ordered key, or a range query was attempted on a non-ordered key.

When executed, this defines the values used for a range query on an ordered key. Any previous query is overwritten.

toString

public java.lang.String toString()
                          throws KeyIncompleteError

Creates a human readable query string.

Overrides:

toString in class java.lang.Object

Throws:

KeyIncompleteError - All the fields for the key have not been defined.

This method returns a string containing a "select" or "for" statement. The string also contains any optimization warnings for the defined query. This information can be used to help diagnose queries.