From: <jul...@us...> - 2011-02-10 15:25:39
|
Revision: 5378 http://nhibernate.svn.sourceforge.net/nhibernate/?rev=5378&view=rev Author: julian-maughan Date: 2011-02-10 15:25:32 +0000 (Thu, 10 Feb 2011) Log Message: ----------- Adding first draft of 'read-only entity' documentation Modified Paths: -------------- branches/ReadOnlyEntities/nhibernate/doc/reference/master.xml Added Paths: ----------- branches/ReadOnlyEntities/nhibernate/doc/reference/modules/readonly.xml Modified: branches/ReadOnlyEntities/nhibernate/doc/reference/master.xml =================================================================== --- branches/ReadOnlyEntities/nhibernate/doc/reference/master.xml 2011-02-10 14:29:39 UTC (rev 5377) +++ branches/ReadOnlyEntities/nhibernate/doc/reference/master.xml 2011-02-10 15:25:32 UTC (rev 5378) @@ -13,13 +13,14 @@ <!ENTITY manipulating-data SYSTEM "modules/manipulating_data.xml"> <!ENTITY transactions SYSTEM "modules/transactions.xml"> <!ENTITY events SYSTEM "modules/events.xml"> -<!ENTITY batch SYSTEM "modules/batch.xml"> +<!ENTITY batch SYSTEM "modules/batch.xml"> <!ENTITY query-hql SYSTEM "modules/query_hql.xml"> <!ENTITY query-criteria SYSTEM "modules/query_criteria.xml"> <!ENTITY query-queryover SYSTEM "modules/query_queryover.xml"> <!ENTITY query-sql SYSTEM "modules/query_sql.xml"> <!ENTITY filters SYSTEM "modules/filters.xml"> <!ENTITY performance SYSTEM "modules/performance.xml"> +<!ENTITY read-only SYSTEM "modules/readonly.xml"> <!ENTITY toolset-guide SYSTEM "modules/toolset_guide.xml"> <!ENTITY example-parentchild SYSTEM "modules/example_parentchild.xml"> <!ENTITY example-weblog SYSTEM "modules/example_weblog.xml"> @@ -38,7 +39,7 @@ <bookinfo> <title>NHibernate - Relational Persistence for Idiomatic .NET</title> <subtitle>NHibernate Reference Documentation</subtitle> - <releaseinfo>3.0.0</releaseinfo> + <releaseinfo>3.0.1</releaseinfo> </bookinfo> <toc /> @@ -59,6 +60,7 @@ &inheritance-mapping; &manipulating-data; + &read-only; &transactions; &events; &batch; Added: branches/ReadOnlyEntities/nhibernate/doc/reference/modules/readonly.xml =================================================================== --- branches/ReadOnlyEntities/nhibernate/doc/reference/modules/readonly.xml (rev 0) +++ branches/ReadOnlyEntities/nhibernate/doc/reference/modules/readonly.xml 2011-02-10 15:25:32 UTC (rev 5378) @@ -0,0 +1,823 @@ +<chapter id="readonly"> + <title>Read-only entities</title> + + <important> + <para> + NHibernate's treatment of <emphasis>read-only</emphasis> entities may + differ from what you may have encountered elsewhere. Incorrect usage + may cause unexpected results. + </para> + </important> + + <para> + When an entity is read-only: + + <itemizedlist> + <listitem> + <para> + NHibernate does not dirty-check the entity's simple + properties or single-ended associations; + </para> + </listitem> + <listitem> + <para> + NHibernate will not update simple properties or updatable + single-ended associations; + </para> + </listitem> + <listitem> + <para> + NHibernate will not update the version of the read-only + entity if only simple properties or single-ended + updatable associations are changed; + </para> + </listitem> + </itemizedlist> + </para> + + <para> + In some ways, NHibernate treats read-only entities the same as entities that are + not read-only: + + <itemizedlist> + <listitem> + <para> + NHibernate cascades operations to associations as + defined in the entity mapping. + </para> + </listitem> + <listitem> + <para> + NHibernate updates the version if the entity has a + collection with changes that dirties the entity; + </para> + </listitem> + <listitem> + <para> + A read-only entity can be deleted. + </para> + </listitem> + </itemizedlist> + </para> + + <para> + Even if an entity is not read-only, its collection association can + be affected if it contains a read-only entity. + </para> + + <para> + For details about the affect of read-only entities on different + property and association types, see + <xref linkend="readonly-proptypes"/>. + </para> + + <para> + For details about how to make entities read-only, see + <xref linkend="readonly-api"/> + </para> + + <para> + NHibernate does some optimizing for read-only entities: + </para> + <itemizedlist> + <listitem> + <para> + It saves execution time by not dirty-checking simple properties or + single-ended associations. + </para> + </listitem> + <listitem> + <para> + It saves memory by deleting database snapshots. + </para> + </listitem> + </itemizedlist> + + <section id="readonly-api"> + <title>Making persistent entities read-only</title> + + <para> + Only persistent entities can be made read-only. Transient and + detached entities must be put in persistent state before they + can be made read-only. + </para> + + <para> + NHibernate provides the following ways to make persistent entities read-only: + </para> + + <itemizedlist> + <listitem> + <para> + you can map an entity class as <emphasis>immutable</emphasis>; + when an entity of an immutable class is made persistent, + NHibernate automatically makes it read-only. + see <xref linkend="readonly-api-immutable"/> for details + </para> + </listitem> + <listitem> + <para> + you can change a default so that entities loaded + into the session by NHibernate are automatically + made read-only; see <xref linkend="readonly-api-loaddefault"/> for details + </para> + </listitem> + <listitem> + <para> + you can make an HQL query or criteria read-only so + that entities loaded when the query or criteria executes, + or iterates, are automatically + made read-only; see <xref linkend="readonly-api-querycriteria"/> for details + </para> + </listitem> + <listitem> + <para> + you can make a persistent entity that is already in the + in the session read-only; see + <xref linkend="readonly-api-entity"/> for details + </para> + </listitem> + </itemizedlist> + + <section id="readonly-api-immutable"> + <title>Entities of immutable classes</title> + + <para> + When an entity instance of an immutable class is made + persistent, NHibernate automatically makes it read-only. + </para> + <para> + An entity of an immutable class can created + and deleted the same as an entity of a mutable class. + </para> + + <para> + NHibernate treats a persistent entity of an immutable + class the same way as a read-only persistent entity + of a mutable class. The only exception is that + NHibernate will not allow an entity of an immutable + class to be changed so it is not read-only. + </para> + + </section> + + <section id="readonly-api-loaddefault"> + <title>Loading persistent entities as read-only</title> + + <note> + <para> + Entities of immutable classes are automatically loaded + as read-only. + </para> + </note> + + <para> + To change the default behavior so NHibernate loads entity + instances of mutable classes into the session and automatically + makes them read-only, call: + </para> + <programlisting role="c#">Session.DefaultReadOnly = true;</programlisting> + + <para> + To change the default back so entities loaded by NHibernate are not + made read-only, call: + </para> + <programlisting role="c#">Session.DefaultReadOnly = false;</programlisting> + + <para> + You can determine the current setting by using the property: + </para> + <programlisting role="c#">Session.DefaultReadOnly;</programlisting> + + <para> + If Session.DefaultReadOnly property returns true, entities loaded by + the following are automatically made read-only: + </para> + <itemizedlist> + <listitem> + <para> + Session.Load() and Session.Load<T> + </para> + </listitem> + <listitem> + <para> + Session.Get() and Session.Get<T> + </para> + </listitem> + <listitem> + <para> + Session.Merge() + </para> + </listitem> + <listitem> + <para> + executing, or iterating HQL queries and + criteria; to override this setting for a particular + HQL query or criteria see + <xref linkend="readonly-api-querycriteria"/> + </para> + </listitem> + </itemizedlist> + + <para> + Changing this default has no effect on: + </para> + <itemizedlist> + <listitem> + <para> + persistent entities already in the session when the + default was changed + </para> + </listitem> + <listitem> + <para> + persistent entities that are refreshed via + Session.Refresh(); a refreshed persistent + entity will only be read-only if it was + read-only before refreshing + </para> + </listitem> + <listitem> + <para> + persistent entities added by the application via + Session.Persist(), Session.Save(), and Session.Update() + Session.SaveOrUpdate() + </para> + </listitem> + </itemizedlist> + + </section> + + <section id="readonly-api-querycriteria"> + <title>Loading read-only entities from an HQL query/criteria</title> + + <note> + <para> + Entities of immutable classes are automatically loaded + as read-only. + </para> + </note> + + <para> + If Session.DefaultReadOnly returns false (the default) + when an HQL query or criteria executes, then entities + and proxies of mutable classes loaded by the query will + not be read-only. + </para> + + <para> + You can override this behavior so that entities and proxies loaded + by an HQL query or criteria are automatically made read-only. + </para> + + <para> + For an HQL query, call: + </para> + <programlisting role="c#">Query.SetReadOnly(true);</programlisting> + + <para> + <literal>Query.SetReadOnly(true)</literal> must be called before + <literal>Query.List()</literal>, <literal>Query.UniqueResult()</literal>, or <literal>Query.Iterate()</literal> + </para> + + <para> + For an HQL criteria, call: + </para> + <programlisting role="c#">Criteria.SetReadOnly(true);</programlisting> + + <para> + <literal>Criteria.SetReadOnly(true)</literal> must be called before + <literal>Criteria.List()</literal>, or <literal>Criteria.UniqueResult()</literal> + </para> + + <para> + Entities and proxies that exist in the session before being returned + by an HQL query or criteria are not affected. + </para> + + <para> + Uninitialized persistent collections returned by the query are + not affected. Later, when the collection is initialized, + entities loaded into the session will be read-only if + Session.DefaultReadOnly returns true. + </para> + + <para> + Using <literal>Query.SetReadOnly(true)</literal> or + <literal>Criteria.SetReadOnly(true)</literal> works well + when a single HQL query or criteria loads all the entities and + intializes all the proxies and collections that the application + needs to be read-only. + </para> + + <para> + When it is not possible to load and initialize all + necessary entities in a single query or criteria, + you can temporarily change the session default to load + entities as read-only before the query is executed. + Then you can explicitly initialize proxies and collections + before restoring the session default. + </para> + + <programlisting role="c#"> +ISession session = factory.OpenSession(); +ITransaction tx = session.BeginTransaction(); + +session.DefaultReadOnly = true; +Contract contract = session.CreateQuery("from Contract where CustomerName = 'Sherman'").UniqueResult<Contract>(); +NHibernate.Initialize(contract.Plan); +NHibernate.Initialize(contract.Variations); +NHibernate.Initialize(contract.Notes); +session.DefaultReadOnly = false; +... +tx.Commit(); +session.Close(); + +</programlisting> + + <para> + If Session.DefaultReadOnly returns true, then you can + use Query.SetReadOnly(false) and Criteria.SetReadOnly(false) + to override this session setting and load entities that are + not read-only. + </para> + + </section> + + <section id="readonly-api-entity"> + <title>Making a persistent entity read-only</title> + <note> + <para> + Persistent entities of immutable classes are automatically + made read-only. + </para> + </note> + + <para> + To make a persistent entity or proxy read-only, call: + </para> + <programlisting>Session.SetReadOnly(entityOrProxy, true)</programlisting> + + <para> + To change a read-only entity or proxy of a mutable class so + it is no longer read-only, call: + </para> + <programlisting>Session.SetReadOnly(entityOrProxy, false)</programlisting> + + <important> + <para> + When a read-only entity or proxy is changed so it is no longer + read-only, NHibernate assumes that the current state of the + read-only entity is consistent with its database representation. + If this is not true, then any non-flushed changes made before + or while the entity was read-only, will be ignored. + </para> + </important> + + <para> + To throw away non-flushed changes and make the persistent entity + consistent with its database representation, call: + </para> + <programlisting role="c#">Session.Refresh(entity);</programlisting> + + <para> + To flush changes made before or while the entity + was read-only and make the database representation + consistent with the current state of the persistent + entity: + </para> +<programlisting role="c#"> +// evict the read-only entity so it is detached +session.Evict(entity); + +// make the detached entity (with the non-flushed changes) persistent +session.Update(entity); + +// now entity is no longer read-only and its changes can be flushed +s.Flush(); +</programlisting> + </section> + </section> + + <section id="readonly-proptypes"> + <title>Read-only affect on property type</title> + + <para> + The following table summarizes how different property types are + affected by making an entity read-only. + </para> + + <table frame="topbot" id="readonly-proptype-summary"> + <title>Affect of read-only entity on property types</title> + <tgroup cols="2"> + <colspec colwidth="1*"/> + <colspec colwidth="1*"/> + <thead> + <row> + <entry>Property/Association Type</entry> + <entry>Changes flushed to DB?</entry> + </row> + </thead> + <tbody> + <row> + <entry> + Simple + <para> + (<xref linkend="readonly-proptypes-simple"/>) + </para> + </entry> + <entry>no*</entry> + </row> + <row> + <entry> + <para>Unidirectional one-to-one</para> + <para>Unidirectional many-to-one</para> + <para> + (<xref linkend="readonly-proptypes-singleended-unidir"/>) + </para> + </entry> + + <entry> + <para>no*</para> + <para>no*</para> + </entry> + </row> + <row> + <entry> + <para>Unidirectional one-to-many</para> + <para>Unidirectional many-to-many</para> + <para> + (<xref linkend="readonly-proptypes-manyended-unidir"/>) + </para> + </entry> + <entry> + <para>yes</para> + <para>yes</para> + </entry> + </row> + <row> + <entry> + <para>Bidirectional one-to-one</para> + <para> + (<xref linkend="readonly-proptypes-onetoone-bidir"/>) + </para> + </entry> + <entry>only if the owning entity is not read-only*</entry> + </row> + <row> + <entry> + <para>Bidirectional one-to-many/many-to-one</para> + <para>inverse collection</para> + <para>non-inverse collection</para> + <para> + (<xref linkend="readonly-proptypes-onetomany-manytoone"/>) + </para> + </entry> + <entry> + <para> </para> + <para>only added/removed entities that are not read-only*</para> + <para>yes</para> + </entry> + </row> + <row> + <entry> + <para>Bidirectional many-to-many</para> + <para> + (<xref linkend="readonly-proptypes-manytomany-bidir"/>) + </para> + </entry> + <entry>yes</entry> + </row> + </tbody> + </tgroup> + </table> + + <para> + * Behavior is different when the entity having the property/association + is read-only, compared to when it is not read-only. + </para> + + <section id="readonly-proptypes-simple"> + <title>Simple properties</title> + + <para> + When a persistent object is read-only, NHibernate does not + dirty-check simple properties. + </para> + + <para> + NHibernate will not synchronize simple property state changes + to the database. If you have automatic versioning, NHibernate + will not increment the version if any simple properties change. + </para> + + <programlisting role="c#"> +ISession session = factory.OpenSession(); +ITransaction tx = session.BeginTransaction(); + +// get a contract and make it read-only +Contract contract = session.Get<Contract>(contractId); +session.SetReadOnly(contract, true); + +// contract.CustomerName is "Sherman" +contract.CustomerName = "Yogi"; +tx.Commit(); + +tx = session.BeginTransaction(); + +contract = session.Get<Contract>(contractId); +// contract.CustomerName is still "Sherman" +... +tx.Commit(); +session.Close(); + </programlisting> + + </section> + + <section id="readonly-prop-types-unidir"> + <title>Unidirectional associations</title> + + <section id="readonly-proptypes-singleended-unidir"> + <title>Unidirectional one-to-one and many-to-one</title> + + <para> + NHibernate treats unidirectional one-to-one and many-to-one + associations in the same way when the owning entity is + read-only. + </para> + + <para> + We use the term <emphasis>unidirectional single-ended + association</emphasis> when referring to functionality + that is common to unidirectional one-to-one and many-to-one + associations. + </para> + + <para> + NHibernate does not dirty-check unidirectional single-ended + associations when the owning entity is read-only. + </para> + + <para> + If you change a read-only entity's reference to a + unidirectional single-ended association to null, + or to refer to a different entity, that change + will not be flushed to the database. + </para> + + <note> + <para> + If an entity is of an immutable class, + then its references to unidirectional single-ended + associations must be assigned when that + entity is first created. Because the entity is + automatically made read-only, these references can + not be updated. + </para> + </note> + + <para> + If automatic versioning is used, NHibernate will not + increment the version due to local changes to + unidirectional single-ended associations. + </para> + + <para> + In the following examples, Contract has a unidirectional + many-to-one association with Plan. Contract cascades save and + update operations to the association. + </para> + + <para> + The following shows that changing a read-only entity's + many-to-one association reference to null has no effect + on the entity's database representation. + </para> + +<programlisting role="c#">// get a contract with an existing plan; +// make the contract read-only and set its plan to null +tx = session.BeginTransaction(); +Contract contract = session.Get<Contract>(contractId); +session.SetReadOnly(contract, true); +contract.Plan = null; +tx.Commit(); + +// get the same contract +tx = session.BeginTransaction(); +Contract contract = session.Get<Contract>(contractId); + +// contract.Plan still refers to the original plan; + +tx.Commit(); +session.Close();</programlisting> + + <para> + The following shows that, even though + an update to a read-only entity's many-to-one + association has no affect on the entity's + database representation, flush still cascades + the save-update operation to the locally + changed association. + </para> + +<programlisting role="c#">// get a contract with an existing plan; +// make the contract read-only and change to a new plan +tx = session.BeginTransaction(); +Contract contract = session.Get<Contract>(contractId); +session.SetReadOnly(contract, true); +Plan newPlan = new Plan("new plan"); +contract.Plan = newPlan; +tx.Commit(); + +// get the same contract +tx = session.BeginTransaction(); +contract = session.Get<Contract>(contractId); +newPlan = session.Get<Plan>(newPlan.Id); + +// contract.Plan still refers to the original plan; +// newPlan is non-null because it was persisted when +// the previous transaction was committed; + +tx.Commit(); +session.Close();</programlisting> + + </section> + + <section id="readonly-proptypes-manyended-unidir"> + <title>Unidirectional one-to-many and many-to-many</title> + + <para> + NHibernate treats unidirectional one-to-many + and many-to-many associations owned by a read-only + entity the same as when owned by an entity that is not + read-only. + </para> + + <para> + NHibernate dirty-checks unidirectional one-to-many and + many-to-many associations; + </para> + + <para> + The collection can contain entities that + are read-only, as well as entities + that are not read-only. + </para> + + <para> + Entities can be added and removed from the + collection; changes are flushed to the database. + </para> + + <para> + If automatic versioning is used, NHibernate will + update the version due to changes in the collection + if they dirty the owning entity. + </para> + + </section> + + </section> + + <section id="readonly-proptypes-bidir"> + <title>Bidirectional associations</title> + + <section id="readonly-proptypes-onetoone-bidir"> + <title>Bidirectional one-to-one</title> + + <para> + If a read-only entity owns a bidirectional + one-to-one association: + </para> + + <itemizedlist> + <listitem> + <para> + NHibernate does not dirty-check the association. + </para> + </listitem> + <listitem> + <para> + updates that change the association reference + to null or to refer to a different entity + will not be flushed to the database. + </para> + </listitem> + <listitem> + <para> + If automatic versioning is used, NHibernate will not + increment the version due to local changes to + the association. + </para> + </listitem> + </itemizedlist> + + <note> + <para> + If an entity is of an immutable class, + and it owns a bidirectional one-to-one + association, then its reference must be + assigned when that entity is first created. + Because the entity is automatically made + read-only, these references cannot be updated. + </para> + </note> + + <para> + When the owner is not read-only, NHibernate treats + an association with a read-only entity the same + as when the association is with an entity that is + not read-only. + </para> + + </section> + + <section id="readonly-proptypes-onetomany-manytoone"> + <title>Bidirectional one-to-many/many-to-one</title> + + <para> + A read-only entity has no impact on a bidirectional + one-to-many/many-to-one association if: + </para> + + <itemizedlist> + <listitem> + <para> + the read-only entity is on the one-to-many side + using an inverse collection; + </para> + </listitem> + <listitem> + <para> + the read-only entity is on the one-to-many side + using a non-inverse collection; + </para> + </listitem> + <listitem> + <para> + the one-to-many side uses a non-inverse collection + that contains the read-only entity + </para> + </listitem> + </itemizedlist> + + <para> + When the one-to-many side uses an inverse collection: + </para> + + <itemizedlist> + <listitem> + <para> + a read-only entity can only be added to the collection + when it is created; + </para> + </listitem> + <listitem> + <para> + a read-only entity can only be removed from the + collection by an orphan delete or by explicitly + deleting the entity. + </para> + </listitem> + </itemizedlist> + + </section> + + <section id="readonly-proptypes-manytomany-bidir"> + <title>Bidirectional many-to-many</title> + <para> + NHibernate treats bidirectional many-to-many + associations owned by a read-only entity the + same as when owned by an entity that is not + read-only. + </para> + + <para> + NHibernate dirty-checks bidirectional many-to-many + associations. + </para> + + <para> + The collection on either side of the association + can contain entities that are read-only, as well + as entities that are not read-only. + </para> + + <para> + Entities are added and removed from both sides + of the collection; changes are flushed to the + database. + </para> + + <para> + If automatic versioning is used, NHibernate will + update the version due to changes in both sides of + the collection if they dirty the entity owning the + respective collections. + </para> + + </section> + + </section> + </section> +</chapter> \ No newline at end of file This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. |