atg.rview
Class RelationalView

java.lang.Object
  atg.rview.RelationalView

public abstract class RelationalView
extends java.lang.Object

A RelationalView comprises two parts:

• An ordered set of rows from a table, or joined set of tables
• A mapping from the columns of one such row to the properties of a Java bean

The methods in a RelationalView provide a means for accessing the rows of the RelationalView using Java beans as the mechanism for passing in row information, or for retrieving row information. All methods in the RelationalView act only on the rows represented by the RelationalView. The insert methods are the notable exceptions, where rows inserted through this interface may or may not appear as part of the row subset encompassed by the RelationalView.

A RelationalView can also provide subviews which are themselves RelationalViews that contain subsets of the rows contained by the parent RelationalView. Subviews may be obtained by providing explicit property conditions, or by selecting a named, parameterized subview.

Field Summary

static java.lang.String

CLASS_VERSION

Constructor Summary

RelationalView()

Method Summary

abstract RelationalView	createSubview(java.util.Dictionary pConstraints) Returns a subview filtered by the given Dictionary.
abstract RelationalView	createSubview(java.util.Dictionary pConstraints, java.lang.String pWhereClause, java.lang.Object[] pWhereClauseParameters, java.lang.String pOrderByClause, java.lang.Object[] pOrderByClauseParameters) This is the same the general createSubview method, except that the value of the distinct flag is taken from the value of this RelationalView's distinct flag.
abstract RelationalView	createSubview(java.util.Dictionary pConstraints, java.lang.String pWhereClause, java.lang.Object[] pWhereClauseParameters, java.lang.String pOrderByClause, java.lang.Object[] pOrderByClauseParameters, boolean pDistinct) This is the most general method for creating a subview at runtime (i.e., a subview that has not been predefined in the description file).
abstract int	delete() Deletes all of the rows in the RelationalView.
abstract java.lang.Object	executeFunction(java.lang.String pFunctionName) Executes a predefined function, identified by name.
abstract java.lang.Object	executeFunction(java.lang.String pFunctionName, java.lang.Object pFunctionParameter) Executes a predefined function, identified by name.
abstract java.lang.Object	executeFunction(java.lang.String pFunctionName, java.lang.Object[] pFunctionParameters) Executes a predefined function, identified by name.
abstract java.lang.Class	getBeanClass() Returns the Class of the bean used to represent the rows handled by this RelationalView.
abstract RelationalViewDefinition	getRelationalViewDefinition() Returns the RelationalViewDefinition that defines this RelationalView and all of its subviews (i.e., subviews of this RelationalView will return the same RelationalViewDefinition).
abstract RelationalViewManager	getRelationalViewManager() Returns the RelationalViewManager that produced this RelationalView.
abstract RelationalView	getSubview(java.lang.String pSubviewName) Returns a pre-defined subview identified by name.
abstract RelationalView	getSubview(java.lang.String pSubviewName, java.lang.Object pSubviewParameter) Returns a pre-defined subview identified by name.
abstract RelationalView	getSubview(java.lang.String pSubviewName, java.lang.Object[] pSubviewParameters) Returns a pre-defined subview identified by name.
abstract RelationalView	getUncachedRelationalView() Returns a RelationalView that is identical to this RelationalView, except that all of its select calls bypass the caches and go directly to the database.
abstract int	insert(java.util.Dictionary pPropertyValues) Inserts a row into the RelationalView.
abstract int	insert(java.lang.Object pBean) Inserts a row into the RelationalView.
abstract int	insert(java.lang.Object[] pBeans) Inserts several rows into the RelationalView.
abstract int	insert(java.lang.Object[] pBeans, java.lang.String[] pPropertyNames) Inserts several rows into the RelationalView.
abstract int	insert(java.lang.Object pBean, java.lang.String[] pPropertyNames) Inserts a row into the RelationalView.
abstract void	invalidateCaches() Invalidate any caches that depend on the relational view.
abstract java.lang.Object[]	select() Returns an array of all the rows in the RelationalView, in order, where each row has been converted into a bean according to the RelationalView's row-to-bean mapping.
abstract java.lang.Object	select(int pIndex) Returns the row specified by the given index (the first row has index 0).
abstract java.lang.Object[]	select(int pIndex, int pCount) Returns up to the specified number of rows starting with the given index (the first row has index 0).
abstract int	selectCount() Returns the number of rows in the RelationalView.
abstract boolean	selectExists() Returns true if there are any rows in the RelationalView, false if not.
abstract java.lang.Object	selectFirst() Returns the first row in the RelationalView.
abstract int	update(java.util.Dictionary pPropertyValues) Updates all of the rows in the RelationalView.
abstract int	update(java.lang.Object pBean) Updates all of the rows in the RelationalView, setting their columns from the properties of the specified bean.
abstract int	update(java.lang.Object pBean, java.lang.String[] pPropertyNames) Updates all of the rows in the RelationalView, setting their columns from the properties of the specified bean.

