Appendix B. Managing Spring Batch Admin

Spring Batch Admin is a web-based administration console for Spring Batch. With it, you can monitor the execution of batch jobs and start and stop executions. You can make Spring Batch Admin the only entry point in your batch infrastructure, because it provides all the features to manage and monitor the behavior of your jobs. In addition, if you find a missing feature, you can implement it and contribute it back to the project, because Spring Batch Admin is an open source project.

Spring Batch Admin builds on top of Spring technologies like the Spring Framework, Spring MVC, and Spring Integration. Spring Batch Admin is a full-blown web application, but it remains easy to configure and deploy. This appendix shows you how to deploy a Spring Batch Admin instance in a couple of minutes. Even if your Spring Batch Admin instance runs on top of an embedded database, it will be helpful for you to discover the web console. You’ll also see how to deploy Spring Batch Admin in its own web application and how to make it cohabit with other applications inside the same web application.

Spring Batch Admin uses Spring for its configuration, and you’ll see how to set it up to connect to your batch metadata. If you’re already running a Spring Batch infrastructure, you’ll be able to browse a web view of it in a matter of minutes. This appendix also covers more advanced configuration scenarios, like deploying job definitions and overriding infrastructure Spring beans in Spring Batch Admin.

B.1. Downloading Spring Batch Admin

Table B.1 lists the relevant web pages about Spring Batch Admin and includes the download page.

Table B.1. Web pages related to the Spring Batch Admin project

URL	Description
http://static.springsource.org/spring-batch-admin/index.html	Home page
http://static.springsource.org/spring-batch-admin/reference/reference.xhtml	User guide
http://www.springsource.com/download/community	Download page

 

Note

We’re using Spring Batch Admin 1.2.0.RELEASE in this appendix.

 

If you download the Spring Batch Admin distribution from the download page, you’ll see the package is small. Spring Batch Admin is a web frontend, so it runs inside a web application, but you can easily embed it in any web application. You can also choose to let it run alone in a dedicated web application. You have multiple deployment options, and we’ll start with the latter, as the distribution contains a sample project to build a web application with Spring Batch Admin in it. This is the quickest way to have a Spring Batch Admin instance running. We’ll then study the second deployment option before covering how to configure Spring Batch Admin in more detail.

B.2. Building Spring Batch Admin from the distribution sample

We’re going to build a web archive with Spring Batch Admin in it. We use the sample provided in the distribution, which uses Maven as the build tool. You’ll need Maven 2 or greater installed on your computer

Unzip the Spring Batch Admin distribution and open an OS command shell in the corresponding directory. Then, type the following commands:

cd sample/
cd spring-batch-admin-parent/
mvn install
cd..
cd spring-batch-admin-sample/
mvn install

The first set of commands installs a parent POM inside your local Maven repository. The sample uses this POM. The second set of commands builds the web archive. Once the last command has finished, you should find a WAR file in the directory spring-batch-admin-sample/target. You can deploy this WAR file in any web container (like Jetty or Tomcat) or any application server (like Glassfish or JBoss).

Once Maven has deployed the archive, go the following URL to check the installation: http://localhost:8080/spring-batch-admin-sample-1.2.0.RELEASE/

The home page of your Spring Batch Admin instance is shown in figure B.1. From this home page, you can navigate through the application and discover its interface.

Figure B.1. The home page of a Spring Batch Admin instance lists the services the application provides.

The Spring Batch Admin sample uses an embedded database and has some default jobs installed. This is useful for a quick tryout of Spring Batch Admin and its main features. You can also use the sample as a starting point for your own Spring Batch Admin installation and customize its Spring configuration files and web.xml file. We’ll see more about the configuration of Spring Batch Admin in section B.4.

Perhaps you already have a web application running and you would like to run Spring Batch Admin in this same application, next to your business application. The next section shows how to embed Spring Batch Admin in an existing web application.

B.3. Embedding Spring Batch Admin in a web application

Spring Batch Admin is a lightweight application: it consists of only two JAR files containing web controllers, Spring configuration files, images, and views. Embedding Spring Batch Admin in a web application is as easy as including these two JARs and their dependencies and configuring the web.xml file. Let’s see how to add Spring Batch Admin dependencies in a Maven project.

B.3.1. Adding Spring Batch Admin dependencies

The following listing shows a Maven POM file that contains Spring Batch Admin dependencies. Spring Batch Admin has its own dependencies (Spring Batch, the Spring Framework, and so forth), but Maven pulls them in automatically.

Listing B.1. Maven dependencies for Spring Batch Admin

