[Nhibernate-commit] nhibernate/doc/reference/en/modules architecture.xml,NONE,1.1 basic_mapping.xml,

SourceForge Headquarters 225 Broadway Suite 1600 San Diego, CA 92101 +1 (858) 422-6466

Update of /cvsroot/nhibernate/nhibernate/doc/reference/en/modules
In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv13983/reference/en/modules

Added Files:
	architecture.xml basic_mapping.xml 
Log Message:
A start on the documentation for nhibernate.

--- NEW FILE: basic_mapping.xml ---
<chapter id="mapping">
	<title>Basic O/R Mapping</title>

	<sect1 id="mapping-declaration">
		<title>Mapping declaration</title>

		<para>
			Object/relational mappings are defined in an XML document. The mapping document
			is designed to be readable and hand-editable. The mapping language is .NET-centric,
			meaning that mappings are constructed around persistent class declarations, not
			table declarations.
		</para>
	
		<para>
			Note that, even though many Hibernate users choose to define XML mappings be hand,
			a number of tools exist to generate the mapping document, including XDoclet,
			Middlegen and AndroMDA.
		</para>

		<para>
			Lets kick off with an example mapping:
		</para>

		<programlisting><![CDATA[
<?xml version="1.0" ?>
<hibernate-mapping xmlns="urn:nhibernate-mapping-2.0">

        <class name="Eg.Cat, Eg" table="CATS" discriminator-value="C">
                <id name="Id" column="uid" type="Int64">
                        <generator class="hilo"/>
                </id>
                <discriminator column="subclass" type="Char"/>
                <property name="Birthdate" type="Date"/>
                <property name="Color" not-null="true"/>
                <property name="Sex" not-null="true" update="false"/>
                <property name="Weight"/>
                <many-to-one name="Mate" column="mate_id"/>
                <set name="Kittens">
                        <key column="mother_id"/>
                        <one-to-many class="Cat"/>
                </set>
                <subclass name="DomesticCat" discriminator-value="D">
                        <property name="Name" type="String"/>
                </subclass>
        </class>

        <class name="Eg.Dog, Eg">
                <!-- mapping for Dog could go here -->
        </class>

</hibernate-mapping>
]]></programlisting>

		<para>
				We will now discuss the content of the mapping document. We will only describe the 
				document elements and attributes that are used by Hibernate at runtime. The mapping 
				document also contains some extra optional attributes and elements that affect the 
				database schemas exported by the schema export tool. (For example the <literal>
				not-null</literal> attribute.)
		</para>

		<sect2 id="mapping-declaration-doctype">
			<title>Schema</title>

			<para>
				All XML mappings have to use the nhibernate-mapping-2.0 schema. The actual schema may be found 
				in the NHibernate source directory, or as an Embedded Resource in <literal>NHibernate.dll</literal>. 
				NHibernate will always use the Embedded Resource as the source for the schema.
			</para>
			
			<para>
				To get intellisense while working with the <literal>hibernate-mapping</literal> xml inside of VisualStudio.NET 
				you should copy the schema to the folder 
				<literal>C:\Program Files\Microsoft Visual Studio .NET 2003\Common7\Packages\schemas\xml</literal>
			</para>
		</sect2>

		<sect2 id="mapping-declaration-mapping">
			<title>hibernate-mapping</title>

			<para>
				This element has four optional attributes. The <literal>schema</literal> attribute
				specifies that tables referred to by this mapping belong to the named schema. If specified, 
				tablenames will be qualified by the given schema name. If missing, tablenames will be 
				unqualified. The <literal>default-cascade</literal> attribute specifies what cascade style
				should be assumed for properties and collections which do not specify a 
				<literal>cascade</literal> attribute. The <literal>auto-import</literal> attribute lets us
				use unqualified class names in the query language, by default.  The <literal>default-access</literal>
				attribute tells us how to access property values.
			</para>
 
			<programlistingco>

				<programlisting>
