Author: aadamchik
Date: Sat Oct 20 12:54:15 2012
New Revision: 1400434
URL: http://svn.apache.org/viewvc?rev=1400434&view=rev
Log:
finished webapps section
(cherry picked from commit 3da6ab4797f57a9d5c41bc12219f078bf76f3819)
Modified:
cayenne/main/branches/STABLE-3.1/docs/docbook/cayenne-guide/src/docbkx/starting-cayenne.xml
Modified:
cayenne/main/branches/STABLE-3.1/docs/docbook/cayenne-guide/src/docbkx/starting-cayenne.xml
URL:
http://svn.apache.org/viewvc/cayenne/main/branches/STABLE-3.1/docs/docbook/cayenne-guide/src/docbkx/starting-cayenne.xml?rev=1400434&r1=1400433&r2=1400434&view=diff
==============================================================================
---
cayenne/main/branches/STABLE-3.1/docs/docbook/cayenne-guide/src/docbkx/starting-cayenne.xml
(original)
+++
cayenne/main/branches/STABLE-3.1/docs/docbook/cayenne-guide/src/docbkx/starting-cayenne.xml
Sat Oct 20 12:54:15 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><web-app>
+ ...
+ <filter>
+ <filter-name>cayenne-project</filter-name>
+
<filter-class>org.apache.cayenne.configuration.web.CayenneFilter</filter-class>
+ </filter>
+ <filter-mapping>
+ <filter-name>cayenne-project</filter-name>
+ <url-pattern>/*</url-pattern>
+ </filter-mapping>
+ ...
+ </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>
