Normally it is not advisable to map primary and foreign key columns (PK and FK) as Java class properties (ObjAttributes). When reverse engineering of the database is done using CayenneModeler, the generated mapping will reflect that PKs and FKs will not be included in the Java class. However, sometimes an application requires access to these values.

For an easier way to obtain an object primary key or to find an object from a known PK, skip to the chapter on the DataObjectUtils class.

Cayenne provides a generic way to access primary and foreign keys by creating custom get* methods in the DataObject subclass. Lets take a Painting class as an example. The following code is generated by CayenneModeler:

package org.apache.art;
 
 public class Painting extends org.apache.art.auto._Painting {
 
-}

+} +

package org.apache.art.auto;
 
 /** Class _Painting was generated by Cayenne.
@@ -108,14 +109,15 @@
         return (String)readProperty("paintingTitle");
     }
 ...
-}

+} +

The following custom methods should be added to the Painting class to access the values of ARTIST_ID and PAINTING_ID:

If you perform class generation using Ant, you can customize class generation templates to generate these methods for you. Eventually CayenneModeler will support this too as optional functionality.

+
 package org.apache.art;
 
 public class Painting extends org.apache.art.auto._Painting {
@@ -133,7 +135,8 @@
                ? (Integer)artist.getObjectId().getIdSnapshot().get(Artist.ARTIST_ID_PK_COLUMN) 
                : null;
    }
-}
+}
+
 

Modified: cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/DataObjects/DataObject Validation/index.html URL: http://svn.apache.org/viewvc/cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne%20Guide/DataObjects/DataObject%20Validation/index.html?rev=829552&r1=829551&r2=829552&view=diff ============================================================================== --- cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/DataObjects/DataObject Validation/index.html (original) +++ cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/DataObjects/DataObject Validation/index.html Sun Oct 25 12:06:20 2009 @@ -90,7 +90,7 @@

Custom validation method implementation would normally append any failures to the provided ValidationResult instance. After validating all non-committed objects, DataContext (or rather its ObjectStore) will check if the ValidationResult is not empty, and throw an exception if there is at least one failure. Typical custom validation method would look like that:

public class Painting extends _Painting {
    ...
    protected void validateForSave(ValidationResult validationResult) {
@@ -105,7 +105,8 @@
       }
    }
    ...
-}

+} +

Validation Methods with Side Effects

Modified: cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/DataObjects/DataObjectUtils/index.html URL: http://svn.apache.org/viewvc/cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne%20Guide/DataObjects/DataObjectUtils/index.html?rev=829552&r1=829551&r2=829552&view=diff ============================================================================== --- cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/DataObjects/DataObjectUtils/index.html (original) +++ cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/DataObjects/DataObjectUtils/index.html Sun Oct 25 12:06:20 2009 @@ -63,18 +63,19 @@

DataObjectUtils class provides an important and easy to use facility to obtain a primary key value from a DataObject and to locate a DataObject in the database for a known primary key. Both operations work in a generic fashion and do not require primary key to be an object property.

Security Warning
DataObjectUtils make it very easy to use a primary key value as a universal "code" for an object in web forms and URLs. This opens a potential security hole in the interface. If application code is not careful enough, a malicious user can gain access to the information she is not allowed to see (e.g. other people's accounts) simply by trying a series of sequential numbers. So, for example, it is probably okay to use product PK to build a bookmarkable link to a catalog product, but it may not be appropriate to do that for a private user profile record.

DataObjectUtils API is really straightforward and self-explanatory. It supports the most common case of a single column integer primary key, but also a more generic case of an arbitrary PK (that can also be compound, i.e. consist of more than one column). Here is an example:

+
 // obtain PK to build a bookmarkable artist page URL
 Artist artist = ...;
 int artistID = DataObjectUtils.intPKForObject(artist);
-String artistURL = "http://www.example.org/catalogapp/artists?a=" + artistID;
+String artistURL = "http://www.example.org/catalogapp/artists?a=" + artistID;
+
 

 
-
+
 // find an artist from URL parameters
 HttpServletRequest request = ...;
 DataContext context = ...;
@@ -82,7 +83,8 @@
 
 if(idString != null) {
   Artist artist = DataObjectUtils.objectForPK(context, Artist.class, Integer.parseInt(idString));
-}
+}
+
 
.


Modified: cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/DataObjects/DataObjects Example/index.html
URL: http://svn.apache.org/viewvc/cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne%20Guide/DataObjects/DataObjects%20Example/index.html?rev=829552&r1=829551&r2=829552&view=diff
==============================================================================
--- cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/DataObjects/DataObjects Example/index.html (original)
+++ cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/DataObjects/DataObjects Example/index.html Sun Oct 25 12:06:20 2009
@@ -62,7 +62,7 @@
 
 

As discussed in DataContext chapter, any changes made to the DataObjects via "set*" methods are synchronized with the database by calling DataContext.commitChanges. Here is an example showing how the Painting object is fetched, modified and saved back. The following modifications are performed: the price of the first retrieved painting is doubled, a new painting is added that belongs to the same artist as the painting fetched before:

import java.math.BigDecimal;
 import java.util.List;
 import org.apache.cayenne.access.DataContext;
@@ -106,10 +106,11 @@
   // save all the changes we've made so far
   ctxt.commitChanges();
 }
-...

+... +

If SQL tracing is turned on, and depending on the preexisting data in the database, the following SQL statements might be printed to console during the commit phase:

[main 12-22 15:50:19] QueryLogger: --- will run 2 queries.
 [main 12-22 15:50:19] QueryLogger: INSERT INTO PAINTING (PAINTING_ID, PAINTING_TITLE, ESTIMATED_PRICE,
  ARTIST_ID) VALUES (?, ?, ?, ?) [params: 200, 'Sunset as it is', 5000000, 10]

Modified: cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/DataObjects/Deleting Objects/index.html
URL: http://svn.apache.org/viewvc/cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne%20Guide/DataObjects/Deleting%20Objects/index.html?rev=829552&r1=829551&r2=829552&view=diff
==============================================================================
--- cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/DataObjects/Deleting Objects/index.html (original)
+++ cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/DataObjects/Deleting Objects/index.html Sun Oct 25 12:06:20 2009
@@ -61,27 +61,29 @@
 Customization

As discussed before, an object must be deleted in the DataContext to trigger a removal of the corresponding row from the database on commit. There are few simple ways to delete individual objects and collections of objects. Quite naturally, a delete operation changes the object state to PersistenceState.DELETED. However there maybe other consequences of such operation for the overall object graph. Such consequences are controlled via delete rules configured for object relationships. Properly configuring delete rules will simplify the application code, as you no longer need to track related objects and do the right thing with them. Other delete rule effects are discussed for each DataContext deletion method individually.

As discussed before, an object must be deleted in the DataContext to trigger a removal of the corresponding row from the database on commit. There are few simple ways to delete individual objects and collections of objects. Quite naturally, a delete operation changes the object state to PersistenceState.DELETED. However there maybe other consequences of such operation for the overall object graph. Such consequences are controlled via Delete Rules configured for object relationships. Properly configuring delete rules will simplify the application code, as you no longer need to track related objects and do the right thing with them. Other delete rule effects are discussed for each DataContext deletion method individually.

Deleting a single object

DataContext context = ...;
 Artist artist = ....;
 
 // this will trigger delete rules for artist, if any
-context.deleteObject(artist);

+context.deleteObject(artist); +

Deleting a collection of objects

DataContext context = ...;
 Artist artist = ....;
 
-context.deleteObjects(artist.getPaintings());

+context.deleteObjects(artist.getPaintings()); +

Deleting in an Iterator

This case can be complicated if an iteration is performed over a relationship list and an object being deleted has a nullify delete rule. Such combination may result in ConcurrencyModificationExceptions as collection underlying the iterator is being modified. If ALL objects in the collection have to be deleted, use "deleteObjects()" method shown above - it will do the right thing. If only a subset of collection objects has to be deleted, you can use the following technique:

+
 DataContext context = ...;
 Artist artist = ....;
 
@@ -96,7 +98,8 @@
       // now do the actual delete
       context.deleteObject(object); 
    }
-}
+}
+
 

Modified: cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/DataObjects/Flattened Relationships/index.html URL: http://svn.apache.org/viewvc/cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne%20Guide/DataObjects/Flattened%20Relationships/index.html?rev=829552&r1=829551&r2=829552&view=diff ============================================================================== --- cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/DataObjects/Flattened Relationships/index.html (original) +++ cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/DataObjects/Flattened Relationships/index.html Sun Oct 25 12:06:20 2009 @@ -61,9 +61,24 @@

Customization

Flattened relationships represent relationship between two types of DataObjects that is not direct in the underlying relational storage. Instead it is mapped across one or more "join" tables. Still from the application point of view there is no diffrence in working with flattened relationships compared to the "normal" ones. Cayenne internally figures out how to build the needed query joins to retrieve related objects. On adding or removing an object to/from a flattened relationship via a corresponding "addTo..." / "removeFrom..." method an appropriate join record is created or removed.

Flattened Relationships Limitations
Currently only many-to-many flattened relatationships with a single join table can be modified. All other types of flattened relationships can be used as "read-only". This is reflected in the DataObject code generated for such relationships - no set/addTo/RemoveFrom methods are created for read-only relationships.

Flattened relationships are a fancy term for a relationship which involves three or more tables in the database. Lets say you have Artists and Exhibits. They are joined with a many-many join table called Artist_Exhibit, because many Artists could collaborate on one Exhibit and each Artist might be part of many Exhibits. Now you could map these as separate joins and end up with Java code which looks like this:

+ +

artist.getArtistExhibits().getExhibits()
+

+ +

but with a flattened join, it is even simpler:

+ +

artist.getExhibits()
+

+ +

From the application point of view there is no difference in working with flattened relationships compared to the "normal" ones. Cayenne internally figures out how to build the needed query joins to retrieve related objects. On adding or removing an object to/from a flattened relationship via a corresponding "addTo..." / "removeFrom..." method an appropriate join record is created or removed.

Flattened Relationships Limitations
Only many-to-many flattened relatationships with a single join table can be modified. All other types of flattened relationships can be used as "read-only". This is reflected in the DataObject code generated for such relationships - no set/addTo/RemoveFrom methods are created for read-only relationships.

+ +

See this documentation on how to create flattened relationships in Cayenne Modeler

Modified: cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/DataObjects/Generic Persistent Class/index.html URL: http://svn.apache.org/viewvc/cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne%20Guide/DataObjects/Generic%20Persistent%20Class/index.html?rev=829552&r1=829551&r2=829552&view=diff ============================================================================== --- cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/DataObjects/Generic Persistent Class/index.html (original) +++ cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/DataObjects/Generic Persistent Class/index.html Sun Oct 25 12:06:20 2009 @@ -65,15 +65,14 @@

Each kind of persistent objects (such as "Artist" or "Painting") is described in Cayenne by a single ObjEntity. The most common and useful scenario is mapping an ObjEntity to a "specialized" Java class, one class per entity. But there is an alternative - use a single generic persistent object class to map any entity.

Generic DataObject hints
-

Generic DataObject hints

Accessing generic objects is done via DataObject API (see examples below).
The simplest "generic" object class for all practical purposes is CayenneDataObject.
"Concrete" DataObject classes are by definition "generic" as they implement DataObject.

When to Use Generic Objects
Generic objects are not type-safe and are not convenient for manual coding. Most applications should stick to concrete classes. Generic objects are useful in cases when all persistent properties are not fully known at compile time. It is also possible to use a hybrid approach when new persistent properties are added to the existing concrete class at runtime.

Mapping in CayenneModeler

@@ -90,53 +89,60 @@

Create a new object:

DataContext context = ...;
-DataObject author = (DataObject) context.newObject("Person");

+DataObject author = (DataObject) context.newObject("Person"); +

Create a new object when using a generic ObjectContext that does not define "newObject(String)" method. In this case we must set ObjectId explicitly - this will tell Cayenne what entity the generic object belongs to:

ObjectContext context = ...;
 DataObject author = new CayenneDataObject();
 author.setObjectId(new ObjectId("Person"));
-context.registerNewObject(author);

+context.registerNewObject(author); +

Build SelectQuery:

Expression e = ExpressionFactory.likeIgnoreCaseExp("subject", "%first%");
-SelectQuery q = new SelectQuery("Message", e);

+SelectQuery q = new SelectQuery("Message", e); +

Use DataObject API to read/write the values instead or getters/setters.

Determine object entity name:

DataObject object = ...;
-String entityName = object.getObjectId().getEntityName();

+String entityName = object.getObjectId().getEntityName(); +

Read a simple property value (attribute or relationship):

String subject = (String) object.readProperty("subject");

String subject = (String) object.readProperty("subject");
+

Read a "nested" property value spanning a chain of DataObjects:

String name = (String) object.readNestedProperty("author.lastName");

String name = (String) object.readNestedProperty("author.lastName");
+

Modify a property value:

object.writeProperty("subject", "Post On Topic");

object.writeProperty("subject", "Post On Topic");
+

Modified: cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/DataObjects/Handling Inheritance/index.html URL: http://svn.apache.org/viewvc/cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne%20Guide/DataObjects/Handling%20Inheritance/index.html?rev=829552&r1=829551&r2=829552&view=diff ============================================================================== --- cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/DataObjects/Handling Inheritance/index.html (original) +++ cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/DataObjects/Handling Inheritance/index.html Sun Oct 25 12:06:20 2009 @@ -61,58 +61,24 @@

Customization

"Inheritance" is an Object Oriented concept absent in traditional RDBMS. Cayenne however allows to map a hierarchical class tree to a single base table (so called "single table inheritance"). Such mapping is described in detail in the Modeler Guide. The idea of single table inheritance is that a "class" of a database row is determined from the values in one or more columns of the base table. These columns are called "class designator columns".

- -

Initial Values of the Classs Designator Columns
Assigning correct values to the "class designator columns" mentioned above is one task that is not yet automated in Cayenne and requires user code in the DataObject, as discussed in the next subsection. In the future versions this will likely be handled in the mapping and completely outside of the Java classes, so the advise below will become obsolete.

Inheritance and new DataObjects

Consider the following class hierarchy (also used in the Modeler Guide example):

If a class designator column is "PERSON_TYPE", AbstractPerson class should define an attribute (for instance called "personType") that maps to PERSON_TYPE. This attribute is redundant and meanigless in Java, since person type is defined already by the Java class of the object, however we still have to keep it around so that when the new objects are saved, correct PERSON_TYPE data is stored in the database. Currently it is a developer responsibility to set "personType" value (or values of any other attributes that map to "class designator columns") when the new object is registered with DataContext. One way to take care of this is to override "setPersistenceState(..)" method on each DataObject class in the inheritance hierarchy to catch when the object is registered with DataContext:

public class Employee extends _Employee {
-    public void setPersistenceState(int state) {
-        super.setPersistenceState(state);
-        
-        // if object was just created
-        if(state == PersistenceState.NEW) {
-           setPersonType("EMPLOYEE");
-        }
-    }
-...
-}
+Cayenne 3.0 has an ability to inject values of designator columns in new objects automatically. In the example above, if ObjEntity Employee has declared qualifier "personType='EMPLOYEE'", a new Employee instance, created using "context.newObject(Employee.class)" will already have a personType attribute set to "EMPLOYEE".
 
-public class Manager extends _Manager {
-    public void setPersistenceState(int state) {
-        super.setPersistenceState(state);
-        
-        // if object was just created
-        if(state == PersistenceState.NEW) {
-           setPersonType("MANAGER");
-        }
-    }
-...
-}
+ Auto-Injection Limitations
The mechanism of injecting values of class designator columns currently supports qualifiers of form "attr=value [AND attr=value]*". Thus, flattened paths, db-paths and other than equality comparisons are not supported. Cayenne will try inject as much as possible, e.g. if ObjEntity "GoodEmployee" has qualifier "personType='EMPLOYEE' and salary>10000", only personType attribute value will be injected.
+
+Whenever manual injecting is required, it is a good practice to perform such operations in PrePersist lifecycle listeners or callbacks
 
-public class CustomerContact extends _CustomerContact {
-    public void setPersistenceState(int state) {
-        super.setPersistenceState(state);
-        
-        // if object was just created
-        if(state == PersistenceState.NEW) {
-           setPersonType("CUSTOMER");
-        }
-    }
-...
-}

Inheritance and SelectQueries

When performing SelectQuery on a table that maps to inheritance hierarchy, Cayenne will only return rows that belong to root class of the query and all its subclasses. No superclasses or objects from parallel inheritance branches will be returned. For example executing a SelectQuery with Employee class as root will potentially return a mix of Employees and Managers (who are also Employees of course), but no CustomerContact objects:

DataContext context;
 ...
 SelectQuery query = new SelectQuery(Employee.class);
@@ -125,12 +91,13 @@
    if(e instanceof Manager) {
    	// do something with manager...
    }
-}

+} +

The need to determine the correct class for each fetched database row makes queries on entities that use inheritance less efficient than the regular queries. If an application doesn't care about the query root class subclasses, the query can be optimized by explicitly turning off inheritance resolution. If this is done, the example above will return all Managers as instances of Employee class, not Manager class:

DataContext context;
 ...
 SelectQuery query = new SelectQuery(Employee.class);
@@ -141,12 +108,13 @@
 List employees = context.performQuery(query);
  
 // employees list will contain no Manager instances...
-// all Managers will be returned as regular Employees

+// all Managers will be returned as regular Employees +

Whenever an object is obtained via a relationship, it is always fully resolved to the lowest possible subclass in an entity inheritance tree.

Use setResolvingInherited(false) with caution, and only if you never plan to work with subclasses. The downside of it is that the DataContext may end up with two objects pointing to the same database row, thus violating uniquing principle. With the above example, this may happen if at a later time user decides to fetch Managers directly, or if a Manager object is obtained via a relationship.

Modified: cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/DataObjects/Relationships/index.html URL: http://svn.apache.org/viewvc/cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne%20Guide/DataObjects/Relationships/index.html?rev=829552&r1=829551&r2=829552&view=diff ============================================================================== --- cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/DataObjects/Relationships/index.html (original) +++ cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/DataObjects/Relationships/index.html Sun Oct 25 12:06:20 2009 @@ -66,7 +66,7 @@

To-One Relationships

"Get" methods for to-one relationships return the target Persistent object. If the object is not in memory yet, it will be fetched on first access. Modifying to-one relationships is no different from modifying attributes - just a simple call to a "set" method:

Painting painting;
 
 // obtain artist for a given painting
@@ -77,17 +77,17 @@
 painting.setToArtist(newArtist);
 
 // or remove Artist at all...
-// painting.setToArtist(null);

+// painting.setToArtist(null); +

When adding or removing an object from any kind of relationship, Cayenne will locate and modify an existing reverse relationship as appropriate.

To-Many Relationships

"Get" methods for to-many relationships return various collections of Persistent objects. To-many relationships can be mapped as Lists (default), Collections, Sets or Maps. Below we may refer to all four types of mappings as "collections", although strictly speaking Map is not a Collection in Java.

Just like individual Persistent objects, relationship collections are also resolved on first access (e.g. when a user tries to read an element from a collection or obtains an Iterator). For modification there are special "addTo..." and "removeFrom..." methods:

Artist artist;
 
 // obtain a list of paintings
@@ -101,12 +101,13 @@
 
 // add a new painting
 Painting newPainting = (Painting)context.newObject(Painting.class);
-artist.addToPaintingArray(newPainting);

+artist.addToPaintingArray(newPainting); +

Not much difference in managing Map relationships. Let's assume that Artist's paintings are modeled as a map, keyed by painting name:

Artist artist;
 
 // obtain a map of paintings
@@ -127,12 +128,13 @@
 // unless the key is object id:
 newPainting.setName("New Painting");
 
-artist.addToPaintingMap(newPainting);

+artist.addToPaintingMap(newPainting); +

There's one caveat though - if an object property that is used as a map key changes, the object is remapped in the relationship only after the context is committed:

Painting girl = (Painting) paintings.get("Girl");
 girl.setName("New Name");
 
@@ -160,7 +162,9 @@
 
 if(paintings.get("New Name") != null) {
    // now true
-}

+} + +

Modified: cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Deployment/Configuring Logging/index.html URL: http://svn.apache.org/viewvc/cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne%20Guide/Deployment/Configuring%20Logging/index.html?rev=829552&r1=829551&r2=829552&view=diff ============================================================================== --- cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Deployment/Configuring Logging/index.html (original) +++ cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Deployment/Configuring Logging/index.html Sun Oct 25 12:06:20 2009 @@ -58,9 +58,9 @@

Customization

Cayenne logging is based on Jakarta Apache commons-logging package. Commons-logging allows users to choose their own logging provider, such as Log4J or java.util.logging. Below is an example of a Log4J-based configuration of the most important Cayenne logger that turns on and off SQL tracing:

# Turn SQL tracing on
 log4j.logger.org.apache.cayenne.access.QueryLogger = INFO
 
@@ -71,7 +71,7 @@
 
 Another example shows how to trace Cayenne configuration loading. Cayenne XML files may contain errors, or maybe missing or inaccessible by the application; there maybe lots of other reasons why Cayenne fails to startup, from missing JDBC drivers to misspelled database URLs. This logger helps you to debug it:
 
-
+
 log4j.logger.org.apache.cayenne.conf = DEBUG
 log4j.logger.org.apache.cayenne.util = DEBUG
 

Modified: cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Deployment/Customizing Configuration/index.html
URL: http://svn.apache.org/viewvc/cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne%20Guide/Deployment/Customizing%20Configuration/index.html?rev=829552&r1=829551&r2=829552&view=diff
==============================================================================
--- cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Deployment/Customizing Configuration/index.html (original)
+++ cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Deployment/Customizing Configuration/index.html Sun Oct 25 12:06:20 2009
@@ -61,11 +61,12 @@
 A user can create her own subclass of Configuration and use it instead of the classes provided by Cayenne. Custom subclasses are usually created to load configuration files from non-standard locations, to automatically configure Cayenne during certain events that happen in deployment containers, etc. Cayenne provides a few implementations of Configuration discussed later in this chapter.
 
 To ensure that Cayenne uses the correct Configuration class, it must be initialized properly before any calls to Configuration are made:
-
+
 import org.apache.cayenne.conf.Configuration
 ...
 Class myConfigSubclass = my.package.ConfigSubclass.class;
-Configuration.initializeSharedConfiguration(myConfigSubclass);
+Configuration.initializeSharedConfiguration(myConfigSubclass);
+

After this code is executed, any subsequent calls to Configuration.getSharedConfiguration() will return an instance of the custom class instead of DefaultConfiguration.

@@ -74,39 +75,43 @@

DefaultConfiguration

DefaultConfiguration uses the application's class path for locating configuration files; this works for both "expanded" class paths and JAR files. "Out of the box" only resources on the top level of the class path are found; very often it is convenient to have a subdirectory ('package') with configuration files. There are two ways to make Configuration find these files:

import org.apache.cayenne.conf.DefaultConfiguration;
 ...
 DefaultConfiguration conf = new DefaultConfiguration();			
 conf.addClassPath("my/package/conf");
-Configuration.initializeSharedConfiguration(conf);

+Configuration.initializeSharedConfiguration(conf); +

Alternatively you can place an empty subclass of DefaultConfiguration into your package and use that class directly:

import my.package.conf.MyPackageConfiguration;
 ...
-Configuration.initializeSharedConfiguration(new MyPackageConfiguration());

+Configuration.initializeSharedConfiguration(new MyPackageConfiguration()); +

FileConfiguration

FileConfiguration uses the regular file system to load its files, and works very silimar to DefaultConfiguration:

import org.apache.cayenne.conf.FileConfiguration;
 ...
 String fileName = "/some/path/to/my-cayenne.xml";
 FileConfiguration conf = new FileConfiguration(new File(fileName));
-Configuration.initializeSharedConfiguration(conf);

+Configuration.initializeSharedConfiguration(conf); +

The fileName argument can be absolute or relative to the application's working directory, and is checked for accessibility. A more flexible lookup can be done by using the name without any path and adding search paths:

import org.apache.cayenne.conf.FileConfiguration;
 ...
 FileConfiguration conf = new FileConfiguration("my-cayenne.xml");
 conf.addFilesystemPath("a/relative/path");
 conf.addFilesystemPath("/another/absolute/path");
 conf.addFilesystemPath(new File("/some/path/that/must/exist/"));
-Configuration.initializeSharedConfiguration(conf);

+Configuration.initializeSharedConfiguration(conf); +

The difference between the String and File arguments is that the latter are checked for existence. Both variants can be absolute or relative, and are evaluated in the order in which they are added to the Configuration.

Modified: cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Deployment/DBCPDataSourceFactory/index.html URL: http://svn.apache.org/viewvc/cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne%20Guide/Deployment/DBCPDataSourceFactory/index.html?rev=829552&r1=829551&r2=829552&view=diff ============================================================================== --- cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Deployment/DBCPDataSourceFactory/index.html (original) +++ cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Deployment/DBCPDataSourceFactory/index.html Sun Oct 25 12:06:20 2009 @@ -58,7 +58,7 @@

Customization

As an alternative to a simple and easy-to-use DataSource bundled with Cayenne, it is possible to configure a more feature-rich DataSource based on Apache Jakarta commons-dbcp. To enable commons-dbcp pool, select DBCPDataSourceFactory in the Modeler for a DataNode:

@@ -68,7 +68,7 @@

Here is an example of such properties file contents:

sample-dbcp.properties

cayenne.dbcp.driverClassName=com.mysql.jdbc.Driver
 cayenne.dbcp.url=jdbc:mysql://localhost/cayenne
 cayenne.dbcp.username=john

Modified: cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Deployment/Standalone Applications/index.html
URL: http://svn.apache.org/viewvc/cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne%20Guide/Deployment/Standalone%20Applications/index.html?rev=829552&r1=829551&r2=829552&view=diff
==============================================================================
--- cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Deployment/Standalone Applications/index.html (original)
+++ cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Deployment/Standalone Applications/index.html Sun Oct 25 12:06:20 2009
@@ -62,10 +62,11 @@
 
 In a standalone Java application, DefaultConfiguration is used to locate and load configuration files. This approach does not require any additional setup. Shared configuration instance can simply be obtained by calling getSharedConfiguration():
 
-
+
 import org.apache.cayenne.conf.Configuration;
 ...           
-Configuration conf = Configuration.getSharedConfiguration();
+Configuration conf = Configuration.getSharedConfiguration();
+

DefaultConfiguration will expect cayenne.xml file to be located in the CLASSPATH. The same is true for DataMaps referenced in cayenne.xml. Their location is resolved relative to CLASSPATH as well. To make these files available to Cayenne, you can simply include them in the root of your application jar file (read Customizing Configuration on how to change that).

@@ -76,19 +77,21 @@

In a setup that relies on shared Configuration a DataContext can be created by calling DataContext.createDataContext() static method that internally uses shared configuration:

import org.apache.cayenne.access.DataContext;
 ...
-DataContext context = DataContext.createDataContext();

+DataContext context = DataContext.createDataContext(); +

Later a DataContext can be passed around in the code explicitly, or it can be bound to an execution thread, making it accessible to all code being run within this thread (e.g. this can be a Swing event thread):

+
 import org.apache.cayenne.access.DataContext;
 ...
 DataContext context = DataContext.createDataContext();
-DataContext.bindThreadDataContext(context);
+DataContext.bindThreadDataContext(context);
+
 

Modified: cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Deployment/Using JNDI/index.html URL: http://svn.apache.org/viewvc/cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne%20Guide/Deployment/Using%20JNDI/index.html?rev=829552&r1=829551&r2=829552&view=diff ============================================================================== --- cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Deployment/Using JNDI/index.html (original) +++ cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Deployment/Using JNDI/index.html Sun Oct 25 12:06:20 2009 @@ -94,7 +94,7 @@

Depending on how the DataSource is mapped in the container, you may optionally need to add a "resource-ref" entry to the web.xml file:

<resource-ref>
    <res-ref-name>jdbc/myds</res-ref-name>
    <res-type>javax.sql.DataSource</res-type>
@@ -108,7 +108,7 @@
 
 Tomcat 5.5 Configuration
 
-
+
 <Context path="/myapp" docBase="myapp">
   <Resource name="jdbc/myds" auth="Container"
           type="javax.sql.DataSource" driverClassName="oracle.jdbc.driver.OracleDriver"

Modified: cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Deployment/Web Applications/index.html
URL: http://svn.apache.org/viewvc/cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne%20Guide/Deployment/Web%20Applications/index.html?rev=829552&r1=829551&r2=829552&view=diff
==============================================================================
--- cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Deployment/Web Applications/index.html (original)
+++ cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Deployment/Web Applications/index.html Sun Oct 25 12:06:20 2009
@@ -62,7 +62,7 @@
 
 When deploying an application in a web container it is possible to follow the procedure for the standalone applications, i.e. put all XML files in the application CLASSPATH (e.g. in "mywebapp/WEB-INF/classes/", but DON'T put it in container shared locations!). Session DataContext can be obtained via ServletUtil:
 
-
+
 HttpSession session = ...;
 DataContext context = ServletUtil.getSessionContext(session);
 
@@ -73,7 +73,7 @@
 
 Adding the following filter to the web.xml would automate Cayenne setup in the web application:
 
-
+
 <filter>
     <filter-name>CayenneFilter</filter-name>
     <filter-class>org.apache.cayenne.conf.WebApplicationContextFilter</filter-class>
@@ -85,15 +85,15 @@
 
 
 
-The filter will ensure that for each matching request a DataContext is bound to the request thread. So you can retrieve it anywhere in the application, even if you don't have a reference to the web environment:
+The filter will ensure that for each matching request a ObjectContext (which is actually a DataContext instance) is bound to the request thread. So you can retrieve it anywhere in the application, even if you don't have a reference to the web environment:
 
-
-DataContext context = DataContext.getThreadDataContext();
+
+ObjectContext context = BaseContext.getThreadObjectContext();
 
 
 Filter can match a specific URL as shown above, or a specific servlet:
 
-
+
 <servlet>
    <servlet-name>MyServlet</servlet-name>
    <servlet-class>org.example.MyServlet</servlet-class>
@@ -113,7 +113,7 @@
 
 Additionally the filter supports putting files in myapp/WEB-INF/ directory instead of the CLASSPATH, so a .war file may look like this:
 
-
+
 index.jsp
 WEB-INF/cayenne.xml
 WEB-INF/xyz.map.xml
@@ -122,7 +122,7 @@
 
 Actually, Cayenne files can be stored in any subdirectory of myapp/WEB-INF/. To specify a subdirectory, you'll need to add <context-param> named cayenne.configuration.path to your application descriptor:
 
-
+
 <context-param>
     <param-name>cayenne.configuration.path</param-name>
     <param-value>/WEB-INF/config/cayenne-files</param-value>

Modified: cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Deployment/index.html
URL: http://svn.apache.org/viewvc/cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne%20Guide/Deployment/index.html?rev=829552&r1=829551&r2=829552&view=diff
==============================================================================
--- cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Deployment/index.html (original)
+++ cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Deployment/index.html Sun Oct 25 12:06:20 2009
@@ -60,13 +60,14 @@
 
 Cayenne application deployment is about configuring the application so that at runtime it can find a main project file (cayenne.xml) and associated resources, such as DataMap and DataNode XML files.
 
-The central point in Cayenne deployment is the Configuration class. It locates and loads all the mapping and configuration information required for Cayenne at runtime. By default Configuration uses a singleton model, i.e. normally there is only one instance of Configuration (or a subclass) that exists in the application. This shared instance can be accessed in the following way:
-
+The central point in Cayenne deployment is the Configuration class. It locates and loads all the mapping and configuration information required for Cayenne at runtime. By default Configuration uses a singleton model, i.e. normally there is only one instance of Configuration (or a subclass) that exists in the application. This shared instance can be accessed in the following way:
+
 import org.apache.cayenne.conf.Configuration;
 import org.apache.cayenne.access.DataDomain;
 ...
 Configuration conf = Configuration.getSharedConfiguration();
-DataDomain domain = conf.getDomain();
+DataDomain domain = conf.getDomain();
+
 
 As discussed in the following chapters Configuration works behind the scenes and users rarely care about it. Application code is normally only concerned with obtaining a DataContext.
 

Modified: cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Design/Cayenne Contract/index.html
URL: http://svn.apache.org/viewvc/cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne%20Guide/Design/Cayenne%20Contract/index.html?rev=829552&r1=829551&r2=829552&view=diff
==============================================================================
--- cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Design/Cayenne Contract/index.html (original)
+++ cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Design/Cayenne Contract/index.html Sun Oct 25 12:06:20 2009
@@ -64,7 +64,7 @@
 
 Cayenne can persist Java objects that implement org.apache.cayenne.Persistent interface. The interface requires for an object to provide getters and setters for three bean properties: objectId, persistenceState and objectContext:
 
-Persistent.java

+Persistent.java

 public interface Persistent extends Serializable {
     ObjectId getObjectId();
 
@@ -128,7 +128,7 @@
 
 If entity A has a relationship to entity B and entity B has a relationshop back to entity A, Cayenne would maintain consistency of the reverse relationship automatically. Consider this example of a many-to-one relationship, written in a form of a unit test:
 
-
+
 A a1;
 B b1;
 B b2;

Modified: cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Design/Persistent Object Lifecycle/index.html
URL: http://svn.apache.org/viewvc/cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne%20Guide/Design/Persistent%20Object%20Lifecycle/index.html?rev=829552&r1=829551&r2=829552&view=diff
==============================================================================
--- cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Design/Persistent Object Lifecycle/index.html (original)
+++ cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Design/Persistent Object Lifecycle/index.html Sun Oct 25 12:06:20 2009
@@ -59,11 +59,11 @@
 A lifecycle of a persistent object can be represented as a number of states and transitions between them. These states are formally defined as "int" constants in org.apache.cayenne.PersistenceState class. Transitions between states (see the diagram below) occur in response to the application interacting with either persistent objects or Cayenne context. Whenever a transition occurs, Cayenne automatically updates "persistenceState" property of all affected objects by calling setPersistenceState().
 
 
-
 
-
+ 
 A new object state transformations:

 
+ 
 A fetched or committed object state transformations:

 
 

Modified: cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Design/Primary Key Generation/Generated Columns/index.html
URL: http://svn.apache.org/viewvc/cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne%20Guide/Design/Primary%20Key%20Generation/Generated%20Columns/index.html?rev=829552&r1=829551&r2=829552&view=diff
==============================================================================
--- cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Design/Primary Key Generation/Generated Columns/index.html (original)
+++ cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Design/Primary Key Generation/Generated Columns/index.html Sun Oct 25 12:06:20 2009
@@ -72,10 +72,11 @@
 
 If you know that your driver supports generated keys API, but Cayenne assumes it does not, you can change this setting manually:
 
-
+
 DataNode node = ...
 JdbcAdapter adapter = (JdbcAdapter) node.getAdapter();
-adapter.setSupportsGeneratedKeys(true);
+adapter.setSupportsGeneratedKeys(true);
+
 
 
 Use of generated keys for PK is configured for each DbEntity individually in CayenneModeler:
@@ -105,8 +106,8 @@
 
 
 
- MS SQLServer Note


-MS drivers prior to 2005 version do not support generated columns, while newer drivers and jTDS support it just fine. Cayenne can automatically detect the driver type and configure SQLServerAdapter, but only when AutoAdapter is used. To make sure auto-detection works, clear the "Custom Adapter" field for the corresponding DataNode in the Modeler.
+ MS SQLServer Note


+MS drivers prior to 2005 version do not support generated columns, while newer drivers and jTDS support it just fine. Cayenne can automatically detect the driver type and configure SQLServerAdapter, but only when AutoAdapter is used. To make sure auto-detection works, clear the "Custom Adapter" field for the corresponding DataNode in the Modeler.
 
   .
   

Added: cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Design/Primary Key Generation/Picture 1.png
URL: http://svn.apache.org/viewvc/cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne%20Guide/Design/Primary%20Key%20Generation/Picture%201.png?rev=829552&view=auto
==============================================================================
Files cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Design/Primary Key Generation/Picture 1.png (added) and cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Design/Primary Key Generation/Picture 1.png Sun Oct 25 12:06:20 2009 differ

Modified: cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Design/Primary Key Generation/index.html
URL: http://svn.apache.org/viewvc/cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne%20Guide/Design/Primary%20Key%20Generation/index.html?rev=829552&r1=829551&r2=829552&view=diff
==============================================================================
--- cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Design/Primary Key Generation/index.html (original)
+++ cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Design/Primary Key Generation/index.html Sun Oct 25 12:06:20 2009
@@ -102,7 +102,8 @@
 
 Primary Key Provided by Database on INSERT
 
-Sometimes databases have their own proprietary mechanism to generate a primary key when a new row is inserted. This feature is called "auto increment" or "identity column". Cayenne supports such primary keys out of the box. For this mechanism to be invoked, PK DbAttributes must be marked as "generated" in the Modeler. Currently MySQL and SQLServer adapters have this feature turned on by default.
+Sometimes databases have their own proprietary mechanism to generate a primary key when a new row is inserted. This feature is called "auto increment" or "identity column". Cayenne supports such primary keys out of the box. For this mechanism to be invoked, the DbEntity primary key generation must be marked as "Database-Generated" in the Modeler. Currently MySQL and SQLServer adapters have this feature turned on by default.

+
 
 Cayenne Generated Primary Key
 
@@ -121,7 +122,7 @@
 
 To generate the necessary database objects for the primary key autogeneration, use CayenneModeler and follow the instructions given here.
 
- Cayenne only supports automatic PK generation for a single column per table.
+ Cayenne only supports automatic PK generation for a single column per table.
 
 Sections
 

Modified: cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Design/Runtime Components/DataChannel/index.html
URL: http://svn.apache.org/viewvc/cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne%20Guide/Design/Runtime%20Components/DataChannel/index.html?rev=829552&r1=829551&r2=829552&view=diff
==============================================================================
--- cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Design/Runtime Components/DataChannel/index.html (original)
+++ cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Design/Runtime Components/DataChannel/index.html Sun Oct 25 12:06:20 2009
@@ -67,7 +67,7 @@
 
 "org.apache.cayenne.DataChannel" is an abstraction of Cayenne persistence stack. It is very simple - it defines only 4 methods, two for actually performing persistent operations, one to access metadata, and one - to access EventManager:
 
-DataChannel.java

+DataChannel.java

 public interface DataChannel {
 
     QueryResponse onQuery(ObjectContext originatingContext, Query query);

Modified: cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Design/Runtime Components/DataSource/index.html
URL: http://svn.apache.org/viewvc/cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne%20Guide/Design/Runtime%20Components/DataSource/index.html?rev=829552&r1=829551&r2=829552&view=diff
==============================================================================
--- cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Design/Runtime Components/DataSource/index.html (original)
+++ cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Design/Runtime Components/DataSource/index.html Sun Oct 25 12:06:20 2009
@@ -67,7 +67,7 @@
 
 DataNode obtains connections via a javax.sql.DataSource. If an application is deployed in a J2EE container, DataSource is normally provided by container via JNDI. For standalone applications (or if you don't want to use JNDI) Cayenne provides its own DataSource that includes connection pooling features. Whenever you select org.apache.cayenne.conf.DriverDataSourceFactory in the Modeler, you are choosing to use Cayenne DataSource. 
 
-Cayenne DataSource implementation is located in the org.apache.cayenne.conn package and is fully independent from the rest of the framework. Since Cayenne DataSource is chosen automatically, users rarely need to know more details. One notable exception are applications requiring users to interactively enter database login information. In this case you can write your own DataSource wrapper, and internally instantiate Cayenne DataSource (org.apache.cayenne.conn.PoolManager) after the user provides login and password.
+Cayenne DataSource implementation is located in the org.apache.cayenne.conn package and is fully independent from the rest of the framework. Since Cayenne DataSource is chosen automatically, users rarely need to know more details. One notable exception are applications requiring users to interactively enter database login information. In this case you can write your own DataSource wrapper, and internally instantiate Cayenne DataSource (org.apache.cayenne.conn.PoolManager) after the user provides login and password.
 
 
   .

Modified: cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Design/Runtime Components/Event Package/index.html
URL: http://svn.apache.org/viewvc/cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne%20Guide/Design/Runtime%20Components/Event%20Package/index.html?rev=829552&r1=829551&r2=829552&view=diff
==============================================================================
--- cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Design/Runtime Components/Event Package/index.html (original)
+++ cayenne/main/trunk/docs/doc/src/main/resources/doc/Documentation/Cayenne Guide/Design/Runtime Components/Event Package/index.html Sun Oct 25 12:06:20 2009
@@ -78,7 +78,7 @@
 
 
 
- The most common error when using EventSubject is not storing a reference to it. This may result in a premature cleanup of a given subject, and automatic unregistering of all listeners. Good practice is to make subject a "public static final" variable of the event sender class if a subject is common for all instances of senders; or make it an ivar of a sender instance if subject is only related to this instance.
+ The most common error when using EventSubject is not storing a reference to it. This may result in a premature cleanup of a given subject, and automatic unregistering of all listeners. Good practice is to make subject a "public static final" variable of the event sender class if a subject is common for all instances of senders; or make it an ivar of a sender instance if subject is only related to this instance.
 
   .