&lt;hibernate-mapping
         schema="schemaName" <co id="hm1-co" linkends="hm1" />
         default-cascade="none|save-update" <co id="hm2-co" linkends="hm2" />
         auto-import="true|false" <co id="hm3-co" linkends="hm3" />
         default-access="property|field|nosetter|ClassName" <co id="hm4-co" linkends="hm4" />
 &gt;
				</programlisting>
				<calloutlist>
						<callout arearefs="hm1-co" id="hm1">
							<para>
								<literal>schema</literal> (optional): The name of a database schema.
							</para>
						</callout>
	
						<callout arearefs="hm2-co" id="hm2">
							<para>
								<literal>default-cascade</literal> (optional - defaults to <literal>none</literal>): 
								A default cascade style.
							</para>
						</callout>
	
						<callout arearefs="hm3-co" id="hm3">
							<para>
								<literal>auto-import</literal> (optional - defaults to <literal>true</literal>):
								Specifies whether we can use unqualified class names (of classes in this mapping)
								in the query language.
							</para>
						</callout>
						<callout arearefs="hm4-co" id="hm4">
							<para>
								<literal>default-access</literal> (optional - defaults to <literal>property</literal>):
								The strategy NHibernate should use for accessing the property value.
							</para>
						</callout>
						
					</calloutlist>
			</programlistingco>
			
			<para>
				If you have two persistent classes with the same (unqualified) name, you should set 
				<literal>auto-import="false"</literal>. NHibernate will throw an exception if you attempt
				to assign two classes to the same "imported" name.
			</para>
	
		</sect2>
	
	</sect1>

	<sect1 id="mapping-quotedidentifiers">
			<title>SQL quoted identifiers</title>
			<para>
				You may force NHibernate to quote an identifier in the generated SQL by enclosing the table or
				column name in backticks in the mapping document.  NHibernate will use the correct quotation
				style for the SQL <literal>Dialect</literal> (usually double quotes, but brackets for SQL
				Server and backticks for MySQL).
			</para>

			<programlisting><![CDATA[
<class name="LineItem" table="`Line Item`">
    <id name="id" column="`Item Id`">
        <generator class="assigned"/>
    </id>
    <property name="itemNumber" column="`Item #`"/>
    ...
</class>]]>
			</programlisting>

    </sect1>

</chapter>


