I like to mind-map and the tool I use is FreeMind. You can add icons to your nodes, import pictures etc.etc. You can also add some color to your mind-map; select a node and change the color. For some -strange- reason I wanted to have all my nodes in different colors and after one minute of selecting nodes, changing colors I already abandoned that idea => too tedious. Ruby to the rescue: Freemind stores your mind-maps in XML format and this little ruby script turns your boring mind-map into something colorful:

require 'rexml/document'
include REXML

def traverse_element(element)
    element.elements.each('node') do |e|
        e.attributes['COLOR']= ("#%06x" % rand(0xffffff))
        traverse_element(e)
    end
end

doc = Document.new(File.new("original_boring_mindmap.mm"))
traverse_element(doc.root)
out = File.new("new_colorful_mindmap.mm","w")
out.write(doc)

Nerdy? You bet ya…..

The starting point is -again- the simple web application from the previous blog. The part of the acegi-security.xml that is relevant is shown below.

	<!--
		The authenticationManager is the hook for all authenticationProviders we want
		to configure.
	-->
	 <bean id="authenticationManager"
        class="org.acegisecurity.providers.ProviderManager">
        <property name="providers">
            <list>
                <ref local="authenticationProvider" />
            </list>
        </property>
    </bean>

	<!--
		The Acegi DaoAuthenticationProvider
	-->
    <bean id="authenticationProvider"
		class="org.acegisecurity.providers.dao.DaoAuthenticationProvider">
        <property name="userDetailsService" ref="userDetailsServiceImpl"/>
	</bean>

    <!--
        The Acegi InMemoryDaoImpl
    -->
    <bean id="userDetailsServiceImpl"
        class="org.acegisecurity.userdetails.memory.InMemoryDaoImpl">
        <property name="userProperties">
            <props>
                <prop key="admin">secret,ROLE_ADMIN</prop>
            </props>
        </property>
    </bean>

We will replace this fragment with the following code:

	 <bean id="authenticationManager"
        class="com.xebia.acegi.CustomAuthenticationManager"/>

What does our CustomAuthenticationManager has to do? Well actually the interface AuthenticationProvider that needs to be implemented is quite straightforward:

public Authentication authenticate(Authentication authentication)
        throws AuthenticationException;

Lets begin with the most simple implementation possible:

	public Authentication authenticate(Authentication authentication) throws AuthenticationException {
		authentication.setAuthenticated(true);
		return authentication;
	}

When we start jetty (see previous blog) we can tweak Maven to give us a remote debugging hook by setting the MAVEN_OPTS variable:

$ echo $MAVEN_OPTS
-XX:MaxPermSize=512m -Xmx1024m -Xdebug -Xnoagent -Djava.compiler=NONE -Xrunjdwp:transport=dt_socket,address=4000,server=y,suspend=n

The first two arguments allocate more memory to the Maven process and the last arguments provide us a way to remotely debug the application. Using eclipse we can configure a remote debug application:

The implementation of the Authentication interface used by Acegi is an instance of UsernamePasswordAuthenticationToken as we can see when debugging the application.

The UsernamePasswordAuthenticationToken is constructed in the AuthenticationProcessingFilter -as configured in acegi-secutiry.xml-, but we could also subclass this filter to use more exotic implementations like the X509AuthenticationToken.

When checking out the result at http://localhost:8080/blog-acegi/site/admin.html it appears the implementation we have provided is to simple:

HTTP ERROR: 500

Cannot set this token to trusted - use constructor containing GrantedAuthority[]s instead

RequestURI=/blog-acegi/j_acegi_security_check
Caused by:

java.lang.IllegalArgumentException: Cannot set this token to trusted - use constructor containing GrantedAuthority[]s instead
	at org.acegisecurity.providers.UsernamePasswordAuthenticationToken.setAuthenticated(UsernamePasswordAuthenticationToken.java:85)
	at com.xebia.acegi.CustomAuthenticationManager.authenticate(CustomAuthenticationManager.java:25)
	at org.acegisecurity.ui.webapp.AuthenticationProcessingFilter.attemptAuthentication(AuthenticationProcessingFilter.java:71)
	at org.acegisecurity.ui.AbstractProcessingFilter.doFilter(AbstractProcessingFilter.java:199)
	at org.acegisecurity.util.FilterChainProxy$VirtualFilterChain.doFilter(FilterChainProxy.java:274)
	at org.acegisecurity.intercept.web.FilterSecurityInterceptor.invoke(FilterSecurityInterceptor.java:107)
	at org.acegisecurity.intercept.web.FilterSecurityInterceptor.doFilter(FilterSecurityInterceptor.java:72)
	at org.acegisecurity.util.FilterChainProxy$VirtualFilterChain.doFilter(FilterChainProxy.java:274)
	at org.acegisecurity.ui.ExceptionTranslationFilter.doFilter(ExceptionTranslationFilter.java:110)
	at org.acegisecurity.util.FilterChainProxy$VirtualFilterChain.doFilter(FilterChainProxy.java:274)
	at org.acegisecurity.util.FilterChainProxy.doFilter(FilterChainProxy.java:148)
	at org.acegisecurity.util.FilterToBeanProxy.doFilter(FilterToBeanProxy.java:98)
	at org.mortbay.jetty.servlet.ServletHandler$CachedChain.doFilter(ServletHandler.java:1065)