<?xml version="1.0"?>
<project (...)>
  <modelVersion>4.0.0</modelVersion>
  <groupId>com.manning.sbia</groupId>
  <artifactId>appB</artifactId>
  <version>1.0.0</version>
  <name>appB</name>
  <packaging>war</packaging>
  <dependencies>

    <dependency>
      <groupId>org.springframework.batch</groupId>
      <artifactId>spring-batch-admin-resources</artifactId>
      <version>1.2.0.RELEASE</version>
    </dependency>

    <dependency>
      <groupId>org.springframework.batch</groupId>
      <artifactId>spring-batch-admin-manager</artifactId>
      <version>1.2.0.RELEASE</version>
    </dependency>

  </dependencies>

  <properties>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
  </properties>

</project>

When adding Spring Batch Admin dependencies to an existing project, be careful of conflicts between dependencies. Your project can have its own dependencies, so you may need more configuration than what listing B.1 provides. This extra configuration can exclude transitive dependencies from Spring Batch Admin, or from your own project.

B.3.2. Declaring Spring Batch Admin in web.xml

The easiest way to configure Spring Batch Admin in the web.xml of your web application is to use the sample’s web.xml file as inspiration. Spring Batch Admin needs the following elements in web.xml:

• A servlet listener to bootstrap the root application context— If your web application uses Spring, this listener is already there, so just add an entry for the Spring Batch Admin Spring configuration file.
• Servlet filters to deal with HTTP headers in requests and responses— They’re useful mainly because Spring Batch Admin uses some RESTful-styled communication between the client and the server.
• A Spring MVC DispatcherServlet— Spring Batch Admin uses Spring MVC as its web layer.
• A ResourceServlet— To serve static resources from JAR files.

