I do want to stress that this is an idea I have about how this can be implemented. I did try it out, but do not consider this as a best practise (yet). See it as inspiration to your own extensions and maybe Hippo will contain something like this in the future.

The idea behind this post came from talks with Allard and Jeroen Reijn, who will write a blog post about a specific part of the solution as I will describe in the post later on.

The problem

Let me start by describing the reason why I wanted a solution like this. For a project we are doing, we want the content of the repository to be available in a Solr instance. Yes I know Hippo comes with Lucene out of the box, but we have have chosen to use solr. The reason behind this is not important for the scope of this blog post. Because of this we need to have information about content in the repository. Of course there are multiple mechanisms available to do this. I have blogged before about repository listeners. There is a big disadvantage with these listeners, they are not part of the repository. They are part of a client that connect to the repository. These listeners are also very low level, they respond to nodes being added or changed. We are more interested in the business events that take place. An example would be the publication of a document. We want to integrate with the workflow in the cms/repository.

Jeroen showed me a way this could be done with hippo 7 using a Daemon module.

The design

The following image gives an overview of the design for the solution.

Let’s start with the WorkflowEventDaemon, this is a class that get’s instantiated by hippo during initialization of the repository. This daemon queries the repository for nodes of type cust:workflowevent. These nodes contain a reference to the implemented EventListeners. The daemon uses these nodes to register event listeners with the EventManager. Next up are the workflow implementations. Currently the provided workflows do not raise events. Luckily it is fairly easy to extend these workflows so they do create the events. The workflow implementations use EventDispatcher instances to actually send an event to the EventManager. Using these events, the EventManager will call the listeners.

That is the basic idea about the solution, let’s focus on the implementation now.

The implementation

Node type defintion

First we need to tell the repository about the new type. This is done using CND file. The file looks like this.

<'cust'='http://www.gridshore.nl/cust/1.0'>
<'hippostd'='http://www.hippoecm.org/hippostd/nt/1.2'>
<'hippo'='http://www.hippoecm.org/nt/1.2'>
[cust:workflowevent]
- cust:class (String)

Hippo has created a mechanism to load nodes into the repository during startup. If you provide a file with the name hippoecm-extension.xml, hippo picks it up and puts these nodes in the repository. To load the CND file we add the following configuration

<?xml version="1.0" encoding="UTF-8"?>
<sv:node xmlns:sv="http://www.jcp.org/jcr/sv/1.0" sv:name="hippo:initialize">
    <sv:property sv:name="jcr:primaryType" sv:type="Name">
        <sv:value>hippo:initializefolder</sv:value>
    </sv:property>

    <sv:node sv:name="cust">
        <sv:property sv:name="jcr:primaryType" sv:type="Name">
            <sv:value>hippo:initializeitem</sv:value>
        </sv:property>
        <sv:property sv:name="hippo:sequence" sv:type="Double">
            <sv:value>10009</sv:value>
        </sv:property>
        <sv:property sv:name="hippo:namespace" sv:type="String">
            <sv:value>http://www.gridshore.nl/cust/1.0</sv:value>
        </sv:property>
        <sv:property sv:name="hippo:nodetypesresource" sv:type="String">
            <sv:value>cust-types.cnd</sv:value>
        </sv:property>
    </sv:node>
</sv:node>

WorkflowEventListener

If you are interested in WorkflowEvents, you need to register a listener. Configuration of these listeners is done in the repository. We can add a node during startup. This is done by adding the following configuration to the hippo-extension.xml file.

    <sv:node sv:name="content-workflowevents">
        <sv:property sv:name="jcr:primaryType" sv:type="Name">
            <sv:value>hippo:initializeitem</sv:value>
        </sv:property>
        <sv:property sv:name="hippo:sequence" sv:type="Double">
            <sv:value>10500</sv:value>
        </sv:property>
        <sv:property sv:name="hippo:contentresource" sv:type="String">
            <sv:value>workflowevents.xml</sv:value>
        </sv:property>
        <sv:property sv:name="hippo:contentroot" sv:type="String">
            <sv:value>/content</sv:value>
        </sv:property>
    </sv:node>

This references the workflowsevents.xml file. The following code shows this file that actually contains a node of type cust:workflowevent containing a reference to a very easy Logging implementation of the WorkflowEventListener interface

