AppInfo is a small library providing the easy way to show always valid, automatic updated information about a version of running software in your web/desktop Java application. Especially useful with automatic builds from CI server deployed on QA. Currently supported are displaying name, version, build number and build date of running software. Information can be passed via environmental variables and works out-of-box with Hudson CI server.
AppInfo (just like many other projects) was emerged to resolve some problem. It is often required to have each built version of software uniquely identifiable. For small projects which are not built very often it could be enough to have person who before manual build increase version number. In a situation where Continuous Integration server builds a new version every night which is automatically deployed on QA server to allow testers work on a current version day by day it is not enough. AppInfo allows to automatically feed your application with a current version number, build date or build number. It can be fetched, freely formatted and displayed in a footer, a title bar, on a console or wherever needed (e.g. "Your fancy app - 1.2.8 - Build 7143 - rev. 10676 - 2010-11-04_21-34"). AppInfo is a set of POJOs and can be used in every Java application (web one deployed on Application server, desktop one written in Swing or even that using console only). There is a predefined configuration which makes usage from Spring based applications very easy (just add our XML to your Spring context configuration), but IoC container is not mandatory. If you use something else and have some useful tips for other users please contribute. Thanks!
There are some other ways to display current version in your application, but with AppInfo you have got:
In the whole process two separate phases exist: getting data during a build process and fetching it to allow display in end application.
In the first phase data has to be collected and stored. The default configuration uses system variable to pass required data and manifest file to keep it for further usage. Because in some situations (e.g. development build from IDE) manifest file or even JAR could not be available AppInfo contains a configurable chain of objects which can provide required data. In a default configuration manifest from JAR/WAR is used. If it fails static configuration from defaultManifest.txt file is read. Sample defaultManifest.txt is provided by appinfo.jar, but those values can be simple overridden by placing another /net/sf/appinfo/defaultManifest.txt in application resources. The last link in a chain is FallbackApplicationInfo which cannot fail and return hardcoded default values (like Unknown app - devel). Thanks to that mechanism your application should always be able to start (at worst with Unknown app in a footer).
In the second phase AppInfo internal structures read data (by default) from manifest and make it available for end application mechanism which can display it where and when needed. Those phases and required configuration are described preciously in the following sections.
In order to use AppInfo from any application it is required to have AppInfo's JAR on the application classpath. AppInfo is available in Central Maven Repository and when end application is built using Maven it can be easily done by adding a dependency in application's pom.xml:
<dependencies>
(...)
<dependency>
<groupId>net.sf.appinfo</groupId>
<artifactId>appinfo</artifactId>
<version>0.5.2</version>
</dependency>
(...)
</dependencies>
In case of not using Maven placing appinfo-0.5.2.jar on the application classpath would be enough.
In the default case AppInfo reads information about running software from a manifest file. It's very easy to manage values using maven-jar-plugin. Following entries from manifest are used:
Sample maven-jar-plugin configuration to put required values into manifest file. Last 4 variables are set automatically when building by Hudson. They can be also set by hand in system when testing or to force specified version.
<build>
(...)
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-jar-plugin</artifactId> <!-- maven-war-plugin for web applications -->
<configuration>
<archive>
<manifestEntries>
<Specification-Title>${project.name}</Specification-Title>
<Specification-Version>${project.version}</Specification-Version>
<!-- Variables set by Hudson -->
<Build-Number>${BUILD_NUMBER}</Build-Number>
<Build-Date>${BUILD_ID}</Build-Date>
<SCM-Revision>${SVN_REVISION}</SCM-Revision>
<!-- Next one for potential usage in the next AppInfo versions -->
<Job-Name>${JOB_NAME}</Job-Name>
</manifestEntries>
</archive>
</configuration>
</plugin>
(...)
</build>
It should be similar easy to do it from Ant or Gradle. In case of using AppInfo with some other build system please contribute sample usage for others. Thanks!
In a running web application WAR is not usually available and in AppInfo ServletContext is used to get MANIFEST.MF file. In addition to appInfoDefaultContext.xml (which contains default core Spring context configuration) appinfo.jar has bundled also appInfoWebContext.xml with defined applicationTypeSpecificManifestReader bean being an instance of ServletContextManifestReader. Those two files added to Spring context configuration (contextConfigLocation in web.xml) should be enough to setup Spring context with ready to use AppInfo beans.
<context-param>
<param-name>contextConfigLocation</param-name>
<param-value>
(...)
classpath:net/sf/appinfo/appInfoDefaultContext.xml,
classpath:net/sf/appinfo/appInfoWebContext.xml,
(...)
</param-value>
</context-param>
AppInfo distribution JAR contains default configuration file for Spring context (classpath:net/sf/appinfo/appInfoDefaultContext.xml) which defined beans required for AppInfo proper work.
When included into context configuration of your application it is only needed to add one bean:
<bean id="applicationTypeSpecificManifestReader" class="net.sf.appinfo.reader.JarManifestReader">
<constructor-arg value="com.example.class.from.application.JAR"/>
</bean>
Most of applications contains many JAR files. It is required for AppInfo to choose proper JAR which the application is run. Mechanism to read values from manifest file which is currently used requires a class from that JAR to be passed, so JarManifestReader bean it cannot be defined in AppInfo JAR file (MANIFEST.MF from appinfo.jar would be used). If you know any better mechanism to get manifest file from JAR from which the application is run please let me know.
Sample application with explanation can be found in a post on my blog.
If the default configuration is not convenient for your needs, necessary beans have to be created in your configuration file. Content of appInfoDefaultContext.xml and JavaDoc for classes can be helpful to determine dependencies between beans.
AppInfo can be easily used with any IoC container or even without it. It is only necessary to create and initialize proper classes. Take a look on appInfoDefaultContext.xml and JavaDoc for classes to get know which are required.
When using Spring with default configuration the easiest is to used appInfoText bean which is a String instance containing already formatted application info text. If custom format is required it is only necessary to extend AbstractApplicationInfoFormatter and override "String getInfo()" method which concatenate separate values available in ApplicationInfo instance.
The latest AppInfo version is 0.5.2. AppInfo is available in Maven Central Repository. In addition a distribution archive (binary JAR, sources and documentation) can be download from SourceForge: https://sourceforge.net/projects/appinfo/files/appinfo/0.5.2/
AppInfo source code is managed by Git - distributed SCM. It can be easily browsed: http://appinfo.git.sourceforge.net/git/gitweb.cgi?p=appinfo/appinfo
It's also possible to make a local branch to work on it: git clone git://appinfo.git.sourceforge.net/gitroot/appinfo/appinfo
AppInfo is developed using Test Driven Development. Source code is control using Checkstyle, PMD and FindBugs. The library has a test suite which gives over 80% code coverage. Before became publicly available AppInfo has been used in a few real projects with success, but nevertheless as every code AppInfo surely contains some bugs. If you find any of them please let me know via email. I will try to fix it as soon as possible. Suggestions for further development as well as patches (and typos in docs) are also welcome.
There are two mailing lists available. appinfo-announce - low traffic mailing list with the announcements about the project appinfo-users - for the discussions about AppInfo
Bugs and feature requests can be report via ticket system: https://jira.codehaus.org/browse/APPINFO
AppInfo was written by Marcin Zajączkowski. The author can be contacted using project's mailing lists or directly via email: mszpak ATT wp DOTT pl. There is also Marcin's blog available: Solid Soft - working code is not enough.