A little bit of background: Since we have established, we had used Email in combination with an internal JIRA system. While this setup worked well with moving support issues to our development JIRA, the communication between us and our customers was hard. Especially our customers were not able to see the status of their request.

The new, Zendesk-based solution provide much better service to our customers: Filing requests through web UI and Email, and status-review through the web UI. Also, it provides forums, which allows you to participate in discussions about our product. There are a few neat features, but the key feature which eventually convinced us to switch to Zendesk is the integration with JIRA, which lets us copy support requests into JIRA and keep the support request and issue in sync.

In this post I describe how to create doc/literal-style Web Services for Confluence using XFire.

Why do you want to do that?

There are two alternatives. Confluence provides the web service plugin module, which offer good support for rpc-style services. However, these don’t work well with some clients, as some platforms do not support rpc-style web services.

Instead of using web services REST might be an alternative. Since Confluence 3.1. there is a plugin module type for REST interfaces, which builds the JAX-WS reference implementation called Jersey. Btw, the REST plugin module type also work on Confluence 3.0, but you will have to install some plugins manually. While REST is certainly the way to go for future developments, it has the same short coming as RPC-style web services: client platforms may not be able to use it (or at least make it hard to use it).

In my case the doc-literal web service client is InfoPath (part of Microsoft Office), which works allows users to edit pages in a office-style application and better keeps the structure of a page than the Word editor.

Overview

XFire is a quite old project and is actually now maintained/developed as CXF at Apache. However, there are three reasons for using XFire: XFire is included in the Confluence distribution, CXF still has some dependencies to XFire and introducing another library doesn’t make things easier (believe me I tried).

In order to use XFire we need to setup the dependencies correctly, create and deploy a XFireServlet as a servlet module, which handles the HTTP request and invokes the XFire web service stack.

POM Configuration

It is not possible to import the XFire packages through OSGi Bundle-Instructions (Atlassian does not expose it to plugins for whatever reason), so it is necessary define XFire as a dependencies. On the other hand it is necessary to exclude all unneeded or conflicting dependendencies of XFire. I added the following dependencies to the default dependency section:

<dependency>
    <groupId>org.codehaus.xfire</groupId>
    <artifactId>xfire-aegis</artifactId>
    <version>1.2.6</version>
</dependency>
<dependency>
    <groupId>org.codehaus.xfire</groupId>
    <artifactId>xfire-java5</artifactId>
    <version>1.2.6</version>
    <exclusions>
        <exclusion>
            <groupId>org.codehaus.xfire</groupId>
            <artifactId>xfire-annotations</artifactId>
        </exclusion>
        <exclusion>
            <groupId>xfire</groupId>
            <artifactId>xfire-jsr181-api</artifactId>
        </exclusion>
    </exclusions>
</dependency>
<dependency>
    <groupId>org.codehaus.xfire</groupId>
    <artifactId>xfire-core</artifactId>
    <version>1.2.6</version>
    <exclusions>
        <exclusion>
            <groupId>javax.activation</groupId>
            <artifactId>activation</artifactId>
        </exclusion>
        <exclusion>
            <groupId>javax.mail</groupId>
            <artifactId>mail</artifactId>
        </exclusion>
        <exclusion>
            <groupId>jaxen</groupId>
            <artifactId>jaxen</artifactId>
        </exclusion>
        <exclusion>
            <groupId>stax</groupId>
            <artifactId>stax-api</artifactId>
        </exclusion>
        <exclusion>
            <groupId>commons-codec</groupId>
            <artifactId>commons-codec</artifactId>
        </exclusion>
        <exclusion>
            <groupId>org.apache.ws.commons</groupId>
            <artifactId>XmlSchema</artifactId>
        </exclusion>
        <exclusion>
            <groupId>org.codehaus.woodstox</groupId>
            <artifactId>wstx-asl</artifactId>
        </exclusion>
        <exclusion>
            <groupId>commons-logging</groupId>
            <artifactId>commons-logging</artifactId>
        </exclusion>
        <exclusion>
            <groupId>commons-httpclient</groupId>
            <artifactId>commons-httpclient</artifactId>
        </exclusion>
    </exclusions>
</dependency>

The XFire-Servlet

The XFire-Servlet handles HTTP Requests and invokes the XFire web service stack, which in turn hands over the web service call to our service implementation. Therefore the servlet initializes the service in the servlets init() method (when trying this yourself, please not that the init() method gets called lazily on first access).

public class MyXfireServlet extends XFireServlet {

    public void init() throws ServletException {
        super.init();

        // The ObjectServiceFactory creates services from Java objects
        ObjectServiceFactory factory = new ObjectServiceFactory(getXFire().getTransportManager(), null);

        // we don't want to expose compareTo
        factory.addIgnoredMethods("java.lang.Comparable");
        Service service = factory.create(DokumentService.class, "dokument", null, null);
        service.setProperty(ObjectInvoker.SERVICE_IMPL_CLASS, DokumentServiceImpl.class);

        // unregister old Service
        Service oldService = getServiceRegistry().getService("dokument");
        if(oldService != null) {
            getServiceRegistry().unregister(oldService);
        }

        getServiceRegistry().register(service);
    }

