com.arsdigita.persistence
Class DataQueryDecorator

java.lang.Object
  extended bycom.arsdigita.persistence.DataQueryDecorator
All Implemented Interfaces:
DataQuery
Direct Known Subclasses:
DataQueryDataCollectionAdapter

public class DataQueryDecorator
extends Object
implements DataQuery

Decorate a data query so that its behavior can be changed and additional methods can be added to a stock data query.

Version:
$Id: //core-platform/dev/src/com/arsdigita/persistence/DataQueryDecorator.java#10 $
Author:
David Lutterkort

Constructor Summary
DataQueryDecorator(DataQuery dq)
          Decorate the data query dq.
DataQueryDecorator(String queryName)
          Retrieve the query with name queryName and decorate it.
 
Method Summary
 Filter addEqualsFilter(String attribute, Object value)
          This creates the appropriate SQL for the given attribute and passed in value.
 Filter addFilter(Filter filter)
          This adds the passed in filter to this query and ANDs it with an existing filters.
 Filter addFilter(String conditions)
          Adds the conditions to the filter that will be used on this query.
 Filter addInSubqueryFilter(String propertyName, String subqueryName)
          Add an 'in' subquery to a query.
 Filter addInSubqueryFilter(String property, String subQueryProperty, String subqueryName)
          Highly experimental; use with caution..
 Filter addNotEqualsFilter(String attribute, Object value)
          This creates the appropriate SQL for the given attribute and passed in value.
 Filter addNotInSubqueryFilter(String propertyName, String subqueryName)
           
 void addOrder(String order)
          Set the order in which the result of this query will be returned.
 void addOrderWithNull(String orderOne, Object orderTwo, boolean isAscending)
          This adds order on the first value if it is not null or the second value if the first value is null.
 void addPath(String path)
          Adds to the set of paths fetched by this DataQuery.
 void alias(String fromPrefix, String toPrefix)
          Alias a compound property name to a different value.
 void clearFilter()
          Clears the current filter for the data query.
 void clearOrder()
          Clears the current order clause for the data query.
 void close()
          Explicitly closes this DataQuery.
 boolean first()
          Moves the cursor to the first row in the query.
 Object get(String propertyName)
          Returns the value of the propertyName property associated with the current position in the sequence.
protected  DataQuery getDataQuery()
           
 FilterFactory getFilterFactory()
          This retrieves the factory that is used to create the filters for this DataQuery
 Object getParameter(String parameterName)
          Allows a caller to get a parameter value for a parameter that has already been set
 int getPosition()
          Returns the current position within the sequence.
 Map getPropertyValues()
          This method returns a map of all property/value pairs.
 CompoundType getType()
          Returns the type of this data query.
 boolean hasProperty(String propertyName)
          Returns true if this query fetches the given property.
 boolean isAfterLast()
          Indicates whether the cursor is after the last row of the query.
 boolean isBeforeFirst()
          Indicates whether the cursor is before the first row of the query.
 boolean isEmpty()
          Returns true if the query has no rows.
 boolean isFirst()
          Indicates whether the cursor is on the first row of the query.
 boolean isLast()
          Indicates whether the cursor is on the last row of the query.
 boolean last()
          Moves the cursor to the last row in the query.
 boolean next()
          Moves the cursor to the next row in the sequence.
 boolean previous()
          Moves to the previous row in the query.
 boolean removeFilter(Filter filter)
          Removes the passed in filter from this query if it was directly added to the query.
 void reset()
          Returns the data query to its initial state by rewinding it and clearing any filters or ordering.
 void rewind()
          Rewinds the row sequence to the beginning.
 Filter setFilter(String conditions)
          Sets a filter for this query.
 void setOrder(String order)
          Set the order in which the result of this query will be returned.
 void setParameter(String parameterName, Object value)
          Allows a user to bind a parameter within a named query.
 void setRange(Integer beginIndex)
          This method allows the developer to set the range of rows desired.
 void setRange(Integer beginIndex, Integer endIndex)
          This method allows the developer to set the range of rows desired.
 void setReturnsLowerBound(int lowerBound)
          This sets the lower bound on the number of rows that can be returned by this query
 void setReturnsUpperBound(int upperBound)
          This sets the upper bound on the number of rows that can be returned by this query
 long size()
          Returns the size of this query.
 String toString()
           
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

