You are viewing a plain text version of this content. The canonical link for it is here.
Posted to torque-dev@db.apache.org by tf...@apache.org on 2012/06/28 05:26:13 UTC
svn commit: r1354810 - in
/db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/modules/runtime/reference:
beans.xml connections-transactions.xml extend-classes.xml
relevant-classes.xml
Author: tfischer
Date: Thu Jun 28 03:26:12 2012
New Revision: 1354810
URL: http://svn.apache.org/viewvc?rev=1354810&view=rev
Log:
Documentation improvements
Modified:
db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/modules/runtime/reference/beans.xml
db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/modules/runtime/reference/connections-transactions.xml
db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/modules/runtime/reference/extend-classes.xml
db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/modules/runtime/reference/relevant-classes.xml
Modified: db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/modules/runtime/reference/beans.xml
URL: http://svn.apache.org/viewvc/db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/modules/runtime/reference/beans.xml?rev=1354810&r1=1354809&r2=1354810&view=diff
==============================================================================
--- db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/modules/runtime/reference/beans.xml (original)
+++ db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/modules/runtime/reference/beans.xml Thu Jun 28 03:26:12 2012
@@ -31,7 +31,7 @@
<p>
Bean creation is turned off by default. To enable bean creation,
you have to generate your object model with the property
- <code>torque.generateBeans</code> set to <code>true</code>.
+ <code>torque.om.generateBeans</code> set to <code>true</code>.
</p>
<p>
@@ -55,6 +55,17 @@
and save the objects generated from the beans.
</p>
+ <p>
+ However, a similar situation can also be achieved
+ by generating the save methods not to the data objects but to the
+ Peer classes by setting the generator switch
+ <code>torque.om.saveMethodsInDbObjects</code> to <code>false</code>.
+ This approach does not have the same separation between objects
+ and Torque as the beans approach, but it has the advantage that no mapping
+ between data objects and beans (which can be cumbersome) is needed.
+ Decide for yourself which is your favorite approach.
+ </p>
+
</section>
<section name="Creation of beans from Torque objects and vice versa">
@@ -106,7 +117,7 @@ public static Author createAuthor(Author
<p>
If a bean is created from an object, the beans gets knowledge about
whether the object it was created from already exists in the database,
- or whether it was changed after redaing it from the database
+ or whether it was changed after reading it from the database
(that is what the isNew() and isModified() methods are for).
So assuming we have at least one author stored in the database,
the following code works as expected
@@ -195,7 +206,8 @@ AuthorBean authorBean = author.getBean()
This is because the related books are never read from the database,
and thus are not included in bean conversion. To include the
related books into the author bean, you have to assure that the
- related books are read into memory. This can be done as follows:
+ related books are read into memory. This can be done as follows
+ if lazy loading for related collections is turned on (the default):
</p>
<source>
Modified: db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/modules/runtime/reference/connections-transactions.xml
URL: http://svn.apache.org/viewvc/db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/modules/runtime/reference/connections-transactions.xml?rev=1354810&r1=1354809&r2=1354810&view=diff
==============================================================================
--- db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/modules/runtime/reference/connections-transactions.xml (original)
+++ db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/modules/runtime/reference/connections-transactions.xml Thu Jun 28 03:26:12 2012
@@ -26,7 +26,7 @@
<body>
- <section name="Connection and transaction handling">
+ <section name="Connection and Transaction Handling">
<p>
To read data from or write data to the database, a connection to the
database is required. To be able to connect to a database,
@@ -56,7 +56,7 @@
</p>
</section>
- <section name="Torque's connection and transaction handling">
+ <section name="Torque's Connection and Transaction Handling">
<p>
When you use Torque, you need not bother about connections and
@@ -75,7 +75,7 @@
</section>
- <section name="Handle connections and transactions yourself">
+ <section name="Handle Connections and Transactions yourself">
<p>
If you want to manipulate the database in some way which is not
@@ -122,18 +122,13 @@ finally
</p>
<p>
- If the database supports transactions and autocomit is turned off,
+ If the database supports transactions and autocommit is turned off,
all database operations are executed in a single transaction.
This has the following effect: For example, you execute two saves in the
try block, and the second save fails. The first save operation will be
rolled back, i.e. the database reverts the changes made by the first save.
- If you do not like this behaviour, the safe way is to wrap everything in
+ If you do not like this behavior, the safe way is to wrap everything in
its own try ... finally block.
- The alternative is to use
- <code>Transaction.beginOptional(Torque.getDefaultDB(), false)</code>
- instead of <code>Transaction.begin()</code> and make sure your
- connection pool returns connections in autocommit mode. This might
- not work with CLOB and BLOB data fields, however.
</p>
<p>
@@ -178,5 +173,24 @@ finally
</section>
+ <section name="Supplying your own Transaction Manager">
+
+ <p>
+ In some situations, e.g. if you use external transaction control from
+ another framework, it is not desirable that Torque attempts to
+ manipulate transaction state. If this is the case, you can configure
+ Torque to use another transaction manager by implementing a
+ org.apache.torque.util.TransactionManager, and then use the
+ <code>Transaction.setTransactionManager()</code> method at
+ application startup time to tell Torque to use your own TransactionManager
+ instead of the built-in one.
+ </p>
+
+ <p>
+ Note that transaction management errors typically occur only under load
+ and are difficult to find, so use this only if you know what you are
+ doing.
+ </p>
+ </section>
</body>
</document>
Modified: db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/modules/runtime/reference/extend-classes.xml
URL: http://svn.apache.org/viewvc/db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/modules/runtime/reference/extend-classes.xml?rev=1354810&r1=1354809&r2=1354810&view=diff
==============================================================================
--- db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/modules/runtime/reference/extend-classes.xml (original)
+++ db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/modules/runtime/reference/extend-classes.xml Thu Jun 28 03:26:12 2012
@@ -32,19 +32,27 @@
<section name="Extending the Base Classes">
<p>
Much of the power of Torque stems from the fact that you can easily add to
- and change the behaviour of the generated Peer and Data Object classes
- by adding or overriding methods. To keep your changes apart from the
- autogenerated code, Torque provides two Peer classes and two
- Data Object classes per table: The Base<table-name>Peer and
- Base<table-name> classes are overwritten each time you regenerate
- the classes from the schema and contain all functionality provided by
- Torque.
- The <table-name>Peer and <table-name> classes inherit from their
- respective Base Classes, but are empty initially. They are not overwritten
- if you regenerate the classes from the schema. All code which you add
- to the data model should go into the <table-name>Peer and
- <table-name> classes.
+ and change the behavior of the generated classes
+ by adding or overriding methods.
</p>
+ <p>
+ To keep your own code changes apart from the generated code,
+ Torque provides two classes of a kind for each table:
+ </p>
+ <ul>
+ <li>
+ The Base... classes are overwritten each time you regenerate
+ the classes from the schema and contain all functionality provided by
+ Torque.
+ </li>
+ <li>
+ The non-base classes inherit from their respective Base Classes,
+ but are empty initially.
+ They are not overwritten if you regenerate the classes from the schema.
+ All code which you add to the data model should go into the
+ non-base classes.
+ </li>
+ </ul>
</section>
@@ -65,16 +73,106 @@
</p>
<source><![CDATA[
-public List doSelectByISBN(String isbn)
+public static List<Book> doSelectByISBN(String isbn)
{
Criteria crit = new Criteria();
crit.add(BookPeer.ISBN, isbn);
- List books = BookPeer.doSelect(crit);
+ List<Book> books = BookPeer.doSelect(crit);
return books;
}
]]></source>
</section>
+ <section name="Adding Methods to the PeerImpl classes">
+
+ <p>
+ If you use the delegation approach of the Peer/PeerImpl classes
+ to exchange the implementation of the Peer classes
+ (e.g. by inserting mocks for component tests), or if you use the
+ PeerImpl classes directly (e.g. in a dependency injection framework),
+ you can also make the changes/additions to the Peer classes in the
+ PeerImpl classes. If you add a method in the first case, you should
+ also add a delegation method to the Peer class.
+ </p>
+
+ <p>
+ Since adding delegation methods is cumbersome, we recommend to add code
+ to the Peer class instead of the PeerImpl class if you do not have a
+ reason to decide otherwise (like one of the above reasons).
+ </p>
+
+ </section>
+
+ <section name="Adding Methods to Data Objects">
+
+ <p>
+ By adding methods to Data Objects, you can add additional behaviour
+ to the data objects.
+ For example, you might want to order authors by their name in memory.
+ To do this, you could make the authors implement the Comparable interface
+ and add a compareTo Method:
+ </p>
+
+<source><![CDATA[
+public class Author
+ extends org.apache.torque.test.BaseAuthor implements Comparable<Author>
+{
+ public int compareTo(Author other)
+ {
+ // null handling omitted for simplicity
+ return getName().compareTo(other.getName());
+ }
+}
+]]></source>
+
+ <p>
+ Then you can sort the authors by name by calling the
+ Collections.sort method.
+ </p>
+
+ <p>
+ To change the behavior of the generated classes, you can override
+ an existing method in a generated class.
+ For example, if you decide to add validation code to an author
+ in order not to allow blank author names, you can override the setter
+ method for the name:
+ </p>
+
+<source><![CDATA[
+import org.apache.commons.lang.StringUtils;
+
+public class Author
+ extends org.apache.torque.test.BaseAuthor
+{
+ @Override
+ public void setName(String name)
+ {
+ // accept blank names which are already in the database
+ if (!isLoading())
+ {
+ if (StringUtils.isBlank(name))
+ {
+ throw new IllegalArgumentException(
+ "author name must not be blank");
+ }
+ }
+ super.setName(name);
+ }
+}
+]]></source>
+
+ </section>
+
+ <section name="Adding Methods to Record mappers">
+
+ <p>
+ Adding methods to or overriding methods in the RecordMapper class
+ will not often occur in practice. Still, it can be done and should
+ be done if the need arises.
+ </p>
+
+ </section>
+
</body>
</document>
Modified: db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/modules/runtime/reference/relevant-classes.xml
URL: http://svn.apache.org/viewvc/db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/modules/runtime/reference/relevant-classes.xml?rev=1354810&r1=1354809&r2=1354810&view=diff
==============================================================================
--- db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/modules/runtime/reference/relevant-classes.xml (original)
+++ db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/modules/runtime/reference/relevant-classes.xml Thu Jun 28 03:26:12 2012
@@ -29,41 +29,63 @@
<body>
<section name="Peers">
<p>
- Everything in Peers resolve around Peer classes. A Peer class has 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 are generated
- for you automatically.
+ A Peer class contains the operations on a specific Database table.
+ Peer classes are generated automatically when you generate the Torque
+ classes.
</p>
<p>
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
- safe.
+ of Peer classes.
+ See the PeerImpl section below if you rather work with instances.
+ Peer methods are thread safe.
</p>
<p>
- Peer classes are generated for you automatically. For each table, two
- Peer classes are generated: Base<table-name>Peer and
- <table-name>Peer. The Base<table-name>Peer class contains
+ For each table, two Peer classes are generated:
+ Base<table-name>Peer and <table-name>Peer.
+ The Base<table-name>Peer class contains
all the functionality and should not be changed. The other class is
empty but can be extended to add or change functionality. If you
- regenerate with torque only the Base* class changes. This allows you
+ regenerate the classes, only the Base* class changes. This allows you
to change the schema, but still keep your existing code.
</p>
</section>
+ <section name="PeerImpl classes">
+ <p>
+ The PeerImpl classes provide a way to exchange the Peer class
+ implementation, e.g. for unit testing, and can be used if instances are
+ desired rather than static access (the latter is usually less code).
+ If you are happy with the Peer classes as they are, you need not bother
+ about the PeerImpl classes.
+ </p>
+ <p>
+ PeerImpl classes are generated automatically when you generate the Torque
+ classes.
+ </p>
+ <p>
+ For each table, two PeerImpl classes are generated:
+ Base<table-name>PeerImpl and <table-name>PeerImpl.
+ The Base<table-name>PeerImpl class contains
+ all the functionality and should not be changed. The other class is
+ empty but can be extended to add or change functionality. If you
+ regenerate the classes, only the Base* class changes.
+ </p>
+ </section>
+
<section name="Data Objects">
<p>
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.
+ They contain a field with getter and setter for each column of the table.
+ Data Objects are generated automatically when you generate the Torque
+ classes.
</p>
<p>
- The Data Object classes also generated automatically. For each table, two
- Data Object classes are generated: Base<table-name> and
- <table-name>. As with the Peers, the Base<table-name> class
+ For each table, two Data Object classes are generated:
+ Base<table-name> and <table-name>.
+ As with the Peers, the Base<table-name> class
contains all the functionality and should not be changed. The other class
is empty but can be extended to add or change functionality. If you
regenerate the classes, only the Base* classes will be overwritten.
@@ -105,6 +127,23 @@
</p>
</section>
+ <section name="Record Mappers">
+ <p>
+ A Record Mapper maps data between JDBC metadata and Data Objects.
+ RecordMapper classes are generated by Torque and used internally,
+ there is usually no need to work with RecordMappers directly.
+ </p>
+
+ <p>
+ For each table, two RecordMapper classes are generated:
+ Base<table-name>RecordMapper and <table-name>RecordMapper.
+ If you regenerate the classes, only the Base* classes will be overwritten.
+ If you want to change the RecordMapper code (which should not happen
+ often), add your changes to the <table-name>RecordMapper class
+ so that they do not get overwritten when regenerating the code.
+ </p>
+ </section>
+
<section name="Database Maps">
<p>
The Peers make use of a DatabaseMap class that holds internal data about
@@ -130,7 +169,8 @@
<p>
All DatabaseMaps are instances of the class
<code>org.apache.torque.map.DatabaseMap</code>.
- They are kept in the instance variable <code>TorqueInstance.dbMaps</code>.
+ They are kept in the field databaseMap of the objects stored in the map
+ <code>TorqueInstance.databases</code>.
The Map for the database with the name key can be retrieved
by the method Torque.getDatabaseMap(key).
</p>
@@ -170,10 +210,11 @@
<p>
Adapters are subclasses of the <code>org.apache.torque.adapter.DB</code>
class.
- The adapters are stored in the private map TorqueInstance.apdapterMap;
- the key of the map is the name of the database (e.g. "bookstore"),
- and the value of the map is the adapter. The adapter for a given key
- can be retrieved via the method Torque.getDB(key).
+ The adapters are stored in the field adapter of the objects
+ kept in the map <code>TorqueInstance.databases</code>.
+ The key of the map is the name of the database (e.g. "bookstore").
+ The adapter for a given key can be retrieved via the method
+ Torque.getDB(key).
</p>
<p>
@@ -186,7 +227,7 @@
<section name="DataSourceFactories">
<p>
To access a database, a connection must be made to the database.
- A DataSource is an object which can provide Connections to the
+ A DataSource is an object which can provide connections to the
database. A DataSourceFactory is used to configure and provide
one DataSource.
</p>
@@ -194,10 +235,8 @@
<p>
All DataSourceFactories used by Torque must implement the interface
<code>org.apache.torque.dsfactory.DataSourceFactory</code>.
- The DataSourceFactories are stored in the private map
- <code>TorqueInstance.dsFactoryMap</code>; the key of the map is the
- name of the database (e.g. "bookstore"), and the
- value of the map is the DataSourceFactory.
+ The adapters are stored in the field dataSourceFactory of the objects
+ kept in the map <code>TorqueInstance.databases</code>.
The DataSourceFactory for a given key can not be retrieved
by a public method; however, a connection from the DataSource
for the DataSourceFactory for a given key can be obtained
@@ -207,7 +246,7 @@
<section name="Other classes">
<p>
- The torque runtime library contains more classes than described above.
+ The Torque runtime library contains more classes than described above.
The classes in the packages org.apache.torque.sql
and org.apache.torque.adapter are not considered public API of torque,
i.e. you can use these classes but they cannot be expected to stay
---------------------------------------------------------------------
To unsubscribe, e-mail: torque-dev-unsubscribe@db.apache.org
For additional commands, e-mail: torque-dev-help@db.apache.org