    protected ServiceRegistry getServiceRegistry() throws ServletException {
        return getController().getServiceRegistry();
    }
}

To register the service the following is needed in Atlassian XML:

<servlet name="Form Editor Servlet" key="com.k15t.example"
    class="com.k15t.example.webservice.XfireServlet">
  <url-pattern>/xfire/*</url-pattern>
</servlet>

This will make the XfireServlet to be available at http://localhost:1990/confluence/plugins/servlet/xfire/ (replace the hostname, port and context root and note the trailing slash). It will list the available services including a link to retrieve the WSDL for the service. In our case there is one service called “dokument”.

Implementing the Service

As you can see above the service is defined in the interface DokumentService and the implementation is implemented in DokumentServiceImpl. XFire will take care of converting the SOAP message to method parameters, if the service interface only uses the following types (source):

• Basic types: int, double, float, long, byte[], short, String, BigDecimal
• Arrays
• Collections
• Dates: java.util.Date, java.util.Calendar, java.sql.Timestamp, java.sql.Date, java.sql.Time
• XML: org.w3c.dom.Docmument, org.jdom.Element, XMLStreamReader, Source
• Complex types which are aggregations of the above

This is the interface of the service, the implementation is calling the Confluence API to do stuff (Dokument is a complex bean containing some page data):

public interface DokumentService {

    public Dokument load(String spaceName, String pageId, String token);

    public void save(Dokument document, String token);

}

That’s all.

It is important to notice, that the ServiceRegistry is shared between different XFireServlets, so take care if you install multiple of those.

Scroll 1.1.1 fixes a few bugs and brings some improvements. For further information please have a look at the changelog.

The Scroll Wiki Exporter lets you do this - it turns your Confluence wiki into the source for single source publishing.

In contrast to Confluence’s built-in export functionality, Scroll builds a semantic model from the wiki pages. From there it produces various output formats (currently DocBook and PDF). Also, it separates content from representation. That way an export can be themed in many ways.

Scroll 1.1 comes with two exciting new features:

• Pluggable and Configurable Themes: Space administrators can now configure their own themes - for example they can define TOC generation, header and title page images, and many more with a few clicks. If more customization is needed Scroll supports so-called theme plugins, which are based on the DocBook XSL stylesheets.
• RenderX XEP is now embedded as PDF Rendering Engine: XEP is one of the world’s leading rendering engines for PDF, Postscript and other formats. With RenderX XEP Scroll will be capable of rendering high-quality output for printing books, brochures, etc. Given that fact, we are happy that Scroll with XEP embedded still comes at a very reasonable price.

Scroll 1.1 is available through the plugin repository (as a Confluence Admin go to Confluence Admin > Configuration > Plugin Repository and search for Scroll). For manual download and installation it is available at the Atlassian Plugin Exchange.

The complete list of feature and improvements can be found in the Scroll 1.1 release notes.

For more information about Scroll please visit our website (http://www.k15t.com/scroll) or watch the recorded webinar from November 5 at the Atlassian News Site (http://blogs.atlassian.com/news/2009/11/video_scroll_wiki_exporter_plugin_for_confluence.html).

About K15t Software
K15t Software develops single source publishing and documentation solutions based on new, collaborative technologies (also known as “Web 2.0″). Its flagship product is the Scroll Wiki Exporter for Confluence a single source publishing solution for Atlassian Confluence.

(In case you cannot watch this video due to firewall issues let us know, we can provide a downloadable version.)

Also, this is a good time to follow us on Twitter.

From the announcement:

Next week we are hosting a webinar with K15t Software who are presenting the Scroll Wiki Exporter Plugin for Confluence.

This plugin allows you to create professional documentation from Confluence pages. This is a an absolute must-see webinar for anyone who likes to export documents or print from the content within Confluence. I can imagine anyone writing a book, students, technical documentation writers, or trainers would greatly benefit from this type of functionality.

REGISTER NOW: Thu, Nov 5, 2009 9:00 AM - 10:00 AM PST

Don’t miss it!

For more information about the Confluence Community Day visit http://www.communardo.de/techblog/confluence_community_day_2009/.

• Stefan Kleineikenscheidt, founder of K15t Software, will be on the commercial plugin panel on Oct 21 at 3pm at AtlasCamp 09 in Half Moon Bay (near San Francisco) representing K15t and Scroll.
• Tobias Anstett, will be presenting our vision of Documentation 2.0 with Confluence at the Confluence Community Day 2009 (Oct 29, 2009) in Frankfurt, Germany.

Some of the benefits of our office: We share our office with architects, graphic and product designers and others, who have created a super-stylish office. We have a lot of pubs, bars, restaurants just around the corner. There is an original Italian coffee machine in our kitchen.

Our new address:

When you are in Stuttgart, don’t forget to stop by for an espresso.

• Basic Support for Scaffolding Plugin
• Compatibility with Confluence 3.0
• Greatly improved performance for big exports using the Scroll Documentation theme.
• Scroll now comes with its own distribution of Apache FOP, which provides better support for links.