DataQueryDecorator

public DataQueryDecorator(DataQuery dq)
Decorate the data query dq.

Parameters:
dq - the data query to decorate

DataQueryDecorator

public DataQueryDecorator(String queryName)
Retrieve the query with name queryName and decorate it.

Parameters:
queryName - the name of the data query to decorate.
Method Detail

getType

public CompoundType getType()
Description copied from interface: DataQuery
Returns the type of this data query.

Specified by:
getType in interface DataQuery

hasProperty

public boolean hasProperty(String propertyName)
Description copied from interface: DataQuery
Returns true if this query fetches the given property.

Specified by:
hasProperty in interface DataQuery
Parameters:
propertyName - A property name.
Returns:
True if this query fetches the given property.

rewind

public void rewind()
Description copied from interface: DataQuery
Rewinds the row sequence to the beginning. It's as if next() was never called.

Specified by:
rewind in interface DataQuery

get

public Object get(String propertyName)
Description copied from interface: DataQuery
Returns the value of the propertyName property associated with the current position in the sequence.

Specified by:
get in interface DataQuery
Parameters:
propertyName - the name of the property
Returns:
the value of the property

getPosition

public int getPosition()
Description copied from interface: DataQuery
Returns the current position within the sequence. The first position is 1.

Specified by:
getPosition in interface DataQuery
Returns:
the current position; 0 if there is no current position

next

public boolean next()
Description copied from interface: DataQuery
Moves the cursor to the next row in the sequence.

Specified by:
next in interface DataQuery
Returns:
true if the new current row is valid; false if there are no more rows.

size

public long size()
Description copied from interface: DataQuery
Returns the size of this query.

Specified by:
size in interface DataQuery
Returns:
the number of rows.

reset

public void reset()
Description copied from interface: DataQuery
Returns the data query to its initial state by rewinding it and clearing any filters or ordering.

Specified by:
reset in interface DataQuery

first

public boolean first()
              throws PersistenceException
Description copied from interface: DataQuery
Moves the cursor to the first row in the query. Not implemented yet.

Specified by:
first in interface DataQuery
Returns:
true if the cursor is on a valid row; false if there are no rows in the query.
Throws:
PersistenceException - Always thrown!

isEmpty

public boolean isEmpty()
                throws PersistenceException
Description copied from interface: DataQuery
Returns true if the query has no rows.

Specified by:
isEmpty in interface DataQuery
Returns:
true if the query has no rows; false otherwise
Throws:
PersistenceException

isBeforeFirst

public boolean isBeforeFirst()
                      throws PersistenceException
Description copied from interface: DataQuery
Indicates whether the cursor is before the first row of the query.

Specified by:
isBeforeFirst in interface DataQuery
Returns:
true if the cursor is before the first row; false if the cursor is at any other position or the result set contains rows.
Throws:
PersistenceException

isFirst

public boolean isFirst()
                throws PersistenceException
Description copied from interface: DataQuery
Indicates whether the cursor is on the first row of the query.

Specified by:
isFirst in interface DataQuery
Returns:
true if the cursor is on the first row; false otherwise
Throws:
PersistenceException

isLast

public boolean isLast()
               throws PersistenceException
Description copied from interface: DataQuery
Indicates whether the cursor is on the last row of the query. Note: Calling the method isLast may be expensive because the JDBC driver might need to fetch ahead one row in order to determine whether the current row is the last row in the result set.

If the query has not yet been executed, it executes the query.

Not implemented yet.

Specified by:
isLast in interface DataQuery
Returns:
True if the cursor is on the last row, false otherwise.
Throws:
PersistenceException

isAfterLast

public boolean isAfterLast()
                    throws PersistenceException
Description copied from interface: DataQuery
Indicates whether the cursor is after the last row of the query.

Specified by:
isAfterLast in interface DataQuery
Returns:
True if the cursor is after the last row, false if the cursor is at any other position or the result set contains no rows.
Throws:
PersistenceException

last

public boolean last()
             throws PersistenceException
Description copied from interface: DataQuery
Moves the cursor to the last row in the query. Not implemented yet.

Not implemented yet.

Specified by:
last in interface DataQuery
Returns:
true if the new current row is valid; false if there are no rows in the query
Throws:
PersistenceException - Always thrown!

previous

