Essentials
Models
Get Involved
Documentation
Database
|
Working With Peers
|
Peers are an Object Relation mapping tool, built on top of Village that gives
you access to a relational database via Java objects. Peers act on a somewhat
lower level than other O-R mapping tools like Castor or Osage. This means that
you have to do some coding by hand, but it allows for the most flexible
solution.
Peers use Turbine's Database adaptor classes that make uniform connection
to a wide range of databases possible. If your database is not supported
you can read the Database Adapter docs on how to create a new adaptor for
your database.
NOTE: If you would like to use Peers outside of the Turbine Servlet
(this is very common), then you need to use the TurbineConfig object to
initialize Turbine's code with the right TurbineResources.properties
file before you execute your Peer code. Please see the
javadoc for the TurbineConfig object for more details.
|
Database Maps
|
Peers make use of a DatabaseMap class that holds internal data about the
relational schema. You will seldom, if ever, need to work with the
DatabaseMap class. It is used internally by Peers to discover information
about the database at runtime.
There is exactly one DatabaseMap for each relational database that you
connect to. You may wish to connect to more that one database in your
application. You should then have one DatabaseMap for each of the
databases.
DatabaseMaps are constructed by classes called MapBuilders. Turbine has
a default MapBuilder, called TurbineMapBuilder, that creates a
DatabaseMap for Turbine's internal database structure. Again you should
seldom work with MapBuilder classes. They are used internally by Peers.
Usually there is a MapBuilder for each table in your database.
MapBuilder classes for new schemas can be generated for you automatically.
|
Peer Classes
|
Everything in Peers resolve around Peer classes. A Peer class have a
one-to-one mapping to a Database table. You use each table's associated
Peer class to do operations on that table. Peer classes can be generated
for you automatically.
Peer classes have static methods only, so you would never create objects of
Peer classes. It is not necessary to have objects on this level because
of the one-to-one mapping with a table. Peer methods are thread-save.
|
Data Objects
|
A Data Object holds information about a single row of a specific table.
Data Objects can be generated automatically for you. It takes the form
of Bean properties for each field of the table.
Data Objects are used almost exclusively with their related Peer classes.
Where peer classes "wraps around" around a database table, a Data Object
"wraps around" individual rows of the table. The two always go together.
You normally use Data Objects in one of two ways. The most common way
is to extract data after you called a doSelect on a Peer class. The
doSelect method returns a vector of Data Objects that holds the data of
the resultset. Secondly you can create Data Objects and pass it to the
overloaded doInsert and doUpdate methods of the relevant Peer class.
|
Criteria Objects
|
Criteria is an abstraction of the criteria of an sql query. We use
criteria objects to specify the criteria of a sql statement. The
database adaptor classes contains information on how this Criteria object
will be translated to different flavours of sql.
Criteria is in effect a map of field names and values that forms the
criteria of a query. By default the comparison is equals (=) but you
can define any comparison operator (<,>,<=,>=,IN,etc.).
Criteria can also be used to do some other sql function like ORDER BY or
DISTINCT. If Criteria is too limited for your purposes (which should not
happen often) you are still free to use raw sql queries.
|
ID Broker
|
One of the cool features of Peers is the ID Broker. ID Broker is used to
automatically create unique primary keys for tables. The ID Broker has
support for auto-increment fields like in MySQL; sequence generators like
in Oracle or if neither is supported it creates id's from a database
table called id_table.
You use the MapBuilder to specify which of the techniques you want to use
with your system. By default the id_table is used, because it is the
only common denominator.
The ID Broker is used in the underlying Peer code. After you have set it
up you need not worry about it anymore.
|
|