SBT and DocBook

As part of our Specs2 Spring project, we wanted to ensure users had access to Spec2 Spring’s documentation in a format they know and love, we figured we’d use DocBook, the multiformat-generating, markup language.

Fortunately a SBT plugin currently exists for DocBook, however it currently doesn’t have a few features we need.

We have forked the SBT DocBook plugin, because we needed to add support for XInclude, syntax highlighting, ePUB and many other improvements. Find it here.

The Setup

Using it is pretty straight-forward. You should have a directory structure similar to this:

MyProject
  build.sbt
  src/
    main/
      java/
      scala/
      docbook/
        main.xml
        chapter1.xml
        ...
  project/
    plugins.sbt

Simply ensure all DocBook files are in the src/main/docbook directory. Note that if you have multiple DocBook files, the main file must be named main.xml. On the other hand, if there is just one file, feel free to name it anything you like.

Include the plugin in your project/plugins.sbt file as follows:

resolvers += ScalaToolsSnapshots

addSbtPlugin("de.undercouch" % "sbt-docbook-plugin" % "0.2-SNAPSHOT")

That’s it!

Run it!

Generating documents in the format of your choice is pretty easy:


$ sbt html



$ sbt pdf



$ sbt xhtml



$ sbt manpage



$ sbt eclipse-help


Checkout the readme for more options.

How have we done it?

Robust documentation is key to getting the community interested and involved in any project and modular documentation is key to the sanity of the project developers. An easy way to produce modular documentation is by using XInclude, sadly the plugin it uses, Saxon 6.5.3, for processing XSLT, cannot handle XInclude.

After extensive googling & hacking, I eventually turned to Xerces2 to resolve XInclude. The code looks a little something like this:

   private def transformDocBook(src: File, dst: File, styleSheet: String,
  cp: Classpath, log: Logger) {
    transform(src, dst, log) {
      //write output to temporary file. this avoids a bug in Saxon
      //that caused spaces in the output filename to be converted to
      //an escaped sequence (%20)
      val temp = File.createTempFile("sbt-docbook-plugin-", ".fo")
      val code = Fork.java(None, Seq[String](
      "-cp", cp.files.mkString(File.pathSeparator),
      "-Djavax.xml.parsers.DocumentBuilderFactory="+
        "org.apache.xerces.jaxp.DocumentBuilderFactoryImpl",
      "-Djavax.xml.parsers.SAXParserFactory=" +
        "org.apache.xerces.jaxp.SAXParserFactoryImpl",
      "-Dorg.apache.xerces.xni.parser.XMLParserConfiguration=" +
        "org.apache.xerces.parsers.XIncludeParserConfiguration",
      "com.icl.saxon.StyleSheet",
      "-o", temp.toString,
        src.toString, styleSheet
      ), log)

      //copy temporary file to real output file
      temp #> dst !

      //delete temporary file (if this files it will be deleted on exit)
      if (!temp.delete()) {
        temp.deleteOnExit()
      }
      code
    }
  }

So what’s going on here? Well Fork.java makes it possible for us to run a separate java process, "-cp" sets up it’s classpath, cp.files.mkString(File.pathSeparator) ensures that the correct path separator is used for your file system, the first 2 -D options set Xerces as Saxon’s xml parser, the last -D option turns on the XInclude feature and -o set’s Saxon’s output file or directory!

Maintaining Specs2 Spring and any other documentation has been made a little easier!

The next focus will be on improving the plugin’s output for documentation split into multiple files, in particular EPUB..

It’s always good talking about jQuery as it’s relatively straight forward for the audience to read and has a shallow learning curve (if you know CSS already). One of the other pleasures talking about jQuery, and other front end tech, is that you can always show interactive demos to “wow” the audience…

Here are my slides followed by a link to my demo code:

I brought some of my demo code up to date showing examples using the live, event delegation functionality with jQuery. You can view my demo here or download it zipped here.

If you have any queries about the above or want assist you in a jQuery, Javascript and AJAX project contact us.

Spring Integration

Jonas Partner from OpenCredo also gave a presentation on the evening on Spring Integration. His slides are below:

interface AsyncWorker {
    <T> T invoke(T t);
    <T> T invoke(T t, int maxWait);
    <T> InvocationIdentity execute(T t, AsyncCallback callback);
}

The implementation of the AsyncWorker will be flexible enough to use simple heap, JMS or database queues to store the invocations and the API is very easy to start using in your existing projects. For example, if you wanted to turn a synchronous call into asynchronous one with as little coding as possible, you’d write