public boolean previous()
                 throws PersistenceException
Description copied from interface: DataQuery
Moves to the previous row in the query. Not implemented yet.

Specified by:
previous in interface DataQuery
Returns:
true if the new current row is valid; false otherwise
Throws:
PersistenceException - Always thrown!

addPath

public void addPath(String path)
Description copied from interface: DataQuery
Adds to the set of paths fetched by this DataQuery. The path is specified by a series of identifiers seperated by dots ('.'). ID properties are automatically added as necessary.
 DataQuery query = ssn.retrieve("exampleQuery");
 query.addPath("foo.bar.name");
 query.addPath("foo.bar.desc");
 while (query.next()) {
     BigInteger id = query.get("foo.bar.id");
     String name = query.get("foo.bar.name");
     String desc = query.get("foo.bar.desc");
 }
 

Specified by:
addPath in interface DataQuery
Parameters:
path - the additional path to fetch

setFilter

public Filter setFilter(String conditions)
Description copied from interface: DataQuery
Sets a filter for this query. The filter consists of a set of SQL condition specified in terms of the properties of this query. The conditions may be combined with "and" and "or". Bind variables may be used in the body of the filter. The values are set by using the set method on the Filter object that is returned.
 Filter f = query.setFilter("id < :maxId and id > :minId");
 f.set("maxId", 10);
 f.set("minId", 1);
 

Specified by:
setFilter in interface DataQuery
Parameters:
conditions - the conditions for the filter
Returns:
the newly created filter for this query

addFilter

public Filter addFilter(String conditions)
Description copied from interface: DataQuery
Adds the conditions to the filter that will be used on this query. If a filter already exists, this alters the filter object and returns the altered object. If one does not already exist, it creates a new filter. When adding filters the user should be aware that their query is wrapped and the filter is appended to the wrapped query. That is, your query will look like the following:

        select * from (<data query here>) results
        where <conditions here>
        

When adding filters, the user should not use the same parameter name in multiple filters. That is, the following will not work

 
 Filter filter = query.addFilter("priority > :bound");
 filter.set("bound", new Integer(3));
 filter = query.addFilter("priority < :bound");
 filter.set("bound", new Integer(8));
 
 
The above actually evaluates to "priority < 8 and priority > 8" which is clearly not what the developer wants.

The following will work.

 
 Filter filter = query.addFilter("priority > :lowerBound");
 filter.set("lowerBound", new Integer(3));
 filter = query.addFilter("priority < :upperBound");
 filter.set("upperBound", new Integer(8));
 
 
It is actually the same as
 
 Filter filter = query.addFilter("priority > :lowerBound
                                  and priority < :uperBound");
 filter.set("upperBound", new Integer(8));
 filter.set("lowerBound", new Integer(3));
 
 

Specified by:
addFilter in interface DataQuery
Parameters:
conditions - The conditions for the filter. This is a string that should be used to filter the DataQuery. Specifically, if this is the first filter added, it appends the information on to a view-on-the-fly. e.g.

        select * from (<data query here>) results
        where <conditions here>
        
unless the WRAP_QUERIES option for the DataQuery is set to "false". If this is the case, the Filter is simply appended to the end of the query as follows:

        <data query here>)
        [where | or] <conditions here>
        
It should normally take the form of

        <attribute_name> <condition> <attribute bind variable>
        
where the "condition" is something like "=", "<", ">", or "!=". The "bind variable" should be a colon followed by some attribute name that will later be set with a call to Filter.set(java.lang.String, java.lang.Object)

It is possible to set multiple conditions with a single addFilter statement by combining the conditions with an "and" or an "or". Conditions may be grouped by using parentheses. Consecutive calls to addFilter append the filters using "and".

If there is already a filter that exists for this query then the passed in conditions are added to the current conditions with an AND like (<current conditions>) and (< passed in conditions>)

Returns:
The filter that has just been added to the query

addFilter

public Filter addFilter(Filter filter)
Description copied from interface: DataQuery
This adds the passed in filter to this query and ANDs it with an existing filters. It returns the filter for this query.

Specified by:
addFilter in interface DataQuery

removeFilter

public boolean removeFilter(Filter filter)
Description copied from interface: DataQuery
Removes the passed in filter from this query if it was directly added to the query. To remove a filter that was added to a CompoundFilter, you must call CompoundFilter.removeFilter().