Acegi insists we create our instance of the Authentication interface. So let’s change our custom authentication manager using the following code:

return new UsernamePasswordAuthenticationToken(
				authentication.getPrincipal(),
				authentication.getCredentials(),
				new GrantedAuthority[] { new GrantedAuthorityImpl("ROLE_ADMIN") });

Of course a more serious implementation would do some lookup of the User and apply business logic to authenticate the user.

Acegi provides also an abstract AbstractUserDetailsAuthenticationProvider class that can be subclassed in able to benefit from the existing functionality from the Acegi framework. We change the relevant xml part in the acegi-security.xml with this fragment:

	<!--
		The authenticationManager is the hook for all authenticationProviders we want
		to configure.
	-->
	 <bean id="authenticationManager"
        class="org.acegisecurity.providers.ProviderManager">
        <property name="providers">
            <list>
                <ref local="authenticationProvider" />
            </list>
        </property>
    </bean>

	<!--
		Our own custom authenticationProvider.
	-->
    <bean id="authenticationProvider"
		class="com.xebia.acegi.CustomUserDetailsAuthenticationProvider">
	</bean>

The abstract methods that need to be implemented are simple:

protected abstract void additionalAuthenticationChecks(UserDetails userDetails,
			UsernamePasswordAuthenticationToken authentication)
			throws AuthenticationException ;

protected UserDetails retrieveUser(String username,
			UsernamePasswordAuthenticationToken authentication)
			throws AuthenticationException ;

And a -again very simple- implementation could be:

protected UserDetails retrieveUser(String username,
			UsernamePasswordAuthenticationToken authentication)
			throws AuthenticationException {
		Assert.hasText(username);
		Assert.notNull(authentication.getCredentials());
		if (username.equals("admin")
				&& authentication.getCredentials().equals("secret")) {
			return new User("admin", "secret", true, true, true, true,
					getAuthorities());
		}
		throw new BadCredentialsException("invalid username/password");
	}
	/*
	 * return GrantedAuthorities
	 */
	private GrantedAuthority[] getAuthorities() {
		return new GrantedAuthority[] { new GrantedAuthorityImpl("ROLE_ADMIN") };
	}

The hook that Acegi offers when subclassing the AbstractUserDetailsAuthenticationProvider allows you to call a web service to get the relevant information, query a legacy database or do whatever it takes to populate the User object. Note that because the authentication providers/managers are normal Spring beans you can inject them with configured data sources or any other -more exotic- beans.

A more complex use case could require the following security constraints to be implemented:

• An user account will be locked if the number of consecutive faulty login attempts exceeds 3.
• The password of an user account must be stored encrypted.
• An user account can be disabled/enabled for a certain period.
• An user account expiries after a certain period of inactivity.
• A password expiries after a certain period.

The actual implementation (not provided , but you can use this as a starting point ) of such a security policy is quite simple using the Acegi framework and the many hooks Acegi provides. When you consider implementing your own authentication provider do have a good look at the stuff that Acegi provides. There is good chance you can use/re-use existing functionality. There is a lot more to tell about the Acegi Framework like securing your services, securing specific part of your pages, accessing the user data stored in the session, integration with LDAP and using Acegi for standalone desktop applications but not now……

In the old days folks used the J2EE securing capabilities of the app server. This is of course still an option, but there are superior alternatives like the Acegi framework. Acegi is far from new and with the latest releases it has become a very stable and easy-to-use framework, especially when combined with Spring. I had to implement a custom security provider for a customer and was very surprised how easy this was accomplished. This blog describes the steps I took to get started with Acegi.

The starting point is a -very- simple web application using the Spring MVC framework. This is the web.xml:

<web-app version="2.4" xmlns="http://java.sun.com/xml/ns/j2ee"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee web-app_2_4.xsd">

    <context-param>
        <param-name>contextConfigLocation</param-name>
        <param-value>/WEB-INF/acegi-security.xml</param-value>
    </context-param>

    <listener>
        <listener-class>
            org.springframework.web.context.ContextLoaderListener
        </listener-class>
    </listener>

    <servlet>
        <servlet-name>blog-acegi-basic</servlet-name>
        <servlet-class>
            org.springframework.web.servlet.DispatcherServlet
        </servlet-class>
        <load-on-startup>1</load-on-startup>
    </servlet>

    <servlet-mapping>
        <servlet-name>blog-acegi-basic</servlet-name>
        <url-pattern>*.html</url-pattern>
    </servlet-mapping>
