|
From: Mark P. <mar...@us...> - 2008-02-26 02:04:38
|
Update of /cvsroot/springnet/Spring.Net/doc/reference/src In directory sc8-pr-cvs8.sourceforge.net:/tmp/cvs-serv12269 Modified Files: index.xml objects.xml orm.xml web.xml Log Message: misc updates. Index: index.xml =================================================================== RCS file: /cvsroot/springnet/Spring.Net/doc/reference/src/index.xml,v retrieving revision 1.80 retrieving revision 1.81 diff -C2 -d -r1.80 -r1.81 *** index.xml 16 Jan 2008 19:41:38 -0000 1.80 --- index.xml 26 Feb 2008 02:04:32 -0000 1.81 *************** *** 55,59 **** <subtitle>Reference Documentation</subtitle> <releaseinfo>Version 1.1</releaseinfo> ! <pubdate>Last Updated January 16, 2007</pubdate> <authorgroup> <author> --- 55,59 ---- <subtitle>Reference Documentation</subtitle> <releaseinfo>Version 1.1</releaseinfo> ! <pubdate>Last Updated February 25, 2008</pubdate> <authorgroup> <author> Index: orm.xml =================================================================== RCS file: /cvsroot/springnet/Spring.Net/doc/reference/src/orm.xml,v retrieving revision 1.15 retrieving revision 1.16 diff -C2 -d -r1.15 -r1.16 *** orm.xml 16 Jan 2008 17:21:44 -0000 1.15 --- orm.xml 26 Feb 2008 02:04:32 -0000 1.16 *************** *** 1,3 **** ! <?xml version="1.0" encoding="UTF-8"?> <chapter id="orm"> <title>Object Relational Mapping (ORM) data access</title> --- 1,3 ---- ! <?xml version="1.0" encoding="UTF-8"?> <chapter id="orm"> <title>Object Relational Mapping (ORM) data access</title> *************** *** 300,304 **** </objects></programlisting> ! <para>The location of NHibernate mapping information can also be specified using Spring's <link linkend="resources">IResource abstraction</link> via the property <literal>MappingResources</literal>. --- 300,310 ---- </objects></programlisting> ! <para>Many of the properties on ! <literal>LocalSessionFactoryObject</literal> are those you will commonly ! configure, for example the property <literal>MappingAssemblies</literal> ! specifies a list of assemblies to seach for hibernate mapping files. The ! property <literal>HibernateProperies</literal> are the familiar ! NHibernate properties used to set typical options such as dialect and ! driver class. The location of NHibernate mapping information can also be specified using Spring's <link linkend="resources">IResource abstraction</link> via the property <literal>MappingResources</literal>. *************** *** 307,311 **** leverage the extensibility of IResource and thereby allow NHibernate to obtain its configuration information from locations such as a database ! or LDAP.</para> </section> --- 313,380 ---- leverage the extensibility of IResource and thereby allow NHibernate to obtain its configuration information from locations such as a database ! or LDAP.For other properties you can configure them as you normal using ! the file <literal>hibernate.cfg.xml</literal> and refer to it via the ! property <literal>ConfigFileNames</literal>. This property is a string ! array so multiple configuration files are supported.</para> ! ! <para>There are other properties in ! <classname>LocalSessionFactoryObject</classname> that relate to the ! integration of Spring with NHibernate. The property ! <literal>ExposeTransactionAwareSessionFactory</literal> is discussed ! below and allows you to use Spring's declarative transaction demarcation ! functionality with the standard NHibernate API (as compared to using ! HibernateTemplate). </para> ! ! <para>The property <literal>DbProvider</literal> is used to infer two ! NHibernate configurations options. </para> ! ! <itemizedlist> ! <listitem> ! <para>Infer the connection string, typically done via the hibernate ! property "hibernate.connection.connection_string". </para> ! </listitem> ! ! <listitem> ! <para>Delegate to the <classname>DbProvider</classname> itself as ! the NHibernate connection provider instead of listing it via ! property hibernate.connection.provider via ! <literal>HibernateProperties</literal>. </para> ! </listitem> ! </itemizedlist> ! ! <para>If you specify both the property hibernate.connection.provider and ! DbProvider (as shown above) the configuration of the property ! hibernate.connection.provider is used and a warning level message is ! logged. If you use Spring's <classname>DbProvider</classname> as the ! NHibernate connection provider then you can take advantage of ! <classname>IDbProvider</classname> implementations that will let you ! change the connection string at runtime such as <link lang="" ! linkend="dbprovider-usercredentials">UserCredentialsDbProvider</link> ! and <link ! linkend="dbprovider-multidelegating">MultiDelegatingDbProvider</link>. ! </para> ! ! <note> ! <para><link lang="" ! linkend="dbprovider-usercredentials">UserCredentialsDbProvider</link> ! and <link ! linkend="dbprovider-multidelegating">MultiDelegatingDbProvider</link> ! only change the connection string at runtime based on values in thread ! local storage and do not clear out the Hibernate cache that is unique ! to each <classname>ISessionFactory</classname> instance. As such, they ! are only useful for selecting at runtime a single database instance. ! Cleaning up an existing session factory when switching to a new ! database is left to user code. Creating a new session factory per ! connection string (assuming the same mapping files can be used across ! all databases connections) is not currently supported. To support this ! functionality, you can subclass ! <classname>LocalSessionFactoryObject</classname> and override the ! method <literal>ISessionFactory NewSessionFactory(Configuration ! config)</literal> so that it returns an implementation of ! <classname>ISessionFactory</classname> that selects among multiple ! instances based on values in thread local storage, much like the ! implementation of ! <classname>MultiDelegatingDbProvider</classname>.</para> ! </note> </section> Index: web.xml =================================================================== RCS file: /cvsroot/springnet/Spring.Net/doc/reference/src/web.xml,v retrieving revision 1.36 retrieving revision 1.37 diff -C2 -d -r1.36 -r1.37 *** web.xml 17 Feb 2008 13:19:51 -0000 1.36 --- web.xml 26 Feb 2008 02:04:32 -0000 1.37 *************** *** 2162,2166 **** if none is specified. TransferNoPreserve issues a server-side transfer with 'preserveForm=false', so that QueryString and Form data are not ! preserved. </para> <para>If one's target page requires parameters, one can define them using --- 2162,2166 ---- if none is specified. TransferNoPreserve issues a server-side transfer with 'preserveForm=false', so that QueryString and Form data are not ! preserved.</para> <para>If one's target page requires parameters, one can define them using *************** *** 2180,2186 **** described in the section <link linkend="objects-factory-placeholderconfigurer">PropertyPlaceholderConfigurer</link>. ! The prefix that should be used in the <literal>Parameters</literal> ! dictionary to avoid this conflict is the percent sign, i.e. ! <literal>%{UserInfo.FullName}</literal>.</para> </note></para> --- 2180,2190 ---- described in the section <link linkend="objects-factory-placeholderconfigurer">PropertyPlaceholderConfigurer</link>. ! As a workaround you can change the prefix and suffix used in ! PropertyPlaceholderConfigurer to be different, for example prefix = ! $${ and suffix = }. In Spring 1.1.1 a new prefix character, the ! percent sign (i.e.<literal>%{UserInfo.FullName}</literal>.) can be ! used in the <literal>Parameters</literal> dictionary to avoid this ! conflict so you can keep the familiar NAnt style ! PropertyPlaceholderConfigurer defaults.</para> </note></para> Index: objects.xml =================================================================== RCS file: /cvsroot/springnet/Spring.Net/doc/reference/src/objects.xml,v retrieving revision 1.118 retrieving revision 1.119 diff -C2 -d -r1.118 -r1.119 *** objects.xml 24 Jan 2008 17:38:31 -0000 1.118 --- objects.xml 26 Feb 2008 02:04:32 -0000 1.119 *************** *** 2028,2044 **** <title>Using <literal>depends-on</literal></title> ! <para>Spring.NET uses the <literal><ref/></literal> element to ! express references to other dependant objects. Unless you have some ! special initialization requirements, you don't have to use the ! <literal><depends-on/></literal> element. However, when you are ! using statics that need initialization or some object needs to be ! initialized because of something else needing preparation, you can use ! the <literal><depends-on/></literal> element. This will ensure all ! objects you've listed as dependencies will get initialized before ! they're actually set on the object. For example... <programlisting><object id="objectOne" type="Examples.ExampleObject, ExamplesLibrary" depends-on="manager"> <property name="manager" ref="manager"/> </object> ! <object id="manager" type="ManagerObject"/></programlisting></para> </sect2> --- 2028,2068 ---- <title>Using <literal>depends-on</literal></title> ! <para>For most situations, the fact that an object is a dependency of ! another is expressed by the fact that one object is set as a property of ! another. This is typically accomploished with the ! <literal><ref/></literal> element in XML-based configuration ! metadata. For the relatively infrequent situations where dependencies ! between objects are less direct (for example, when a static initializer ! in a class needs to be triggered) the '<literal>depends-on</literal>' ! attribute may be used to explicitly force one or more objects to be ! initialized before the object using this element is initialized. Find ! below an example of using the '<literal>depends-on</literal>' attribute ! to express a dependency on a single object.. <programlisting><object id="objectOne" type="Examples.ExampleObject, ExamplesLibrary" depends-on="manager"> <property name="manager" ref="manager"/> </object> ! <object id="manager" type="Examples.ManagerObject, ExamplesLibrary"/></programlisting></para> ! ! <para>If you need to express a dependency on multiple objects, you can ! supply a list of object names as the value of the ! '<literal>depends-on</literal>' attribute, with commas, whitespace and ! semicolons all valid delimiters, like so:</para> ! ! <programlisting><object id="objectOne" type="Examples.ExampleObject, ExamplesLibrary" depends-on="manager,accountDao"> ! <property name="manager" ref="manager" /> ! </object> ! ! <object id="manager" type="Examples.ManagerObject, ExamplesLibrary" /> ! <object id="accountDao" type="Examples.AdoAccountDao, ExamplesLibrary" /></programlisting> ! ! <para><note> ! <para>The '<literal>depends-on</literal>' attribute and property is ! used not only to specify an initialization time dependency, but also ! to specify the corresponding destroy time dependency (in the case of ! singleton objects only). Dependent objects that are defined in the ! 'depends-on' attribute will be destroyed after the relevant object ! itself is destroyed. This thus allows you to control shutdown order ! too</para> ! </note></para> </sect2> *************** *** 2103,2116 **** <title>Autowiring collaborators</title> ! <para>Spring.NET has autowire capabilities, meaning that it is possible ! to automatically let Spring.NET resolve collaborators (other objects) ! for your object by inspecting the object definitions in the container. ! Autowiring is specified <emphasis>per</emphasis> object and can thus be ! enabled for some objects, while other objects won't be autowired. Using ! autowiring, it is possible to reduce or even wholly eliminate the need ! to specify properties or constructor arguments. <footnote> ! <para>See <xref linkend="objects-factory-collaborators" /></para> ! </footnote> The autowiring functionality has five modes... <table ! frame="all"> <title>Autowiring modes</title> --- 2127,2144 ---- <title>Autowiring collaborators</title> ! <para>The Spring container is able to autowire relationships between ! collaborating objects. This means that it is possible to automatically ! let Spring resolve collaborators (other objects) for your object by ! inspecting the contents of the IoC container.. The autowiring ! functionality has five modes. Autowiring is specified per object and can ! thus be enabled for some object, while other objects will not be ! autowired. Using autowiring, it is possible to reduce or eliminate the ! need to specify properties or constructor arguments, thus saving a ! significant amount of typing. When using XML-based configuration ! metadata, the autowire mode for an object definition is specified by ! using the autowire attribute of the <object/> element. The ! following values are allowed:</para> ! ! <para><table frame="all"> <title>Autowiring modes</title> *************** *** 2190,2196 **** </table></para> ! <note> ! Explicit dependencies always override autowiring. Autowire behavior can be combined with dependency checking, which will be performed after all autowiring has been completed. ! </note> </sect2> --- 2218,2289 ---- </table></para> ! <para>Note that explicit dependencies in property and constructor-arg ! settings always override autowiring. Please also note that it is not ! currently possible to autowire so-called simple properties such as ! primitives, Strings, and Types (and arrays of such simple properties). ! (This is by-design and should be considered a feature.) When using ! either the byType or constructor autowiring mode, it is possible to wire ! arrays and typed-collections. In such cases all autowire candidates ! within the container that match the expected type will be provided to ! satisfy the dependency. Strongly-typed IDictionaries can even be ! autowired if the expected key type is string. An autowired IDictionary ! values will consist of all object instances that match the expected ! type, and the IDictionary's keys will contain the corresponding object ! names.</para> ! ! <para>Autowire behavior can be combined with dependency checking, which ! will be performed after all autowiring has been completed. It is ! important to understand the various advantages and disadvantages of ! autowiring. Some advantages of autowiring include:</para> ! ! <itemizedlist> ! <listitem> ! <para>Autowiring can significantly reduce the volume of ! configuration required. However, mechanisms such as the use of a ! object template (discussed elsewhere in this chapter) are also ! valuable in this regard.</para> ! </listitem> ! ! <listitem> ! <para>Autowiring can cause configuration to keep itself up to date ! as your objects evolve. For example, if you need to add an ! additional dependency to a class, that dependency can be satisfied ! automatically without the need to modify configuration. Thus there ! may be a strong case for autowiring during development, without ! ruling out the option of switching to explicit wiring when the code ! base becomes more stable.</para> ! </listitem> ! </itemizedlist> ! ! <para>Some disadvantages of autowiring:</para> ! ! <itemizedlist> ! <listitem> ! <para>Autowiring is more magical than explicit wiring. Although, as ! noted in the above table, Spring is careful to avoid guessing in ! case of ambiguity which might have unexpected results, the ! relationships between your Spring-managed objects are no longer ! documented explicitly.</para> ! </listitem> ! ! <listitem> ! <para>Wiring information may not be available to tools that may ! generate documentation from a Spring container.</para> ! </listitem> ! </itemizedlist> ! ! <para>Another issue to consider when autowiring by type is that multiple ! object definitions within the container may match the type specified by ! the setter method or constructor argument to be autowired. For arrays, ! collections, or IDictionary, this is not necessarily a problem. However ! for dependencies that expect a single value, this ambiguity will not be ! arbitrarily resolved. Instead, if no unique object definition is ! available, an Exception will be thrown.</para> ! ! <para>When deciding whether to use autowiring, there is no wrong or ! right answer in all cases. A degree of consistency across a project is ! best though; for example, if autowiring is not used in general, it might ! be confusing to developers to use it just to wire one or two object ! definitions.</para> </sect2> |
