Added: incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User Guide/Ant Tasks/cdataport/index.html URL: http://svn.apache.org/viewvc/incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User%20Guide/Ant%20Tasks/cdataport/index.html?view=auto&rev=488202 ============================================================================== --- incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User Guide/Ant Tasks/cdataport/index.html (added) +++ incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User Guide/Ant Tasks/cdataport/index.html Mon Dec 18 02:24:19 2006 @@ -0,0 +1,130 @@ + + + + Apache Cayenne Documentation - cdataport + + + +
+
+ Cayenne User Documentation
+ cdataport +
+
+ +
+

Sometimes it is necessary to recreate a database, copying data from another existing database. For instance, recreating development database instance from production data, etc. While most RDBMS provide data import/export tools, they normally require advanced DBA skills to use and are most often not portable across database engines. Cayenne will provide a lightweight ant task to do data porting between the databases with identical schema, using DataMap information.

+ +

cdataport is an Ant task that takes a Cayenne project (cayenne.xml) with at least one DataMap and two DataNodes and ports data from source DataNode to a destination DataNode. All DataMaps linked to either the source or the target DataNode will be considered for porting.

+ +
Parameters
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
AttributeDescriptionRequired
projectFileLocation of Cayenne project file containing mapping.Yes
mapsA comma-separated list of DataMap names within the project, whoose entities data needs to be ported. If ommitted, all DataMaps in the project will be ported.No
srcNodeSource DataNode name.Yes
destNodeDestination DataNode name.Yes
cleanDestIf false, will skip deleting data from the destination tables. True is default.No
includeTablesComma-separated list of tables to include in the port. If ommitted, all mapped DbEntities will be used. It is possible to use "*" to indicate name patterns.No
excludeTablesComma-separated list of tables to exclude from the port. If ommitted, all mapped DbEntities will be used. It is possible to use "*" to indicate name patterns.No
+ +
Examples
+

Here is an example of using cdataport to port data using all source DataMaps, excluding DBEntities with name matching "BILL_*":

+ +

Load the Ant task (note: if you already loaded all Cayenne tasks via an antlib taskdef described before, this step is not needed):

+
+
<taskdef name="cdataport" classname="org.apache.cayenne.tools.DataPortTask">
+     <classpath refid="classpath"/>
+</taskdef>
+
+ +

Invoke the Ant task:

+
+
<cdataport projectFile="subdir/cayenne.xml" srcNode="ProductionNode" destNode="DevNode" excludeTables="BILL_*"/>
+
+ +
.
+
+ + + + + Propchange: incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User Guide/Ant Tasks/cdataport/index.html ------------------------------------------------------------------------------ svn:eol-style = native Added: incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User Guide/Ant Tasks/cdbgen/index.html URL: http://svn.apache.org/viewvc/incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User%20Guide/Ant%20Tasks/cdbgen/index.html?view=auto&rev=488202 ============================================================================== --- incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User Guide/Ant Tasks/cdbgen/index.html (added) +++ incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User Guide/Ant Tasks/cdbgen/index.html Mon Dec 18 02:24:19 2006 @@ -0,0 +1,154 @@ + + + + Apache Cayenne Documentation - cdbgen + + + +
+
+ Cayenne User Documentation
+ cdbgen +
+
+ +
+

cdbgen is an Ant task that uses Cayenne DataMap to drop and/or generate schema objects of a specified database.

+ +

Parameters

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
AttributeDescriptionRequired
mapDataMap XML file to use as a schema descriptor.Yes
adapterJava class implementing org.apache.cayenne.dba.DbAdapter. While this attribute is optional (a generic JdbcAdapter is used if not set), it is highly recommended to specify correct target adapter.No (but strongly recommended)
driverA class of JDBC driver to use for the target database.Yes
urlJDBC connection URL of a target database.Yes
usernameDatabase user name.No
passwordDatabase user password.No
droptablesDefines whether cdbgen should drop the tables before attempting to create new ones. Default is "No".No
droppkDefines whether cdbgen should drop Cayenne primary key support objects. Default is "No".No
createtablesDefines whether cdbgen should create new tables. Default is "Yes".No
createpkDefines whether cdbgen should create Cayenne-specific auto PK objects. Default is "Yes".No
createfkDefines whether cdbgen should create foreign key copnstraints. Default is "Yes".No
+ +
Driver Classpath
Support for "classpath" or "classpathref" attributes is pending. To work around this limitation, JDBC driver (and custom DbAdapter) classpath can be appended to the classpath used to load the task via "taskdef".
+ +