</web-app>

And the blog-acegi-basic-servlet.xml configuration.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE beans PUBLIC "-//SPRING//DTD BEAN//EN" "http://www.springframework.org/dtd/spring-beans.dtd">

<beans>

    <bean id="viewResolver"
        class="org.springframework.web.servlet.view.InternalResourceViewResolver">
        <property name="viewClass">
            <value>org.springframework.web.servlet.view.JstlView</value>
        </property>
        <property name="prefix">
            <value>/WEB-INF/views/</value>
        </property>
        <property name="suffix">
            <value>.jsp</value>
        </property>
    </bean>

    <bean name="/site/admin.html"
        class="com.xebia.mvc.AdminController">
    </bean>

    <bean name="/site/public.html"
        class="com.xebia.mvc.PublicController">
    </bean>

</beans>

The two Controllers are also very simple (for demo purposes):

public class AdminController implements Controller {
	/*
	 * (non-Javadoc)
	 *
	 * @see org.springframework.web.servlet.mvc.Controller#handleRequest(javax.servlet.http.HttpServletRequest,
	 *      javax.servlet.http.HttpServletResponse)
	 */
	public ModelAndView handleRequest(HttpServletRequest request,
			HttpServletResponse response) throws Exception {
		return new ModelAndView("admin", "info", "adminInfo");
	}
}

public class PublicController implements Controller {
	/*
	 * (non-Javadoc)
	 *
	 * @see org.springframework.web.servlet.mvc.Controller#handleRequest(javax.servlet.http.HttpServletRequest,
	 *      javax.servlet.http.HttpServletResponse)
	 */
	public ModelAndView handleRequest(HttpServletRequest request,
			HttpServletResponse response) throws Exception {
		return new ModelAndView("public", "info", "publicInfo");
	}
}

As are the views admin.jsp

<?xml version="1.0" encoding="ISO-8859-1" ?>
<%@ page language="java" contentType="text/html; charset=ISO-8859-1"
    pageEncoding="ISO-8859-1"%>
<%@ taglib prefix="authz" uri="http://acegisecurity.org/authz" %>
<%@ taglib prefix="c" uri="http://java.sun.com/jsp/jstl/core" %>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
	<head>
		<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" />
		<title>Admin</title>
	</head>
	<body>
		Hello Admin
		<c:out value='${info}' />
	</body>
</html>

and public.jsp that are placed in the folder WEB-INF/views:

<?xml version="1.0" encoding="ISO-8859-1" ?>
<%@ page language="java" contentType="text/html; charset=ISO-8859-1"
    pageEncoding="ISO-8859-1"%>
<%@ taglib prefix="authz" uri="http://acegisecurity.org/authz" %>
<%@ taglib prefix="c" uri="http://java.sun.com/jsp/jstl/core" %>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
	<head>
		<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" />
		<title>Public</title>
	</head>
	<body>
		Hello Public
		<c:out value='${info}'/>
	</body>
</html>

For now we’ll leave the acegi-security.xml empty.

<!DOCTYPE beans PUBLIC "-//SPRING//DTD BEAN//EN" "http://www.springframework.org/dtd/spring-beans.dtd">

<beans>
</beans>

When you use maven2 to build your web-application you can use the jetty plugin to test it. The following pom.xml has all dependencies and the plugin configuration to use jetty with the jdk1.5:

