com.arsdigita.persistence
Interface DataAssociation

All Superinterfaces:
DataCollection, DataQuery

public interface DataAssociation
extends DataCollection

This is used to represent the relationship between two objects.

It is important to note that when the deprecated methods in this class are removed, this class will no longer extend DataCollection. If you want something that extends DataCollection, use DataAssociationCursor instead.

Version:
$Revision: #11 $ $Date: 2004/04/07 $
Author:
rhs@mit.edu, randyg@alum.mit.edu

Field Summary
static String versionId
           
 
Method Summary
 DataObject add(DataObject object)
          Adds object to the persistent association.
 Filter addFilter(String conditions)
          Deprecated. use cursor().addFilter(String conditions)
 void addOrder(String order)
          Deprecated. use cursor().addOrder(String order)
 void clear()
          Removes all the objects in the persistent association.
 void clearFilter()
          Deprecated. use cursor().clearFilter()
 void clearOrder()
          Deprecated. use cursor().clearOrder()
 void close()
          Deprecated. use cursor().close()
 DataAssociationCursor cursor()
          Returns a data association iterator that allows users to iterate through all of the data associations This is a convenience method for getDataAssociationCursor()
 boolean first()
          Deprecated. use cursor().first()
 Object get(String propertyName)
          Deprecated. use cursor().get()
 DataAssociationCursor getDataAssociationCursor()
          Returns a data association iterator that allows users to iterate through all of the data associations
 DataCollection getDataCollection()
          Returns a data collection containing all the objects in this association.
 DataObject getDataObject()
          Deprecated. use cursor().getDataObject()
 Object getLinkProperty(String name)
          Deprecated. Use cursor().getLinkProperty
 ObjectType getObjectType()
          Deprecated. use cursor().getObjectType()
 Object getParameter(String parameterName)
          Deprecated. use cursor().getParameter(String parameterName)
 int getPosition()
          Deprecated. use cursor().getPosition()
 boolean isEmpty()
          Deprecated. use cursor().isEmpty()
 boolean isFirst()
          Deprecated. use cursor().isFirst()
 boolean isLast()
          Deprecated. use cursor().isLast()
 boolean isModified()
          Returns true if the collection has been modified.
 boolean last()
          Deprecated. use cursor().last()
 boolean next()
          Deprecated. use cursor().next()
 boolean previous()
          Deprecated. use cursor().previous()
 void remove()
          Deprecated. Use remove(DataObject object) or cursor(), loop through the object and then call remove()
 void remove(DataObject object)
          Removes object from the collection.
 void remove(OID oid)
          Removes object from the collection.
 void reset()
          Deprecated. use cursor().reset()
 void rewind()
          Deprecated. use cursor().rewind()
 Filter setFilter(String conditions)
          Deprecated. see #addFilter
 void setOrder(String order)
          Deprecated. see #addOrder
 void setParameter(String parameterName, Object value)
          Deprecated. use cursor().setParameter(Strin parameterName, Object value)}
 long size()
          Deprecated. use cursor().size()
 
Methods inherited from interface com.arsdigita.persistence.DataCollection
contains, contains
 
Methods inherited from interface com.arsdigita.persistence.DataQuery
addEqualsFilter, addFilter, addInSubqueryFilter, addInSubqueryFilter, addNotEqualsFilter, addNotInSubqueryFilter, addOrderWithNull, addPath, alias, getFilterFactory, getPropertyValues, getType, hasProperty, isAfterLast, isBeforeFirst, removeFilter, setRange, setRange, setReturnsLowerBound, setReturnsUpperBound
 

Field Detail

versionId

public static final String versionId
See Also:
Constant Field Values
Method Detail

add

public DataObject add(DataObject object)
Adds object to the persistent association. Note: The object does NOT truly become part of the association until save() is called on the association's parent object. This means, for example, that cursor() will return the same cursor that it did before any objects are added.

Parameters:
object - The object to add.

clear

public void clear()
Removes all the objects in the persistent association.


getDataCollection

public DataCollection getDataCollection()
Returns a data collection containing all the objects in this association.


getDataAssociationCursor

public DataAssociationCursor getDataAssociationCursor()
Returns a data association iterator that allows users to iterate through all of the data associations