Example

+ +

Load the Ant task (note: if you already loaded all Cayenne tasks via an antlib taskdef described before, this step is not needed):

+
+
<taskdef name="cdbgen" classname="org.apache.cayenne.tools.DbGeneratorTask">
+    <classpath refid="classpath"/>
+</taskdef>
+
+ +

Here is an example of using cdbgen to create DB schema objects on a local HSQLDB.

+ +
+
<cdbgen map="${context.dir}/WEB-INF/DefaultMap.map.xml" 
+    adapter="org.apache.cayenne.dba.hsqldb.HSQLDBAdapter"
+    driver="org.hsqldb.jdbcDriver" 
+    url="jdbc:hsqldb:hsql://localhost/bookmarker" 
+    username="sa"/>
+
+ +
.
+
+ + + + + Propchange: incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User Guide/Ant Tasks/cdbgen/index.html ------------------------------------------------------------------------------ svn:eol-style = native Added: incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User Guide/Ant Tasks/cdeploy/index.html URL: http://svn.apache.org/viewvc/incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User%20Guide/Ant%20Tasks/cdeploy/index.html?view=auto&rev=488202 ============================================================================== --- incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User Guide/Ant Tasks/cdeploy/index.html (added) +++ incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User Guide/Ant Tasks/cdeploy/index.html Mon Dec 18 02:24:19 2006 @@ -0,0 +1,154 @@ + + + + Apache Cayenne Documentation - cdeploy + + + +
+
+ Cayenne User Documentation
+ cdeploy +
+
+ +
+

cdeploy is an Ant task that configures Cayenne connection information in existing jar files that contain Cayenne project information. It is useful for the automation of deployment of Cayenne-based frameworks in different environments.

+ +

Parameters

+ + + + + + + + + + + + + + + + + + + + + +
AttributeDescriptionRequired
srcSource jar file that contains Cayenne project files among other things.Yes
destDestination jar file that should be generated as a result of this task execution. If omitted, src is used.No
altProjectFileAn alternative location of cayenne.xml file. User can specify an arbitrary file. This file will be used as the main project file, replacing any existing cayenne.xml in the source jar. This gives the users an ultimate flexibility in configuring deployment libraries. For instance this feature can be used to deploy standalone DataMaps.No
+ +

Nested Elements:

+ +
node
+

One or more nested "node" elements specify connection information for the named nodes. All nested nodes must exist in the project, or otherwise they will be ignored.
+Nested node Parameters:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
AttributeDescriptionRequired
nameDataNode nameYes
domainParent DataDomain of this node. If omitted, project must have only a single domain (very common case).No
adapterDataNode adapter.No
dataSourceDataSource name to use for this node.No
driverFileFile that contains driver information.No
+ +

"dataSource" and "driverFile" are mutually exclusive, but none of them are required.

+ +

Examples

+ +

Load the Ant task (note: if you already loaded all Cayenne tasks via an antlib taskdef described before, this step is not needed):

+
+
<taskdef name="cdeploy" classname="org.apache.cayenne.tools.DeploymentConfigurator"/>
+
+ +

Here is an example of using cdeploy to regenerate a jar file called "business.jar" with connection info located in "alt.driver.xml":

+ +
+
<cdeploy src="business.jar">
+    <node name="main-node" driverFile="alt.driver.xml"/>
+</cdeploy>
+
+ +

An example of using cdeploy to redeploy a 3rd party library that contains DataMaps, but may not contain cayenne.xml:

+ +
+
<cdeploy src="business.jar" altProjectFile="my-cayenne.xml"/>
+
+ +
.
+
+ + + + + Propchange: incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User Guide/Ant Tasks/cdeploy/index.html ------------------------------------------------------------------------------ svn:eol-style = native Added: incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User Guide/Ant Tasks/cgen/index.html URL: http://svn.apache.org/viewvc/incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User%20Guide/Ant%20Tasks/cgen/index.html?view=auto&rev=488202 ============================================================================== --- incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User Guide/Ant Tasks/cgen/index.html (added) +++ incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User Guide/Ant Tasks/cgen/index.html Mon Dec 18 02:24:19 2006 @@ -0,0 +1,240 @@ + + + + Apache Cayenne Documentation - cgen + + + +
+
+ Cayenne User Documentation
+ cgen +
+
+ +
+