<project xmlns="http://maven.apache.org/POM/4.0.0"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <groupId>com.xebia</groupId>
    <artifactId>acegi-blog</artifactId>
    <packaging>war</packaging>
    <version>0-1-SNAPSHOT</version>
    <name>acegi-blog</name>
    <url>http://maven.apache.org</url>
    <dependencies>
        <dependency>
            <groupId>org.springframework</groupId>
            <artifactId>spring</artifactId>
            <version>2.0.2</version>
        </dependency>
        <dependency>
            <groupId>junit</groupId>
            <artifactId>junit</artifactId>
            <version>3.8.1</version>
            <scope>test</scope>
        </dependency>
        <dependency>
            <groupId>org.springframework</groupId>
            <artifactId>spring-mock</artifactId>
            <version>2.0.2</version>
            <scope>test</scope>
        </dependency>
        <dependency>
            <groupId>org.acegisecurity</groupId>
            <artifactId>acegi-security</artifactId>
            <version>1.0.3</version>
            <exclusions>
                <exclusion>
                    <groupId>org.springframework</groupId>
                    <artifactId>spring-jdbc</artifactId>
                </exclusion>
                <exclusion>
                    <groupId>org.springframework</groupId>
                    <artifactId>spring-core</artifactId>
                </exclusion>
                <exclusion>
                    <groupId>org.springframework</groupId>
                    <artifactId>spring-aop</artifactId>
                </exclusion>
                <exclusion>
                    <groupId>org.springframework</groupId>
                    <artifactId>spring-webmvc</artifactId>
                </exclusion>
                <exclusion>
                    <groupId>org.springframework</groupId>
                    <artifactId>spring-beans</artifactId>
                </exclusion>
                <exclusion>
                    <groupId>org.springframework</groupId>
                    <artifactId>spring-dao</artifactId>
                </exclusion>
                <exclusion>
                    <groupId>org.springframework</groupId>
                    <artifactId>spring-context</artifactId>
                </exclusion>
                <exclusion>
                    <groupId>org.springframework</groupId>
                    <artifactId>spring-web</artifactId>
                </exclusion>
                <exclusion>
                    <groupId>org.springframework</groupId>
                    <artifactId>spring-support</artifactId>
                </exclusion>
                <exclusion>
                    <groupId>org.springframework</groupId>
                    <artifactId>spring-remoting</artifactId>
                </exclusion>
            </exclusions>
        </dependency>
        <dependency>
            <groupId>javax.servlet</groupId>
            <artifactId>servlet-api</artifactId>
            <version>2.4</version>
            <scope>provided</scope>
        </dependency>
        <dependency>
            <groupId>log4j</groupId>
            <artifactId>log4j</artifactId>
            <version>1.2.14</version>
        </dependency>
    </dependencies>
    <build>
        <plugins>
            <plugin>
                <groupId>org.mortbay.jetty</groupId>
                <artifactId>maven-jetty-plugin</artifactId>
                <version>6.1.1</version>
                <configuration>
                    <scanIntervalSeconds>1</scanIntervalSeconds>
                    <contextPath>/blog-acegi</contextPath>
                </configuration>
            </plugin>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-compiler-plugin</artifactId>
                <configuration>
                    <source>1.5</source>
                    <target>1.5</target>
                </configuration>
            </plugin>
        </plugins>
    </build>

</project>

The transitive dependency mechanism of maven2 pulls in a lot of the Spring dependencies because of the Acegi 1.0.3 pom configuration. Because I want to use the latest release of Spring I have excluded them from Acegi. When you fire up jetty:

$ mvn jetty:start

