SPR-6092: add section on EBR/Maven and tidy up references to jar files throughout
This commit is contained in:
parent
95fb766d10
commit
d1dfa873b7
|
@ -3115,7 +3115,7 @@ public class Account {
|
|||
<emphasis>without making any modifications to the application server's
|
||||
launch script</emphasis> that will be needed to add
|
||||
<literal>-javaagent:path/to/aspectjweaver.jar</literal> or (as we describe later in this
|
||||
section) <literal>-javaagent:path/to/org.springframework.instrument.jar</literal> (previously named
|
||||
section) <literal>-javaagent:path/to/spring-instrument.jar</literal> (previously named
|
||||
<literal>spring-agent.jar</literal>). Developers simply modify
|
||||
one or more files that form the application context to enable load-time
|
||||
weaving instead of relying on administrators who typically are in charge
|
||||
|
@ -3258,7 +3258,7 @@ public final class Main {
|
|||
(supplied with Spring) to switch on the LTW. This is the command line
|
||||
we will use to run the above <classname>Main</classname> class:</para>
|
||||
|
||||
<programlisting>java -javaagent:C:/projects/foo/lib/global/org.springframework.instrument.jar foo.Main</programlisting>
|
||||
<programlisting>java -javaagent:C:/projects/foo/lib/global/spring-instrument.jar foo.Main</programlisting>
|
||||
|
||||
<para>The '<literal>-javaagent</literal>' is a Java 5+ flag for
|
||||
specifying and enabling <ulink
|
||||
|
@ -3266,8 +3266,8 @@ public final class Main {
|
|||
to instrument programs running on the JVM</ulink>. The Spring
|
||||
Framework ships with such an agent, the
|
||||
<classname>InstrumentationSavingAgent</classname>, which is packaged
|
||||
in the <filename class="libraryfile">org.springframework.instrument.jar</filename> (previously
|
||||
named <filename class="libraryfile">spring-agent.jar</filename>) that
|
||||
in the <filename class="libraryfile">spring-instrument.jar</filename>
|
||||
that
|
||||
was supplied as the value of the <literal>-javaagent</literal>
|
||||
argument in the above example.</para>
|
||||
|
||||
|
@ -3368,8 +3368,8 @@ public final class Main {
|
|||
|
||||
<orderedlist>
|
||||
<listitem>
|
||||
<para><filename class="libraryfile">spring.jar</filename> (version
|
||||
2.5 or later)</para>
|
||||
<para><filename class="libraryfile">spring-aop.jar</filename> (version
|
||||
2.5 or later, plus all mandatory dependencies)</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
|
@ -3390,8 +3390,7 @@ public final class Main {
|
|||
<orderedlist>
|
||||
<listitem>
|
||||
<para><filename
|
||||
class="libraryfile">org.springframework.instrument.jar</filename> (previously named
|
||||
<filename class="libraryfile">spring-agent.jar</filename>)</para>
|
||||
class="libraryfile">spring-instrument.jar</filename></para>
|
||||
</listitem>
|
||||
</orderedlist>
|
||||
</section>
|
||||
|
@ -3509,7 +3508,7 @@ http://www.springframework.org/schema/context
|
|||
<entry><para>JVM started with Spring
|
||||
<classname>InstrumentationSavingAgent</classname></para>
|
||||
<para><emphasis><literal>(java
|
||||
-javaagent:path/to/org.springframework.instrument.jar)</literal></emphasis></para></entry>
|
||||
-javaagent:path/to/spring-instrument.jar)</literal></emphasis></para></entry>
|
||||
<entry><para><classname>InstrumentationLoadTimeWeaver</classname></para></entry>
|
||||
</row>
|
||||
|
||||
|
@ -3623,8 +3622,7 @@ http://www.springframework.org/schema/context
|
|||
(standalone as well as application server based) through the use of
|
||||
the Spring-provided instrumentation agent. To do so, start
|
||||
the VM by by specifying the
|
||||
<literal>-javaagent:path/to/org.springframework.instrument.jar</literal> option
|
||||
(the jar was previously named <literal>spring-agent.jar</literal>).
|
||||
<literal>-javaagent:path/to/spring-instrument.jar</literal> option.
|
||||
Note that this requires modification of the VM launch script
|
||||
which may prevent you from using this in application server
|
||||
environments (depending on your operation policies).</para>
|
||||
|
@ -3639,8 +3637,7 @@ http://www.springframework.org/schema/context
|
|||
looks as follows, to be included either in Tomcat's central
|
||||
<literal>server.xml</literal> file or in an application-specific
|
||||
<literal>META-INF/context.xml</literal> file within the WAR root.
|
||||
Spring's <literal>org.springframework.instrument.tomcat.jar</literal>
|
||||
(previously named <literal>spring-tomcat-weaver.jar</literal>) needs to be
|
||||
Spring's <literal>spring-instrument-tomcat.jar</literal> needs to be
|
||||
included in Tomcat's common lib directory in order to make this
|
||||
setup work.</para>
|
||||
|
||||
|
@ -3677,7 +3674,7 @@ http://www.springframework.org/schema/context
|
|||
You can enable LTW by simply activating <literal>context:load-time-weaver</literal>
|
||||
as described earlier. Specifically, you do <emphasis>not</emphasis>
|
||||
need to modify the launch script to add
|
||||
<literal>-javaagent:path/to/org.springframework.instrument.jar</literal>.</para>
|
||||
<literal>-javaagent:path/to/spring-instrument.jar</literal>.</para>
|
||||
|
||||
<para>GlassFish provides an instrumentation-capable ClassLoader as well,
|
||||
but only in its EAR environment. For GlassFish web applications,
|
||||
|
|
|
@ -74,9 +74,9 @@
|
|||
yourself</emphasis> in your application.</para>
|
||||
|
||||
<para>The Spring Framework <emphasis>Inversion of Control</emphasis> (IoC)
|
||||
component addresses this concern by
|
||||
providing a formalized means of composing disparate components into a
|
||||
fully working application ready for use. <!--Preceding sentence sounds like a description of what patterns do (and Spring uses patterns). Distinguish from patterns.-->The
|
||||
component addresses this concern by providing a formalized means of
|
||||
composing disparate components into a fully working application ready for
|
||||
use. <!--Preceding sentence sounds like a description of what patterns do (and Spring uses patterns). Distinguish from patterns.-->The
|
||||
Spring Framework codifies formalized design patterns as first-class
|
||||
objects that you can integrate into your own application(s). <!--Preceding sentence suggests that you already have the application and *then* you integrate design patterns into it. Again, I--><!--don't see a major distinction here from use of patterns (as described in earlier paragraph) and use of IoC component to build apps.
|
||||
|
||||
|
@ -199,16 +199,15 @@ TR: This section doesn't read well and I think we should try to rewrite it.-->Nu
|
|||
model-view-controller (<link
|
||||
linkend="mvc-introduction"><emphasis>MVC</emphasis></link>)
|
||||
implementation for web applications. Spring's MVC framework provides a
|
||||
clean separation between domain model code and web
|
||||
forms, and integrates with all the other features of the Spring
|
||||
Framework.<!--MVC allows you to use *all other features*? (Or just all other features in Web layer?) How do you mean? Does this need elaboration?
|
||||
clean separation between domain model code and web forms, and integrates
|
||||
with all the other features of the Spring Framework.<!--MVC allows you to use *all other features*? (Or just all other features in Web layer?) How do you mean? Does this need elaboration?
|
||||
It sounds important.--><!--TR: REVISED, PLS REVIEW.--></para>
|
||||
|
||||
<para>The <emphasis>Web-Struts</emphasis> module contains the support
|
||||
classes for integrating a classic Struts web tier within a Spring application.
|
||||
Note that this support is now deprecated as of Spring 3.0. Consider
|
||||
migrating your application to Struts 2.0 and its Spring integration or
|
||||
to a Spring MVC solution.</para>
|
||||
<para>The <emphasis>Web-Struts</emphasis> module contains the support
|
||||
classes for integrating a classic Struts web tier within a Spring
|
||||
application. Note that this support is now deprecated as of Spring 3.0.
|
||||
Consider migrating your application to Struts 2.0 and its Spring
|
||||
integration or to a Spring MVC solution.</para>
|
||||
|
||||
<para>The <emphasis>Web-Portlet</emphasis> module provides the MVC
|
||||
implementation to be used in a portlet environment and mirrors the
|
||||
|
@ -346,10 +345,565 @@ TR: OK. Added to diagram.--></para>
|
|||
<caption><para>EJBs - Wrapping existing POJOs</para></caption>
|
||||
</mediaobject></para>
|
||||
|
||||
<para>The Spring Framework also provides an <link linkend="ejb">access
|
||||
and abstraction layer</link> for Enterprise JavaBeans, enabling you to
|
||||
reuse your existing POJOs and wrap them in stateless session beans for
|
||||
use in scalable, fail-safe web applications that might need declarative
|
||||
<para>The Spring Framework also provides an <link linkend="ejb">access and
|
||||
abstraction layer</link> for Enterprise JavaBeans, enabling you to reuse
|
||||
your existing POJOs and wrap them in stateless session beans for use in
|
||||
scalable, fail-safe web applications that might need declarative
|
||||
security.</para>
|
||||
|
||||
<section>
|
||||
<title>Dependency Management and Naming Conventions</title>
|
||||
|
||||
<para>Dependency management and dependency injection are different
|
||||
things. To get those nice features of Spring into your application (like
|
||||
dependency injection) you need to assemble all the libraries needed (jar
|
||||
files) and get them onto your classpath at runtime, and possibly at
|
||||
compile time. These dependencies are not virtual components that are
|
||||
injected, but physical resources in a file system (typically). The
|
||||
process of dependency management involves locating those resources,
|
||||
storing them and adding them to classpaths. Dependencies can be direct
|
||||
(e.g. my application depends on Spring at runtime), or indirect (e.g. my
|
||||
application depends on <code>commons-dbcp</code> which depends on
|
||||
<code>commons-pool</code>). The indirect dependencies are also known as
|
||||
"transitive" and it is those dependencies that are hardest to identify
|
||||
and manage.</para>
|
||||
|
||||
<para>If you are going to use Spring you need to get a copy of the jar
|
||||
libraries that comprise the pieces of Spring that you need. To make this
|
||||
easier Spring is packaged as a set of modules that separate the
|
||||
dependencies as much as possible, so for example if you don't want to
|
||||
write a web application you don't need the spring-web modules. To refer
|
||||
to Spring library modules in this guide we use a shorthand naming
|
||||
convention <code>spring-*</code> or <code>spring-*.jar,</code> where "*"
|
||||
represents shot name for the module (e.g. <code>spring-core</code>,
|
||||
<code>spring-webmvc</code>, <code>spring-jms</code>, etc.). The actual
|
||||
jar file name that you use may be in this form (see below) or it may
|
||||
not, and normally it also has a version number in the file name (e.g.
|
||||
<code>spring-core-3.0.0.RELEASE.jar</code>).</para>
|
||||
|
||||
<para>In general, Spring publishes its artifacts to four different
|
||||
places:<itemizedlist>
|
||||
<listitem>
|
||||
<para>On the community download site <ulink
|
||||
url="http://www.springsource.org/downloads/community">http://www.springsource.org/downloads/community</ulink>.
|
||||
Here you find all the Spring jars bundled together into a zip file
|
||||
for easy download. The names of the jars here since version 3.0
|
||||
are in the form
|
||||
<code>org.springframework.*-<version>.jar</code>.</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para>Maven Central, which is the default repository that Maven
|
||||
queries, and does not require any special configuration to use.
|
||||
Many of the common libraries that Spring depends on also are
|
||||
available from Maven Central and a large section of the Spring
|
||||
community uses Maven for dependency management, so this is
|
||||
convenient for them. The names of the jars here are in the form
|
||||
<code>spring-*-<version>.jar</code> and the Maven groupId is
|
||||
<code>org.springframework</code>.</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para>The Enterprise Bundle Repository (EBR), which is run by
|
||||
SpringSource and also hosts all the libraries that integrate with
|
||||
Spring. Both Maven and Ivy repositories are available here for all
|
||||
Spring jars and their dependencies, plus a large number of other
|
||||
common libraries that people use in applications with Spring. Both
|
||||
full releases and also milestones and development snapshots are
|
||||
deployed here. The names of the jar files are in the same form as
|
||||
the community download
|
||||
(<code>org.springframework.*-<version>.jar</code>), and the
|
||||
dependencies are also in this "long" form, with external libraries
|
||||
(not from SpringSource) having the prefix
|
||||
<code>com.springsource</code>.</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para>In a public Maven repository hosted on Amazon S3 for
|
||||
development snapshots and milestone releases (a copy of the final
|
||||
releases is also held here). The jar file names are in the same
|
||||
form as Maven Central, so this is a useful place to get
|
||||
development versions of Spring to use with other libraries depoyed
|
||||
in Maven Central.</para>
|
||||
</listitem>
|
||||
</itemizedlist></para>
|
||||
|
||||
<para>So the first thing you need to decide is how to manage your
|
||||
dependencies: most people use an automated system like Maven or Ivy, but
|
||||
you can also do it manually by downloading all the jars yourself. When
|
||||
obtaining Spring with Maven or Ivy you have then to decide which place
|
||||
you'll get it from. In general, if you care about OSGi, use the EBR,
|
||||
since it houses OSGi compatible artifacts for all of Spring's
|
||||
dependencies, such as Hibernate and Freemarker. If OSGi does not matter
|
||||
to you, either place works, though there are some pros and cons between
|
||||
them. In general, pick one place or the other for your project; do not
|
||||
mix them. This is particularly important since EBR artifacts necessarily
|
||||
use a different naming convention than Maven Central artifacts.</para>
|
||||
|
||||
<para><table>
|
||||
<title>Comparison of Maven Central and SpringSource EBR
|
||||
Repositories</title>
|
||||
|
||||
<tgroup cols="3">
|
||||
<thead>
|
||||
<row>
|
||||
<entry>Feature</entry>
|
||||
|
||||
<entry>Maven Central</entry>
|
||||
|
||||
<entry>EBR</entry>
|
||||
</row>
|
||||
</thead>
|
||||
|
||||
<tbody>
|
||||
<row>
|
||||
<entry>OSGi Compatible</entry>
|
||||
|
||||
<entry>Not explicit</entry>
|
||||
|
||||
<entry>Yes</entry>
|
||||
</row>
|
||||
|
||||
<row>
|
||||
<entry>Number of Artifacts</entry>
|
||||
|
||||
<entry>Tens of thousands; all kinds</entry>
|
||||
|
||||
<entry>Hundreds; those that Spring integrates with</entry>
|
||||
</row>
|
||||
|
||||
<row>
|
||||
<entry>Consistent Naming Conventions</entry>
|
||||
|
||||
<entry>No</entry>
|
||||
|
||||
<entry>Yes</entry>
|
||||
</row>
|
||||
|
||||
<row>
|
||||
<entry>Naming Convention: GroupId</entry>
|
||||
|
||||
<entry>Varies. Newer artifacts often use domain name, e.g.
|
||||
org.slf4j. Older ones often just use the artifact name, e.g.
|
||||
log4j.</entry>
|
||||
|
||||
<entry>Domain name of origin or main package root, e.g.
|
||||
org.springframework</entry>
|
||||
</row>
|
||||
|
||||
<row>
|
||||
<entry>Naming Convention: ArtifactId</entry>
|
||||
|
||||
<entry>Varies. Generally the project or module name, using a
|
||||
hyphen "-" separator, e.g. spring-core, logj4.</entry>
|
||||
|
||||
<entry>Bundle Symbolic Name, derived from the main package
|
||||
root, e.g. org.springframework.beans. If the jar had to be
|
||||
patched to ensure OSGi compliance then com.springsource is
|
||||
appended, e.g. com.springsource.org.apache.log4j</entry>
|
||||
</row>
|
||||
|
||||
<row>
|
||||
<entry>Naming Convention: Version</entry>
|
||||
|
||||
<entry>Varies. Many new artifacts use m.m.m or m.m.m.X (with
|
||||
m=digit, X=text). Older ones use m.m. Some neither. Ordering
|
||||
is defined but not often relied on, so not strictly
|
||||
reliable.</entry>
|
||||
|
||||
<entry>OSGi version number m.m.m.X, e.g. 3.0.0.RC3. The text
|
||||
qualifier imposes alphabetic ordering on versions with the
|
||||
same numeric values.</entry>
|
||||
</row>
|
||||
|
||||
<row>
|
||||
<entry>Publishing</entry>
|
||||
|
||||
<entry>Usually automatic via rsync or source control updates.
|
||||
Project authors can upload individual jars to JIRA.</entry>
|
||||
|
||||
<entry>Manual (JIRA processed by SpringSource)</entry>
|
||||
</row>
|
||||
|
||||
<row>
|
||||
<entry>Quality Assurance</entry>
|
||||
|
||||
<entry>By policy. Accuracy is responsibility of
|
||||
authors.</entry>
|
||||
|
||||
<entry>Extensive for OSGi manifest, Maven POM and Ivy
|
||||
metadata. QA performed by Spring team.</entry>
|
||||
</row>
|
||||
|
||||
<row>
|
||||
<entry>Hosting</entry>
|
||||
|
||||
<entry>Contegix. Funded by Sonatype with several
|
||||
mirrors.</entry>
|
||||
|
||||
<entry>S3 funded by SpringSource.</entry>
|
||||
</row>
|
||||
|
||||
<row>
|
||||
<entry>Search Utilities</entry>
|
||||
|
||||
<entry>Various</entry>
|
||||
|
||||
<entry><ulink
|
||||
url="http://www.springsource.com/repository">http://www.springsource.com/repository</ulink></entry>
|
||||
</row>
|
||||
|
||||
<row>
|
||||
<entry>Integration with SpringSource Tools</entry>
|
||||
|
||||
<entry>Integration through STS with Maven dependency
|
||||
management</entry>
|
||||
|
||||
<entry>Extensive integration through STS with Maven, Roo,
|
||||
CloudFoundry</entry>
|
||||
</row>
|
||||
</tbody>
|
||||
</tgroup>
|
||||
</table></para>
|
||||
|
||||
<section>
|
||||
<title>Spring Dependencies and Depending on Spring</title>
|
||||
|
||||
<para>Although Spring provides integration and support for a huge
|
||||
range of enterprise and other external tools, it intentionally keeps
|
||||
its mandatory dependencies to an absolute minimum: you shouldn't have
|
||||
to locate and download (even automatically) a large number of jar
|
||||
libraries in order to use Spring for simple use cases. For basic
|
||||
dependency injection there is only one mandatory external dependency,
|
||||
and that is for logging (see below for a more detailed description of
|
||||
logging options). If you are using Maven for dependency management you
|
||||
don't even need to supply the logging dependency explicitly. For
|
||||
example, to create an application context and use dependency injection
|
||||
to configure an application, your Maven dependencies will look like
|
||||
this:</para>
|
||||
|
||||
<para><programlisting><dependencies>
|
||||
<dependency>
|
||||
<groupId>org.springframework</groupId>
|
||||
<artifactId>spring-context</artifactId>
|
||||
<version>3.0.0.RELEASE</version>
|
||||
<scope>runtime</scope>
|
||||
</dependency>
|
||||
</dependencies> </programlisting></para>
|
||||
|
||||
<para>That's it. Note the scope can be declared as runtime if you
|
||||
don't need to compile against Spring APIs, which is typically the case
|
||||
for basic dependency injection use cases.</para>
|
||||
|
||||
<para>We used the Maven Central naming conventions in the example
|
||||
above, so that works with Maven Central or the SpringSource S3 Maven
|
||||
repository. To use the S3 Maven repository (e.g. for milestones or
|
||||
developer snaphots), you need to specify the repository location in
|
||||
your Maven configuration. For full releases:</para>
|
||||
|
||||
<programlisting><repositories>
|
||||
<repository>
|
||||
<id>com.springsource.repository.maven.release</id>
|
||||
<url>http://s3.amazonaws.com/maven.springsource.com/release/</url>
|
||||
<snapshots><enabled>false</enabled></snapshots>
|
||||
</repository>
|
||||
</repositories></programlisting>
|
||||
|
||||
<para>For milestones:</para>
|
||||
|
||||
<programlisting><repositories>
|
||||
<repository>
|
||||
<id>com.springsource.repository.maven.milestone</id>
|
||||
<url>http://s3.amazonaws.com/maven.springsource.com/milestone/</url>
|
||||
<snapshots><enabled>false</enabled></snapshots>
|
||||
</repository>
|
||||
</repositories></programlisting>
|
||||
|
||||
<para>And for snapshots:</para>
|
||||
|
||||
<programlisting><repositories>
|
||||
<repository>
|
||||
<id>com.springsource.repository.maven.snapshot</id>
|
||||
<url>http://s3.amazonaws.com/maven.springsource.com/snapshot/</url>
|
||||
<snapshots><enabled>true</enabled></snapshots>
|
||||
</repository>
|
||||
</repositories></programlisting>
|
||||
|
||||
<para>To use the SpringSource EBR you would need to use a different
|
||||
naming convention for the dependencies. The names are usually easy to
|
||||
guess, e.g. in this case it is:</para>
|
||||
|
||||
<programlisting><dependencies>
|
||||
<dependency>
|
||||
<groupId>org.springframework</groupId>
|
||||
<artifactId>org.springframework.context</artifactId>
|
||||
<version>3.0.0.RELEASE</version>
|
||||
<scope>runtime</scope>
|
||||
</dependency>
|
||||
</dependencies></programlisting>
|
||||
|
||||
<para>You also need to declare the location of the repository
|
||||
explicitly (only the URL is important):</para>
|
||||
|
||||
<programlisting><repositories>
|
||||
<repository>
|
||||
<id>com.springsource.repository.bundles.release</id>
|
||||
<url>http://repository.springsource.com/maven/bundles/release/</url>
|
||||
</repository>
|
||||
</repositories></programlisting>
|
||||
|
||||
<para>If you are managing your dependencies by hand, the URL in the
|
||||
repository declaration above is not browseable, but there is a user
|
||||
interface at <ulink
|
||||
url="http://www.springsource.com/repository">http://www.springsource.com/repository</ulink>
|
||||
that can be used to search for and download dependencies. It also has
|
||||
handy snippets of Maven and Ivy configuration that you can copy and
|
||||
paste if you are using those tools.</para>
|
||||
|
||||
<para>If you prefer to use <ulink url="http://ant.apache.org/ivy">
|
||||
Ivy</ulink> to manage dependencies then there are
|
||||
similar names and configuration options there (refer to the
|
||||
documentation of your dependency management system, or look at some
|
||||
sample code - Spring itself uses Ivy to manage dependencies when it is
|
||||
building).</para>
|
||||
|
||||
</section>
|
||||
</section>
|
||||
|
||||
<section>
|
||||
<title>Logging</title>
|
||||
|
||||
<para>Logging is a very important dependency for Spring because a) it is
|
||||
the only mandatory external dependency, b) everyone likes to see some
|
||||
output from the tools they are using, and c) Spring integrates with lots
|
||||
of other tools all of which have also made a choice of logging
|
||||
dependency. One of the goals of an application developer is often to
|
||||
have unified logging configured in a central place for the whole
|
||||
application, including all external components. This is more difficult
|
||||
than it might have been since there are so many choices of logging
|
||||
framework.</para>
|
||||
|
||||
<para>The mandatory logging dependency in Spring is the Jakarta Commons
|
||||
Logging API (JCL). We compile against JCL and we also make JCL
|
||||
<classname>Log</classname> objects visible for classes that extend the
|
||||
Spring Framework. It's important to users that all versions of Spring
|
||||
use the same logging library: migration is easy because backwards
|
||||
compatibility is preserved even with applications that extend Spring.
|
||||
The way we do this is to make one of the modules in Spring depend
|
||||
explicitly on <code>commons-logging</code> (the canonical implementation
|
||||
of JCL), and then make all the other modules depend on that at compile
|
||||
time. If you are using Maven for example, and wondering where you picked
|
||||
up the dependency on <code>commons-logging</code>, then it is from
|
||||
Spring and specifically from the central module called
|
||||
<code>spring-core</code>.</para>
|
||||
|
||||
<para>The nice thing about <code>commons-logging</code> is that you don't need
|
||||
anything else to make your application work. It has a runtime discovery
|
||||
algorithm that looks for other logging frameworks in well known places
|
||||
on the classpath and uses one that it thinks is appropriate (or you can
|
||||
tell it which one if you need to). If nothing else is available you get
|
||||
pretty nice looking logs just from the JDK (java.util.logging or JUL for
|
||||
short). You should find that your Spring application works and logs
|
||||
happily to the console out of the box in most situations, and that's
|
||||
important.</para>
|
||||
|
||||
<section>
|
||||
<title>Not Using Commons Logging</title>
|
||||
|
||||
<para>Unfortunately, the worst thing about <code>commons-logging</code>, and what
|
||||
has made it unpopular with new tools, is also the runtime discovery
|
||||
algorithm. If we could turn back the clock and start Spring now as a
|
||||
new project it would use a different logging dependency. Probably the
|
||||
first choice would be the Simple Logging Framework for Java (<ulink
|
||||
url="http://www.slf4j.org">SLF4J</ulink>),
|
||||
which is also used by a lot of other tools
|
||||
that people use with Spring inside their applications.</para>
|
||||
|
||||
<para>To switch off <code>commons-logging</code> is easy: just make sure it isn't
|
||||
on the classpath at runtime. In Maven terms you exclude the
|
||||
dependency, and because of the way that the Spring dependencies are
|
||||
declared, you only have to do that once.</para>
|
||||
|
||||
<programlisting><dependencies>
|
||||
<dependency>
|
||||
<groupId>org.springframework</groupId>
|
||||
<artifactId>spring-context</artifactId>
|
||||
<version>3.0.0.RELEASE</version>
|
||||
<scope>runtime</scope>
|
||||
<exclusions>
|
||||
<exclusion>
|
||||
<groupId>commons-logging</groupId>
|
||||
<artifactId>commons-logging</artifactId>
|
||||
</exclusion>
|
||||
</exclusions>
|
||||
</dependency>
|
||||
</dependencies> </programlisting>
|
||||
|
||||
<para>Now this application is probably broken because there is no
|
||||
implementation of the JCL API on the classpath, so to fix it a new one
|
||||
has to be prvided. In the next section we show you how to provide an
|
||||
alternative implementation of JCL using SLF4J as an example.</para>
|
||||
</section>
|
||||
|
||||
<section>
|
||||
<title>Using SLF4J</title>
|
||||
</section>
|
||||
|
||||
<para>SLF4J is a cleaner dependency and more efficient at runtime than
|
||||
<code>commons-logging</code> because it uses compile-time bindings instead of runtime
|
||||
discovery of the other logging frameworks it integrates. This also means
|
||||
that you have to be more explicit about what you want to happen at
|
||||
runtime, and declare it or configure it accordingly. SLF4J provides
|
||||
bindings to many common logging frameworks, so you can usually choose
|
||||
one that you already use, and bind to that for configuration and
|
||||
management.</para>
|
||||
|
||||
<para>SLF4J provides bindings to many common logging frameworks,
|
||||
including JCL, and it also does the reverse: bridges between other
|
||||
logging frameworks and itself. So to use SLF4J with Spring you need to
|
||||
replace the <code>commons-logging</code> dependency with the SLF4J-JCL bridge. Once
|
||||
you have done that then logging calls from within Spring will be
|
||||
translated into logging calls to the SLF4J API, so if other libraries in
|
||||
your application use that API, then you have a single place to configure
|
||||
and manage logging.</para>
|
||||
|
||||
<para>A common choice might be to bridge Spring to SLF4J, and then
|
||||
provide explicit binding from SLF4J to Log4J. You need to supply 4
|
||||
dependencies (and exclude the existing <code>commons-logging</code>): the bridge, the
|
||||
SLF4J API, the binding to Log4J, and the Log4J implementation itself. In
|
||||
Maven you would do that like this</para>
|
||||
|
||||
<programlisting><dependencies>
|
||||
<dependency>
|
||||
<groupId>org.springframework</groupId>
|
||||
<artifactId>spring-context</artifactId>
|
||||
<version>3.0.0.RELEASE</version>
|
||||
<scope>runtime</scope>
|
||||
<exclusions>
|
||||
<exclusion>
|
||||
<groupId>commons-logging</groupId>
|
||||
<artifactId>commons-logging</artifactId>
|
||||
</exclusion>
|
||||
</exclusions>
|
||||
</dependency>
|
||||
<dependency>
|
||||
<groupId>org.slf4j</groupId>
|
||||
<artifactId>jcl-slf4j</artifactId>
|
||||
<version>1.5.8</version>
|
||||
<scope>runtime</scope>
|
||||
</dependency>
|
||||
<dependency>
|
||||
<groupId>org.slf4j</groupId>
|
||||
<artifactId>slf4j-api</artifactId>
|
||||
<version>1.5.8</version>
|
||||
<scope>runtime</scope>
|
||||
</dependency>
|
||||
<dependency>
|
||||
<groupId>org.slf4j</groupId>
|
||||
<artifactId>slf4j-log4j12</artifactId>
|
||||
<version>1.5.8</version>
|
||||
<scope>runtime</scope>
|
||||
</dependency>
|
||||
<dependency>
|
||||
<groupId>log4j</groupId>
|
||||
<artifactId>log4j</artifactId>
|
||||
<version>1.2.14</version>
|
||||
<scope>runtime</scope>
|
||||
</dependency>
|
||||
</dependencies> </programlisting>
|
||||
|
||||
<para>That might seem like a lot of dependencies just to get some
|
||||
logging. Well it is, but it <emphasis>is</emphasis> optional, and it
|
||||
should behave better than the vanilla <code>commons-logging</code> with
|
||||
respect to classloader issues, notably if you are in a strict container
|
||||
like an OSGi platform. Allegedly there is also a performance benefit
|
||||
because the bindings are at compile-time not runtime.</para>
|
||||
|
||||
<para>A more common choice amongst SLF4J users, which uses fewer steps
|
||||
and generates fewer dependencies, is to bind directly to <ulink type=""
|
||||
url="http://logback.qos.ch">Logback</ulink>.
|
||||
This removes the extra binding step because
|
||||
Logback implements SLF4J directly, so you only need to depend on two
|
||||
libaries not four (<code>jcl-slf4j</code> and <code>logback</code>). If
|
||||
you do that you might also need to exlude the slf4j-api dependency from
|
||||
other external dependencies (not Spring), because you only want one
|
||||
version of that API on the classpath.</para>
|
||||
|
||||
<section>
|
||||
<title>Using Log4J</title>
|
||||
|
||||
<para>Many people use <ulink
|
||||
url="http://logging.apache.org/log4j">Log4j</ulink> as a logging
|
||||
framework for configuration and management purposes. It's efficient
|
||||
and well established, and in fact it's what we use at runtime when we
|
||||
build and test Spring. Spring also provides some utilities for
|
||||
configuring and initializing Log4j, so it have an optional compile
|
||||
time dependency on Log4j in some modules.</para>
|
||||
|
||||
<para>To make Log4j work with the default JCL dependency
|
||||
(<code>commons-logging</code>) all you need to do is put Log4j on the
|
||||
classpath, and provide it with a configuration file
|
||||
(<code>log4j.properties</code> or <code>log4j.xml</code> in the root
|
||||
of the classpath). So for Maven users this is your dependency
|
||||
declaration:</para>
|
||||
|
||||
<programlisting><dependencies>
|
||||
<dependency>
|
||||
<groupId>org.springframework</groupId>
|
||||
<artifactId>spring-context</artifactId>
|
||||
<version>3.0.0.RELEASE</version>
|
||||
<scope>runtime</scope>
|
||||
</dependency>
|
||||
<dependency>
|
||||
<groupId>log4j</groupId>
|
||||
<artifactId>log4j</artifactId>
|
||||
<version>1.2.14</version>
|
||||
<scope>runtime</scope>
|
||||
</dependency>
|
||||
</dependencies> </programlisting>
|
||||
|
||||
<para>And here's a sample log4j.properties for logging to the
|
||||
console:</para>
|
||||
|
||||
<programlisting>log4j.rootCategory=INFO, stdout
|
||||
|
||||
log4j.appender.stdout=org.apache.log4j.ConsoleAppender
|
||||
log4j.appender.stdout.layout=org.apache.log4j.PatternLayout
|
||||
log4j.appender.stdout.layout.ConversionPattern=%d{ABSOLUTE} %5p %t %c{2}:%L - %m%n
|
||||
|
||||
log4j.category.org.springframework.beans.factory=DEBUG</programlisting>
|
||||
|
||||
<section>
|
||||
<title>Runtime Containers with Native JCL</title>
|
||||
|
||||
<para>Many people run their Spring applications in a container that
|
||||
itself provides an implementation of JCL. IBM Websphere Application
|
||||
Server (WAS) is the archetype. This often causes problems, and
|
||||
unfortunately there is no silver bullet solution; simply excluding
|
||||
<code>commons-logging</code> from your application is not enough in
|
||||
most situations.</para>
|
||||
|
||||
<para>To be clear about this: the problems reported are usually not
|
||||
with JCL per se, or even with <code>commons-logging</code>: rather
|
||||
they are to do with binding <code>commons-logging</code> to another
|
||||
framework (often Log4J). This can fail because
|
||||
<code>commons-logging</code> changed the way they do the runtime
|
||||
discovery in between the older versions (1.0) found in some
|
||||
containers and the modern versions that most people use now (1.1).
|
||||
Spring does not use any unusual parts of the JCL API, so nothing
|
||||
breaks there, but as soon as Spring or your application tries to do
|
||||
any logging you can find that the bindings to Log4J are not
|
||||
working.</para>
|
||||
|
||||
<para>In such cases with WAS the easiest thing to do is to invert
|
||||
the class loader hierarchy (IBM calls it "parent last") so that the
|
||||
application controls the JCL dependency, not the container. That
|
||||
option isn't always open, but there are plenty of other suggestions
|
||||
in the public domain for alternative approaches, and your mileage
|
||||
may vary depending on the exact version and feature set of the
|
||||
container.</para>
|
||||
</section>
|
||||
</section>
|
||||
</section>
|
||||
</section>
|
||||
</chapter>
|
||||
|
|
|
@ -1,374 +1,503 @@
|
|||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
|
||||
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
|
||||
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
|
||||
<book>
|
||||
<bookinfo>
|
||||
<title>Reference Documentation</title>
|
||||
|
||||
<book xmlns:xi="http://www.w3.org/2001/XInclude">
|
||||
<bookinfo>
|
||||
<title>Reference Documentation</title>
|
||||
<productname>Spring Framework</productname>
|
||||
<releaseinfo>3.0.RC3</releaseinfo>
|
||||
<mediaobject>
|
||||
<imageobject role="fo">
|
||||
<imagedata align="center" fileref="images/logo-pdf.png"
|
||||
format="PNG" width="240"/>
|
||||
</imageobject>
|
||||
</mediaobject>
|
||||
<authorgroup>
|
||||
<author>
|
||||
<firstname>Rod</firstname>
|
||||
<surname>Johnson</surname>
|
||||
</author>
|
||||
<author>
|
||||
<firstname>Juergen</firstname>
|
||||
<surname>Hoeller</surname>
|
||||
</author>
|
||||
<author>
|
||||
<firstname>Keith</firstname>
|
||||
<surname>Donald</surname>
|
||||
</author>
|
||||
<author>
|
||||
<firstname>Colin</firstname>
|
||||
<surname>Sampaleanu</surname>
|
||||
</author>
|
||||
<author>
|
||||
<firstname>Rob</firstname>
|
||||
<surname>Harrop</surname>
|
||||
</author>
|
||||
<author>
|
||||
<firstname>Thomas</firstname>
|
||||
<surname>Risberg</surname>
|
||||
</author>
|
||||
<author>
|
||||
<firstname>Alef</firstname>
|
||||
<surname>Arendsen</surname>
|
||||
</author>
|
||||
<author>
|
||||
<firstname>Darren</firstname>
|
||||
<surname>Davison</surname>
|
||||
</author>
|
||||
<author>
|
||||
<firstname>Dmitriy</firstname>
|
||||
<surname>Kopylenko</surname>
|
||||
</author>
|
||||
<author>
|
||||
<firstname>Mark</firstname>
|
||||
<surname>Pollack</surname>
|
||||
</author>
|
||||
<author>
|
||||
<firstname>Thierry</firstname>
|
||||
<surname>Templier</surname>
|
||||
</author>
|
||||
<author>
|
||||
<firstname>Erwin</firstname>
|
||||
<surname>Vervaet</surname>
|
||||
</author>
|
||||
<author>
|
||||
<firstname>Portia</firstname>
|
||||
<surname>Tung</surname>
|
||||
</author>
|
||||
<author>
|
||||
<firstname>Ben</firstname>
|
||||
<surname>Hale</surname>
|
||||
</author>
|
||||
<author>
|
||||
<firstname>Adrian</firstname>
|
||||
<surname>Colyer</surname>
|
||||
</author>
|
||||
<author>
|
||||
<firstname>John</firstname>
|
||||
<surname>Lewis</surname>
|
||||
</author>
|
||||
<author>
|
||||
<firstname>Costin</firstname>
|
||||
<surname>Leau</surname>
|
||||
</author>
|
||||
<author>
|
||||
<firstname>Mark</firstname>
|
||||
<surname>Fisher</surname>
|
||||
</author>
|
||||
<author>
|
||||
<firstname>Sam</firstname>
|
||||
<surname>Brannen</surname>
|
||||
</author>
|
||||
<author>
|
||||
<firstname>Ramnivas</firstname>
|
||||
<surname>Laddad</surname>
|
||||
</author>
|
||||
<author>
|
||||
<firstname>Arjen</firstname>
|
||||
<surname>Poutsma</surname>
|
||||
</author>
|
||||
<author>
|
||||
<firstname>Chris</firstname>
|
||||
<surname>Beams</surname>
|
||||
</author>
|
||||
<author>
|
||||
<firstname>Tareq</firstname>
|
||||
<surname>Abedrabbo</surname>
|
||||
</author>
|
||||
<author>
|
||||
<firstname>Andy</firstname>
|
||||
<surname>Clement</surname>
|
||||
</author>
|
||||
</authorgroup>
|
||||
<copyright>
|
||||
<year>2004-2009</year>
|
||||
<holder>Rod Johnson, Juergen Hoeller, Keith Donald, Colin Sampaleanu, Rob Harrop, Alef Arendsen, Thomas Risberg, Darren Davison,
|
||||
Dmitriy Kopylenko, Mark Pollack, Thierry Templier, Erwin Vervaet, Portia Tung, Ben Hale, Adrian Colyer, John Lewis,
|
||||
Costin Leau, Mark Fisher, Sam Brannen, Ramnivas Laddad, Arjen Poutsma, Chris Beams, Tareq Abedrabbo, Andy Clement
|
||||
</holder>
|
||||
</copyright>
|
||||
<legalnotice>
|
||||
<para>Copies of this document may be made for your own use and for
|
||||
distribution to others, provided that you do not charge any
|
||||
fee for such copies and further provided that each copy
|
||||
contains this Copyright Notice, whether distributed in print
|
||||
or electronically.</para>
|
||||
</legalnotice>
|
||||
</bookinfo>
|
||||
<!-- front matter -->
|
||||
<toc/>
|
||||
<part id="spring-introduction">
|
||||
<title>Overview of Spring Framework</title>
|
||||
<partintro id="spring-core-intro">
|
||||
<para>The Spring Framework is a lightweight solution and a potential
|
||||
one-stop-shop for building your enterprise-ready applications. However,
|
||||
Spring is modular, allowing you to use only those parts that you need,
|
||||
without having to bring in the rest. You can use the IoC container, with
|
||||
Struts on top, but you can also use only the <link
|
||||
linkend="orm-hibernate">Hibernate integration code</link> or the <link
|
||||
linkend="jdbc-introduction">JDBC abstraction layer</link>. The Spring
|
||||
Framework supports declarative transaction management, remote access to your
|
||||
logic through RMI or web services, and various options for persisting your
|
||||
data. It offers a full-featured <link linkend="mvc-introduction">MVC
|
||||
framework</link>, and enables you to integrate <link
|
||||
linkend="aop-introduction">AOP</link> transparently into your
|
||||
software.</para>
|
||||
<productname>Spring Framework</productname>
|
||||
|
||||
<para>Spring is designed to be non-intrusive, meaning that your domain logic
|
||||
code generally has no dependencies on the framework itself. In your
|
||||
integration layer (such as the data access layer), some dependencies on the
|
||||
data access technology and the Spring libraries will exist. However, it
|
||||
should be easy to isolate these dependencies from the rest of your code
|
||||
base.</para>
|
||||
<releaseinfo>3.0.RC3</releaseinfo>
|
||||
|
||||
<para>This document is a reference guide to Spring Framework features. If
|
||||
you have any requests, comments, or questions on this document, please post
|
||||
them on the user mailing list or on the support forums at <ulink
|
||||
url="http://forum.springsource.org/"></ulink>.<!--Missing link above. PDF shows it as http://forum.springsource.org/--></para>
|
||||
</partintro>
|
||||
<xi:include href="overview.xml"/>
|
||||
</part>
|
||||
<part id="spring-whats-new">
|
||||
<title>What's New in Spring 3.0</title>
|
||||
<xi:include href="new-in-3.xml"/>
|
||||
</part>
|
||||
<part id="spring-core">
|
||||
<title>Core Technologies</title>
|
||||
<partintro id="spring-core-intro">
|
||||
<para>
|
||||
This part of the reference documentation covers
|
||||
all of those technologies that are absolutely integral
|
||||
to the Spring Framework.
|
||||
</para>
|
||||
<para>
|
||||
Foremost amongst these is the Spring Framework's
|
||||
Inversion of Control (IoC) container. A thorough treatment
|
||||
of the Spring Framework's IoC container is closely followed
|
||||
by comprehensive coverage of Spring's Aspect-Oriented
|
||||
Programming (AOP) technologies. The Spring Framework has
|
||||
its own AOP framework, which is conceptually easy to understand,
|
||||
and which successfully addresses the 80% sweet spot of AOP
|
||||
requirements in Java enterprise programming.
|
||||
</para>
|
||||
<para>
|
||||
Coverage of Spring's integration with AspectJ (currently
|
||||
the richest - in terms of features - and certainly most
|
||||
mature AOP implementation in the Java enterprise space)
|
||||
is also provided.
|
||||
</para>
|
||||
<para>
|
||||
Finally, the adoption of the test-driven-development (TDD)
|
||||
approach to software development is certainly advocated by
|
||||
the Spring team, and so coverage of Spring's support for
|
||||
integration testing is covered (alongside best practices for
|
||||
unit testing). The Spring team has found that the correct
|
||||
use of IoC certainly does make both unit and integration
|
||||
testing easier (in that the presence of setter methods and
|
||||
appropriate constructors on classes makes them
|
||||
easier to wire together in a test without having to set up
|
||||
service locator registries and suchlike)... the chapter
|
||||
dedicated solely to testing will hopefully convince you of
|
||||
this as well.
|
||||
</para>
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para><xref linkend="beans"/></para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para><xref linkend="resources"/></para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para><xref linkend="validation"/></para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para><xref linkend="expressions"/></para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para><xref linkend="aop"/></para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para><xref linkend="aop-api"/></para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para><xref linkend="testing"/></para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
</partintro>
|
||||
<xi:include href="beans.xml"/>
|
||||
<xi:include href="resources.xml"/>
|
||||
<xi:include href="validation.xml"/>
|
||||
<xi:include href="expressions.xml"/>
|
||||
<xi:include href="aop.xml"/>
|
||||
<xi:include href="aop-api.xml"/>
|
||||
<xi:include href="testing.xml"/>
|
||||
</part>
|
||||
<part id="spring-data-tier">
|
||||
<title>Data Access</title>
|
||||
<partintro id="spring-data-tier-intro">
|
||||
<para>
|
||||
This part of the reference documentation is concerned
|
||||
with data access and the interaction between the data access
|
||||
layer and the business or service layer.
|
||||
</para>
|
||||
<para>
|
||||
Spring's comprehensive transaction management support is
|
||||
covered in some detail, followed by thorough coverage of
|
||||
the various data access frameworks and
|
||||
technologies that the Spring Framework integrates with.
|
||||
</para>
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para><xref linkend="transaction"/></para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para><xref linkend="dao"/></para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para><xref linkend="jdbc"/></para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para><xref linkend="orm"/></para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para><xref linkend="oxm"/></para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
</partintro>
|
||||
<xi:include href="transaction.xml"/>
|
||||
<xi:include href="dao.xml"/>
|
||||
<xi:include href="jdbc.xml"/>
|
||||
<xi:include href="orm.xml"/>
|
||||
<xi:include href="oxm.xml"/>
|
||||
</part>
|
||||
<part id="spring-web">
|
||||
<title>The Web</title>
|
||||
<partintro id="spring-web-intro">
|
||||
<para>
|
||||
This part of the reference documentation covers the
|
||||
Spring Framework's support for the presentation tier
|
||||
(and specifically web-based presentation tiers).
|
||||
</para>
|
||||
<para>
|
||||
The Spring Framework's own web framework,
|
||||
<link linkend="mvc">Spring Web MVC</link>, is covered in
|
||||
the first couple of chapters. A number of the remaining
|
||||
chapters in this part of the reference documentation are
|
||||
concerned with the Spring Framework's integration with
|
||||
other web technologies, such as <link linkend="struts">Struts</link>
|
||||
and <link linkend="jsf">JSF</link> (to name but two).
|
||||
</para>
|
||||
<para>
|
||||
This section concludes with coverage of Spring's MVC
|
||||
<link linkend="portlet">portlet framework</link>.
|
||||
</para>
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para><xref linkend="mvc"/></para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para><xref linkend="view"/></para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para><xref linkend="web-integration"/></para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para><xref linkend="portlet"/></para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
</partintro>
|
||||
<xi:include href="mvc.xml"/>
|
||||
<xi:include href="view.xml"/>
|
||||
<xi:include href="web-integration.xml"/>
|
||||
<xi:include href="portlet.xml"/>
|
||||
</part>
|
||||
<part id="spring-integration">
|
||||
<title>Integration</title>
|
||||
<partintro id="spring-integration-intro">
|
||||
<para>
|
||||
This part of the reference documentation covers
|
||||
the Spring Framework's integration with a number of Java EE
|
||||
(and related) technologies.
|
||||
</para>
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para><xref linkend="remoting"/></para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para><xref linkend="ejb"/></para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para><xref linkend="jms"/></para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para><xref linkend="jmx"/></para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para><xref linkend="cci"/></para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para><xref linkend="mail"/></para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para><xref linkend="scheduling"/></para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para><xref linkend="dynamic-language"/></para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para><xref linkend="metadata"/></para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
</partintro>
|
||||
<xi:include href="remoting.xml"/>
|
||||
<xi:include href="ejb.xml"/>
|
||||
<xi:include href="jms.xml"/>
|
||||
<xi:include href="jmx.xml"/>
|
||||
<xi:include href="cci.xml"/>
|
||||
<xi:include href="mail.xml"/>
|
||||
<xi:include href="scheduling.xml"/>
|
||||
<xi:include href="dynamic-languages.xml"/>
|
||||
<xi:include href="metadata.xml"/>
|
||||
</part>
|
||||
<!-- back matter -->
|
||||
<part id="spring-appendices">
|
||||
<title>Appendices</title>
|
||||
<xi:include href="classic-spring.xml"/>
|
||||
<xi:include href="classic-aop-spring.xml"/>
|
||||
<xi:include href="xsd-configuration.xml"/>
|
||||
<xi:include href="xml-custom.xml"/>
|
||||
<xi:include href="dtd.xml"/>
|
||||
<xi:include href="spring.tld.xml"/>
|
||||
<xi:include href="spring-form.tld.xml"/>
|
||||
</part>
|
||||
<mediaobject>
|
||||
<imageobject role="fo">
|
||||
<imagedata align="center" fileref="images/logo-pdf.png" format="PNG"
|
||||
width="240" />
|
||||
</imageobject>
|
||||
</mediaobject>
|
||||
|
||||
<authorgroup>
|
||||
<author>
|
||||
<firstname>Rod</firstname>
|
||||
|
||||
<surname>Johnson</surname>
|
||||
</author>
|
||||
|
||||
<author>
|
||||
<firstname>Juergen</firstname>
|
||||
|
||||
<surname>Hoeller</surname>
|
||||
</author>
|
||||
|
||||
<author>
|
||||
<firstname>Keith</firstname>
|
||||
|
||||
<surname>Donald</surname>
|
||||
</author>
|
||||
|
||||
<author>
|
||||
<firstname>Colin</firstname>
|
||||
|
||||
<surname>Sampaleanu</surname>
|
||||
</author>
|
||||
|
||||
<author>
|
||||
<firstname>Rob</firstname>
|
||||
|
||||
<surname>Harrop</surname>
|
||||
</author>
|
||||
|
||||
<author>
|
||||
<firstname>Thomas</firstname>
|
||||
|
||||
<surname>Risberg</surname>
|
||||
</author>
|
||||
|
||||
<author>
|
||||
<firstname>Alef</firstname>
|
||||
|
||||
<surname>Arendsen</surname>
|
||||
</author>
|
||||
|
||||
<author>
|
||||
<firstname>Darren</firstname>
|
||||
|
||||
<surname>Davison</surname>
|
||||
</author>
|
||||
|
||||
<author>
|
||||
<firstname>Dmitriy</firstname>
|
||||
|
||||
<surname>Kopylenko</surname>
|
||||
</author>
|
||||
|
||||
<author>
|
||||
<firstname>Mark</firstname>
|
||||
|
||||
<surname>Pollack</surname>
|
||||
</author>
|
||||
|
||||
<author>
|
||||
<firstname>Thierry</firstname>
|
||||
|
||||
<surname>Templier</surname>
|
||||
</author>
|
||||
|
||||
<author>
|
||||
<firstname>Erwin</firstname>
|
||||
|
||||
<surname>Vervaet</surname>
|
||||
</author>
|
||||
|
||||
<author>
|
||||
<firstname>Portia</firstname>
|
||||
|
||||
<surname>Tung</surname>
|
||||
</author>
|
||||
|
||||
<author>
|
||||
<firstname>Ben</firstname>
|
||||
|
||||
<surname>Hale</surname>
|
||||
</author>
|
||||
|
||||
<author>
|
||||
<firstname>Adrian</firstname>
|
||||
|
||||
<surname>Colyer</surname>
|
||||
</author>
|
||||
|
||||
<author>
|
||||
<firstname>John</firstname>
|
||||
|
||||
<surname>Lewis</surname>
|
||||
</author>
|
||||
|
||||
<author>
|
||||
<firstname>Costin</firstname>
|
||||
|
||||
<surname>Leau</surname>
|
||||
</author>
|
||||
|
||||
<author>
|
||||
<firstname>Mark</firstname>
|
||||
|
||||
<surname>Fisher</surname>
|
||||
</author>
|
||||
|
||||
<author>
|
||||
<firstname>Sam</firstname>
|
||||
|
||||
<surname>Brannen</surname>
|
||||
</author>
|
||||
|
||||
<author>
|
||||
<firstname>Ramnivas</firstname>
|
||||
|
||||
<surname>Laddad</surname>
|
||||
</author>
|
||||
|
||||
<author>
|
||||
<firstname>Arjen</firstname>
|
||||
|
||||
<surname>Poutsma</surname>
|
||||
</author>
|
||||
|
||||
<author>
|
||||
<firstname>Chris</firstname>
|
||||
|
||||
<surname>Beams</surname>
|
||||
</author>
|
||||
|
||||
<author>
|
||||
<firstname>Tareq</firstname>
|
||||
|
||||
<surname>Abedrabbo</surname>
|
||||
</author>
|
||||
|
||||
<author>
|
||||
<firstname>Andy</firstname>
|
||||
|
||||
<surname>Clement</surname>
|
||||
</author>
|
||||
|
||||
<author>
|
||||
<firstname>Dave</firstname>
|
||||
|
||||
<surname>Syer</surname>
|
||||
</author>
|
||||
</authorgroup>
|
||||
|
||||
<copyright>
|
||||
<year>2004-2009</year>
|
||||
|
||||
<holder>Rod Johnson, Juergen Hoeller, Keith Donald, Colin Sampaleanu,
|
||||
Rob Harrop, Alef Arendsen, Thomas Risberg, Darren Davison, Dmitriy
|
||||
Kopylenko, Mark Pollack, Thierry Templier, Erwin Vervaet, Portia Tung,
|
||||
Ben Hale, Adrian Colyer, John Lewis, Costin Leau, Mark Fisher, Sam
|
||||
Brannen, Ramnivas Laddad, Arjen Poutsma, Chris Beams, Tareq Abedrabbo,
|
||||
Andy Clement</holder>
|
||||
</copyright>
|
||||
|
||||
<legalnotice>
|
||||
<para>Copies of this document may be made for your own use and for
|
||||
distribution to others, provided that you do not charge any fee for such
|
||||
copies and further provided that each copy contains this Copyright
|
||||
Notice, whether distributed in print or electronically.</para>
|
||||
</legalnotice>
|
||||
</bookinfo>
|
||||
|
||||
<!-- front matter -->
|
||||
|
||||
<toc></toc>
|
||||
|
||||
<part id="spring-introduction">
|
||||
<title>Overview of Spring Framework</title>
|
||||
|
||||
<partintro id="spring-core-intro">
|
||||
<para>The Spring Framework is a lightweight solution and a potential
|
||||
one-stop-shop for building your enterprise-ready applications. However,
|
||||
Spring is modular, allowing you to use only those parts that you need,
|
||||
without having to bring in the rest. You can use the IoC container, with
|
||||
Struts on top, but you can also use only the <link
|
||||
linkend="orm-hibernate">Hibernate integration code</link> or the <link
|
||||
linkend="jdbc-introduction">JDBC abstraction layer</link>. The Spring
|
||||
Framework supports declarative transaction management, remote access to
|
||||
your logic through RMI or web services, and various options for
|
||||
persisting your data. It offers a full-featured <link
|
||||
linkend="mvc-introduction">MVC framework</link>, and enables you to
|
||||
integrate <link linkend="aop-introduction">AOP</link> transparently into
|
||||
your software.</para>
|
||||
|
||||
<para>Spring is designed to be non-intrusive, meaning that your domain
|
||||
logic code generally has no dependencies on the framework itself. In
|
||||
your integration layer (such as the data access layer), some
|
||||
dependencies on the data access technology and the Spring libraries will
|
||||
exist. However, it should be easy to isolate these dependencies from the
|
||||
rest of your code base.</para>
|
||||
|
||||
<para>This document is a reference guide to Spring Framework features.
|
||||
If you have any requests, comments, or questions on this document,
|
||||
please post them on the user mailing list or on the support forums at
|
||||
<ulink url="http://forum.springsource.org/"></ulink>.<!--Missing link above. PDF shows it as http://forum.springsource.org/--></para>
|
||||
</partintro>
|
||||
|
||||
<xi:include href="overview.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
|
||||
</part>
|
||||
|
||||
<part id="spring-whats-new">
|
||||
<title>What's New in Spring 3.0</title>
|
||||
|
||||
<xi:include href="new-in-3.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
|
||||
</part>
|
||||
|
||||
<part id="spring-core">
|
||||
<title>Core Technologies</title>
|
||||
|
||||
<partintro id="spring-core-intro">
|
||||
<para>This part of the reference documentation covers all of those
|
||||
technologies that are absolutely integral to the Spring
|
||||
Framework.</para>
|
||||
|
||||
<para>Foremost amongst these is the Spring Framework's Inversion of
|
||||
Control (IoC) container. A thorough treatment of the Spring Framework's
|
||||
IoC container is closely followed by comprehensive coverage of Spring's
|
||||
Aspect-Oriented Programming (AOP) technologies. The Spring Framework has
|
||||
its own AOP framework, which is conceptually easy to understand, and
|
||||
which successfully addresses the 80% sweet spot of AOP requirements in
|
||||
Java enterprise programming.</para>
|
||||
|
||||
<para>Coverage of Spring's integration with AspectJ (currently the
|
||||
richest - in terms of features - and certainly most mature AOP
|
||||
implementation in the Java enterprise space) is also provided.</para>
|
||||
|
||||
<para>Finally, the adoption of the test-driven-development (TDD)
|
||||
approach to software development is certainly advocated by the Spring
|
||||
team, and so coverage of Spring's support for integration testing is
|
||||
covered (alongside best practices for unit testing). The Spring team has
|
||||
found that the correct use of IoC certainly does make both unit and
|
||||
integration testing easier (in that the presence of setter methods and
|
||||
appropriate constructors on classes makes them easier to wire together
|
||||
in a test without having to set up service locator registries and
|
||||
suchlike)... the chapter dedicated solely to testing will hopefully
|
||||
convince you of this as well.</para>
|
||||
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para><xref linkend="beans" /></para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para><xref linkend="resources" /></para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para><xref linkend="validation" /></para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para><xref linkend="expressions" /></para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para><xref linkend="aop" /></para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para><xref linkend="aop-api" /></para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para><xref linkend="testing" /></para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
</partintro>
|
||||
|
||||
<xi:include href="beans.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
|
||||
|
||||
<xi:include href="resources.xml"
|
||||
xmlns:xi="http://www.w3.org/2001/XInclude" />
|
||||
|
||||
<xi:include href="validation.xml"
|
||||
xmlns:xi="http://www.w3.org/2001/XInclude" />
|
||||
|
||||
<xi:include href="expressions.xml"
|
||||
xmlns:xi="http://www.w3.org/2001/XInclude" />
|
||||
|
||||
<xi:include href="aop.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
|
||||
|
||||
<xi:include href="aop-api.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
|
||||
|
||||
<xi:include href="testing.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
|
||||
</part>
|
||||
|
||||
<part id="spring-data-tier">
|
||||
<title>Data Access</title>
|
||||
|
||||
<partintro id="spring-data-tier-intro">
|
||||
<para>This part of the reference documentation is concerned with data
|
||||
access and the interaction between the data access layer and the
|
||||
business or service layer.</para>
|
||||
|
||||
<para>Spring's comprehensive transaction management support is covered
|
||||
in some detail, followed by thorough coverage of the various data access
|
||||
frameworks and technologies that the Spring Framework integrates
|
||||
with.</para>
|
||||
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para><xref linkend="transaction" /></para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para><xref linkend="dao" /></para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para><xref linkend="jdbc" /></para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para><xref linkend="orm" /></para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para><xref linkend="oxm" /></para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
</partintro>
|
||||
|
||||
<xi:include href="transaction.xml"
|
||||
xmlns:xi="http://www.w3.org/2001/XInclude" />
|
||||
|
||||
<xi:include href="dao.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
|
||||
|
||||
<xi:include href="jdbc.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
|
||||
|
||||
<xi:include href="orm.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
|
||||
|
||||
<xi:include href="oxm.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
|
||||
</part>
|
||||
|
||||
<part id="spring-web">
|
||||
<title>The Web</title>
|
||||
|
||||
<partintro id="spring-web-intro">
|
||||
<para>This part of the reference documentation covers the Spring
|
||||
Framework's support for the presentation tier (and specifically
|
||||
web-based presentation tiers).</para>
|
||||
|
||||
<para>The Spring Framework's own web framework, <link
|
||||
linkend="mvc">Spring Web MVC</link>, is covered in the first couple of
|
||||
chapters. A number of the remaining chapters in this part of the
|
||||
reference documentation are concerned with the Spring Framework's
|
||||
integration with other web technologies, such as <link
|
||||
linkend="struts">Struts</link> and <link linkend="jsf">JSF</link> (to
|
||||
name but two).</para>
|
||||
|
||||
<para>This section concludes with coverage of Spring's MVC <link
|
||||
linkend="portlet">portlet framework</link>.</para>
|
||||
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para><xref linkend="mvc" /></para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para><xref linkend="view" /></para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para><xref linkend="web-integration" /></para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para><xref linkend="portlet" /></para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
</partintro>
|
||||
|
||||
<xi:include href="mvc.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
|
||||
|
||||
<xi:include href="view.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
|
||||
|
||||
<xi:include href="web-integration.xml"
|
||||
xmlns:xi="http://www.w3.org/2001/XInclude" />
|
||||
|
||||
<xi:include href="portlet.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
|
||||
</part>
|
||||
|
||||
<part id="spring-integration">
|
||||
<title>Integration</title>
|
||||
|
||||
<partintro id="spring-integration-intro">
|
||||
<para>This part of the reference documentation covers the Spring
|
||||
Framework's integration with a number of Java EE (and related)
|
||||
technologies.</para>
|
||||
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para><xref linkend="remoting" /></para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para><xref linkend="ejb" /></para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para><xref linkend="jms" /></para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para><xref linkend="jmx" /></para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para><xref linkend="cci" /></para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para><xref linkend="mail" /></para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para><xref linkend="scheduling" /></para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para><xref linkend="dynamic-language" /></para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para><xref linkend="metadata" /></para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
</partintro>
|
||||
|
||||
<xi:include href="remoting.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
|
||||
|
||||
<xi:include href="ejb.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
|
||||
|
||||
<xi:include href="jms.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
|
||||
|
||||
<xi:include href="jmx.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
|
||||
|
||||
<xi:include href="cci.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
|
||||
|
||||
<xi:include href="mail.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
|
||||
|
||||
<xi:include href="scheduling.xml"
|
||||
xmlns:xi="http://www.w3.org/2001/XInclude" />
|
||||
|
||||
<xi:include href="dynamic-languages.xml"
|
||||
xmlns:xi="http://www.w3.org/2001/XInclude" />
|
||||
|
||||
<xi:include href="metadata.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
|
||||
</part>
|
||||
|
||||
<!-- back matter -->
|
||||
|
||||
<part id="spring-appendices">
|
||||
<title>Appendices</title>
|
||||
|
||||
<xi:include href="classic-spring.xml"
|
||||
xmlns:xi="http://www.w3.org/2001/XInclude" />
|
||||
|
||||
<xi:include href="classic-aop-spring.xml"
|
||||
xmlns:xi="http://www.w3.org/2001/XInclude" />
|
||||
|
||||
<xi:include href="xsd-configuration.xml"
|
||||
xmlns:xi="http://www.w3.org/2001/XInclude" />
|
||||
|
||||
<xi:include href="xml-custom.xml"
|
||||
xmlns:xi="http://www.w3.org/2001/XInclude" />
|
||||
|
||||
<xi:include href="dtd.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
|
||||
|
||||
<xi:include href="spring.tld.xml"
|
||||
xmlns:xi="http://www.w3.org/2001/XInclude" />
|
||||
|
||||
<xi:include href="spring-form.tld.xml"
|
||||
xmlns:xi="http://www.w3.org/2001/XInclude" />
|
||||
</part>
|
||||
</book>
|
||||
|
|
|
@ -157,7 +157,7 @@
|
|||
|
||||
<para>The Spring Framework provides first class support for integration
|
||||
testing in the <filename
|
||||
class="libraryfile">org.springframework.test-VERSION.jar</filename>
|
||||
class="libraryfile">spring-test.jar</filename>
|
||||
library (where <literal>VERSION</literal> is the release version). This
|
||||
library includes the <literal>org.springframework.test</literal>
|
||||
package, which contains valuable classes for integration testing with a
|
||||
|
|
|
@ -100,7 +100,7 @@ productList.url=/WEB-INF/jsp/productlist.jsp</programlisting>
|
|||
escaping of characters.</para>
|
||||
|
||||
<para>The tag library descriptor (TLD) is included in the <filename
|
||||
class="libraryfile">org.springframework.web.servlet-3.0.0.RELEASE.jar</filename>.
|
||||
class="libraryfile">spring-webmvc.jar</filename>.
|
||||
Further information about the individual tags can be found in
|
||||
the appendix entitled <xref linkend="spring.tld" />.</para>
|
||||
</section>
|
||||
|
@ -129,7 +129,7 @@ productList.url=/WEB-INF/jsp/productlist.jsp</programlisting>
|
|||
<title>Configuration</title>
|
||||
|
||||
<para>The form tag library comes bundled in
|
||||
<literal>org.springframework.web.servlet-3.0.0.RELEASE.jar</literal>.
|
||||
<literal>spring-webmvc.jar</literal>.
|
||||
The library descriptor is called
|
||||
<literal>spring-form.tld</literal>.</para>
|
||||
|
||||
|
@ -1004,7 +1004,7 @@ findOwnersForm.url=/WEB-INF/jsp/findOwners.jsp
|
|||
<literal>WEB-INF/lib</literal> folder where they are guaranteed to be
|
||||
found by a Java EE server and added to the classpath for your application.
|
||||
It is of course assumed that you already have the <filename
|
||||
class="libraryfile">spring.jar</filename> in your <filename
|
||||
class="libraryfile">spring-webmvc.jar</filename> in your <filename
|
||||
class="directory">'WEB-INF/lib'</filename> directory too! If you make use of
|
||||
Spring's 'dateToolAttribute' or 'numberToolAttribute' in your Velocity
|
||||
views, you will also need to include the <filename
|
||||
|
@ -1098,7 +1098,7 @@ findOwnersForm.url=/WEB-INF/jsp/findOwners.jsp
|
|||
<literal>VelocityConfigurer</literal> bean definition above.</para>
|
||||
|
||||
<programlisting language="xml"><bean id="velocityConfig" class="org.springframework.web.servlet.view.velocity.VelocityConfigurer">
|
||||
<property name="configLocation value="/WEB-INF/velocity.properties"/>
|
||||
<property name="configLocation" value="/WEB-INF/velocity.properties"/>
|
||||
</bean></programlisting>
|
||||
|
||||
<para>Alternatively, you can specify velocity properties directly in
|
||||
|
@ -1170,7 +1170,7 @@ findOwnersForm.url=/WEB-INF/jsp/findOwners.jsp
|
|||
<title>The bind macros</title>
|
||||
|
||||
<para>A standard set of macros are maintained within the
|
||||
<literal>spring.jar</literal> file for both languages, so they are
|
||||
<literal>spring-webmvc.jar</literal> file for both languages, so they are
|
||||
always available to a suitably configured application.</para>
|
||||
|
||||
<para>Some of the macros defined in the Spring libraries are
|
||||
|
@ -1865,7 +1865,7 @@ home.root=words</programlisting>
|
|||
|
|
||||
+- lib
|
||||
| |
|
||||
| +- spring.jar
|
||||
| +- spring-*.jar
|
||||
|
|
||||
+- xsl
|
||||
| |
|
||||
|
|
Loading…
Reference in New Issue