cgen is an Ant task that generates and maintains DataObjects source files based on Cayenne DataMap. If "makepairs" is set to "true" (default), this task will generate a pair of classes (superclass/subclass) for each ObjEntity in the DataMap. Superclasses should not be changed manually, since they are always overwritten. Subclasses are never overwritten and may be later customized by the user. If "makepairs" is set to "false", a single class will be generated for each ObjEntity.

+ +

By creating custom templates, Cgen can also be used to generate other output (such as web pages, reports, specialized code templates) based on DataMap information.

+ +

Parameters

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
AttributeDescriptionRequired
mapDataMap XML file to use as a base for class generation.Yes
additionalMapsPath to additional DataMap XML files to use for class generation.No
destDirDestination directory for Java classes (ignoring their package names).Yes
overwriteIf set to "true", will overwrite older versions of generated classes. Ignored unless makepairs is set to "false".No
makepairsIf set to "true", will generate subclass/superclass pairs, with all generated code included in superclass (default is "true").No
templateLocation of Velocity template file for Java class generation. If omitted, default template is used.No
supertemplateLocation of Velocity template file for Java superclass generation. Ignored unless "makepairs" set to "true". If omitted, default template is used.No
superpkgJava package name of generated superclasses. Ignored unless "makepairs" set to "true". If omitted, each superclass will be assigned the same package as subclass. Note that having superclass in a different package would only make sense when "usepkgpath" is set to "true". Otherwise classes from different packages will end up in the same directory.No
usepkgpathIf set to "true" (default), a directory tree will be generated in "destDir" corresponding to the class package structure, if set to "false", classes will be generated in "destDir" ignoring their package.No
encodingSpecify generated file encoding if different from the default on current platform. Target encoding must be supported by the JVM running Ant build. Standard encodings supported by Java on all platforms are US-ASCII, ISO-8859-1, UTF-8, UTF-16BE, UTF-16LE, UTF-16. See Sun Java Docs for java.nio.charset.Charset for more information.No
versionSpecifies template location and generator behavior. "1.1" is the old behavior, with templates located in "dotemplates" and "classgen" as the only velocity context attribute. "1.2" is the new behavior, with templates located in "dotemplates/v1.2" and "objEntity", "entityUtils", "stringUtils", and "importUtils" in the velocity context. (Default is "1.1")No
excludeEntitiesEntities (expressed as a perl5 regex) to exclude from template generation. (Default is to include all entities in the DataMap)No
includeEntitiesEntities (expressed as a perl5 regex) to include in template generation. (Default is to include all entities in the DataMap)No
outputPatternName of file for generated output. (Default is "*.java")No
modeSpecifies generator iteration target. "entity" performs one iteration for each selected entity. "datamap" performs one iteration per datamap (This is always one iteration since cgen currently supports specifying one-and-only-one datamap). (Default is "entity")No
clientWhether we are generating classes for the client tier in a Remote Object Persistence application. Default is "false"No
+ +

Parameters specified as nested elements

+ + + + + + + + + + + +
AttributeDescriptionRequired
configCGen with version="1.2" also supports VPP config nested elements for configuring the velocity template engine and adding objects to the velocity template. You can also reference a vppconfig element declared outside of the CGen task, but you'll need to insure that both vppconfig and cgen have been loaded with the same classloader by using the same ant taskdef loaderRef value for both tasks. See the VPP VPPConfig Manual page for complete information.No
+ +

Examples

+ +

Load the Ant task (note: if you already loaded all Cayenne tasks via an antlib taskdef described before, this step is not needed):

+ +
+
<taskdef name="cgen" classname="org.apache.cayenne.tools.CayenneGenerator">
+    <classpath refid="classpath"/>
+</taskdef>
+
+ +

Here is an example of using CGen to generate DataObject subclass/superclass pairs from DataMap located in "src/datamap.xml". All generated subclasses and superclasses will be saved in the same directory "src/java/dobj" regardless of their package names:

+
+
<cgen map="src/datamap.xml" destDir="src/java/dobj" usepkgpath="false"/>
+
+

Here is an example of using CGen to generate html pages for all entities starting with "Artist" in the DataMap:

+
+
<cgen map="src/datamap.xml" destDir="src/doc/web" makepairs="false" usepkgpath="false"
+    template="EntityReport.vm" includeEntities="Artist*" outputPattern="*Report.html"/>
+
+ +

Here is an example of using CGen with a nested config element:

