This chapter describes how to set up your application to use Instrumented Spring Framework, Web Services, Web Flow, and Security. It outlines the necessary build and configuration steps that will allow Instrumented Spring products to automatically export their components to your application's JMX MBeanServer and enable automatic monitoring of those components. If you do not already use Spring Framework, you can learn more about it from Spring Framework Reference.
The JARs that you must add to your application are in the "dist" and
"lib" directories of the unpacked spring-<instrumented
product>-instrumented-management zip files for Instrumented
Spring Framework, Web Services, Web Flow, and Security.
![]() | Note |
|---|---|
If you will be replacing open source JARs with corresponding instrumented JARs, your replacements must be of the same maintenance release, that is, a release where the first and second digits of the release numbers are identical. For example, you can replace open source Spring Web Flow 2.0.0 with Instrumented Spring Web Flow 2.0.8. However, you cannot replace open source Spring Framework 2.5.x with Instrumented Spring Framework 3.0.0. You must first upgrade to Spring Framework 3.0.x. To do so, refer to the Spring Framework Upgrade Guide and the 3.0 Spring Framework Reference. |
The JARs you need to use depend on the application you are instrumenting. For more information about these JARs, see JAR Components.
org.springframework.<module>.instrumented-<version>.jar:
Instrumented JARs that are compile-time woven versions of their open
source counterparts.
com.springsource.management.instrumentation.<instrumentedproduct>.<module>-<version>.jar:
Instrumentation JARs that contain the AspectJ aspects used to weave
the instrumented JARs at compile time.
com.springsource.management.agent.<module>-<version>.jar
and
com.springsource.management.adapter.<module>-version.jar:
Spring Framework JARs that contain the API used to auto-discover
Spring beans, export them to JMX, and obtain and store monitoring
data.
Add the instrumented JAR files to your application classpath. If
you are already using open source Spring Framework, replace each Spring
Framework JAR in your application with the corresponding instrumented
JAR in the dist directory. These jars are named
org.springframework.<module>.instrumented-<version>.jar. See Mapping Maven Central JAR Names to EBR JAR Names if you originally obtained your non-instrumented Spring JAR files from the Maven Central repository.
![]() | Note |
|---|---|
You cannot use both an instrumented JAR file and its open source equivalent. You must remove the open source JAR and add the corresponding instrumented JAR in its place. |
For each instrumented JAR that you add to your application,
include the matching instrumentation JAR,
com.springsource.management.instrumentation.springframework.<module
name>-<version>.jar. These instrumentation jars
contain the aspects and Java classes used to manage and monitor the
components in the instrumented JAR. Make sure you include
com.springsource.management.instrumentation.springframework.applicationcontext.jar.
It must be present to enable auto-discovery.
Some instrumentation JARs are shared among the instrumented Spring
modules. For example, subclasses of
AbstractPlatformTransactionManager exist in
multiple jars. As such, all of these JARs may have a dependency on the
com.springsource.management.instrumentation.springframework.transaction.manager.jar.
When in doubt, consult the Import-Packages statement of the instrumented
jar Manifest for the required dependencies.
Include the following Management API jars:
com.springsource.management.adapter.jmx-<version>.jar
com.springsource.management.agent.bootstrap-<version>.jar
com.springsource.management.agent.config-<version>.jar
com.springsource.management.agent.control-<version>.jar
com.springsource.management.agent.discovery.domain-<version>.jar
com.springsource.management.agent.discovery.resource-<version>.jar
com.springsource.management.agent.inventory-<version>.jar
com.springsource.management.agent.monitoring-<version>.jar
Include one of the following, depending on whether you are instrumenting a standalone application or a web application:
com.springsource.management.agent.discovery.application.standalone-<version>.jar OR
com.springsource.management.agent.discovery.application.web-<version>.jar
Add the instrumented JAR files to your application classpath. If
you are using open source versions of these products, replace the JARs
in your application with the corresponding instrumented jars in the dist
directory of the Instrumented Spring Web Flow, Web Services, and
Security components. These jars are named
org.springframework.<module>.instrumented-<version>.jar. See Mapping Maven Central JAR Names to EBR JAR Names if you originally obtained your non-instrumented Spring JAR files from the Maven Central repository.
![]() | Note |
|---|---|
You cannot use both an instrumented JAR file and its open-source equivalent. You must remove the open-source JAR and add the corresponding instrumented JAR in its place. |
![]() | Note |
|---|---|
The latest Instrumented Spring Security (2.0.6) does not include instrumented versions of all jars distributed with open source Spring Security 3.0.x. Use the open source Spring Security 3.0 instead of instrumented Spring Security if you need these additional jars. (Spring Security 3.0.x requires Spring Framework 3.0.x.) |
For each instrumented JAR that you add to your application,
include the matching instrumentation JAR,
com.springsource.management.instrumentation.<instrumentedproduct>.<module
name>-<version>.jar. These instrumentation jars
contain the aspects and Java classes used to manage and monitor the
components in the instrumented JAR.
Typically, when you write your Spring applications, you obtain the Spring JAR files from one of the following two repositories:
Maven Central, which is the default repository for Maven queries.
Enterprise Bundle Repository (EBR), which is run by SpringSource and also hosts all the libraries that integrate with Spring.
However, it is important to note that each repository uses a different naming scheme for the JAR files. The Spring instrumented JAR files are all based on the naming in EBR. This means that if you originally obtained your non-instrumented Spring JAR files from Maven Central, and now want to replace them with instrumented JAR files, you will need to translate the JAR names appropriately.
For example, if your application uses the non-instrumented JAR file from Maven Central called spring-webmvc-version.jar and you want to replace it with the instrumented JAR, you would replace it with the following file: org.springframework.web.servlet.instrumented-version.jar.
The following table lists the most common Spring JAR names, first using their Maven Central names and then their corresponding EBR name.
Table 4.1. Mapping Between Maven Central and EBR JAR Names
| Maven Central JAR Name | EBR JAR Name |
|---|---|
spring-aop | org.springframework.aop |
spring-asm | org.springframework.asm |
spring-aspects | org.springframework.aspects |
spring-beans | org.springframework.beans |
spring-context | org.springframework.context |
spring-context-support | org.springframework.context.support |
spring-core | org.springframework.core |
spring-expression | org.springframework.expression |
spring-instrument | org.springframework.instrument |
spring-jdbc | org.springframework.jdbc |
spring-jms | org.springframework.jms |
spring-orm | org.springframework.orm |
spring-oxm | org.springframework.oxm |
spring-test | org.springframework.test |
spring-tx | org.springframework.transaction |
spring-web | org.springframework.web |
spring-webmvc | org.springframework.web.servlet |
spring-webmvc-portlet | org.springframework.web.portlet |