Specified by:
removeFilter in interface DataQuery

addInSubqueryFilter

public Filter addInSubqueryFilter(String propertyName,
                                  String subqueryName)
Description copied from interface: DataQuery
Add an 'in' subquery to a query.

Specified by:
addInSubqueryFilter in interface DataQuery
Parameters:
propertyName - The column to be filtered on.
subqueryName - The full name of a query defined in a PDL file.

addInSubqueryFilter

public Filter addInSubqueryFilter(String property,
                                  String subQueryProperty,
                                  String subqueryName)
Description copied from interface: DataQuery
Highly experimental; use with caution.. Add an 'in' subquery to a query. This version can be used with subqueries which return more than 1 column as it wraps the subquery. subQueryProperty is the column pulled out of the subquery.

Specified by:
addInSubqueryFilter in interface DataQuery
Parameters:
property - The column to be filtered on.
subQueryProperty - The column in the subquery to be used.
subqueryName - The full name of a query defined in a PDL file.
Returns:
The Filter object associated with this filter.

addNotInSubqueryFilter

public Filter addNotInSubqueryFilter(String propertyName,
                                     String subqueryName)
Specified by:
addNotInSubqueryFilter in interface DataQuery

addEqualsFilter

public Filter addEqualsFilter(String attribute,
                              Object value)
Description copied from interface: DataQuery
This creates the appropriate SQL for the given attribute and passed in value. It creates a filter for "attribute = 'value.toString()'" unless the value is an integer (in which case it creates "attribute = value.toString()") or the developer is using oracle and the value is null. In this case, it would create "attribute is null".

This is simply a convenience method for addFilter(getFilterFactory().equals(attribute, value));

Specified by:
addEqualsFilter in interface DataQuery
Parameters:
attribute - The name of the attribute to bind with the value
value - The value for the specified attribute

addNotEqualsFilter

public Filter addNotEqualsFilter(String attribute,
                                 Object value)
Description copied from interface: DataQuery
This creates the appropriate SQL for the given attribute and passed in value. It creates a filter for "attribute = 'value.toString()'" unless the value is an integer (in which case it creates "attribute != value.toString()") or the developer is using oracle and the value is null. In this case, it would create "attribute is not null".

This is simply a convenience method for addFilter(getFilterFactory().notEquals(attribute, value));

Specified by:
addNotEqualsFilter in interface DataQuery
Parameters:
attribute - The name of the attribute to bind with the value
value - The value for the specified attribute

clearFilter

public void clearFilter()
Description copied from interface: DataQuery
Clears the current filter for the data query.

Specified by:
clearFilter in interface DataQuery

getFilterFactory

public FilterFactory getFilterFactory()
Description copied from interface: DataQuery
This retrieves the factory that is used to create the filters for this DataQuery

Specified by:
getFilterFactory in interface DataQuery

setOrder

public void setOrder(String order)
              throws PersistenceException
Description copied from interface: DataQuery
Set the order in which the result of this query will be returned. The string passed is a standard SQL order by clause specified in terms of the properties. For example:
 query.setOrder("creationDate desc, id");
 

Specified by:
setOrder in interface DataQuery
Throws:
PersistenceException

addOrder

public void addOrder(String order)
              throws PersistenceException
Description copied from interface: DataQuery
Set the order in which the result of this query will be returned. The string passed is a standard SQL order by clause specified in terms of the properties. For example:
 query.addOrder("creationDate desc, id");
 

Specified by:
addOrder in interface DataQuery
Parameters:
order - This String parameter specifies the ordering of the output. This should be a comma seperated list of Attribute names (not the database column names) in the order of precedence. Separating attributes by commas is the same as calling addOrder multiple times, each with the next attribute. For instance, this

              addOrder("creationDate");
              addOrder("creationUser");
              
is the same as

              addOrder("creationDate, creationUser");
              

If the items should be ordered in ascending order, the attribute name should be followed by the word "asc" If the items should be ordered in descending order, the attribute should be followed by the word "desc" For instance, or order by ascending date and descending user (for users created with the same date), you would use the following:


              addOrder("creationDate asc, creationUser desc");
              
Throws:
PersistenceException

addOrderWithNull

public void addOrderWithNull(String orderOne,
                             Object orderTwo,
                             boolean isAscending)