You can view the public and admin page with the url’s http://localhost:8080/blog-acegi/site/public.html and http://localhost:8080/blog-acegi/site/admin.html. Now we will introduce Acegi into the equation. We will secure the admin page with an user/password combination, while the public page may remain unsecured. First we add an Acegi Filter to the web.xml:

	<filter>
		<filter-name>Acegi Filter Chain Proxy</filter-name>
		<filter-class>
			org.acegisecurity.util.FilterToBeanProxy
		</filter-class>
		<init-param>
			<param-name>targetClass</param-name>
			<param-value>
				org.acegisecurity.util.FilterChainProxy
			</param-value>
		</init-param>
	</filter>

	<filter-mapping>
		<filter-name>Acegi Filter Chain Proxy</filter-name>
		<url-pattern>/*</url-pattern>
	</filter-mapping>

The FilterToBeanProxy is configured with a targetClass. Acegi expects an instance of this target class configured in the Spring bean context. We will code the Acegi beans in the Spring context file acegi-security.xml.

As specified in the Acegi Filter we need at least an instance of the FilterChainProxy in the acegi-secutity.xml.

<!DOCTYPE beans PUBLIC "-//SPRING//DTD BEAN//EN" "http://www.springframework.org/dtd/spring-beans.dtd">

<beans>

	<bean id="filterChainProxy"
		class="org.acegisecurity.util.FilterChainProxy">
		<property name="filterInvocationDefinitionSource">
			<value>
				<![CDATA[
                PATTERN_TYPE_APACHE_ANT
                /**=exceptionTranslationFilter,filterInvocationInterceptor,authenticationProcessingFilter
            ]]>
			</value>
		</property>
	</bean>

	<bean id="exceptionTranslationFilter"
		class="org.acegisecurity.ui.ExceptionTranslationFilter">
		<property name="authenticationEntryPoint">
			<bean
				class="org.acegisecurity.ui.webapp.AuthenticationProcessingFilterEntryPoint">
				<property name="loginFormUrl" value="/login.jsp" />
				<property name="forceHttps" value="false" />
			</bean>
		</property>

	</bean>

	<bean id="authenticationProcessingFilter"
		class="org.acegisecurity.ui.webapp.AuthenticationProcessingFilter">
		<property name="authenticationManager"
			ref="authenticationManager" />
		<property name="authenticationFailureUrl"
			value="/login.jsp?login_error=1" />
		<property name="defaultTargetUrl" value="/site/public.html" />
		<property name="filterProcessesUrl"
			value="/j_acegi_security_check" />
	</bean>

	<bean id="filterInvocationInterceptor"
		class="org.acegisecurity.intercept.web.FilterSecurityInterceptor">
		<property name="authenticationManager"
			ref="authenticationManager" />
			<property name="accessDecisionManager">
			<bean class="org.acegisecurity.vote.AffirmativeBased">
				<property name="allowIfAllAbstainDecisions"
					value="false" />
				<property name="decisionVoters">
					<list>
						<bean class="org.acegisecurity.vote.RoleVoter" />
						<bean
							class="org.acegisecurity.vote.AuthenticatedVoter" />
					</list>
				</property>
			</bean>
		</property>
		<property name="objectDefinitionSource">
			<value>
				<![CDATA[
                PATTERN_TYPE_APACHE_ANT
                /site/admin.html=ROLE_ADMIN
            ]]>
			</value>
		</property>
	</bean>

	 <bean id="authenticationManager"
        class="org.acegisecurity.providers.ProviderManager">
        <property name="providers">
            <list>
                <ref local="authenticationProvider" />
            </list>
        </property>
    </bean>

    <bean id="authenticationProvider"
		class="org.acegisecurity.providers.dao.DaoAuthenticationProvider">
        <property name="userDetailsService" ref="userDetailsServiceImpl"/>
	</bean>

    <bean id="userDetailsServiceImpl"
        class="org.acegisecurity.userdetails.memory.InMemoryDaoImpl">
        <property name="userProperties">
            <props>
                <prop key="admin">secret,ROLE_ADMIN</prop>
            </props>
        </property>
    </bean>

</beans>

This rather large xml document configures Acegi to prevent people to see the admin part of the application. The configured beans with some details:

• The filterChainProxy defines all filters that will be called when an user requests a url that matches the Acegi Filter Chain Proxy filter mapping in the web.xml. I have configured 3 filters.
• The exceptionTranslationFilter is responsible for redirecting to the login.jsp in case of a Security Exception. Without this bean our admin page would stil be secured, but the user would get a error stacktrace when trying to access the page without being logged in.
• The authenticationProcessingFilter is responsible for handling the form post in the login.jsp. In case of failure it will redirect to the login page and in case of a successfull login the user will be redirected to the defaultTargetUrl.
• The filterInvocationInterceptor contains the actual configuration of the security restrictions. It uses two acegi decisionVoters that will check the username/password and the role of the user. In this case we limit the access to the url /site/admin.html to users with the role ROLE_ADMIN.
• The authenticationManager is the hook for all authenticationProviders we want to configure. In this example we use only one provider, but you could configure as many as you would like. I have not encountered an usecase yet where this was required.
• The authenticationProvider we use is the one which is provided by Acegi. The retrieving of the user is being delegated to an implementation of the userDetailsService
• The implementation of the userDetailsService we use is the InMemoryDaoImpl which can be configured with a list of users, password and roles. Acegi also provides a JdbcDaoImpl which actually retrieves the users and their roles from the database.

Because auto-formatting the acegi-secutiry.xml file can mess up the ANT like configuration I have coded those parts within CDATA sections. The one thing missing is the login.jsp; the login.jsp needs to be placed in the root of war file. When using maven2 for packaging the war the login.jsp must be placed in the webapp directory.

<%@ taglib prefix='c' uri='http://java.sun.com/jstl/core_rt'%>
<%@ page import="org.acegisecurity.ui.AbstractProcessingFilter"%>
<%@ page
	import="org.acegisecurity.ui.webapp.AuthenticationProcessingFilter"%>
<%@ page import="org.acegisecurity.AuthenticationException"%>

<html>
	<head>
		<title>Login</title>
	</head>

	<body>
	<c:if test="${not empty param.login_error}">
		<font color="red"> Your login attempt was not successful, try
		again.<BR>
		<BR>
		Reason: <%=((AuthenticationException) session
											.getAttribute(AbstractProcessingFilter.ACEGI_SECURITY_LAST_EXCEPTION_KEY))
											.getMessage()%> </font>
	</c:if>

	<form action="<c:url value='j_acegi_security_check'/>" method="POST">

	<center>
		<table align="center" cellpadding="4" cellspacing="0" border="0"
					class="loginform">
			<tr>
				<td bgcolor="f0f0f0" colspan="2">Enter your details below to
					login to admin site:</td>
			</tr>
			<tr />
			<tr>
				<td nowrap align="right" valign="top"><label class="label"><u>U</u>sername:</label></td>
				<td><input type='text' name='j_username' accessKey="U"></td>
			</tr>
			<tr>
				<td nowrap align="right" valign="top"><label class="label"><u>P</u>assword:</label></td>
				<td><input type='password' name='j_password' accessKey="P"></td>
			</tr>

			<tr>
				<td valign="middle" align="center" colspan="2"><input
						id="loginButton" type="submit" value="Log In" /></td>
			</tr>

		</table>
	</center>
	</form>

	</body>
</html>

Again using the jetty plugin we can verify the result. When trying to access the admin page we will be prompted for an username and password and when providing the correct combination we will be forwarded to the admin page. The public page is still accessible for everyone. I have attached the source code of this example. The InMemoryDaoImpl is of course not very sophisticated. In a next blog I’ll show you how to implement your own security provider.

A couple a weeks ago me and some colleagues took a two day course in AOP. The course was given by the excellent teacher Adrian Colyer. In this short blog I want to show you a very nice (not well known) feature of AspectJ and how you can integrate AspectJ in your build using the maven2 plugin.

When you want to play around with AspectJ the first thing you should do is install the AspectJ eclipse plugin. With this plugin you can enable AspectJ support for your project.

Often the use of aspects, beside the obvious usages like security, transactions, and tracing, is frowned upon: too complex, too difficult and where is the world going to. Conservatists! I was one of those people, but in the course Adrian showed us some good real-world usecases where aspects can improve your code. I’ll show you one example (and I hope Adrian won’t mind me using some of his code).

I don’t like code like this:

    //do Something
    System.out.println("Something happened");

Everyone will agree that it is far better to use a logging framework to inform people that something happened.

    //do Something
    if (log.isDebugEnabled()) {
        log.debug("Something happened");
    }

But when doing audits/working on projects I almost always encounter the ‘System.out’ anti-pattern. With AspectJ it is very easy to write an aspect that checks during the build if the code tries to write messages to the console.

/**
 * @author Adrian Colyer
 */