Methods inherited from class java.lang.Object

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

Field Detail

CLASS_VERSION

public static java.lang.String CLASS_VERSION

Constructor Detail

RelationalView

public RelationalView()

Method Detail

getRelationalViewManager

public abstract RelationalViewManager getRelationalViewManager()

Returns the RelationalViewManager that produced this RelationalView.

getRelationalViewDefinition

public abstract RelationalViewDefinition getRelationalViewDefinition()

Returns the RelationalViewDefinition that defines this RelationalView and all of its subviews (i.e., subviews of this RelationalView will return the same RelationalViewDefinition). From the RelationalViewDefinition, one can get the list of tables, columns, etc.

getBeanClass

public abstract java.lang.Class getBeanClass()

Returns the Class of the bean used to represent the rows handled by this RelationalView.

insert

public abstract int insert(java.lang.Object pBean)
                    throws java.sql.SQLException

Inserts a row into the RelationalView. The columns of the row are set from the properties of the specified bean. Note that the inserted row may not fit the criteria for this RelationalView, and therefore may not be a part of the RelationalView's row set. Returns the total number of rows that were inserted into all affected tables - note that if the relational view spans multiple tables, this number may be greater than the number of beans that were inserted.

Parameters:

pBean - the bean whose properties are to be inserted into the row's columns. The bean's class must match the type of bean associated with this RelationalView.

Throws:

java.sql.SQLException - if a database error occurred

insert

public abstract int insert(java.lang.Object pBean,
                           java.lang.String[] pPropertyNames)
                    throws java.sql.SQLException

Inserts a row into the RelationalView. The columns of the row are set from the properties of the specified bean. Note that the inserted row may not fit the criteria for this RelationalView, and therefore may not be a part of the RelationalView's row set. Returns the total number of rows that were inserted into all affected tables - note that if the relational view spans multiple tables, this number may be greater than the number of beans that were inserted.

Parameters:

pBean - the bean whose properties are to be inserted into the row's columns. The bean's class must match the type of bean associated with this RelationalView.

pPropertyNames - the list of properties whose columns are to be set. Any properties not named in this list will not have their corresponding columns assigned values. This can be used to allow columns to take on the default values specified by the database.

Throws:

java.sql.SQLException - if a database error occurred

insert

public abstract int insert(java.lang.Object[] pBeans)
                    throws java.sql.SQLException

Inserts several rows into the RelationalView. The columns of the row are set from the properties of the specified beans. Note that the inserted rows may not fit the criteria for this RelationalView, and therefore may not be a part of the RelationalView's row set. Returns the total number of rows that were inserted into all affected tables - note that if the relational view spans multiple tables, this number may be greater than the number of beans that were inserted.

Parameters:

pBeans - the array of beans whose properties are to be inserted into the row's columns. The bean's class must match the type of bean associated with this RelationalView.

Throws:

java.sql.SQLException - if a database error occurred

insert

public abstract int insert(java.lang.Object[] pBeans,
                           java.lang.String[] pPropertyNames)
                    throws java.sql.SQLException

Inserts several rows into the RelationalView. The columns of the row are set from the properties of the specified beans. Note that the inserted rows may not fit the criteria for this RelationalView, and therefore may not be a part of the RelationalView's row set. Returns the total number of rows that were inserted into all affected tables - note that if the relational view spans multiple tables, this number may be greater than the number of beans that were inserted.

Parameters:

pBeans - the array of beans whose properties are to be inserted into the row's columns. The bean's class must match the type of bean associated with this RelationalView.

pPropertyNames - the list of properties whose columns are to be set. Any properties not named in this list will not have their corresponding columns assigned values. This can be used to allow columns to take on the default values specified by the database.

Throws:

java.sql.SQLException - if a database error occurred

insert

public abstract int insert(java.util.Dictionary pPropertyValues)
                    throws java.sql.SQLException

Inserts a row into the RelationalView. A Dictionary is used to provide the property names and values to be inserted into the row's columns. Any property names not specified in the Dictionary will not be set explicitly, and will take on their default values from the database. Returns the total number of rows that were inserted into all affected tables - note that if the relational view spans multiple tables, this number may be greater than the number of beans that were inserted.

Parameters:

pPropertyValues - a mapping of property names to their corresponding values to be inserted into the row.

Throws:

java.sql.SQLException - if a database error occurred

delete

public abstract int delete()
                    throws java.sql.SQLException

Deletes all of the rows in the RelationalView. Returns the total number of rows that were deleted from all affected tables - note that if the relational view spans multiple tables, this number may be greater than the number of beans that were deleted.

Throws:

java.sql.SQLException - if a database error occurred

update

public abstract int update(java.lang.Object pBean)
                    throws java.sql.SQLException

Updates all of the rows in the RelationalView, setting their columns from the properties of the specified bean. Returns the total number of rows that were updated in all affected tables - note that if the relational view spans multiple tables, this number may be greater than the number of beans that were updated.

Parameters:

pBean - the bean whose properties are to be updated into the rows' columns. The bean's class must match the type of bean associated with this RelationalView.

Throws:

java.sql.SQLException - if a database error occurred

update

public abstract int update(java.lang.Object pBean,
                           java.lang.String[] pPropertyNames)
                    throws java.sql.SQLException

Updates all of the rows in the RelationalView, setting their columns from the properties of the specified bean. Returns the total number of rows that were updated in all affected tables - note that if the relational view spans multiple tables, this number may be greater than the number of beans that were updated.

Parameters:

pBean - the bean whose properties are to be updated into the rows' columns. The bean's class must match the type of bean associated with this RelationalView.

pPropertyNames - the list of properties whose columns are to be set. Any properties not named in this list will not have their corresponding columns assigned values. This can be used to prevent certain columns from being modified.

Throws:

java.sql.SQLException - if a database error occurred

update

public abstract int update(java.util.Dictionary pPropertyValues)
                    throws java.sql.SQLException

Updates all of the rows in the RelationalView. A Dictionary is used to provide the property names and values to be updated into the rows' columns. Any property names not specified in the Dictionary will not be updated. It is an error for an unrecognized property name to be specified in the Dictionary. Returns the total number of rows that were updated in all affected tables - note that if the relational view spans multiple tables, this number may be greater than the number of beans that were updated.

Parameters:

pPropertyValues - a mapping of property names to their corresponding values to be updated into the row.

Throws:

java.sql.SQLException - if a database error occurred

select

public abstract java.lang.Object[] select()
                                   throws java.sql.SQLException

Returns an array of all the rows in the RelationalView, in order, where each row has been converted into a bean according to the RelationalView's row-to-bean mapping. The array may be cast to an array of the RelationalView's bean, i.e., (DiscussionEntry[]).

Throws:

java.sql.SQLException - if a database error occurred

select

public abstract java.lang.Object select(int pIndex)
                                 throws java.sql.SQLException

Returns the row specified by the given index (the first row has index 0). The row is converted into a bean according to the RelationalView's row-to-bean mapping. If the given index is greater than or equal to the number of rows in the RelationalView, then null is returned.

Parameters:

pIndex - the index number of the row to be returned (0 is the first row)

Throws:

java.sql.SQLException - if a database error occurred

selectFirst

public abstract java.lang.Object selectFirst()
                                      throws java.sql.SQLException

Returns the first row in the RelationalView. This is equivalent to calling select (0). Returns null if there are no rows in the RelationalView.

Throws:

java.sql.SQLException - if a database error occurred

select

public abstract java.lang.Object[] select(int pIndex,
                                          int pCount)
                                   throws java.sql.SQLException