+ +
+
<cgen map="src/datamap.xml"
+    destDir="src/doc/web"
+    makepairs="false"
+    usepkgpath="false"
+    template="EntityReport.vm"
+    includeEntities="Artist*"
+    outputPattern="*Report.html">
+    <config>
+        <context>
+            <property key="myPropertyName" value="myPropertyValue" />
+            <tool key="myToolName" className="org.myDomain.MyTool" />
+        </context>
+    </config>
+</cgen>
+
+ +

Here is an example of using CGen with vppconfig:

+ +
+
<typedef name="vppconfig"
+    classname="foundrylogic.vpp.VPPConfig"
+    loaderref="aclasspathloader">
+    <classpath refid="aclasspath"/>
+</typedef>
+
+<vppconfig id="myconfig">
+    <context>
+        <property key="myPropertyName" value="myPropertyValue" />
+        <tool key="myToolName" className="org.myDomain.MyTool" />
+    </context>
+</vppconfig>
+
+<cgen map="src/datamap.xml"
+    destDir="src/doc/web"
+    makepairs="false"
+    usepkgpath="false"
+    template="EntityReport.vm"
+    includeEntities="Artist*"
+    outputPattern="*Report.html">
+    <config refid="myconfig" />
+</cgen>
+
+ +
.
+
+ + + + + Propchange: incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User Guide/Ant Tasks/cgen/index.html ------------------------------------------------------------------------------ svn:eol-style = native Added: incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User Guide/Ant Tasks/index.html URL: http://svn.apache.org/viewvc/incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User%20Guide/Ant%20Tasks/index.html?view=auto&rev=488202 ============================================================================== --- incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User Guide/Ant Tasks/index.html (added) +++ incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User Guide/Ant Tasks/index.html Mon Dec 18 02:24:19 2006 @@ -0,0 +1,88 @@ + + + + Apache Cayenne Documentation - Ant Tasks + + + +
+
+ Cayenne User Documentation
+ Ant Tasks +
+
+ +
+

Cayenne ships with Ant tasks that provide Ant frontend to a number of useful operations in Cayenne. The following tasks are included:

+ + + + +

Importing Cayenne Tasks in build.xml

+

Cayenne tasks above can be imported individually using Ant taskdef, as described in each task documentation page. However the users of Ant 1.6 and newer can take advantage of Antlib Ant feature. Antlib allows 3rd party tasks and types to be defined easily. Cayenne has an embedded antlib.xml descriptor file in the package org.apache.cayenne.tools. All of Cayenne's Ant tasks can be defined at once using the following definition in your Ant build file:

+ +
+
<typedef resource="org/apache/cayenne/tools/antlib.xml"> 
+   <classpath refid="classpath"/> 
+</typedef>
+
+ +

When using the Antlib construct, omit the <taskdef> elements shown in the examples of each task, as the antlib.xml file defines all of the Cayenne Ant tasks.

+ +
+ +
.
+
+ + + + + Propchange: incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User Guide/Ant Tasks/index.html ------------------------------------------------------------------------------ svn:eol-style = native Added: incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User Guide/Caching and Fresh Data/RefreshQuery/index.html URL: http://svn.apache.org/viewvc/incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User%20Guide/Caching%20and%20Fresh%20Data/RefreshQuery/index.html?view=auto&rev=488202 ============================================================================== --- incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User Guide/Caching and Fresh Data/RefreshQuery/index.html (added) +++ incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User Guide/Caching and Fresh Data/RefreshQuery/index.html Mon Dec 18 02:24:19 2006 @@ -0,0 +1,116 @@ + + + + Apache Cayenne Documentation - RefreshQuery + + + +
+
+ Cayenne User Documentation
+ RefreshQuery +
+
+ +
+

Motivation

+ +

There is a need for a simple to use cache management mechanism that handles both individual objects and cached query results, transparently interacting with multi-level caches that exist in Cayenne. Currently there are a number of solutions that are not unified and are hard to comprehend:

+ + + + +

Use Cases

+ +

Refresh a collection of objects

+ +

Internally Cayenne will remove those objects from caches. All object relationships should be invalidated as well. No query results are affected, but objects in those result lists should get invalidated.

+ +

Limitation: shared list cache stores all results as DataRows and doesn't use uniquing ... so such refresh would fail to invalidate ids stored in the shared cache; possible solution - store ObjectIds in the shared cache instead of full DataRows and resolve them on the fly.

+ +

Refresh a single object

+ +

A special case of refresh collection of objects. Should probably use the same logic.