cursor

public DataAssociationCursor cursor()
Returns a data association iterator that allows users to iterate through all of the data associations This is a convenience method for getDataAssociationCursor()


getLinkProperty

public Object getLinkProperty(String name)
Deprecated. Use cursor().getLinkProperty

Calls get("link." + name).

Parameters:
name - The name of the link property.
Returns:
The property value.

remove

public void remove()
Deprecated. Use remove(DataObject object) or cursor(), loop through the object and then call remove()

Removes the object associated with the current position in the collection.


remove

public void remove(DataObject object)
Removes object from the collection. Note: The object does NOT truly get removed from the association until save() is called on the association's parent object. This means, for example, that cursor() will return the same cursor that it did before any objects are added.

Parameters:
object - The object to remove.

remove

public void remove(OID oid)
Removes object from the collection. Note: The object does NOT truly get removed from the association until save() is called on the association's parent object. This means, for example, that cursor() will return the same cursor that it did before any objects are added.

Parameters:
oid - The OID of the object to remove.

isModified

public boolean isModified()
Returns true if the collection has been modified.

Returns:
True if modified, false otherwise.

rewind

public void rewind()
Deprecated. use cursor().rewind()

Rewinds the data query to the beginning, i.e. it's as if next() was never called.

Specified by:
rewind in interface DataQuery

reset

public void reset()
Deprecated. use cursor().reset()

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
Deprecated. use cursor().first()

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!

get

public Object get(String propertyName)
           throws PersistenceException
Deprecated. use cursor().get()

Returns the value of the propertyName property associated with the current position in the query.

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

getPosition

public int getPosition()
                throws PersistenceException
Deprecated. use cursor().getPosition()

Returns the current position within the query. The first position is 1.

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

isEmpty

public boolean isEmpty()
                throws PersistenceException
Deprecated. use cursor().isEmpty()

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

isFirst

public boolean isFirst()
                throws PersistenceException
Deprecated. use cursor().isFirst()

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
Deprecated. use cursor().isLast()

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.

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

last

public boolean last()
             throws PersistenceException
Deprecated. use cursor().last()

Moves the cursor to the last row in the query. 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!

next

public boolean next()
             throws PersistenceException
Deprecated. use cursor().next()

Moves the cursor to the next row in the query.

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

previous

public boolean previous()
                 throws PersistenceException
Deprecated. use cursor().previous()

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!

setFilter

public Filter setFilter(String conditions)
Deprecated. see #addFilter

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)
Deprecated. use cursor().addFilter(String conditions)

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 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 < 3 and priority > 3" which is clearly now 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 represent part of a SQL "where" clause. Specifically, it should normally take the form of

        <column_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

clearFilter

public void clearFilter()
Deprecated. use cursor().clearFilter()

Clears the current filter for the data query.

Specified by:
clearFilter in interface DataQuery

setOrder

public void setOrder(String order)
              throws PersistenceException
Deprecated. see #addOrder

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
Deprecated. use cursor().addOrder(String order)

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

clearOrder

public void clearOrder()
Deprecated. use cursor().clearOrder()

Clears the current order clause for the data query.

Specified by:
clearOrder in interface DataQuery

size

public long size()
          throws PersistenceException
Deprecated. use cursor().size()

Returns the size of this query (i.e. the number of rows that are returned).

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

setParameter

public void setParameter(String parameterName,
                         Object value)
Deprecated. use cursor().setParameter(Strin parameterName, Object value)}

Allows a user to bind a parameter within a named query.

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

getParameter

public Object getParameter(String parameterName)
Deprecated. use cursor().getParameter(String parameterName)

Allows a caller to get a parameter value for a parameter that has already been set

Specified by:
getParameter in interface DataCollection
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.

close

public void close()
Deprecated. use cursor().close()

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

getDataObject

public DataObject getDataObject()
Deprecated. use cursor().getDataObject()

Returns a data object for the current position in the collection.

Specified by:
getDataObject in interface DataCollection
Returns:
A DataObject.

getObjectType

public ObjectType getObjectType()
Deprecated. use cursor().getObjectType()

Returns the object type of the data collection.

Specified by:
getObjectType in interface DataCollection
Returns:
The object type of the data collection.


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