diff --git a/spring-framework-reference/src/overview.xml b/spring-framework-reference/src/overview.xml index 5c16eafd2c8..3c214e16094 100644 --- a/spring-framework-reference/src/overview.xml +++ b/spring-framework-reference/src/overview.xml @@ -415,7 +415,9 @@ TR: OK. Added to diagram.--> (org.springframework.*-<version>.jar), and the dependencies are also in this "long" form, with external libraries (not from SpringSource) having the prefix - com.springsource. + com.springsource. See the FAQ + for more information. @@ -576,10 +578,23 @@ TR: OK. Added to diagram.--> 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 + logging options). + + Next we outline the basic steps needed to configure an + application that depends on Spring, first with Maven and then with + Ivy. In all cases, if anything is unclear, 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, and + our samples mostly use Maven. + + +
+ Maven Dependency Management + + 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: <dependencies> @@ -659,14 +674,53 @@ TR: OK. Added to diagram.--> 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. +
- If you prefer to use - Ivy 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). +
+ Ivy Dependency Management + If you prefer to use Ivy to manage dependencies + then there are similar names and configuration options. + + To configure Ivy to point to the SpringSource EBR add the + following resolvers to your + ivysettings.xml: + + <resolvers> + + <url name="com.springsource.repository.bundles.release"> + + <ivy pattern="http://repository.springsource.com/ivy/bundles/release/ + [organisation]/[module]/[revision]/[artifact]-[revision].[ext]" /> + <artifact pattern="http://repository.springsource.com/ivy/bundles/release/ + [organisation]/[module]/[revision]/[artifact]-[revision].[ext]" /> + + </url> + + <url name="com.springsource.repository.bundles.external"> + + <ivy pattern="http://repository.springsource.com/ivy/bundles/external/ + [organisation]/[module]/[revision]/[artifact]-[revision].[ext]" /> + <artifact pattern="http://repository.springsource.com/ivy/bundles/external/ + [organisation]/[module]/[revision]/[artifact]-[revision].[ext]" /> + + </url> + +</resolvers> + + The XML above is not valid because the lines are too long - if + you copy-paste then remove the extra line endings in the middle of the + url patterns. + + Once Ivy is configured to look in the EBR adding a dependency is + easy. Simply pull up the details page for the bundle in question in + the repository browser and you'll find an Ivy snippet ready for you to + include in your dependencies section. For example (in + ivy.xml): + + <dependency org="org.springframework" + name="org.springframework.core" rev="3.0.0.RELEASE" conf="compile->runtime"/>
@@ -697,32 +751,33 @@ TR: OK. Added to diagram.--> Spring and specifically from the central module called spring-core. - The nice thing about commons-logging 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. + The nice thing about commons-logging 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.
Not Using Commons Logging - Unfortunately, the worst thing about commons-logging, 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 (SLF4J), - which is also used by a lot of other tools - that people use with Spring inside their applications. + Unfortunately, the worst thing about + commons-logging, 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 (SLF4J), which is also used by a lot + of other tools that people use with Spring inside their + applications. - To switch off commons-logging 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. + To switch off commons-logging 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. <dependencies> <dependency> @@ -750,28 +805,28 @@ TR: OK. Added to diagram.-->
SLF4J is a cleaner dependency and more efficient at runtime than - commons-logging 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. + commons-logging 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. 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 commons-logging 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. + replace the commons-logging 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. 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 commons-logging): the bridge, the - SLF4J API, the binding to Log4J, and the Log4J implementation itself. In - Maven you would do that like this + dependencies (and exclude the existing commons-logging): + the bridge, the SLF4J API, the binding to Log4J, and the Log4J + implementation itself. In Maven you would do that like this <dependencies> <dependency> @@ -821,13 +876,12 @@ TR: OK. Added to diagram.--> A more common choice amongst SLF4J users, which uses fewer steps and generates fewer dependencies, is to bind directly to Logback. - This removes the extra binding step because - Logback implements SLF4J directly, so you only need to depend on two - libaries not four (jcl-slf4j and logback). 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. + url="http://logback.qos.ch">Logback. This removes the extra + binding step because Logback implements SLF4J directly, so you only need + to depend on two libaries not four (jcl-slf4j and + logback). 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.
Using Log4J