@Controller
class ExistingController {
    private SomeService someService;
    private AsyncWorker asyncWorker;

    @RequestMapping(...)
    public void index() {
        // this.someService.doWork(1, 2, "hello");     #A
        this.asyncWorker.invoke(this.someService).     #B
            doWork(1, 2, "hello");
    }
}

That should be it! Instead of synchronous call on line #A, you will use the AsyncWorker on line #B. The AsyncWorker will queue the invocation of the doWork method of SomeService and will return immediately. Because of the asynchronous nature of the call, the value returned from the method call will be default for the return type (0 for int, long, 0.0 for double, float, null for object reference, etc.).
The alternatives, as you can guess, are using the invoke(T, int) method, which will also invoke any method of T asynchronously, but will wait up to the specified timespan before returning. If the invoked method completes within the specified timespan, the returned value will be valid, otherwise it will be the default value.
Finally, you can use the execute method to schedule the asynchronous call — this gives you the highest degree of control and you will get an InvocationIdentity object back. You will be able to use the returned InvocationIdentity to monitor the progress of the call.

Call for comments

If you think this is a good idea, please comment and add any features you’d find useful. We will be releasing this project under the Open Source Central under Apache Licence.

Let’s see how to enable this functionality with Acegi Security.

Firstly, add org.acegisecurity.concurrent.SessionRegistry implementation bean to your security context:

<bean id="sessionRegistry" class="org.acegisecurity.concurrent.SessionRegistryImpl" />

We are using default Acegi implementation org.acegisecurity.concurrent.SessionRegistryImpl.

Next, define the org.acegisecurity.concurrent.SessionController bean:

    <bean id="sessionController" class="org.acegisecurity.
           concurrent.ConcurrentSessionControllerImpl">
        <property name="exceptionIfMaximumExceeded" value="true"/>
        <property name="maximumSessions" value="1" />
        <property name="sessionRegistry" ref="sessionRegistry"/>
    </bean>

As you can see, it takes sessionRegistry property, as well as two additional properties maximumSessions and exceptionIfMAximumExceeded.
maximumSessions says how meny concurrent login sessions are allowed (in our case just one)
if exceptionIfMAximumExceeded property is set to true, exception will be thrown every time the user tries to login concurrently. You can check this exception in your login controller and display user with a message.
Otherwise, if exceptionIfMAximumExceeded property is set to false, exception will NOT be thrown. If user tries to login concurrently, he will be allowed, but his last login session (before the concurrent one) will be invalidated.

Last step is to add sessionController property to your ProviderManager bean:

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

And you’re ready to run.

Some users have encountered problems with concurrent logins: If a user logs out, and then tries to log in again, the ConcurrentLoginException is thrown, so user cannot log in again. This happens when Acegi logout does not remove the session data for the user that has been logout out (before his login session has expired)
In order to fix this, you can manually clear the authentication session for the user that’s logged out:

public void logout() {
        SecurityContext context = SecurityContextHolder.getContext();
        if (context == null) return;
        Authentication authentication = context.getAuthentication();
        if (authentication == null) return;
        String sessionId = SessionRegistryUtils.obtainSessionIdFromAuthentication(authentication);
        this.sessionRegistry.removeSessionInformation(sessionId);
}

You will also need this code to be run when Acegi session gets unpublished.
For this implement org.acegisecurity.ui.session.HttpSessionEventPublisher, and configure listener for it in your web.xml:

public class MyHttpSessionEventPublisher extends HttpSessionEventPublisher {
    private static final Log logger = LogFactory.getLog(MyHttpSessionEventPublisher.class);
    private UserContext userContext;

    public void sessionDestroyed(HttpSessionEvent event) {
        logger.info("unpublishing session");
        if (userContext == null) {
            this.userContext = lookupBean(
                        WebApplicationContextUtils.
                             getWebApplicationContext(
                              event.getSession().getServletContext()),
                       "userContext",
                       UserContext.class);
        }

        this.userContext.invalidate();
        super.sessionDestroyed(event);
    }

    private  T lookupBean(final ApplicationContext applicationContext, final String beanName, final Class c) {
        //noinspection unchecked
        return (T) applicationContext.getBean(beanName, c);
    }
}

In web.xml you will have:

<listener>
        <listener-class>net.cakesolutions.service.security.acegi.BimHttpSessionEventPublisher</listener-class>
</listener>

And you’re ready to go.

Hope this article has helped anyone in configuring concurrent logins with Acegi Security.