+ +

Refresh results of a query

+ +

Query lists are removed from caches. Since any objects matched by query need to be refreshed as well, the query is executed eagerly.

+ +

Refresh results of a group of queries identified by one or more cache group names.

+ +

Removes or invalidates query results for the specified group keys, in hope that the objects will be refreshed the next time any query from the group is executed.

+ +

Limitation: This is the only case that doesn't allow to target individual objects.

+ +

Refresh All

+ +

Refreshes all objects (including reverting and refreshing dirty objects) and all query results. This can be done lazily. Not sure if we need fine-grained control (refresh a single context; refresh shared caches).

+ +

Proposed Solution: RefreshQuery

+ +

Related JIRA issue: http://issues.apache.org/cayenne/browse/CAY-632
+RefreshQuery: http://svn.apache.org/repos/asf/incubator/cayenne/main/trunk/core/cayenne-jdk1.4/src/main/java/org/apache/cayenne/query/RefreshQuery.java

+ +

There are the following advantages to this approach:

+ + + + +
+ +
.
+
+ + + + + Propchange: incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User Guide/Caching and Fresh Data/RefreshQuery/index.html ------------------------------------------------------------------------------ svn:eol-style = native Added: incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User Guide/Caching and Fresh Data/index.html URL: http://svn.apache.org/viewvc/incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User%20Guide/Caching%20and%20Fresh%20Data/index.html?view=auto&rev=488202 ============================================================================== --- incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User Guide/Caching and Fresh Data/index.html (added) +++ incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User Guide/Caching and Fresh Data/index.html Mon Dec 18 02:24:19 2006 @@ -0,0 +1,65 @@ + + + + Apache Cayenne Documentation - Caching and Fresh Data + + + +
+
+ Cayenne User Documentation
+ Caching and Fresh Data +
+
+ +
+

TODO

+
+ +
.
+
+ + + + + Propchange: incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User Guide/Caching and Fresh Data/index.html ------------------------------------------------------------------------------ svn:eol-style = native Added: incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User Guide/Customizing/Extended Types/index.html URL: http://svn.apache.org/viewvc/incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User%20Guide/Customizing/Extended%20Types/index.html?view=auto&rev=488202 ============================================================================== --- incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User Guide/Customizing/Extended Types/index.html (added) +++ incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User Guide/Customizing/Extended Types/index.html Mon Dec 18 02:24:19 2006 @@ -0,0 +1,85 @@ + + + + Apache Cayenne Documentation - Extended Types + + + +
+
+ Cayenne User Documentation
+ Extended Types +
+
+ +
+

JDBC specification defines a set of "standard" database column types (defined in java.sql.Types class) and a very specific mapping of these types to Java Object Types, such as java.lang.String, java.math.BigDecimal, etc. Sometimes there is a need to use a custom Java type not known to JDBC driver. CayenneModeler allows to configure an arbitrary Java class as an org.apache.cayenne.map.ObjAttribute type by simply entering a fully-qualified name such class in the type column of an ObjAttribute. However there is more to it than just that. Cayenne needs to know how to instantiate this type from a database "primitive" value, and conversly, how to transform an object of the custom type to a JDBC-compatible object.

+ +

Supporting Non-Standard Types

+ +

org.apache.cayenne.access.types.ExtendedType interface serves to integrate a custom attribute type to Cayenne. An implementation must provide ExtendedType.getClassName() method that returns a fully qualified Java class name for the supported custom type, and a number of methods that convert data between JDBC and custom type. Installing an ExtendedType currently has to be done in the code, some time during Cayenne startup (modeler support will be added in the future). The following code sample demonstrates this procedure:

+
+
// create custom ExtendedType instance
+ExtendedType customType = new MyCustomType();
+
+// Find DataNode
+DataDomain domain = Configuration.getSharedConfiguration().getDomain();
+DataNode node = domain.getNode("node_name_from_the_project");
+
+// install ExtendedType
+node.getAdapter().getExtendedTypes().registerType(customType);
+
+ +

DbAdapters and Extended Types

+ +

As shown in the example above, ExtendedTypes are stored by DbAdapter. In fact DbAdapters often install their own extended types to address incompatibilities, incompletness and differences between JDBC drivers in handling "standard" JDBC types. For instance some drivers support reading large character columns (CLOB) as java.sql.Clob, but some other - as "character stream", etc. Adapters provided with Cayenne override configureExtendedTypes() method to install their own types, possibly substituting Cayenne defaults. Custom DbAdapters can use the same technique.