public aspect DontWriteToTheConsole {

	pointcut sysOutOrErrAccess() : get(* System.out) || get(* System.err);

	declare error
	  : sysOutOrErrAccess()
	  : "Don't write to the console";

}

The above pointcut expression detects all attempts to access the public property ‘out’ of the ‘System’ class and generates a compile error (it would probably be better to declare a warning in this specific case, but this is just an example). When you want to check all of your code simply put the aspect in your codebase and add the following dependency to your maven2 pom.xml:

<dependency>
<groupId>aspectj</groupId>
<artifactId>aspectjrt</artifactId>
<version>1.5.2a</version>
</dependency>

The next thing you want to do is add the aspectj-maven-plugin to the build section of your pom.xml:

<plugins>
<plugin>
<groupId>org.codehaus.mojo</groupId>
<artifactId>aspectj-maven-plugin</artifactId>
<executions>
<execution>
<goals>
<goal>compile</goal><!– use this goal to weave all your main classes –>
<goal>test-compile</goal><!– use this goal to weave all your test classes –>
</goals>
</execution>
</executions>
</plugin>
</plugins>

Now when your build your project

$ mvn clean install

the build breaks when you write “Hello World” to the console:

[INFO] ————————————————————————
[ERROR] BUILD ERROR
[INFO] ————————————————————————
[INFO] Compiler errors :
error at System.out.println(“Hello World!”);
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
E:\workspace\play-time\src\main\java\org\harsta\HelloWorld.java:9:0::0 Don’t write to the console
see also: E:\workspace\play-time\src\main\java\org\harsta\DontWriteToTheConsole.aj:18::0

The example is simple, but there are a lot more ways to check if your code is ‘clean’. You could even write a maven2 profile that enables the weaving process only under some circumstances (like the presence of an environment variable).

If you want to read more about AspectJ in combination with Spring 2.0 this article is a good starting point.

I’ll be assuming in this blog that you use Maven2 for building the different parts of your Java application. If this is not the case I advise you to have a look at Maven2. With release 2.0.4 Maven2 has come to a maturity level that I feel I can safely recommend it to customers. Maven2 advocates one artifact for each project. A typical Java application has more than one sub-artifact: several jar files, a web archive and finally an ear file to package the lot. This typical setup is supported by Maven through the use of sub-modules. First you begin with a top level pom.xml where you define all the global configurations of your application. These normally would include things like:

• The groupId.
• The version.
• An ‘issueManagement’ section
• A ‘ciManagement’ section
• Information about the developers
• The configuration of the repositories (local and remote)
• Source Control Management (scm) information
• All the shared dependencies for all modules
• ‘distributionManagement’ section including site information, your local company repository and snapshotRepository

The next thing to configure in your top pom.xml are the sub-modules of your project. The following xml fragment specifies that your application has five sub modules (oh, not the petshop again…):

<modules>
    <module>xebia-petshop-core-jar</module>
    <module>xebia-petshop-util-jar</module>
    <module>xebia-petshop-war</module>
    <module>xebia-petshop-statistices-war</module>
    <module>xebia-petshop-ear</module>
  </modules>

Good descriptive names of your sub-modules, including their artifact type, are always helpful and especially as their number grow. I have found it good practice to have the artifactId of a module equal the name of the module minus the type definition. Following this rule the artifactId name of the xebia-petshop-util-jar module would be xebia-petshop-util resulting in the artifact xebia-petshop-util-0.1-SNAPSHOT.jar. The pom.xml configuration of this sub-module would be something like this:

  <parent>
    <groupId>com.xebia.petshop</groupId>
    <artifactId>xebia-petshop</artifactId>
    <version>0.1-SNAPSHOT</version>
  </parent>
  <artifactId>xebia-petshop-util</artifactId>
  <packaging>jar</packaging>