Returns up to the specified number of rows starting with the given index (the first row has index 0). The rows are converted into beans according to the RelationalView's row-to-bean mapping. If there aren't enough rows to satisfy the specified count, then the method will return as many rows as it can. If the given index is greater than or equal to the number of rows in the RelationalView, or if the count is 0, then a zero-length array is returned (not null).

Parameters:

pIndex - the index number of the row to be returned (0 is the first row)

pCount - the maximum number of rows to be returned

Throws:

java.sql.SQLException - if a database error occurred

selectCount

public abstract int selectCount()
                         throws java.sql.SQLException

Returns the number of rows in the RelationalView.

Throws:

java.sql.SQLException - if a database error occurred

selectExists

public abstract boolean selectExists()
                              throws java.sql.SQLException

Returns true if there are any rows in the RelationalView, false if not.

Throws:

java.sql.SQLException - if a database error occurred

createSubview

public abstract RelationalView createSubview(java.util.Dictionary pConstraints,
                                             java.lang.String pWhereClause,
                                             java.lang.Object[] pWhereClauseParameters,
                                             java.lang.String pOrderByClause,
                                             java.lang.Object[] pOrderByClauseParameters,
                                             boolean pDistinct)
                                      throws java.sql.SQLException

This is the most general method for creating a subview at runtime (i.e., a subview that has not been predefined in the description file). You can specify the constraints, an arbitrary WHERE clause, and an arbitrary ORDER BY clause.

Parameters:

pConstraints - a Dictionary containing the constraints for the subview. The Dictionary's keys are the names of properties, and the values are values corresponding to those properties. The resulting RelationalView will contain only those rows where the columns corresponding to the specified properties contain the values corresponding the values specified in the Dictionary. If this argument is null, then it is ignored.

pWhereClause - this is a WHERE clause written in SQL. All column and table names should be written in terms of relational views using the ":" syntax. All literal values should be passed as parameters in pWhereClauseParameters and referred to using ":" syntax. The clause should not include the actual "WHERE" keyword. For example: ":this.age >= :0(INTEGER)". If this argument is null, then it is ignored.

pWhereClauseParameters - these are the parameters to the WHERE clause, as referred to using the ":" syntax. For example, ":0" would refer to the first element in this parameter list. If there are no parameters, or there is no WHERE clause, this argument may be left as null.

pOrderByClause - this is an ORDER BY clause written in SQL. All column and table names should be written in terms of relational views using the ":" syntax. All literal values should be passed as parameters in pOrderByClauseParameters and referred to using ":" syntax. The clause should not include the actual "ORDER BY" keywords. For example: ":this.name, :this.age desc". If this argument is null, then it is ignored.

pOrderByClauseParameters - these are the parameters to the ORDER BY clause, as referred to using the ":" syntax. For example, ":0" would refer to the first element in this parameter list. If there are no parameters, or there is no ORDER BY clause, this argument may be left as null.

pDistinct - if true, then the SELECT statements for this subview will be generated using the DISTINCT keyword. Otherwise, the DISTINCT keyword will not be used.

Returns:

a subview reflecting the above constraints, WHERE, and ORDER BY clauses.

Throws:

java.sql.SQLException - if a database error occurred, or if an unknown property name was included in the Dictionary

createSubview

public abstract RelationalView createSubview(java.util.Dictionary pConstraints,
                                             java.lang.String pWhereClause,
                                             java.lang.Object[] pWhereClauseParameters,
                                             java.lang.String pOrderByClause,
                                             java.lang.Object[] pOrderByClauseParameters)
                                      throws java.sql.SQLException

This is the same the general createSubview method, except that the value of the distinct flag is taken from the value of this RelationalView's distinct flag.

Throws:

java.sql.SQLException - if a database error occurred, or if an unknown property name was included in the Dictionary

createSubview

public abstract RelationalView createSubview(java.util.Dictionary pConstraints)
                                      throws java.sql.SQLException

Returns a subview filtered by the given Dictionary. The Dictionary's keys are the names of properties, and the values are values corresponding to those properties. The resulting RelationalView will contain only those rows where the columns corresponding to the specified properties contain the values corresponding the values specified in the Dictionary. It is an error for the Dictionary to specify an unknown property name.

