com.boylesoftware.cb2.DAO
|
||||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | |||||||||
java.lang.Object
Database Access Object (the DAO) provides high-level API for database
operations. Internally, it is based on JDBC, but working through the DAO
allows application code not to worry about opening and closing database
connections, creating and executing statements, processing result sets. The
DAO works with Data Models (DMs), which are very simple objects extending
DataModel abstract class and containing public data fields that
match to result set columns. When a fetch call (corresponding to SQL
SELECT) is performed, the DAO processes the result set, for
each row it create a DM, stores data from the result set columns to the
appropriate fields of the DM, and then returns the while fetch result to the
caller as an array of populated DMs. When an update or insert is performed,
the DAO constructs an appropriate SQL query automatically basing on the DM's
set of fields, and then executes it. DMs fields a mapped to result set
columns by names - in the simpliest case, the DAO finds the result set
column's label via standard JDBC method getColumnLabel on
ResultSetMetaData and then matches it to the DM's field with
the same name. In reality, before the DAO matches column label to the DM
field, it chops off prefix from the label. Column label prefix is a string,
which prepends the corresponding DM field name in a column label and is
separated from it by a special character sequence called field name
separator, which is specified in the DAO configuration. The prefix plays
no role in result set column to DM field matching and its actual usage is
dicussed later.
executeFetch
and executeUpdate, which allow the application to pass SQL
query text to be executed directly to the method, that is not the usual DAO
usage. Instead, the majority of the DAO's methods work with queries
specified externally in the DAO configuration and identified by names. This
approach allows to isolate SQL code from the application's Java code. The
DAO configuration is represented by an instance of DAOConfig
class, which is built from a <dao-config> element in the
blo-config.xml file. In order to create an instance of DAO it
is always required to specify an appropriate DAO config object. Beside query
definitions, the DAO configuration also contains descriptors for all data
models. The descriptors provide some meta data for the DMs, such as to what
database table a DM corresponds, and also allow to specify in query
definitions what DM class this or that fetch query returns. See
http://www.cb2project.com/dtd/blo-config_1_0.dtd
for the blo-config.xml file structure.
It is often required to fetch data not from one table, but from a number
of joined tables. To make it easy, DMs can have nested DMs, to which data
from the joined tables go. In order to allow the DAO to match result set
columns to the appropriate DMs, the result set must be structured in a
specific way. The columns in the result set are always processed from left
to right, so the order of the select list is important. First, columns are
matched against the top DM's fields. Then, if a column labeled so it matches
to the DM's field which is in turn another DM, the context switches to the
other DM. Depending on whether it is one to zero-or-one or one to
zero-or-more relationship, the nested field may be represented by a single
DM class field or by an array of DMs. The result set column labeled by the
nested DM field's name, which is called the header column, must have
different values for these two cases. In the case of a single nested DM the
header column's value must be the number of result set columns that follow
this one and must be stored to the nested DM. In the case of an array of
nested DMs, the header column's value must be something, that identifies
the parent record, so consequent result set rows that have the same value in
the header column will go to one array nested in one parent DM until the
header column's value changes and a new parent DM is created with a new
nested array in it. Note, that rows belonging to the same nested array must
immediately follow each other in the result set, which usually requires an
appropriate ORDER BY or GROUP BY clause in the SQL
query. Also, the first column in the sequence of columns that correspond to
the nested array must not be nullable - it it is NULL in the
result set, which is possible in the case of an outer join, the nested array
in the parent DM is left empty. In the case of nested DM arrays, the DAO
considers all columns following the header column until the last column in
the result set row belonging to the nested DM. It means that columns that
go to the nested array must be all groupped together at the very end of the
select list.
Nested DM fields, either single nested DMs or nested DM arrays, are never
set to null by the DAO - in case of an outer join when no
record exists corresponding to the nested field, if the field is a single
DM, an instance of the DM class will be created and all fields in it will be
set to null. If it is a nested array, an epmty array will be
set into the parent DM's field.
The DAO also correctly processes nested DMs in other nested DMs allowing unlimited nesting levels. However, please note that due to the nature of relational databases, it is impossible to have more than one nested array on the same nesting level.
Sometimes the database does not allow having columns within one select
list labeled with identical names. On the other hand, in the case of nested
DMs it is possible that two DMs have fields with the same names. To help
solve the problem, column labels can be prepended by prefixes, that will
make them unique. A prefix is any string separated from the rest of the
column label, which is the corresponding DM field name, by a field name
separator sequence, which can be configured by a
<field-name-separator> element in the DAO configuration.
Suppose the field name separator is an underscore character, then column
labeled "person_firstName" will be matched to a DM field named "firstName",
while the "person_" prefix is discarded.
Using nested DMs is a relatively complex issue. You should read the CB2 User Manual, available on the web-site, for better understanding.
Note, that it is safe to add nested DM fields to DMs that are used for
DAO updates and inserts - those calls ignore fields that are of type derived
from DataModel and arrays of such types when constructing SQL
statements.
Note also, that because of the DAO Extended Syntax, described below, it is rarely (or never?) needed to manually construct proper select lists in queries to structure result sets.
{...} contructs, similar to JDBC escape
syntax, that are interpreted by the DAO. Below is the list of such
constructs:
{macro ...} - allows to define a piece of SQL code
in a <sqlmacro> element and then insert it into
different SQL queries. The syntax for the construct is as follows:
{macro <macro name> [(<param 1 value> [, <param 2 value> ...])]}
Every occurence of this construct will be replaced by the body of the
defined by an <sqlmacro> element macro with approprite
{mparam ...} constucts replaced by the provided macro parameter
values.{mparam ...} - used in <sql>
subelements of <sqlmacro> elements to identify macro
parameter placeholders. The syntax is:
{mparam <param name>}
Where <param name> is the name of a parameter
defined by a <param> element.{dm ...} - renders select list for the DM,
associated with the query by usedm attribute of the
<query> element, which may include select lists for
nested DMs as well. The syntax is as follows:
{dm [from <table name>]
[prefix <column label prefix>]
[excluding (<DM field 1> [, <DM field 2> ...])|only (<DM field 1> [, <DM field 2> ...])]
[{<nested DM field>
[from <table name>]
[prefix <column label prefix>]
[excluding (<DM field 1> [, <DM field 2> ...])|only (<DM field 1> [, <DM field 2> ...])]
[by <parent DM field>]
[{<nested DM field> ...}
...
]
}
...
]
}
Here is the meaning of the optional parameters:
from - specifies table from which DM fields should
be selected. By default, the tables associated with the DM by
table attribute of its <dm> element is
used.prefix - prefix to be added to the column labels. By
default no prefix is added to the top DM fields and a prefix consisting of
parent DM field names up to the toppest one separated by the field name
separator sequence is added to nested DMs.excluding - allows to exclude named DM fields from
the select list. By default all DM fields that are not nested DMs and not
arrays of nested DMs are included.only - opposite to excluding, which
tells to include only the named DM fields to the select
list.by - in the context of a nested DM array specifies
the name of the parent DM's field which should be used as the value of the
header column. By default the first, or the only id field (specified by an
<idfield> element in the DM descriptor) of the parent DM
is used.{<nested DM field> ...} - allows to
render select list for a nested DM including the appropriate header
column.See CB2 User Manual for examples.
{cond ...} - allows to have dynamic SQL. Some
variations of the DAO's methods take conds argument, which
is a set of condition names to include in the query. Bodies of
{cond ...} constructs are included to the final SQL query
only if the construct's name is present in the conds set.
Here is the full syntax:
{cond (<cond name>) <SQL text>}
Where <cond name> is the condition name to be put
to the conds set if the condition's body should be
included.{? ...} and {?? ...} - named
query parameter placeholders. DAO methods fetchWithNameParams
and updateWithNamedParams allow to specify query parameters
not by positions, but by names. These constructs identify where the named
parameters go in the query. Here is the syntax:
{? <param name> [[+]<SQL type>]}
{?? <param name> [[+]<SQL type>]}
Specifying parameter's SQL type plays role when the DAO tries to set the
parameter to null. The JDBC's setNull method on
the PreparedStatement object requires the the SQL type of the
target parameter is specified. By default, it the SQL type is not in the
parameter's placeholder, the DAO uses java.sql.Types.VARCHAR,
which some JDBC drivers may dislike when used with, say, a numeric column.
If the SQL type is specified with the placeholder, the DAO uses it when
calling setNull method. Names of SQL types are case-insensitive
names of constants in the java.sql.Types class. A plus sign
in from of a type name makes the DAO to use it not only with
setNull method, but also with setObject method
when the parameter's value is not null.
See below for the explanation of what double question mark means.
Another extension of standard JDBC is double question marks as parameter
placeholders. It allows to have arrays as query parameters - the
corresponding double question mark will be expanded by the DAO to a sequence
of comma-separated single question marks, which is the standard JDBC query
parameter placeholder mark, with the exactly the same length as the number
of elements in the query parameter array, so the values from the array will
be set to the appropriate places. This is especially useful with SQL
IN conditions.
<plugin> elements. To see what kinds of plugins DAO
supports see subinterfaces of the DAOPlugin abstract interface.
There is also another kind of hook, which is not actually a DAO plugin,
but is used quite similarly. Objects implementing
FetchResultProcessor can be used with the DAO fetch calls to
perform certain application specific operations on DMs as the DAO creates
them in its internal result set processing loop. If can even completely
change the fetch call's effect. For example, you have a query, which returns
hundreds of thousands of rows and what you need is to process the data and
store the information in a file. If you let the fetch call return the result
as an array of DMs, first, the memory consumption will be irrational, second
you will have two loops going over the whole array - first time when the DAO
processes the result set rows, second time when you loop through the
resulting array to process the returned DMs. The correct way to solve such a
task is to have a FetchResultProcessor implementation, which
processes individual DMs as they come out of the DAO, append data to the
file, and then discard the DM instance so it does not take memory.
FetchExecutor interface. The
default CB2 implementation, GenericFetchExecutor, uses
scrollable result sets to scroll to and then fetch the requested page. Note,
that unfortunately not all JDBC drivers implement scrollable result sets
correctly, in which case it may require a database specific approach,
usually rather complex and tricky, if your application needs the
functionality of result set pagination. CB2 has some database specific
solutions packaged with it, see com.boylesoftware.cb2.db.*
packages.
The result set pagination mechanism assumes that one row in the result set corresponds to one record, which is not true if nested DM arrays are used, where a sequence of rows following each other may be packed into one DM. The result set pagination does not work correctly with nested DM arrays. It is not a bug, but certainly a limitation.
getDAO protected method. Also, the DAO class is completly
thread safe, so it is perfectly fine if one instance is used by multiple
threads at the same time.
However, there are advanced cases when the application would need to
create its own instance of the DAO. For example, if it needs to make the DAO
to work with a particular database connection not available through the
application context. Note, that sometimes there is a need to execute a
sequence of database calls with a guarantee that they all are executed on
the same connection. That situation is not a reason for creating an instance
of DAO - the BL Manager's DAO can be still used provided that the connection
is "pinned down" to the thread by a pinConnection call. Another
way to execute several SQL statements on the same connection is to define
multiple <sql> subelements (so-called "sql chunks")
within one <query> element in the DAO configuration.
When an instance of DAO needs to be created, it requires specifying the
appropriate DAO config object. The DAO config objects are also maintained
by the BL Manager, one for each configured data source, and can be retieved
from within any BLO via its getDAOConfig protected method.
The DAO logs messages related to its operation under "com.boylesoftware.cb2.DAOBJT" log channel.
| Field Summary | |
static int |
ORDER_ASC
Used with fetch methods to indicate that the caller wants ascending order in the result set. |
static int |
ORDER_DESC
Used with fetch methods to indicate that the caller wants descending order in the result set. |
static int |
ORDER_NOORDER
Deprecated. use ORDER_UNUSED instead. |
static int |
ORDER_UNUSED
Used with fetch methods to indicate that automatic ORDER BY
clause generation is not used, or it is used, but no ASC
nor DESC keywords should be added to the column names in
the clause. |
| Fields inherited from interface com.boylesoftware.cb2.StatusProvider |
TIMESTAMP_FORMAT |
| Constructor Summary | |
DAO(DAOConfig config,
boolean isTransactional)
Constructs a DAO instance, which automatically retrieves database connections from the application context every time it needs it. |
|
DAO(DAOConfig config,
java.sql.Connection con)
Constructs a DAO instance configured to use a certain database connection. |
|
| Method Summary | |
int |
delete(DataModel dm)
Constructs and executes an SQL DELETE statement for
the specified DM. |
DataModel[] |
executeFetch(java.lang.Class dmClass,
java.lang.String query,
java.lang.Object[] queryParams)
Calls executeFetch(dmClass, query, queryParams, 0, 0, null,
null). |
DataModel[] |
executeFetch(java.lang.Class dmClass,
java.lang.String query,
java.lang.Object[] queryParams,
int page,
int pageSize,
FetchResultDescriptor fetchResultDescriptor)
Calls executeFetch(dmClass, query, queryParams, page, pageSize,
null, fetchResultDescriptor). |
DataModel[] |
executeFetch(java.lang.Class dmClass,
java.lang.String query,
java.lang.Object[] queryParams,
int page,
int pageSize,
FetchResultProcessorHandler[] hooks,
FetchResultDescriptor fetchResultDescriptor)
Fetches data from the database using the specified SQL query and returns the result as an array of DMs. |
int |
executeUpdate(java.lang.String query,
java.lang.Object[] queryParams)
Executes the specified SQL query and returns the number of affected rows. |
DataModel[] |
fetch(java.lang.String queryName,
java.lang.Object[] queryParams)
Calls fetch(queryName, null, queryParams, null, DAO.ORDER_UNUSED,
0, 0, null, null). |
DataModel[] |
fetch(java.lang.String queryName,
java.lang.Object[] queryParams,
int page,
int pageSize,
FetchResultDescriptor fetchResultDescriptor)
Calls fetch(queryName, null, queryParams, null, DAO.ORDER_UNUSED,
page, pageSize, null, fetchResultDescriptor). |
DataModel[] |
fetch(java.lang.String queryName,
java.lang.Object[] queryParams,
java.lang.String[] orderBy,
int order)
Calls fetch(queryName, null, queryParams, orderBy, order, 0, 0,
null, null). |
DataModel[] |
fetch(java.lang.String queryName,
java.lang.Object[] queryParams,
java.lang.String[] orderBy,
int order,
int page,
int pageSize,
FetchResultDescriptor fetchResultDescriptor)
Calls fetch(queryName, null, queryParams, orderBy, order, page,
pageSize, null, fetchResultDescriptor). |
DataModel[] |
fetch(java.lang.String queryName,
java.util.Set conditions,
java.lang.Object[] queryParams)
Calls fetch(queryName, conditions, queryParams, null,
DAO.ORDER_UNUSED, 0, 0, null, null). |
DataModel[] |
fetch(java.lang.String queryName,
java.util.Set conditions,
java.lang.Object[] queryParams,
int page,
int pageSize,
FetchResultDescriptor fetchResultDescriptor)
Calls fetch(queryName, conditions, queryParams, null,
DAO.ORDER_UNUSED, page, pageSize, null, fetchResultDescriptor). |
DataModel[] |
fetch(java.lang.String queryName,
java.util.Set conditions,
java.lang.Object[] queryParams,
java.lang.String[] orderBy,
int order)
Calls fetch(queryName, conditions, queryParams, orderBy, order, 0,
0, null, null). |
DataModel[] |
fetch(java.lang.String queryName,
java.util.Set conditions,
java.lang.Object[] queryParams,
java.lang.String[] orderBy,
int order,
int page,
int pageSize,
FetchResultDescriptor fetchResultDescriptor)
Calls fetch(queryName, conditions, queryParams, orderBy, order,
page, pageSize, null, fetchResultDescriptor). |
DataModel[] |
fetch(java.lang.String queryName,
java.util.Set conditions,
java.lang.Object[] queryParams,
java.lang.String[] orderBy,
int order,
int page,
int pageSize,
FetchResultProcessorHandler[] hooks,
FetchResultDescriptor fetchResultDescriptor)
Fetches data from the database using a query from the DAO configuration and returns the result as an array of DMs. |
DataModel[] |
fetchWithNamedParams(java.lang.String queryName,
java.util.Map queryParams)
Calls fetchWithNamedParams(queryName, null, queryParams, null,
DAO.ORDER_UNUSED, 0, 0, null, null). |
DataModel[] |
fetchWithNamedParams(java.lang.String queryName,
java.util.Map queryParams,
int page,
int pageSize,
FetchResultDescriptor fetchResultDescriptor)
Calls fetchWithNamedParams(queryName, null, queryParams, null,
DAO.ORDER_UNUSED, page, pageSize, null, fetchResultDescriptor). |
DataModel[] |
fetchWithNamedParams(java.lang.String queryName,
java.util.Map queryParams,
java.lang.String[] orderBy,
int order)
Calls fetchWithNamedParams(queryName, null, queryParams, orderBy,
order, 0, 0, null, null). |
DataModel[] |
fetchWithNamedParams(java.lang.String queryName,
java.util.Map queryParams,
java.lang.String[] orderBy,
int order,
int page,
int pageSize,
FetchResultDescriptor fetchResultDescriptor)
Calls fetchWithNamedParams(queryName, null, queryParams, orderBy,
order, page, pageSize, null, fetchResultDescriptor). |
DataModel[] |
fetchWithNamedParams(java.lang.String queryName,
java.util.Set conditions,
java.util.Map queryParams)
Calls fetchWithNamedParams(queryName, conditions, queryParams,
null, DAO.ORDER_UNUSED, 0, 0, null, null). |
DataModel[] |
fetchWithNamedParams(java.lang.String queryName,
java.util.Set conditions,
java.util.Map queryParams,
int page,
int pageSize,
FetchResultDescriptor fetchResultDescriptor)
Calls fetchWithNamedParams(queryName, conditions, queryParams,
null, DAO.ORDER_UNUSED, page, pageSize, null,
fetchResultDescriptor). |
DataModel[] |
fetchWithNamedParams(java.lang.String queryName,
java.util.Set conditions,
java.util.Map queryParams,
java.lang.String[] orderBy,
int order)
Calls fetchWithNamedParams(queryName, conditions, queryParams,
orderBy, order, 0, 0, null, null). |
DataModel[] |
fetchWithNamedParams(java.lang.String queryName,
java.util.Set conditions,
java.util.Map queryParams,
java.lang.String[] orderBy,
int order,
int page,
int pageSize,
FetchResultDescriptor fetchResultDescriptor)
Calls fetchWithNamedParams(queryName, conditions, queryParams,
orderBy, order, page, pageSize, null, fetchResultDescriptor). |
DataModel[] |
fetchWithNamedParams(java.lang.String queryName,
java.util.Set conditions,
java.util.Map queryParams,
java.lang.String[] orderBy,
int order,
int page,
int pageSize,
FetchResultProcessorHandler[] hooks,
FetchResultDescriptor fetchResultDescriptor)
Version of fetch(String, Set, Object [], String [], int, int,
int, FetchResultProcessorHandler [], FetchResultDescriptor), which
works with named query parameters. |
EventStatistics |
getEventStats(java.lang.String eventName)
Not used in this class, always returns null. |
java.lang.String |
getQuery(java.lang.String queryName)
Deprecated. there is no direct substitution for this method. If you needed this method for building dynamic SQL queries you should consider using {cond ...} constructs of the DAO Extended Syntax. |
byte[] |
getStats()
Retrieves information about the DAO and returns it as an XML text. |
int |
insert(DataModel dm)
Constructs and executes an SQL INSERT statement for
the specified DM. |
void |
pinConnection(boolean forUpdate)
"Pins down" a database connection to the current thread. |
void |
unpinConnection()
Releases and closes the database connection "pinned" by an earlier pinConnection call. |
int |
update(DataModel dm)
Constructs and executes an SQL UPDATE statement for
the specified DM. |
int |
update(java.lang.String queryName,
java.lang.Object[] queryParams)
Calls update(queryName, null, queryParams). |
int |
update(java.lang.String queryName,
java.util.Set conditions,
java.lang.Object[] queryParams)
Executes a query from the DAO configuration as an update query and returns the number of affected rows. |
int |
updateDiff(DataModel oldDm,
DataModel newDm)
Similar to update(DataModel), but update only those fields,
that have different values in the two specified DMs. |
int |
updateExcludingFields(DataModel dm,
java.util.Set fields)
Similar to update(DataModel), except that only fields not
listed in the fields set are included into the generated
UPDATE statement. |
int |
updateFields(DataModel dm,
java.util.Set fields)
Similar to update(DataModel), except that only fields listed in
the fields set are included into the generated
UPDATE statement. |
int |
updateWithNamedParams(java.lang.String queryName,
java.util.Map queryParams)
Calls updateWithNamedParams(queryName, null, queryParams). |
int |
updateWithNamedParams(java.lang.String queryName,
java.util.Set conditions,
java.util.Map queryParams)
Version of update(String, Set, Object []), which works with
named query parameters. |
| Methods inherited from class java.lang.Object |
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
| Field Detail |
public static final int ORDER_UNUSED
ORDER BY
clause generation is not used, or it is used, but no ASC
nor DESC keywords should be added to the column names in
the clause.
public static final int ORDER_NOORDER
ORDER_UNUSED instead.
ORDER_UNUSED.
public static final int ORDER_ASC
ASC will then be added
to all column names in the automatically generated ORDER BY
clause.
public static final int ORDER_DESC
DESC will then be
added to all column names in the automatically generated
ORDER BY clause.
| Constructor Detail |
public DAO(DAOConfig config,
boolean isTransactional)
Depending on the value of the isTransactional parameter,
the DAO will be using application context's standard
getConnection method, which returns transactional database
connections, or it will be using low-level
getNoTXConnection method.
config - the DAOConfig object.isTransactional - set to true if this DAO should use
transactional database connections, which is the normal mode. Otherwise,
the DAO will be using getNoTXConnection method on the
application context to get database connections.
public DAO(DAOConfig config,
java.sql.Connection con)
config - the DAOConfig object.con - the database connection to be used by the DAO. Note, that it
should be a connection borrowed from the same data source, with which
the specified DAOConfig object is associated. It is
required, because the DAOConfig gathers information about
the database connection's features when it is created. That information
is later used by the DAO to adjust the way it operates on the
connection.| Method Detail |
public void pinConnection(boolean forUpdate)
throws BLException
DAO(DAOConfig config, Connection con) constructor) from the
same thread will be using the same connection until
unpinConnection is called from within the thread.
It is highly recommended to have an unpinConnection call
in a finally block!
This method does nothing if called on a DAO created via
DAO(DAOConfig config, Connection con) constructor.
forUpdate - indicates if your are going to run queries that modify
data in the database. Set to false if you are going to
execute only queries that read data (fetch calls) while the connection
is "pinned".
BLException - if the connection could not be retrieved from the
application context.unpinConnection()
public void unpinConnection()
throws BLException
pinConnection call.
This method does nothing if called on a DAO created via
DAO(DAOConfig config, Connection con) constructor.
BLException - if the connection could not be closed. Even
if an exception is thrown the connection still becomes disassociated
from the thread, that is "unpinned".
java.lang.IllegalStateException - if no connection has been "pinned"
earlier.pinConnection(boolean)
public java.lang.String getQuery(java.lang.String queryName)
throws BLException
{cond ...} constructs of the DAO Extended Syntax.
queryName - the query name.
BLException - if there is no query with the specified name.
public DataModel[] fetchWithNamedParams(java.lang.String queryName,
java.util.Set conditions,
java.util.Map queryParams,
java.lang.String[] orderBy,
int order,
int page,
int pageSize,
FetchResultProcessorHandler[] hooks,
FetchResultDescriptor fetchResultDescriptor)
throws BLException
fetch(String, Set, Object [], String [], int, int,
int, FetchResultProcessorHandler [], FetchResultDescriptor), which
works with named query parameters. Instead of object array, this method
takes query parameters as a map, which allows to associate names with
values. In the query's body {? <param name>}
and {?? <param name>} DAO Extended Syntax
constructs are used to mark parameter placeholders. As opposed to the
standard JDBC way of associating parameters with placeholders basing on
the placeholders' positions in the query text, using named query
parameters allows to disassociate the SQL query's structure from the way
it is called from Java. The disadvantage of it though is a slight lost
in performace, which can be ignored in the most cases.
Unnamed parameter placeholders, that is ? and
??, still can be used with this call. For such unnamed
placeholders the parameter name in the map should be a string
representation of its position starting from 1.
queryParams - collection of values for the query parameters. The
keys are parameters names (objects of String), the values
are parameter values. A value can be an object, a null, or
an array of objects for a double-question mark placeholder. If value is
not present in the map for a parameter, it is assumed to be
null. This argument is optional and can be
null if the query does not have parameters.
usedm attribute of the
<query> element in the DAO configuration. Never
returns null, but can return an empty array.
BLException - if an unexpected error happens and the query cannot
be executed.
public DataModel[] fetch(java.lang.String queryName,
java.util.Set conditions,
java.lang.Object[] queryParams,
java.lang.String[] orderBy,
int order,
int page,
int pageSize,
FetchResultProcessorHandler[] hooks,
FetchResultDescriptor fetchResultDescriptor)
throws BLException
This method, if requested, can append an ORDER BY clause
the query. If does so if the orderBy method argument is not
null and is not an empty array. The method simply appends
each element in the array to the generated ORDER BY clause
separating the elements by commas. If the order method
argument is not ORDER_UNUSED, it also appends
ASC or DESC after each element. Since no
checks are performed, the orderBy array can contain whole
sequencies of column names separated by commas with their individual
ASC and DESC modifiers, or it can be used so
each element contains a single column name, and then using the
order argument may make sense.
queryName - name of the SQL query to execute defined in the DAO
configuration.conditions - set of names (objects of String) of
{cond ...} DAO Extended Syntax elements that should be
included in the query. Can be null if the query contains
no {cond ...} elements, should not be null
otherwise.queryParams - array of values for the query parameters matched to
the parameter placeholders in the query's body basing on their
positions. An element in this array may be an object, a
null, or an array of objects for double-question mark
parameter placeholders. Can be null if the query has no
parameters.orderBy - array of elements that will be added to the automatically
generated ORDER BY clause separated by commas. If automatic
ORDER BY clause should not be generated and appended to the
query, this parameter should be null or an empty array.order - one of ORDER_xxx constants telling if
ASC, DESC or nothing should be added to each
element in the orderBy array when generating an automatic
ORDER BY clause.page - number of the result set page to return starting from zero.
Ignored if pageSize parameter is equal or less than zero.pageSize - number of records in one result set page. If this
parameter is equal or less than zero, no result set pagination is
performed and the whole result set is processed and returned.hooks - array of hooks called by the DAO from within its internal
result set processing loop for each DM on the specified by the hook
DM nesting level. Can be null or an empty array.fetchResultDescriptor - output parameter, which is updated after
the method call and contains additional information about the result
set. The method ignores this parameter if non-paginated result set is
requested (pageSize parameter is equal or less than zero).
Can be null.
usedm attribute of the
<query> element in the DAO configuration. Never
returns null, but can return an empty array.
BLException - if an unexpected error happens and the query cannot
be executed.
public int updateWithNamedParams(java.lang.String queryName,
java.util.Set conditions,
java.util.Map queryParams)
throws BLException
update(String, Set, Object []), which works with
named query parameters.
See fetchWithNamedParams(String, Set, Map, String[], int,
int, int, FetchResultProcessorHandler[], FetchResultDescriptor) for
more information on named query parameters.
-1.
BLException - if an unexpected error happens and the query cannot
be executed.
public int update(java.lang.String queryName,
java.util.Set conditions,
java.lang.Object[] queryParams)
throws BLException
queryName - name of the SQL query to execute defined in the DAO
configuration.conditions - set of names (objects of String) of
{cond ...} DAO Extended Syntax elements that should be
included in the query. Can be null if the query contains
no {cond ...} elements, should not be null
otherwise.queryParams - array of values for the query parameters matched to
the parameter placeholders in the query's body basing on their
positions. An element in this array may be an object, a
null, or an array of objects for double-question mark
parameter placeholders. Can be null if the query has no
parameters.
-1.
BLException - if an unexpected error happens and the query cannot
be executed.
public int insert(DataModel dm)
throws BLException
INSERT statement for
the specified DM. The DM must have table attribute in its
descriptor in the DAO configuration, as well as appropriate definition
of its id fields (<idfield> subelements). This method
updates id fields in the specified DM instance with the values inserted
into the table. The way the new values are aquired for the id fields is
determined by srcquery and srcorder attributes
of the appropriate <idfield> elements.
This method ignores any nested DM and nested DM array fields so the same DM class can be used for complex fetch calls with joined tables as well as for inserts.
dm - DM with data to be inserted into the associated with the DM
database table. The id fields are ignored and then updated with the
values inserted into the table.
BLException - if an error happens and the query cannot be
constructed or executed.
public int update(DataModel dm)
throws BLException
UPDATE statement for
the specified DM. The DM must have table attribute in its
descriptor in the DAO configuration, as well as appropriate definition
of its id fields (<idfield> subelements). The rows
to be updated are selected by values in the specified instance's id
fields - the id fields and their values go to the statement's
WHERE clause to select appropriate record, while other
fields go to the SET clause. If the DM has multiple id
fields, the condition in the WHERE clause uses
AND logical operation.
This method ignores any nested DM and nested DM array fields so the same DM class can be used for complex fetch calls with joined tables as well as for updates.
dm - DM with data to be set into the associated with the DM
database table. The rows to be updated are selected by values in the
DM's id fields.
BLException - if an error happens and the query cannot be
constructed or executed.
public int updateFields(DataModel dm,
java.util.Set fields)
throws BLException
update(DataModel), except that only fields listed in
the fields set are included into the generated
UPDATE statement.
Note, that id fields, even if don't appear in the set, are always
included into the statement's WHERE clause.
dm - DM with data to be set into the associated with the DM
database table. The rows to be updated are selected by values in the
DM's id fields. Values in fields not listed in the fields
set are ignored.fields - set of DM field names (objects of String)
that should be updated by the generated statement. Fields that don't
appear in the set are left untouched.
BLException - if an error happens and the query cannot be
constructed or executed.updateExcludingFields(DataModel, Set)
public int updateExcludingFields(DataModel dm,
java.util.Set fields)
throws BLException
update(DataModel), except that only fields not
listed in the fields set are included into the generated
UPDATE statement.
Note, that id fields, even if appear in the set, are always included
into the statement's WHERE clause.
dm - DM with data to be set into the associated with the DM
database table. The rows to be updated are selected by values in the
DM's id fields. Values in fields listed in the fields
set are ignored.fields - set of DM field names (objects of String)
that should be excluded from the update. Fields that appear in the set
are left untouched.
BLException - if an error happens and the query cannot be
constructed or executed.updateFields(DataModel, Set)
public int updateDiff(DataModel oldDm,
DataModel newDm)
throws BLException
update(DataModel), but update only those fields,
that have different values in the two specified DMs. This method uses
diff on DataModel to compare the DMs so all
rules that apply to the diff method do apply to this method
as well. If the DMs are identical, the method does nothing.
Note, that this method does not check if the id fields are identical,
although logically they should always be. In any case, the id field
values from the newDm are taken when creating the
statement.
oldDm - DM with "old" data.newDm - DM with "new" data, that will be stored into the database.
BLException - if an error happens and the query cannot be
constructed or executed.
java.lang.IllegalArgumentException - if types of the specified DMs are
different.DataModel.diff(com.boylesoftware.cb2.DataModel)
public int delete(DataModel dm)
throws BLException
DELETE statement for
the specified DM. The DM must have table attribute in its
descriptor in the DAO configuration, as well as appropriate definition
of its id fields (<idfield> subelements). The rows
to be deleted are selected by values in the specified instance's id
fields - the id fields and their values go to the statement's
WHERE clause to select appropriate record, while other
fields are ignored. If the DM has multiple id fields, the condition in
the WHERE clause uses AND logical operation.
dm - DM with id fields set to select rows to delete.
BLException - if an error happens and the query cannot be
constructed or executed.
public DataModel[] executeFetch(java.lang.Class dmClass,
java.lang.String query,
java.lang.Object[] queryParams,
int page,
int pageSize,
FetchResultProcessorHandler[] hooks,
FetchResultDescriptor fetchResultDescriptor)
throws BLException
<dm> element.
Note, that this low-level method does not support DAO Extended Syntax constructs in the query's SQL except double question marks.
See fetch(String, Set, Object [], String [], int, int, int,
FetchResultProcessorHandler [], FetchResultDescriptor) for description
of common method parameters.
dmClass - class of the DM this query returns. Should be a subclass
of DataModel.query - the query's SQL text.
null, but can return an empty array.
BLException - if an unexpected error happens and the query cannot
be executed.
public int executeUpdate(java.lang.String query,
java.lang.Object[] queryParams)
throws BLException
Note, that this low-level method does not support DAO Extended Syntax constructs in the query's SQL except double question marks.
See update(String, Set, Object[]) for description of common
method parameters.
query - the query's SQL text.
-1.
BLException - if an unexpected error happens and the query cannot
be executed.
public DataModel[] fetch(java.lang.String queryName,
java.lang.Object[] queryParams)
throws BLException
fetch(queryName, null, queryParams, null, DAO.ORDER_UNUSED,
0, 0, null, null).
BLExceptionfetch(String, Set, Object [], String [], int, int, int, FetchResultProcessorHandler [], FetchResultDescriptor)
public DataModel[] fetch(java.lang.String queryName,
java.lang.Object[] queryParams,
java.lang.String[] orderBy,
int order)
throws BLException
fetch(queryName, null, queryParams, orderBy, order, 0, 0,
null, null).
BLExceptionfetch(String, Set, Object [], String [], int, int, int, FetchResultProcessorHandler [], FetchResultDescriptor)
public DataModel[] fetch(java.lang.String queryName,
java.lang.Object[] queryParams,
int page,
int pageSize,
FetchResultDescriptor fetchResultDescriptor)
throws BLException
fetch(queryName, null, queryParams, null, DAO.ORDER_UNUSED,
page, pageSize, null, fetchResultDescriptor).
BLExceptionfetch(String, Set, Object [], String [], int, int, int, FetchResultProcessorHandler [], FetchResultDescriptor)
public DataModel[] fetch(java.lang.String queryName,
java.lang.Object[] queryParams,
java.lang.String[] orderBy,
int order,
int page,
int pageSize,
FetchResultDescriptor fetchResultDescriptor)
throws BLException
fetch(queryName, null, queryParams, orderBy, order, page,
pageSize, null, fetchResultDescriptor).
BLExceptionfetch(String, Set, Object [], String [], int, int, int, FetchResultProcessorHandler [], FetchResultDescriptor)
public DataModel[] fetch(java.lang.String queryName,
java.util.Set conditions,
java.lang.Object[] queryParams)
throws BLException
fetch(queryName, conditions, queryParams, null,
DAO.ORDER_UNUSED, 0, 0, null, null).
BLExceptionfetch(String, Set, Object [], String [], int, int, int, FetchResultProcessorHandler [], FetchResultDescriptor)
public DataModel[] fetch(java.lang.String queryName,
java.util.Set conditions,
java.lang.Object[] queryParams,
java.lang.String[] orderBy,
int order)
throws BLException
fetch(queryName, conditions, queryParams, orderBy, order, 0,
0, null, null).
BLExceptionfetch(String, Set, Object [], String [], int, int, int, FetchResultProcessorHandler [], FetchResultDescriptor)
public DataModel[] fetch(java.lang.String queryName,
java.util.Set conditions,
java.lang.Object[] queryParams,
int page,
int pageSize,
FetchResultDescriptor fetchResultDescriptor)
throws BLException
fetch(queryName, conditions, queryParams, null,
DAO.ORDER_UNUSED, page, pageSize, null, fetchResultDescriptor).
BLExceptionfetch(String, Set, Object [], String [], int, int, int, FetchResultProcessorHandler [], FetchResultDescriptor)
public DataModel[] fetch(java.lang.String queryName,
java.util.Set conditions,
java.lang.Object[] queryParams,
java.lang.String[] orderBy,
int order,
int page,
int pageSize,
FetchResultDescriptor fetchResultDescriptor)
throws BLException
fetch(queryName, conditions, queryParams, orderBy, order,
page, pageSize, null, fetchResultDescriptor).
BLExceptionfetch(String, Set, Object [], String [], int, int, int, FetchResultProcessorHandler [], FetchResultDescriptor)
public DataModel[] fetchWithNamedParams(java.lang.String queryName,
java.util.Map queryParams)
throws BLException
fetchWithNamedParams(queryName, null, queryParams, null,
DAO.ORDER_UNUSED, 0, 0, null, null).
BLExceptionfetchWithNamedParams(String, Set, Map, String [], int, int, int, FetchResultProcessorHandler [], FetchResultDescriptor)
public DataModel[] fetchWithNamedParams(java.lang.String queryName,
java.util.Map queryParams,
java.lang.String[] orderBy,
int order)
throws BLException
fetchWithNamedParams(queryName, null, queryParams, orderBy,
order, 0, 0, null, null).
BLExceptionfetchWithNamedParams(String, Set, Map, String [], int, int, int, FetchResultProcessorHandler [], FetchResultDescriptor)
public DataModel[] fetchWithNamedParams(java.lang.String queryName,
java.util.Map queryParams,
int page,
int pageSize,
FetchResultDescriptor fetchResultDescriptor)
throws BLException
fetchWithNamedParams(queryName, null, queryParams, null,
DAO.ORDER_UNUSED, page, pageSize, null, fetchResultDescriptor).
BLExceptionfetchWithNamedParams(String, Set, Map, String [], int, int, int, FetchResultProcessorHandler [], FetchResultDescriptor)
public DataModel[] fetchWithNamedParams(java.lang.String queryName,
java.util.Map queryParams,
java.lang.String[] orderBy,
int order,
int page,
int pageSize,
FetchResultDescriptor fetchResultDescriptor)
throws BLException
fetchWithNamedParams(queryName, null, queryParams, orderBy,
order, page, pageSize, null, fetchResultDescriptor).
BLExceptionfetchWithNamedParams(String, Set, Map, String [], int, int, int, FetchResultProcessorHandler [], FetchResultDescriptor)
public DataModel[] fetchWithNamedParams(java.lang.String queryName,
java.util.Set conditions,
java.util.Map queryParams)
throws BLException
fetchWithNamedParams(queryName, conditions, queryParams,
null, DAO.ORDER_UNUSED, 0, 0, null, null).
BLExceptionfetchWithNamedParams(String, Set, Map, String [], int, int, int, FetchResultProcessorHandler [], FetchResultDescriptor)
public DataModel[] fetchWithNamedParams(java.lang.String queryName,
java.util.Set conditions,
java.util.Map queryParams,
java.lang.String[] orderBy,
int order)
throws BLException
fetchWithNamedParams(queryName, conditions, queryParams,
orderBy, order, 0, 0, null, null).
BLExceptionfetchWithNamedParams(String, Set, Map, String [], int, int, int, FetchResultProcessorHandler [], FetchResultDescriptor)
public DataModel[] fetchWithNamedParams(java.lang.String queryName,
java.util.Set conditions,
java.util.Map queryParams,
int page,
int pageSize,
FetchResultDescriptor fetchResultDescriptor)
throws BLException
fetchWithNamedParams(queryName, conditions, queryParams,
null, DAO.ORDER_UNUSED, page, pageSize, null,
fetchResultDescriptor).
BLExceptionfetchWithNamedParams(String, Set, Map, String [], int, int, int, FetchResultProcessorHandler [], FetchResultDescriptor)
public DataModel[] fetchWithNamedParams(java.lang.String queryName,
java.util.Set conditions,
java.util.Map queryParams,
java.lang.String[] orderBy,
int order,
int page,
int pageSize,
FetchResultDescriptor fetchResultDescriptor)
throws BLException
fetchWithNamedParams(queryName, conditions, queryParams,
orderBy, order, page, pageSize, null, fetchResultDescriptor).
BLExceptionfetchWithNamedParams(String, Set, Map, String [], int, int, int, FetchResultProcessorHandler [], FetchResultDescriptor)
public DataModel[] executeFetch(java.lang.Class dmClass,
java.lang.String query,
java.lang.Object[] queryParams)
throws BLException
executeFetch(dmClass, query, queryParams, 0, 0, null,
null).
BLExceptionexecuteFetch(Class, String, Object [], int, int, FetchResultProcessorHandler [], FetchResultDescriptor)
public DataModel[] executeFetch(java.lang.Class dmClass,
java.lang.String query,
java.lang.Object[] queryParams,
int page,
int pageSize,
FetchResultDescriptor fetchResultDescriptor)
throws BLException
executeFetch(dmClass, query, queryParams, page, pageSize,
null, fetchResultDescriptor).
BLExceptionexecuteFetch(Class, String, Object [], int, int, FetchResultProcessorHandler [], FetchResultDescriptor)
public int update(java.lang.String queryName,
java.lang.Object[] queryParams)
throws BLException
update(queryName, null, queryParams).
BLExceptionupdate(String, Set, Object [])
public int updateWithNamedParams(java.lang.String queryName,
java.util.Map queryParams)
throws BLException
updateWithNamedParams(queryName, null, queryParams).
BLExceptionupdateWithNamedParams(String, Set, Map)
public byte[] getStats()
throws java.io.UnsupportedEncodingException
getStats in interface StatusProviderjava.io.UnsupportedEncodingException - if UTF-8 is not supported on this
platform, which is practically impossible.public EventStatistics getEventStats(java.lang.String eventName)
null.
getEventStats in interface StatusProvidereventName - implementation specific event name, for which current
statistics are requested.
null if the event is unknown.
|
||||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | |||||||||