Looking at the names of the sub-modules it is not too difficult to guess what the content would be. The xebia-petshop-core module has a dependency on the xebia-petshop-util module. The xebia-petshop-war module is dependent on the xebia-petshop-core module (this way the artifact of xebia-petshop-core will end up in the WEB-INF/lib directory of the xebia-petshop-0.1-SNAPSHOT.war. Finally the xebia-petshop-ear is dependent on the two war modules. The final deployable artifact is the xebia-petshop-0.1-SNAPSHOT.ear. I have found it also good practice to have an environment independent deployable artifact. So with this multi-module setup all the tests will be run and the -sub- artifacts will be created and deployed to your local and company repository when issuing the following Maven2 command:

$ mvn clean install deploy

Using the excellent Maven2 release plugin you can perform a release saving a lot of repetitive, manual work like updating the version, tagging the source code and deploying the artifacts to your repository. Now basically here should end your tasks as developer or not? The department or person responsible for deploying the
xebia-petshop-0.1-SNAPSHOT.ear probably needs additional information to succesfully deploy the application. For this reason we introduce a new module:

<module>xebia-petshop-dist</module>

The xebia-petshop-dist module will produce a tar archive including our ear and everything else needed for configuring the target environment. The choice of your application server of course has a significant impact on the required configuration. Let us assume that the IT department has developed a hardened configuration of the open source JBoss server. A hardened configuration of the JBoss server should at least address the following issues:

• Securing the management console.
• Securing the jmx console and jmx invoker.
• Removal of the http invokers.
• Removal of the default HsqDB datasource/database.
• Configuration of the different security domains.
• SSL enabling.
• Removal of the download service.
• Configuration of Log4J.
• Configuration of the clustering capabilities.

It is out-of-scope to discuss in detail how to configure this. Based on a company specific configuration the developers of the xebia-petshop application must specify to the deployer which additional resources the application depends on. Let us assume that the application uses the following environment specific resources:

• A DataSource configured in a xebia-petshop-ds.xml file.
• Environment specific variables for configuring and injecting a Ldap server instance coded in a jndi.properties file.
• SQL create scripts for the database schema and alternatively alter scripts for consecutive releases.

It is a matter of taste where to store these additional configuration files. Basically you will have to choose between the xebia-petshop-dist or xebia-petshop-ear module. Lets choose the second option and configure the pom.xml of the xebia-petshop-dist to use the assembly plug-in of Maven2 to build a tar archive including the ear file and the additional configuration files in order for the deployer to do his work:

 <build>
    <plugins>
      <plugin>
        <artifactId>maven-assembly-plugin</artifactId>
        <executions>
          <execution>
            <goals>
              <goal>attached</goal>
            </goals>
            <phase>package</phase>
          </execution>
        </executions>
        <configuration>
          <descriptor>src/main/assembly/dep.xml</descriptor>
        </configuration>
      </plugin>
   </plugins>
 </build>
 </build>
  <dependencies>
    <dependency>
      <groupId>com.xebia.petshop</groupId>
      <artifactId>xebia-petshop-ear</artifactId>
      <type>ear</type>
    </dependency>
  </dependencies>

The xebia-petshop-ds.xml and the jndi.properties files contains placeholders for the variables that need to be replaced by the deployer.

<datasources>
   <local-tx-datasource>
        <jndi-name>PetshopDS</jndi-name>
        <connection-url>@petshop.jdbc.url@</connection-url>
        <driver-class>com.mysql.jdbc.Driver</driver-class>
        <user-name>@petshop.jdbc.user@</user-name>
        <password>@petshop.jdbc.password@</password>
    </local-tx-datasource>
</datasources>

One additional file is necessary to include in our final archive: a README.html file that sums up the content of the archive and contains a list of all placeholders that need to replaced by the deployment team. The assembly plugin source file ‘dep.xml’ sums up all the content to be placed in the final archive.

<?xml version="1.0"?>
<assembly>
  <id>bin</id>
  <formats>
    <format>tar.gz</format>
  </formats>
  <fileSets>
    <fileSet>
      <directory>src/main/html/</directory>
      <outputDirectory>/</outputDirectory>
      <includes>
        <include>README.html</include>
      </includes>
    </fileSet>
    <fileSet>
      <directory>../xebia-petshop-ear/src/jboss4x/deploy</directory>
      <outputDirectory>jboss/deploy</outputDirectory>
      <includes>
        <include>**/*.*</include>
      </includes>
    </fileSet>
    <fileSet>
      <directory>../xebia-petshop-ear/src/jboss4x/conf</directory>
      <outputDirectory>jboss/conf</outputDirectory>
      <includes>
        <include>**/*.*</include>
      </includes>
    </fileSet>
    <fileSet>
      <directory>../xebia-petshop-ear/src/main/sql</directory>
      <outputDirectory>db</outputDirectory>
      <includes>
        <include>**/*.*</include>
      </includes>
    </fileSet>
  </fileSets>
  <dependencySets>
    <dependencySet>
      <outputDirectory>/</outputDirectory>
      <unpack>false</unpack>
      <scope>runtime</scope>
    </dependencySet>
  </dependencySets>
</assembly>

When the xebia-petshop-dist module is installed the xebia-petshop-dist-0.1-SNAPSHOT-bin.tar.gz will be uploaded to your local company maven2 repository where the deployer can pick it up and actually start his/their deployment procedure. One could even use the docbook plugin of Maven2 to generate the README.html based on a docbook xml source file.

Having an ‘dist’ module in your Maven2 project structure that uses the assembly plugin to archive all necessary resources and artifacts is a good step to a more controlled and automated release procedure.

Applications often need resources like databases, third-company web services, ldap servers and other external systems. It is common practice to externalize the configuration of such resources. In the case of a database dependency the use of a DataSource (hiding the complexity of configuring and connecting to the database) is a good example of this. The details of the configuration are in most cases platform environment specific. So how do we properly externalize the details of the configuration?

Basically the development team has two options:

• Build an application and specify the target environment
• Externalize the variables from the deployable unit

I have seen many development teams using the first option. They use ant, maven or maven2 to build their java application and they use a command parameter to specify the target environment of the build. It usually looks something like this:

$ ant install -Denv=test

or in the case of maven2 using profiles:

$ mvn -P test clean install

There are numerous ways to accomplish this using properties files, xml descriptors, filtering etc. The end result is a deployable unit that can only be deployed in the environment it was built for. I don’t like this approach. It is better to have a deployable unit that can be deployed in any environment. This is mainly because the deployment of an application should not be the responsibility of developers. It is the responsibility of the maintenance department and the environment specific variables should be part of the environment and not of the application. The final argument is that developers often have no knowledge about the acceptance or production environmental resources. For instance, how can they possibly know the username/password of the production database? So how do we make the deployable unit independent of the target environment?

First it requires that we don’t hardcode any environment specific values in the codebase. This is, apart from the problem we are dealing with, always a good practice. So we use properties files or even better (when using Spring, and you should!) we use placeholders in our application context files. An example: we are using an LDAP server to authenticate our users in combination with the excellent Acegi framework. Let us assume we have a test LDAP server and a production LDAP server.

<bean id="initialDirContextFactory" class="org.acegisecurity.ldap.DefaultInitialDirContextFactory">
   <constructor-arg index="0" value="${ldap_address}"/>
</bean>

Spring already has support for resolving placeholders like ${ldap_address} during the runtime initialization of the bean factory. Simply define a PropertyPlaceholderConfigurer in your application context file that uses a properties file for pulling values into bean definitions. However the problem with that approach is that you have to wire the PropertyPlaceholderConfigurer with the location of the properties file. The developer can not make assumptions about the location of the properties file nor is it wise to do so. It would be nice if we had a generic way of wiring a PropertyPlaceholderConfigurer with the correct values. Enter Jndi! If you would have a generic hook to populate the environment of the InitialContext with the values of the placeholders then we could use the Jndi Context to lookup and resolve the specific placeholders. Most application servers have such a hook and I will show how to do this with the excellent JBoss application server.

Using the jndi.properties file in the conf directory of your server configuration you can easily pass the platform environment specific values to the InitialContext. You don’t have to hardcode an absolute or relative path into your PropertyPlaceholderConfigurer if you use the jndi.properties file. Continuing our example we would need the following key-value entry for our initialDirContextFactory bean:

ldap_address=ldap://organization.intra.local.test

Add this key-value pair to the jndi.properties file located in the conf directory of your JBoss server configuration and use a customized PropertyPlaceholderConfigurer to resolve your placeholders:

public class JndiPlaceholderConfigurer extends PropertyPlaceholderConfigurer  implements InitializingBean {
    private Map environment;
    public void afterPropertiesSet() throws Exception {
        Context context = new InitialContext();
        environment = context.getEnvironment();
    }
    protected String resolvePlaceholder(String placeholder, Properties props) {
        return (String) this.environment.get(placeholder);
    }
}

With one line of xml code in one of your spring bean definitions files the post-processing of the BeanFactory initialization will take care of resolving the placeholders:

<bean id="propertyConfigurer" class="xxx.xxx.JndiPlaceholderConfigurer"/>

Of course you need a proper procedure set up for communicating the environment specific variables your application depends on to the person/department responsible for deploying the application. Currently I’m looking at the Assembly plugin for Maven 2 to automate the process of delivering more than just the deployable application unit to the people responsible for deploying applications. In my next blog I will elaborate more on the assembly plugin and how to make sure that the application server configuration meets the demands of your application.