--- NEW FILE: architecture.xml ---
<chapter id="architecture">

    <title>Architecture</title>

    <sect1 id="architecture-overview">
        <title>Overview</title>
        
        <para>
            A (very) high-level view of the NHibernate architecture:
        </para>
		
        <mediaobject>
            <!--
            <imageobject role="fo">
                <imagedata fileref="images/overview.svg" format="SVG" align="center"/>
            </imageobject>
			-->
            <imageobject role="html">
                <imagedata fileref="../shared/images/overview.gif" format="GIF" align="center"/>
            </imageobject>
        </mediaobject>
        <para>
            This diagram shows NHibernate using the database and configuration data to
            provide persistence services (and persistent objects) to the application.
        </para>

        <para>
            We would like to show a more detailed view of the runtime architecture.
            Unfortunately, NHibernate is flexible and supports several approaches. We will
            show the two extremes. The "lite" architecture has the application
            provide its own ADO.NET connections and manage its own transactions. This approach
            uses a minimal subset of NHibernate's APIs:
        </para>
		
		<mediaobject>
            <!--
			<imageobject role="fo">
                <imagedata fileref="images/lite.svg" format="SVG" align="center"/>
            </imageobject>
			-->
            <imageobject role="html">
                <imagedata fileref="../shared/images/lite.gif" format="GIF" align="center"/>
            </imageobject>
        </mediaobject>
        
        <para>
            The "full cream" architecture abstracts the application away from the
            underlying ADO.NET API and lets NHibernate take care of the details.
        </para>

        <!-- TODO: make images -->
		<mediaobject>
            <!--
			<imageobject role="fo">
                <imagedata fileref="images/full_cream.svg" format="SVG" align="center"/>
            </imageobject>
			-->
            <imageobject role="html">
                <imagedata fileref="../shared/images/full_cream.gif" format="GIF" align="center"/>
            </imageobject>
        </mediaobject>

        <para>
            Heres some definitions of the objects in the diagrams:

            <variablelist spacing="compact">
                <varlistentry>
                    <term>SessionFactory (<literal>NHibernate.ISessionFactory</literal>)</term>
                    <listitem>
                        <para>
                            A threadsafe (immutable) cache of compiled mappings for a single database.
                            A factory for <literal>Session</literal> and a client of
                            <literal>ConnectionProvider</literal>. Might hold an optional (second-level)
                            cache of data that is reusable between transactions, at a
                            process- or cluster-level.
                        </para>
                    </listitem>
                </varlistentry>
                <varlistentry>
                    <term>Session (<literal>NHibernate.ISession</literal>)</term>
                    <listitem>
                        <para>
                            A single-threaded, short-lived object representing a conversation between
                            the application and the persistent store. Wraps an ADO.NET connection. Factory
                            for <literal>Transaction</literal>. Holds a mandatory (first-level) cache
                            of persistent objects, used when navigating the object graph or looking up
                            objects by identifier.
                        </para>
                    </listitem>
                </varlistentry>
                <varlistentry>
                    <term>Persistent Objects and Collections</term>
                    <listitem>
                        <para>
                            Short-lived, single threaded objects containing persistent state and business
                            function. These might be ordinary objects, the only special thing about
                            them is that they are currently associated with (exactly one)
                            <literal>Session</literal>. As soon as the <literal>Session</literal> is closed,
                            they will be detached and free to use in any application layer (e.g. directly
                            as data transfer objects to and from presentation).
                        </para>
                    </listitem>
                </varlistentry>
                <varlistentry>
                    <term>Transient Objects and Collections</term>
                    <listitem>
                        <para>
                            Instances of persistent classes that are not currently associated with a
                            <literal>Session</literal>. They may have been instantiated by
                            the application and not (yet) persisted or they may have been instantiated by a
                            closed <literal>Session</literal>.
                        </para>
                    </listitem>
                </varlistentry>
                <varlistentry>
                    <term>Transaction (<literal>NHibernate.ITransaction</literal>)</term>
                    <listitem>
                        <para>
                            (Optional) A single-threaded, short-lived object used by the application to
                            specify atomic units of work. Abstracts application from underlying ADO.NET 
                            transaction. A <literal>Session</literal> might span several
                            <literal>Transaction</literal>s in some cases.
                        </para>
                    </listitem>
                </varlistentry>
                <varlistentry>
                    <term>ConnectionProvider (<literal>NHibernate.Connection.ConnectionProvider</literal>)</term>
                    <listitem>
                        <para>
                            (Optional) A factory for ADO.NET connections. Abstracts application from
                            underlying <literal>IDbConnection</literal>. Not exposed to application, 
                            but can be extended/implemented by the developer.
                        </para>
                    </listitem>
                </varlistentry>
                <varlistentry>
                    <term>TransactionFactory (<literal>net.sf.hibernate.TransactionFactory</literal>)</term>
                    <listitem>
                        <para>
                            (Optional) A factory for <literal>Transaction</literal> instances. Not exposed to the
                            application, but can be extended/implemented by the developer.
                        </para>
                    </listitem>
                </varlistentry>
            </variablelist>
        </para>

        <para>
            Given a "lite" architecture, the application bypasses the
            <literal>Transaction</literal>/<literal>TransactionFactory</literal> and/or
            <literal>ConnectionProvider</literal> APIs to talk to ADO.NET directly.
        </para>
    </sect1>

    
</chapter>

[Nhibernate-commit] nhibernate/doc/reference/en/modules architecture.xml,NONE,1.1 basic_mapping.xml,

[Nhibernate-commit] nhibernate/doc/reference/en/modules architecture.xml,NONE,1.1 basic_mapping.xml,NONE,1.1