Throws:

java.sql.SQLException - if a database error occurred, or if an unknown property name was included in the Dictionary

getSubview

public abstract RelationalView getSubview(java.lang.String pSubviewName,
                                          java.lang.Object[] pSubviewParameters)
                                   throws java.sql.SQLException

Returns a pre-defined subview identified by name. That subview may expect a list of parameters to further specify how the subview is constructed. How subviews are defined depends on the implementation of the RelationalView.

Parameters:

pSubviewName - the name of the pre-defined subview

pSubviewParameters - the list of parameters to be associated with the subview

Throws:

java.sql.SQLException - if a database error occurred, the specified subview name is not defined, or if the subview's parameters are incorrectly specified (wrong number or type).

getSubview

public abstract RelationalView getSubview(java.lang.String pSubviewName,
                                          java.lang.Object pSubviewParameter)
                                   throws java.sql.SQLException

Returns a pre-defined subview identified by name. That subview should expect a single parameter to further specify how the subview is constructed. How subviews are defined depends on the implementation of the RelationalView.

Parameters:

pSubviewName - the name of the pre-defined subview

pSubviewParameter - the parameter to be associated with the subview

Throws:

java.sql.SQLException - if a database error occurred, the specified subview name is not defined, or if the subview's parameters are incorrectly specified (wrong number or type).

getSubview

public abstract RelationalView getSubview(java.lang.String pSubviewName)
                                   throws java.sql.SQLException

Returns a pre-defined subview identified by name. That subview should expect no parameters to further specify how the subview is constructed. How subviews are defined depends on the implementation of the RelationalView.

Parameters:

pSubviewName - the name of the pre-defined subview

Throws:

java.sql.SQLException - if a database error occurred, the specified subview name is not defined, or if the subview's parameters are incorrectly specified (wrong number or type).

executeFunction

public abstract java.lang.Object executeFunction(java.lang.String pFunctionName,
                                                 java.lang.Object[] pFunctionParameters)
                                          throws java.sql.SQLException

Executes a predefined function, identified by name. The result of the function depends on how the function is defined. How functions are defined depends on the implementation of the RelationalView.

Parameters:

pFunctionName - the name of the pre-defined function

pFunctionParameters - the list of parameters to be passed to the function

Throws:

java.sql.SQLException - if a database error occurred, the specified function name is not defined, or if the function's parameters are incorrectly specified (wrong number or type).

executeFunction

public abstract java.lang.Object executeFunction(java.lang.String pFunctionName,
                                                 java.lang.Object pFunctionParameter)
                                          throws java.sql.SQLException

Executes a predefined function, identified by name. The function should expect a single parameter. The result of the function depends on how the function is defined. How functions are defined depends on the implementation of the RelationalView.

Parameters:

pFunctionName - the name of the pre-defined function

pFunctionParameter - the parameter to be passed to the function

Throws:

java.sql.SQLException - if a database error occurred, the specified function name is not defined, or if the function's parameters are incorrectly specified (wrong number or type).

executeFunction

public abstract java.lang.Object executeFunction(java.lang.String pFunctionName)
                                          throws java.sql.SQLException

Executes a predefined function, identified by name. The function should expect no parameters. The result of the function depends on how the function is defined. How functions are defined depends on the implementation of the RelationalView.

Parameters:

pFunctionName - the name of the pre-defined function

Throws:

java.sql.SQLException - if a database error occurred, the specified function name is not defined, or if the function's parameters are incorrectly specified (wrong number or type).

getUncachedRelationalView

public abstract RelationalView getUncachedRelationalView()
                                                  throws java.sql.SQLException

Returns a RelationalView that is identical to this RelationalView, except that all of its select calls bypass the caches and go directly to the database. Functions that modify the database will still invalidate the appropriate cache entries.

Throws:

java.sql.SQLException - if a database error occurred

invalidateCaches

public abstract void invalidateCaches()

Invalidate any caches that depend on the relational view. The effect on the caches is the same as if update() were called on this subview. All of the caches associated with this subview are invalidated as appropriate. Caches for other subviews that might be affected by the rows in this subview are also invalidated. Note that the invalidations will take effect immediately.