Be careful to avoid conflicts with your own application when configuring the URL mapping of Spring Batch Admin. The sample uses /* which handles all inbound URLs.

Once you have completed this configuration, you can package your web application with Maven and deploy it in a web container. You’ll get the same result as in the previous section, but now Spring Batch Admin will be bundled inside your own application!

The next section covers how to configure Spring Batch Admin to plug in your own environment.

B.4. Configuring Spring Batch Admin

Spring Batch Admin uses Spring for its configuration, and it’s straightforward to set up for your own environment. We’ll see first how to plug Spring Batch Admin into the batch metadata. You’ll be able to monitor the execution of your batch jobs, even if they don’t run in the same process as Spring Batch Admin. Then, we’ll see how to add job configurations to Spring Batch Admin. You’ll be able to monitor job executions and start and stop jobs from Spring Batch Admin. We’ll finish with advanced settings used to integrate Spring Batch Admin more deeply with an existing application.

B.4.1. Plugging into your batch metadata

Spring Batch Admin needs only one thing to plug into batch metadata: how to connect to the database that hosts these metadata. In Java terms, this means configuring a data source. You don’t have to bother with Spring configuration; you can just specify the connection parameters in a batch-default.properties file located at the root of the classpath. The following listing shows an example of such a properties file to connect to an H2 database.

Listing B.2. Configuring the database connection in batch-default.properties

The batch-default.properties file must be located at the root of the classpath. In a Maven project, the file can be in the src/main/resources directory. The file must contain the four usual database connection settings: driver class, URL, username, and password. You can also specify the implementation of a value incrementer for Spring Batch to generate primary keys. Look at implementations of the DataFieldMaxValueIncrementer interface in the Spring Framework and pick the one matching your database.

 

Note

Don’t forget to put the JDBC database driver JAR file on the classpath of the web application.

 

The configuration in listing B.2 tells Spring Batch not to run any SQL scripts on the target database. This assumes the database contains all the batch metadata tables (remember, the scripts to create these tables are in the Spring Batch core JAR file).

Once you complete the database settings, you can package the application and deploy it. The application will connect to the batch metadata, and you’ll be able to monitor the execution of your jobs. By configuring just the connection to the batch metadata, you can’t really use Spring Batch Admin as the only entry point to your batch infrastructure. To be able to launch executions directly from Spring Batch Admin, add all your job resources—Java classes, Spring Batch configuration—to the web application.

B.4.2. Deploying your own job files

Spring Batch Admin scans a specific location to find Spring configuration files that define jobs. This specific location is the META-INF/spring/batch/jobs directory on the classpath (any JAR file is eligible as a root for scanning, as is the WEB-INF/classes directory in the web application).

Each configuration file must be self-contained: it must define a job and all the Spring beans the job depends on, except for infrastructure beans like the job repository, the data source, and the transaction manager. Every bean defined in the root application context of the web application is visible to a job in a Spring configuration file. That’s why job configurations can depend on such common beans and don’t need to define them.

A typical job configuration file inside the META-INF/spring/batch/jobs directory will then contain the job definition—using the batch namespace—and Spring beans like item readers and item writers for the job.

Such a deployment is powerful: you can write your Spring Batch jobs in standalone projects and deploy them inside a Spring Batch Admin instance. As long you locate the configuration files in the META-INF/spring/batch/jobs directory, Spring Batch Admin will pick them up and make them available in the user interface.

 

Note

The sample from the Spring Batch Admin distribution defines some dummy jobs in its META-INF/spring/batch/jobs directory. Delete these jobs if you don’t want them to appear in your Spring Batch Admin instance.

 

The Spring Batch Admin UI isn’t the only way to trigger a job execution: you can embed a Java scheduler like Quartz or Spring Scheduler inside the application and let jobs be kicked off periodically. Look at chapter 4 for the various ways to use a Java scheduler with Spring Batch.

Once Spring Batch Admin connects to your batch metadata and can accept your new jobs, it gives you a great view of your batch infrastructure. You can even go further through the configuration and change some Spring Batch Admin internals. This is especially useful when Spring Batch Admin must cohabit with an existing business application in the same web application.

B.4.3. Overriding the Spring Batch Admin configuration

Spring Batch Admin includes configuration for Spring beans like the data source, the transaction manager, and the job repository. Spring Batch Admin lets you configure parts of these beans, as we saw in section B.4.1 when we used a properties file for the connection to the database. Spring Batch Admin also lets you override part of its configuration. This means you can define Spring beans that Spring Batch Admin will use in place of the default beans. Imagine that your data source comes from an application server as a Java Naming and Directory Interface (JNDI) resource. In this case, the database connection settings don’t make sense because you only need to perform a JNDI lookup. You can define a data source bean and use Spring’s JNDI support for the lookup.

There are two conditions for overriding to work:

1. The bean must have the same ID as the bean defined in the Spring Batch Admin configuration.
2. The bean definition must be loaded after Spring Batch Admin bean definitions.

To meet the first condition, you need to know the names of beans in the Spring Batch Admin configuration. Table B.2 lists some of the beans that are likely to be overridden. If you want to know all the beans you can override, the best source is...the source code! The Spring configuration files are located in the META-INF/spring/batch/bootstrap directory of the Spring Batch Admin manager module. The Spring Batch Admin reference guide also provides the list of the beans you can override.

Table B.2. Some beans to override in Spring Batch Admin

Bean name	Interface	Default
dataSource	DataSource	Commons database connection pool
transactionManager	PlatformTransactionManager	DataSourceTransactionManager
jobLauncher	JobLauncher	SimpleJobLauncher
jobLauncherTaskExecutor	TaskExecutor	Asynchronous, with Java 5 thread pool
jobRepository	JobRepository	Persistent job repository

You now know about overriding infrastructure beans, which is the first condition to meet to change the configuration of Spring Batch Admin. The second condition is to ensure that the definitions of the new beans are loaded after the Spring Batch Admin configuration. This doesn’t mean you need an extra application context; it means you need to be careful about the order in which Spring configuration files are loaded. Bean definitions override previous definitions with the same ID, so the order in which configuration files are loaded matters. This a rule Spring enforces in its application context implementations. To be sure your properly named beans override the default beans, you have two options (you can use one or the other or both):

1. Declare your beans in files located in the /META-INF/spring/batch/override/ directory— Spring Batch Admin ensures such files are loaded after the default files.
2. Declare your configuration files after the Spring Batch Admin files— In the contextConfigLocation parameter that specifies the files for the root application context in the web.xml file, declare the Spring Batch Admin configuration file in the first position, followed by your own application files.

Once both conditions are met (names for the beans and correct locations for the files), you’re ready to configure some the Spring Batch Admin infrastructure. The following listing shows how to override the data source and the task executor to launch jobs.

Listing B.3. Overriding infrastructure beans

By default, the task:executor element uses the Java 5 thread pool. Being able to override some of the key components of Spring Batch Admin is powerful. Spring Batch Admin can share any resource you use in your business application. You can plug in a server-provided data source, as we did in listing B.3, where Spring looks up the data source through JNDI. In listing B.3, we also defined our own thread-pooled task executor for the job launcher to use. Note that you can also plug in a server-provided thread pool like the JCA WorkManager or CommonJ (depending on what’s available in your application server). Spring provides a bridge with a TaskExecutor implementation for CommonJ. Spring Batch Admin can then use resources from the application server.

B.5. Summary

Spring Batch Admin includes all the features needed to monitor accurately your Spring Batch–powered infrastructure. You have multiple deployment options with Spring Batch Admin: you can deploy it in its own web application or let it cohabit with other applications in the same web application. The former is well suited to headless batch jobs if they’re not part of any web frontend. The latter works nicely when you embed Spring Batch in a web application and run it as a business application frontend.

The first setup step is to plug Spring Batch Admin into your batch metadata to monitor the execution of your jobs. You can then go further and use Spring Batch Admin to start and stop job executions. You can also override the Spring Batch Admin infrastructure to plug in existing infrastructure components, like a data source or a thread pool provided by your server.