+ +
.
+
+ + + + + Propchange: incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User Guide/Customizing/Extended Types/index.html ------------------------------------------------------------------------------ svn:eol-style = native Added: incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User Guide/Customizing/index.html URL: http://svn.apache.org/viewvc/incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User%20Guide/Customizing/index.html?view=auto&rev=488202 ============================================================================== --- incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User Guide/Customizing/index.html (added) +++ incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User Guide/Customizing/index.html Mon Dec 18 02:24:19 2006 @@ -0,0 +1,71 @@ + + + + Apache Cayenne Documentation - Customizing + + + +
+
+ Cayenne User Documentation
+ Customizing +
+
+ +
+
+

Here we will discuss a few Cayenne customization techniques:

+ + + +
+ +
.
+
+ + + + + Propchange: incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User Guide/Customizing/index.html ------------------------------------------------------------------------------ svn:eol-style = native Added: incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User Guide/DataContext/DataContextDelegate/index.html URL: http://svn.apache.org/viewvc/incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User%20Guide/DataContext/DataContextDelegate/index.html?view=auto&rev=488202 ============================================================================== --- incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User Guide/DataContext/DataContextDelegate/index.html (added) +++ incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User Guide/DataContext/DataContextDelegate/index.html Mon Dec 18 02:24:19 2006 @@ -0,0 +1,92 @@ + + + + Apache Cayenne Documentation - DataContextDelegate + + + +
+
+ Cayenne User Documentation
+ DataContextDelegate +
+
+ +
+
+

DataContext supports runtime customization via a DataContextDelegate interface. A user can assign a custom delegate instance to a DataContext by calling DataContext.setDelegate(..). Delegate is optional, and if it is not set, DataContext would go on with its default behavior. If a delegate is set, DataContext consults with it at some critical points in the normal flow execution. A delegate can modify the flow, abort an operation, modify objects participating in an operation, or perform any other tasks it deems necessary.

+ +

DataContextDelegate currently has two groups of methods - method to filter select queries, and methods to react to external updates of the ObjectStore:

+ + + + +

Called from DataContext.performQuery(...) before running any select query, including prefetch queries. Implementation has a choice to modify an original query, replace it with alternative one, or return NULL, blocking query execution alltogether.

+ + + + +

These methods are called by the ObjectStore whenever it performs an update of its state triggered by external events. Default ObjectStore behavior is to merge all changes to the existing objects, and change deleted objects state to TRANSIENT, removing them from the store. Delegate has an option to abort standard processing by returning "false" from "should*" methods.

+ +
.
+
+ + + + + Propchange: incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User Guide/DataContext/DataContextDelegate/index.html ------------------------------------------------------------------------------ svn:eol-style = native Added: incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User Guide/DataContext/DataContextFactory/datacontextfactory.jpg URL: http://svn.apache.org/viewvc/incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User%20Guide/DataContext/DataContextFactory/datacontextfactory.jpg?view=auto&rev=488202 ============================================================================== Binary file - no diff available. Propchange: incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User Guide/DataContext/DataContextFactory/datacontextfactory.jpg ------------------------------------------------------------------------------ svn:mime-type = application/octet-stream Added: incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User Guide/DataContext/DataContextFactory/index.html URL: http://svn.apache.org/viewvc/incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User%20Guide/DataContext/DataContextFactory/index.html?view=auto&rev=488202 ============================================================================== --- incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User Guide/DataContext/DataContextFactory/index.html (added) +++ incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User Guide/DataContext/DataContextFactory/index.html Mon Dec 18 02:24:19 2006 @@ -0,0 +1,74 @@ + + + + Apache Cayenne Documentation - DataContextFactory + + + +
+
+ Cayenne User Documentation
+ DataContextFactory +
+
+ +
+

To customize how the DataContext is built, an optional DataContextFactory can be registered with DataDomain in the Modeler. The class name you enter must implement org.apache.cayenne.access.DataContextFactory interface. If a factory is entered, Cayenne will use it in all places where the DataContext is created. A single factory instance is reused for the life of the DataDomain.

+ +

+ +
.
+
+ + + + + Propchange: incubator/cayenne/main/trunk/assembly/cayenne-generic/src/doc/confluence/Documentation/User Guide/DataContext/DataContextFactory/index.html ------------------------------------------------------------------------------ svn:eol-style = native