<?xml version="1.0" encoding="UTF-8"?>
<sv:node sv:name="workflowevents" xmlns:sv="http://www.jcp.org/jcr/sv/1.0">
    <sv:property sv:name="jcr:primaryType" sv:type="Name">
        <sv:value>hippostd:folder</sv:value>
    </sv:property>
    <sv:property sv:name="jcr:mixinTypes" sv:type="Name">
        <sv:value>hippo:harddocument</sv:value>
    </sv:property>

    <sv:node sv:name="Logging Listener">
        <sv:property sv:name="jcr:primaryType" sv:type="Name">
            <sv:value>cust:workflowevent</sv:value>
        </sv:property>
        <sv:property sv:name="cust:class" sv:type="String">
            <sv:value>nl.gridshore.addons.events.impl.LoggerWorkflowEventListener</sv:value>
        </sv:property>
    </sv:node>
</sv:node>

Now we have the nodes in the repository that daemon queries for. So let’s have a look at the daemon.

The daemon

Now we have come to the part where Jeroen helped me out. It turns out that hippo looks on it’s classpath for all MANIFEST.MF files. If such a file contains an entry for the property Hippo-Modules, hippo expects a space delimited number of classes that are implementations of the DeamonModule interface. If you are using maven, this is very easy to accomplish using the jar plugin.

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-jar-plugin</artifactId>
    <configuration>
        <archive>
            <manifestEntries>
                <Hippo-Modules>nl.gridshore.hippo.addons.deamon.WorkflowEventDeamon</Hippo-Modules>
            </manifestEntries>
        </archive>
    </configuration>
</plugin>

The daemon itself contains three parts

• Query the repository for registered WorkflowEventListeners
• Instantiate each listener using reflection
• Register each listener with the EventManager

The following code block shows the complete implementation of the daemon. I hope the code is clear enough.

public class WorkflowEventDeamon implements DaemonModule {
    private Session session;

    public void initialize(Session session) throws RepositoryException {
        this.session = session;

        NodeIterator nodes = obtainRegisteredWorkflowEventListeners(session);
        while (nodes.hasNext()) {
            Node node = nodes.nextNode();
            Property property = node.getProperty("cust:class");

            WorkflowEventListener listener = constructListener(property.getString());
            if (listener != null) {
                EventManager.getInstance().addWorkflowEventListener(listener);
            }
        }
    }

    private NodeIterator obtainRegisteredWorkflowEventListeners(Session session) throws RepositoryException {
        QueryManager queryManager = session.getWorkspace().getQueryManager();
        Query query = queryManager.createQuery("select * from cust:workflowevent", Query.SQL);
        QueryResult queryResult = query.execute();
        return queryResult.getNodes();
    }

    private WorkflowEventListener constructListener(String className) {
        WorkflowEventListener listener = null;
        try {
            Class clazz = this.getClass().getClassLoader().loadClass(className);
            listener = (WorkflowEventListener) clazz.getConstructor().newInstance();
        } catch (ClassNotFoundException e) {
            logger.error("FATAL error when loading listener class : class not found",e);
        } catch (NoSuchMethodException e) {
            logger.error("FATAL error when loading listener class : no such method",e);
        } catch (IllegalAccessException e) {
            logger.error("FATAL error when loading listener class : illegal access",e);
        } catch (InvocationTargetException e) {
            logger.error("FATAL error when loading listener class : invocation target",e);
        } catch (InstantiationException e) {
            logger.error("FATAL error when loading listener class : instantiation",e);
        }
        return listener;
    }

    public void shutdown() {
        session.logout();
    }
}

The EventManager

The implementation of the EventManager is pretty straightforward. It contains a method to register listeners and a method to add an event. The following code block shows the implementation.

public class EventManager {
    private final static EventManager eventManager = new EventManager();
    private final Set<WorkflowEventListener> eventListeners = Collections.synchronizedSet(new HashSet<WorkflowEventListener>());

    private EventManager() {}

    public void addEvent(WorkflowEvent workflowEvent) {
        for (WorkflowEventListener workflowEventListener : eventListeners) {
            workflowEventListener.handleEvent(workflowEvent);
        }
    }

    public void addWorkflowEventListener(WorkflowEventListener workflowEventListener) {
        eventListeners.add(workflowEventListener);
    }

    public static EventManager getInstance() {
        return eventManager;
    }
}

Dispatching events

I already mentioned I want to dispatch events from workflow components. It is a bit out of scope of this blog item to discuss workflows in Hippo very detailed. To be honest, I would not be the right person to do that. Still I want to give you a very short introduction.