Description copied from interface: DataQuery
This adds order on the first value if it is not null or the second value if the first value is null. This is similar to doing an addOrder(nvl(columnOne, columnTwo))

Specified by:
addOrderWithNull in interface DataQuery
Parameters:
orderOne - This is typically the column that will be used for the ordering. If this column is null then the value of orderTwo is used for the ordering
orderTwo - This is typically an actual value (such as -1) but can also be a column name the value used for the ordering
isAscending - If this is true then the items are ordered in ascending order. Otherwise, they are ordering in descending order

clearOrder

public void clearOrder()
Description copied from interface: DataQuery
Clears the current order clause for the data query.

Specified by:
clearOrder in interface DataQuery

setParameter

public void setParameter(String parameterName,
                         Object value)
Description copied from interface: DataQuery
Allows a user to bind a parameter within a named query.

Specified by:
setParameter in interface DataQuery
Parameters:
parameterName - The name of the parameter to bind
value - The value to assign to the parameter

getParameter

public Object getParameter(String parameterName)
Description copied from interface: DataQuery
Allows a caller to get a parameter value for a parameter that has already been set

Specified by:
getParameter in interface DataQuery
Parameters:
parameterName - The name of the parameter to retrieve
Returns:
This returns the object representing the value of the parameter specified by the name or "null" if the parameter value has not yet been set.

setRange

public void setRange(Integer beginIndex)
Description copied from interface: DataQuery
This method allows the developer to set the range of rows desired. Thus, the DataQuery will only return the rows between beginIndex and endIndex. The range begins at the specified beginIndex and returns all rows after that. Thus, if a query returns 30 rows and the beginIndex is set to 6, the last 25 rows of the query will be returned.

Specified by:
setRange in interface DataQuery
Parameters:
beginIndex - This is the number of the first row that should be returned by this query. Setting beginIndex to 1 returns all rows. This is inclusive.

setRange

public void setRange(Integer beginIndex,
                     Integer endIndex)
Description copied from interface: DataQuery
This method allows the developer to set the range of rows desired. Thus, the DataQuery will only return the rows between beginIndex and endIndex. The range begins at the specified beginIndex and extends to the row at index endIndex - 1. Thus the number of rows returned is endIndex-beginIndex.

Specified by:
setRange in interface DataQuery
Parameters:
beginIndex - This is the number of the first row that should be returned by this query. Setting beginIndex to 1 returns the rows from the beginning. This is inclusive.
endIndex - This is the number of the row after the last row that should be returned. That is, this is exclusive (specifying beginIndex = 1 and endIndex = 10 returns 9 rows);

getPropertyValues

public Map getPropertyValues()
Description copied from interface: DataQuery
This method returns a map of all property/value pairs. This essentially allows a single "row" of the query to be passed around.

Specified by:
getPropertyValues in interface DataQuery

setReturnsUpperBound

public void setReturnsUpperBound(int upperBound)
Description copied from interface: DataQuery
This sets the upper bound on the number of rows that can be returned by this query

Specified by:
setReturnsUpperBound in interface DataQuery

setReturnsLowerBound

public void setReturnsLowerBound(int lowerBound)
Description copied from interface: DataQuery
This sets the lower bound on the number of rows that can be returned by this query

Specified by:
setReturnsLowerBound in interface DataQuery

alias

public void alias(String fromPrefix,
                  String toPrefix)
Description copied from interface: DataQuery
Alias a compound property name to a different value. Use the empty string ("") to add a prefix to all compound property names that don't match any other aliases.

Specified by:
alias in interface DataQuery
Parameters:
fromPrefix - the prefix that you're mapping from i.e., the prefix in the PDL file.
toPrefix - the prefix that you're mapping to i.e., the prefix that the programmer is going to use.

close

public void close()
Description copied from interface: DataQuery
Explicitly closes this DataQuery. Query should automatically be closed when next returns false, but this method should be explicitly called in the case where all of the data in a query is not needed (e.g. a "while (next())" loop is exited early or only one value is retrieved with if (next()) {...}).

Specified by:
close in interface DataQuery

toString

public String toString()

getDataQuery

protected DataQuery getDataQuery()


Copyright (c) 2004 Red Hat, Inc. Corporation. All Rights Reserved. Generated at July 21 2004:2337 UTC