svn commit: r1382268 - in /cayenne/main/branches/STABLE-3.1/docs/docbook/cayenne-guide/src/docbkx: cayennemodeler-application.xml persistent-objects-objectcontext.xml

[aa...@apache.org]

Author: aadamchik
Date: Sat Sep  8 09:25:40 2012
New Revision: 1382268

URL: http://svn.apache.org/viewvc?rev=1382268&view=rev
Log:
docs

generic objects

(cherry picked from commit 9c5b43f17c3075a0d9bc8d3ceb378f0dfcd61ab3)

Modified:
    cayenne/main/branches/STABLE-3.1/docs/docbook/cayenne-guide/src/docbkx/cayennemodeler-application.xml
    cayenne/main/branches/STABLE-3.1/docs/docbook/cayenne-guide/src/docbkx/persistent-objects-objectcontext.xml

Modified: cayenne/main/branches/STABLE-3.1/docs/docbook/cayenne-guide/src/docbkx/cayennemodeler-application.xml
URL: http://svn.apache.org/viewvc/cayenne/main/branches/STABLE-3.1/docs/docbook/cayenne-guide/src/docbkx/cayennemodeler-application.xml?rev=1382268&r1=1382267&r2=1382268&view=diff
==============================================================================
--- cayenne/main/branches/STABLE-3.1/docs/docbook/cayenne-guide/src/docbkx/cayennemodeler-application.xml (original)
+++ cayenne/main/branches/STABLE-3.1/docs/docbook/cayenne-guide/src/docbkx/cayennemodeler-application.xml Sat Sep  8 09:25:40 2012
@@ -20,6 +20,22 @@
 	<section xml:id="modeling-inheritance">
 		<title>Modeling Inheritance</title>
 	</section>
+	<section xml:id="generating-java-classes">
+		<title>Modeling Generic Persistent Classes</title>
+		<para>Normally each ObjEntity is mapped to a specific Java class (such as Artist or
+			Painting) that explicitly declare all entity properties as pairs of getters and setters.
+			However Cayenne allows to map a completly generic class to any number of entities. The
+			only expectation is that a generic class implements
+				<emphasis>org.apache.cayenne.DataObject</emphasis>. So an ideal candidate for a
+			generic class is CayenneDataObject, or some custom subclass of CayenneDataObject.</para>
+		<para>If you don't enter anything for Java Class of an ObjEntity, Cayenne assumes generic
+			mapping and uses the following implicit rules to determine a class of a generic object.
+			If DataMap "Custom Superclass" is set, runtime uses this class to instantiate new
+			objects. If not, org.apache.cayenne.CayenneDataObject is used.</para>
+		<para>Class generation procedures (either done in the Modeler or with Ant or Maven) would
+			skip entities that are mapped to CayenneDataObject explicitly or have no class
+			mapping.</para>
+	</section>
 	<section xml:id="modeling-pk-generation-strategy">
 		<title>Modeling Primary Key Generation Strategy</title>
 	</section>

Modified: cayenne/main/branches/STABLE-3.1/docs/docbook/cayenne-guide/src/docbkx/persistent-objects-objectcontext.xml
URL: http://svn.apache.org/viewvc/cayenne/main/branches/STABLE-3.1/docs/docbook/cayenne-guide/src/docbkx/persistent-objects-objectcontext.xml?rev=1382268&r1=1382267&r2=1382268&view=diff
==============================================================================
--- cayenne/main/branches/STABLE-3.1/docs/docbook/cayenne-guide/src/docbkx/persistent-objects-objectcontext.xml (original)
+++ cayenne/main/branches/STABLE-3.1/docs/docbook/cayenne-guide/src/docbkx/persistent-objects-objectcontext.xml Sat Sep  8 09:25:40 2012
@@ -205,6 +205,27 @@ nested.rollbackChanges();</programlistin
 	</section>
 	<section xml:id="generic-persistent-objects">
 		<title>Generic Persistent Objects</title>
+		<para>As described in the CayenneModeler chapter, Cayenne supports mapping of completely
+			generic classes to specific entities. Although for conveniece most applications should
+			stick with entity-specific class mappings, the generic feature offers some interesting
+			possibilities, such as creating mappings completely on the fly in a running application,
+			etc.</para>
+		<para>Generic objects are first class citizens in Cayenne, and all common persistent
+			operations apply to them as well. There are some pecularities however, described
+			below.</para>
+		<para>When creating a new generic object, either cast your ObjectContext to DataContext
+			(that provides "newObject(String)" API), or provide your object with an explicit
+			ObjectId:<programlisting>DataObject generic = ((DataContext) context).newObject("GenericEntity");</programlisting><programlisting>DataObject generic = new CayenneDataObject();
+generic.setObjectId(new ObjectId("GenericEntity"));
+context.registerNewObject(generic);</programlisting>SelectQuery
+			for generic object should be created passing entity name String in constructor, instead
+			of a Java
+			class:<programlisting>SelectQuery query = new SelectQuery("GenericEntity");</programlisting>Use
+			DataObject API to access and modify properties of a generic
+			object:<programlisting>String name = (String) generic.readProperty("name");
+generic.writeProperty("name", "New Name");</programlisting>This
+			is how an application can obtain entity name of a generic
+			object:<programlisting>String entityName = generic.getObjectId().getEntityName();</programlisting></para>
 	</section>
 	<section xml:id="transactions">
 		<title>Transactions</title>