The default workflow for promoting content from draft into publication is the Reviewed actions workflow. This workflow is provided in the default installation. Workflow items in here define what needs to happen when an author opens a document in edit mode or when an editor can do. These kind of workflow items are initiated by the frontend plugins. These plugins are wicket components that put a save and cancel button on the screen. In this blog item I’ll describe the way to extend such a workflow and how to configure the repository/cms to use our custom workflow item.

Let’s start with the custom workflow item

public class CustomBasicReviewedActionsWorkflowImpl extends BasicReviewedActionsWorkflowImpl
        implements BasicReviewedActionsWorkflow {
    public CustomBasicReviewedActionsWorkflowImpl() throws RemoteException {
        super();
    }

    public void publish(Date date) throws WorkflowException, MappingException, RepositoryException, RemoteException {
        super.publish(date);
        EventManager.getInstance().addEvent(new WorkflowEvent("This is my first workflow event from the publish"));
    }

    public void commitEditableInstance() throws WorkflowException {
        super.commitEditableInstance();
        EventManager.getInstance().addEvent(new WorkflowEvent("This is my first workflow event from the commit editable instance"));
    }
}

The workflow items are configured in the repository in the following path
/hippo:configuration/hippo:workflows/. For the specific BasicReviewedActionsWorkflow we need to change two locations. In the following two locations we need to change the property hippo:classname:

• /hippo:configuration/hippo:workflows/default/authorreviewedactions
• /hippo:configuration/hippo:workflows/editing/reviewedactions

There is one thing left to do, hippo uses jpox to enrich the worklfow. This enriching needs to be done using the jpox maven plugin. The following code block gives an example:

            <plugin>
                <groupId>jpox</groupId>
                <artifactId>jpox-maven-plugin</artifactId>
                <version>1.2.0-beta-2</version>
                <configuration>
                    <verbose>false</verbose>
                </configuration>
                <executions>
                    <execution>
                        <phase>compile</phase>
                        <goals>
                            <goal>enhance</goal>
                        </goals>
                    </execution>
                </executions>
            </plugin>

That is about it, if you fire up your repository and cms, and you change the properties as mentioned above, the workflow items should be sending events when someone saves and closes a document.

Hope this helped in you exploration of hippo workflows.

References

• http://www.onehippo.org/cms7//delve_into/custom/reference/repository/workflow.html
• Blog Jeroen for more information about the DaemonModule

For this article I have made use of the hippo 6 version. Things might change a lot when you are dealing with hippo 7. Starting release 7, hippo is fully compliant with the Java Content Repository API.

Continue reading if you want to learn about how to integrate hippo 6 with springframework.

Before jumping into the code, let’s have a look at the general architecture of the application:

There are two front end applications. You can use the hippo cms to create content and configure your repository. This is usually not a front end normal visitors will see. For Hippo 7, the cms is completely rewritten. And to be honest, they did that for a good reason. But that is not what this article is about, so that is the last thing I have said about it.

The other front end application is the “frontend application” . This is the actual spring framework application. Here you can find the base architecture for a pretty standard spring mvc application. For completeness, I’ll give you an overview for that as well.

The design contains the usual layers: interaction (web and import), business, dao, domain and common. To completely separate the hippo stuff, I have moved them into an extra integration layer. This layer embeds the hippo api. This is also the module I’ll focus on. Next to that I will also show some samples of a HippoDao class and most of all the abstract parent for all hippo data access classes.

Let’s start with the integration module, there is one class that is the interface to the hippo repository. Let’s call the interface the content connector and the the actual implementation the HippoContentConnector. To be able to connect to the repository, we have the availability of the hippo api. There are some components that we need to use to connect to hippo.

• nl.hippo.client.webdav.service.WebdavServiceImpl – implementation that actually does the communication with the repository using the webdav functionality.
• nl.hippo.client.event.service.UpdateNotificationServiceImpl – This service is used by the api to invalidate it’s cache. It gets messages via jms with information about updated repository items.
• nl.hippo.client.caching.service.CachingServiceImpl – As the name says, this is all about caching. It is used by the webdav service to determine if an item should be obtained from the repository or not.
• nl.hippo.client.api.event.EventAwareManager – The relationship between the update service and the caching service. The event manager receives the events and notifies the caching service.

The following image clarifies the relations that are available and that we need to create spring beans for. A few of the beans are not yet discussed. They are used to configure the other beans. In the image all the greens beans are hippo provided classes, the yellow ones come from the project. They are just factory beans to provided the appropriate configuration.

Next step is to have a look at the actual spring configuration:

< ?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xmlns:aop="http://www.springframework.org/schema/aop"
       xsi:schemaLocation="
              http://www.springframework.org/schema/aop http://www.springframework.org/schema/aop/spring-aop-2.5.xsd
              http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-2.0.xsd">
    <bean id="connectionProps" class="org.springframework.beans.factory.config.PropertyPlaceholderConfigurer">
        <property name="locations" value="file:${config.dir}/connection.properties"/>
        <property name="placeholderPrefix" value="$con{"/>
    </bean>
    <bean id="<strong>contentConnector" class="nl.jteam.knvb.integration.hippo.HippoContentConnector">
        <property name="webdavService" ref="webdavService"/>
    </bean>
    <bean id="<strong>hippoCachingService" class="nl.hippo.client.caching.service.CachingServiceImpl">
        <constructor -arg index="0">
            <bean class="nl.hippo.client.caching.JCSDefaultCache">
                <constructor -arg value="default"/>
            </bean>
        </constructor>
        <constructor-arg index="1" ref="hippoEventAwareManager"/>
        <constructor-arg index="2" value="default"/>
    </bean>
    <bean id="<strong>hippoEventAwareManager" factory-bean="updateNotificationService" factory-method="getEventAwareManager"/>
    </bean><bean id="updateNotificationService" class="nl.hippo.client.event.service.UpdateNotificationServiceImpl"
          init-method="start">
        <constructor -arg index="0" ref="updateNotificationConfigFactory"/>
    </bean>
    <bean id="<strong>webdavService" class="nl.hippo.client.webdav.service.WebdavServiceImpl">
        <constructor -arg index="0" ref="webdavConfig"/>
        <constructor -arg index="1" ref="hippoCachingService"/>
        <constructor -arg index="2" value="true"/>
    </bean>
    <bean id="<strong>webdavConfig" class="nl.hippo.client.webdav.WebdavConfig">
        <constructor -arg index="0" ref="webdavConfigFactory"/>
    </bean>
    <bean id="<strong>webdavConfigFactory" class="nl.jteam.knvb.integration.hippo.WebdavConfigFactorybean">
        <property name="webdavFilesPath" value="$con{webdav.filesPath}"/>
        <property name="webdavHost" value="$con{webdav.host}"/>
        <property name="webdavNamespace" value="$con{webdav.namespace}"/>
        <property name="webdavPassword" value="$con{webdav.password}"/>
        <property name="webdavPort" value="$con{webdav.port}"/>
        <property name="webdavProtocol" value="$con{webdav.protocol}"/>
        <property name="webdavRealm" value="$con{webdav.realm}"/>
        <property name="webdavUsername" value="$con{webdav.username}"/>
    </bean>
    <bean id="<strong>updateNotificationConfigFactory"class="nl.jteam.knvb.integration.hippo.UpdateNotificationConfigFactorybean">
        <property name="jndiInitialContextFactory" value="$con{jndi.initialContextFactory}"/>
        <property name="jndiProviderURL" value="$con{jndi.providerURL}"/>
        <property name="jmsConnectionFactory" value="$con{jms.connectionFactory}"/>
        <property name="jmsPassword" value="$con{jms.password}"/>
        <property name="jmsUsername" value="$con{jms.username}"/>
        <property name="jmsTopic" value="$con{jms.topic}"/>
        <property name="jmsReconnectDelay" value="$con{jms.reconnectDelay}"/>
    </bean>
</beans>

You can see from the config we make use of factory beans (webdavConfigFactory) and factory methods (hippoEventAwareManager). That is the most important part of the spring configuration. We now have a fully configured ContentConnector that knows how to do stuff with the hippo repository. Some of the methods that are implemented are the following:

DomDocument obtainDocumentByPath(String path);
DomDocument obtainDocumentByUUID(String uuid);
<t extends BaseDasl> CollectionResults obtainDocumentCollection(
    T dasl, boolean completeDocument);
void deleteDocument(String path);
void createDocument(String relativePath, InputStream content);
void updateMetadataForDocument(String relativePath, Property[] props);

The last part is using the content connector to actually obtain items from the repository. There are some things you need to take care of, one of them being obtaining data from the returned data. You probably need to do some marshalling and unmarshalling. We used an abstract class to make it easier to create dao classes. The next piece of code is a method from the abstract class, just to give an indication.

protected T findItem(String path) {
    DomDocument foundDoc = getContentConnector().obtainDocumentByPath(path);
    if (foundDoc == null) {
        throw new ResourceNotFoundException("Request not found: " + path);
    }
    return unmarshalHippoDoc(foundDoc);
}

That is about it for this blog item. The source is not available online like usual, if you have additional questions, please use the comments.