svn commit: r1400401 - /cayenne/main/trunk/docs/docbook/cayenne-guide/src/docbkx/starting-cayenne.xml

[aa...@apache.org]

Author: aadamchik
Date: Sat Oct 20 09:51:02 2012
New Revision: 1400401

URL: http://svn.apache.org/viewvc?rev=1400401&view=rev
Log:
finished webapps section

Modified:
    cayenne/main/trunk/docs/docbook/cayenne-guide/src/docbkx/starting-cayenne.xml

Modified: cayenne/main/trunk/docs/docbook/cayenne-guide/src/docbkx/starting-cayenne.xml
URL: http://svn.apache.org/viewvc/cayenne/main/trunk/docs/docbook/cayenne-guide/src/docbkx/starting-cayenne.xml?rev=1400401&r1=1400400&r2=1400401&view=diff
==============================================================================
--- cayenne/main/trunk/docs/docbook/cayenne-guide/src/docbkx/starting-cayenne.xml (original)
+++ cayenne/main/trunk/docs/docbook/cayenne-guide/src/docbkx/starting-cayenne.xml Sat Oct 20 09:51:02 2012
@@ -91,5 +91,56 @@ ServerRuntime runtime = 
 	</section>
 	<section xml:id="webapps">
 		<title>Web Applications</title>
+		<para>Web applications can use a variety of mechanisms to configure and start the "services"
+			they need, Cayenne being one of such services. Configuration can be done within standard
+			Servlet specification objects like Servlets, Filters, or ServletContextListeners, or can
+			use Spring, JEE CDI, etc. This is a user's architectural choice and Cayenne is agnostic
+			to it and will happily work in any environment. As described above, all that is needed
+			is to create an instance of ServerRuntime somewhere and provide the application code
+			with means to access it. And shut it down when the application ends to avoid container
+			leaks.</para>
+		<para>Still Cayenne includes a piece of web app configuration code that can assist in
+			quickly setting up simple Cayenne-enabled web applications. We are talking about
+			CayenneFilter. It is declared in
+			web.xml:<programlisting>&lt;web-app>
+	...
+	&lt;filter>           
+		&lt;filter-name>cayenne-project&lt;/filter-name>
+		&lt;filter-class>org.apache.cayenne.configuration.web.CayenneFilter&lt;/filter-class>
+    &lt;/filter>
+     &lt;filter-mapping>
+        &lt;filter-name>cayenne-project&lt;/filter-name>
+        &lt;url-pattern>/*&lt;/url-pattern>
+     &lt;/filter-mapping>
+	...
+ &lt;/web-app>       </programlisting></para>
+		<para>When started by the web container, it creates a instance of ServerRuntime and stores
+			it in the ServletContext. Note that the name of Cayenne XML project file is derived from
+			the "filter-name". In the example above CayenneFilter will look for an XML file
+			"cayenne-project.xml". This can be overridden with "configuration-location" init
+			parameter.</para>
+		<para>When the application runs, all HTTP requests matching the filter url-pattern will have
+			access to a session-scoped ObjectContext like
+			this:<programlisting>ObjectContext context = BaseContext.getThreadObjectContext();</programlisting>Of
+			course the ObjectContext scope, and other behavior of the Cayenne runtime can be
+			customized via dependency injection. For this another filter init parameter called
+			"extra-modules" is used. "extra-modules" is a comma or space-separated list of class
+			names, with each class implementing Module interface. These optional custom modules are
+			loaded after the the standard ones, which allows users to override all standard
+			definitions.</para>
+		<para>For those interested in the DI container contents of the runtime created by CayenneFilter,
+			it is the same ServerRuntime as would've been created by other means, but with an extra
+				<code>org.apache.cayenne.configuration.web.WebModule</code> module that provides
+				<code>org.apache.cayenne.configuration.web.RequestHandler</code> service. This is
+			the service to override in the custom modules if you need to provide a different
+			ObjectContext scope, etc.</para>
+		<para>
+			<note>
+				<para>Please do not think of CayenneFilter as the only way to start and use Cayenne in a web
+					application. CayenneFilter is entirely optional. Use it if you don't have any
+					special design for application service management. If you do, simply integrate
+					Cayenne into that design.</para>
+			</note>
+		</para>
 	</section>
 </chapter>