http://blog.dutchworks.nl/2011/12/13/embedding-rss-in-hippo-using-the-pipelines-feature/

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

One remark I like to make is about the connection pool. This pool is probably not production ready. I did not do any performance tests and it is a bit rough around the edges.

That said, let’s move on and start talking about the solution.

Overview

Let’s start of with an overview of the problem domain. You have a running hippo repository, you can use the cms to edit content, the console to configure the details, the site toolkit to create a site and maven to bundle it all together. Now you have a website (maybe an existing, maybe a new one) that needs to serve content from the repository. Or you want to expose the content using an rss feed, or maybe even a web service. The sample application that you can find on the forge of hippo uses a web service to demonstrate the capabilities.

To be able to connect and interact with the hippo repository (over rmi), you need two jar files: hippo-ecm-api.jar and hippo-ecm-repository-connector.jar. Using these jars and a bit of spring wiring, You can create a wrapper layer around the Hippo repository connection.

The following image shows the classes we need for interacting with the repository. The SessionFactory uses the class org.hippoecm.repository.HippoRepositoryFactory to get a reference to the hippo repository. With this reference new sessions can be created. So that’s it? No not really. For performance reasons we want to reuse session when they are only used for read only actions. We also want to recover from connection problems and we want a mechanism to listen for specific events in the repository.

Session pooling

To be able to do more with sessions, we wrap the standard javax.jcr.Session. The interface we expose is different than the standard session. This enables us to create a common interface for normal obtained sessions and pooled sessions. An important method for pooled sessions is the close method. For normal sessions, this means logout, for pooled sessions this means return to the pool.

Obtaining a session from the pool is done via the DefaultHippoSessionPool using the interface HippoSessionPool. To be able to initialize the pool and to clean it, two methods are exposed as well. This enables you to re-initialize the pool when for instance the connection was broken.

Listening to the repository

When creating an external application it might be interesting to know what happens in the repository. That is why the event listener is available. The SessionListenerService accepts RepoEventListener objects and notifies them of events taking place in the repository. The service uses a session to register the listeners. Do remember that the listeners are registered over an rmi connection. If the connection dies, the listeners will not receive events.

Session Manager

In order to handle broken connections, starting up pools, re-registering listeners and provide an easy interface to obtain read-only as well as normal sessions, we have the SessionManager. The SessionManager initializes the pool and registeres the listeners. It also closes the pool and tries to de-register listeners when closing down or in case of problems.

The SessionManager is the class used by your code to access the repository. An example is the BaseQueryTemplateAdapter that uses the SessionManager to easily query the repository for a search string.

CircuitBreaker

We already talked about broken connections, re-initializing the pool, re-registering the listners. How do we know the connection is broken? This is less obvious than you expect. Especially for the listeners. A session can be checked for liveness, but the listeners are not in a normal synchronous process. The listeners are also not notified of broken connections. Therefore we have introduced the circuit breaker that takes away part of the pain. The following image gives you an overview of the circuit breaker implementation. If you want to read more about the circuit breaker in general, read the post from Allard.

So how does it work? The mothods in the HippoSessionFactory are annotated with the @Monitored tag. That way the aspect AnnotatedMethodCircuitBreakerInterceptor wraps all method calls to create a new session. If errors occur it might cause the CircuitBreaker implementation to move to OPEN state. After the cooldown period, a connection is tried again. If that connection succeeds, the state is changed to CLOSED again. All registered listeners of type StateChangeListener are notifed. The SessionManager also implements the StateChangeListener interface. That way the CircuitBreaker notifies the SessionManager when the state is changed. The SessionManager uses this information to re-initialize the session pool and re-register the listeners.

Last remarks

That’s it for this post. I hope it is clear how you can connect to hippo using spring by now. Hippo provides documentation on this topic itself as well. If you want to try this out, go to the hippo website below. Look for the quickstart. Run the repository and fire up the sample I have provided. For more information about the webservice, check my previous post.

References

• http://www.gridshore.nl/2008/12/04/roadtrip-from-springframework-to-hippo-7/
• http://www.gridshore.nl/2008/10/30/bring-some-stability-to-your-architecture/
• http://docs.onehippo.org/
• http://www.onehippo.org/cms7/delve_into/quickstart.html
• http://forge.onehippo.org/projects/soap-exposure/

This post will talk about connecting to the hippo repository using the spring framework. I’ll show a very basic (not production ready) connection pooling into the repository. Using this connection, the spring webservices project will step in and take over. Using spring-ws I am exposing a search into the documents.

Feel free to post a comment if you have questions, the sources are again available on google code.

I want to start with some references to the frameworks that I have used. That way you can try to follow along.

1. Hippo ecm quickstart – easy access to start your own hippo repository. If you are having problems starting the application, check the start script and remove the -Xms stuff at the end of the file somewhere.
2. Apache maven – Used to build the sample
3. source code – The source code for the complete project.
4. IntelliJ – You might try another IDE, but I cannot make any guarantees.
5. SoapUI – Nice tool for testing the webservice, but any webservice client should be able to access the wsdl and use it.

Let’s start with the basics, I think you were able to get the hippo quickstart running. I am not going into details in that area, check the hippo documentation which is becoming very useful. Now that you have a running repository, you want to connect to it. Startup your favorite IDE (oke, no jokes anymore) and create a very difficult class with code as shown in the following piece of code.

String location = "rmi://localhost:1099/hipporepository";
HippoRepositoryFactory.setDefaultRepository(location);
HippoRepository repo = HippoRepositoryFactory.getHippoRepository();
Session session = repo.login("admin", "admin".toCharArray());
Workspace workspace = session.getWorkspace();
Query query = queryManager.createQuery(
	"//element(*,defaultcontent:article)[jcr:like(@defaultcontent:title,'%title%')]", Query.XPATH);
QueryResult queryResult = query.execute();
NodeIterator nodes = queryResult.getNodes();
while (nodes.hasNext()) {
    Node node = nodes.nextNode();
    System.out.println("title : " + node.getProperty("defaultcontent:title"));
}
session.close();

Problem is that you need a lot of dependencies to do this. You can look up the right document on the hippo website and download all the jars, you can also follow along and build it in a slightly more sturctured way. But in the end, this is all there is to it. First you get a reference to the Hippo repository, than you create a session by a executing a login. From the session you ask the workspace and the query manager. The querymanager is used to execute a query that looks for all documents of type defaultcontent:article with a title containing the word title. Then we use the QueryResult to print the actual titles from all found articles.

Now that we know how to connect to Hippo, we are going to use this knowledge to make it useable in the springframework world. The following image shows the interfaces and classes that we need to obtain a session.

The image shows the blue HippoRepositoryFactory, blue means a gridshore class. This is a spring FactoryBean that creates an implementation of the HippoRepository, the orange ones are from Hippo. It uses the orange HippoRepositoryFactory to actually create the HippoRepository instance. Just like in the first code block I showed. The following code block shows the implementation of this class. The other blue item is the HippoSessionFactory. Implementations of this interface create sessions represented by the green color coming from the original JackRabbit libraries. We’ll discuss this class after the code block.

public class HippoRepositoryFactory implements FactoryBean, InitializingBean {
    private String location = "rmi://localhost:1099/hipporepository"; 

    public HippoRepositoryFactory() {
    }

    public HippoRepositoryFactory(String location) {
        if (null != location && !"".equals(location)) {
            this.location = location;
        }
    }

    public Object getObject() throws Exception {
        return org.hippoecm.repository.HippoRepositoryFactory.getHippoRepository();
    }

    public Class getObjectType() {
        return HippoRepository.class;
    }

    public boolean isSingleton() {
        return true;
    }

    public void afterPropertiesSet() throws Exception {
        org.hippoecm.repository.HippoRepositoryFactory.setDefaultRepository(location);
    }
}

The code block shows you we initialize the HippoRepositoryFactory wit the default location. We also need to implement the methods getObject() and getObjectType. This kind of classes can be used immediately in the spring configuration. The following code block shows part of this configuration in spring for the mentioned objects.

<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd">
    <!-- loads the propety file from the classpath with some configuration parameters
         default file is loaded from the jar file. Place your on version ealier on the classpath.
     -->
    <bean id="jcrConfig" class="org.springframework.beans.factory.config.PropertyPlaceholderConfigurer">
        <property name="location" value="classpath:/jcrconfig.properties"/>
        <property name="placeholderPrefix" value="$jcr{"/>
    </bean>
    <!-- Special spring factory bean to create a HippoRepository instance -->
    <bean id="hippoRepositoryFactory" class="nl.gridshore.samples.hippo.impl.HippoRepositoryFactory">
        <!-- Since we use the default the following is optional -->
        <constructor-arg index="0" value="$jcr{jcr.rmi.connection.url}"/>
    </bean>
    <!-- Factory bean used to create new Sessions for the hippo repository -->
    <bean id="sessionFactory" class="nl.gridshore.samples.hippo.impl.HippoSessionFactoryImpl">
        <property name="hippoRepository" ref="hippoRepositoryFactory"/>
        <!-- following parameters are optional -->
        <property name="defaultUsername" value="$jcr{jcr.username}"/>
        <property name="defaultPassword" value="$jcr{jcr.password}"/>
    </bean>
</beans>

Now it is possible to create a client that uses the spring configuration to make a call to the hippo repository. Actually the following piece of code shows what you can do right now.

public class ReadRepository {
    public static void main(String[] args) throws RepositoryException {
        ApplicationContext ctx = new ClassPathXmlApplicationContext(new String[]{"connector-config.xml"});

        RepoSessionTemplate repoSessionTemplate = (RepoSessionTemplate) ctx.getBean("sessionTemplate");
        readNodes(repoSessionTemplate);
    }

    private static void readNodes(RepoSessionTemplate repoSessionTemplate) throws RepositoryException {
        QueryResult queryResult;

        queryResult = repoSessionTemplate.readFromSession(new SessionCallback() {
            public QueryResult readFromSession(QueryManager queryManager) throws RepositoryException {
                Query query = queryManager.createQuery(
                        "//element(*,defaultcontent:article)[jcr:like(@defaultcontent:title,'%title%')]", Query.XPATH);
                return query.execute();
            }
        });
        NodeIterator nodes = queryResult.getNodes();
        while (nodes.hasNext()) {
            Node node = nodes.nextNode();
            System.out.println("Node title : " + node.getName());
        }
    }
}

The result when you run this class, if you have your repository running, will be:

Node title : myarticle1

Node title : hippo:prototype

Node title : myarticle1

Node title : myarticle2

Oke I have to admit, I cheat. There are more classes used in this sample. But before I’ll go into these classes, I want to explain some very basic things of hippo, or using JackRabbit in general.

The entry point for doing something with a repository is the Session. Creating a session object is not a cheap operation. Therefore it is advisable to reuse created sessions when only reading data. Websites with a lot of traffic will find great performance increases when using a Session pool. To help people not to close session that need to be pooled, I have created a class hierarchy around the sessions and a session pool object. Another class I have created is the RepoSessionTemplate. This is a very common approach in the springframework world. It prevents you from having to write to much boiler plate code. The following image shows the relationships between the different classes.

The image might be a bit overwhelming. I suggest you download the code and have a look at it. I think it is not really hard. There is a RepoSession interface that defines the methods that our clients might need when using a session. The WrappedSession represents a RepoSession that contains a wrapped repository session. The PooledSession is a special WrappedSession, it is not closed when you call the close() method. Instead it returns the session back to the pool. Now I want to have a look at the RepoSessionTemplate and it’s concrete implementation. This interface has two methods, one with username/password and one without. By providing a username, you will not get a pooled session. By omitting a username, you do get a pooled connection. No matter which path you choose to go, the template adapter will follow the same road, accept for creating the RepoSession. In the first situation it is created in the Template adapter itself using the session factory, in the other situation, the template makes use of the pool to obtain a RepoSession. Let’s have a look at the template adapter code.

    public QueryResult readFromSession(SessionCallback sessionCallback) throws RepositoryException {
        logger.debug("Read from session is called without username");
        RepoSession session = hippoSessionPool.obtainSession();
        return doReadFromSession(sessionCallback, session);
    }

    protected QueryResult doReadFromSession(SessionCallback sessionCallback, RepoSession session) throws RepositoryException {
        logger.debug("Execute the callback and close the session afterwards");
        QueryResult queryResult;
        try {
            Workspace workspace = session.getWorkspace();
            queryResult = sessionCallback.readFromSession(workspace.getQueryManager());
        } finally {
            session.close();
        }
        return queryResult;
    }

The structure is the same as the first code block I showed. In another code block you already saw the SessionCallback at work. I’ll repeat it in one of the following blocks of code when discussing the webservice part. Actually it is not a bad moment to start talking about that part of the application. We now have access to a mechanism to fire queries at the repository. Let’s use that to obtain a search parameter from a webservice request and return the found documents in a response.

So what do we need to create a webservice, well a guide to help us would be nice. Well you have multiple options. One is a blogpost I wrote quite some time a go: using spring-ws to create a webservice or the reference documentation. For the sample I used the reference manual, especially for the JDom part. Since it has been written down so well and I have the source code for you available, I will not go into the configuration of the webservice stuff. Check the file spring-servlet.xml and the xsd document.xsd. Instead of all that, let’s focus on the endpoint. The endpoint is used for analyzing the request as well as creating the response. I have chosen a payload endpoint, no need for all the soap specifics, I only want the actual content. Reading from the request is done using XPath expressions. Creating the response is done with JDom. The following piece of code shows you the first part of the class with request handling in it.

public class SearchNewsEndpoint extends AbstractJDomPayloadEndpoint {
    private static Logger logger = LoggerFactory.getLogger(SearchNewsEndpoint.class);

    private RepoSessionTemplate repoSessionTemplate;

    private XPath searchTextExpression;
    private Namespace namespace;

    public SearchNewsEndpoint() {
        namespace = Namespace.getNamespace("grid", "http://gridshore.nl/schemas");
        try {
            searchTextExpression = XPath.newInstance("//grid:SearchText");
            searchTextExpression.addNamespace(namespace);
        } catch (JDOMException e) {
            logger.error("Problem while creating an XPath");
            throw new EndpointConfigurationException("Problem in the SearchNewsEndpoint", e);
        }
    }

    protected Element invokeInternal(Element requestElement) throws Exception {
        final String searchText = searchTextExpression.valueOf(requestElement);
        ...
    }
}

In the code you see that I use the JDomPayload endpoint. I first create a namespace and using that namespace an XPath. By reading the xsd, you can see that the SearchRequest element must contain an element SearchText. This element contains the actual string that we use in the search. The searchTextExpression now contain the expression that we can use when a request comes in. The method invokeInternal is called when a request comes in and as you can see I obtain the value of the SearchText element and store it in the variable searchText. The following piece of code comes instead of the … above.

        Element searchResponse = new Element("SearchResponse", namespace);

        QueryResult queryResult = repoSessionTemplate.readFromSession(new SessionCallback() {
            public QueryResult readFromSession(QueryManager queryManager) throws RepositoryException {
                Query query = queryManager.createQuery("//element(*,defaultcontent:article)[jcr:like(@defaultcontent:title,'%"
                        + searchText + "%')]", Query.XPATH);
                return query.execute();
            }
        });
        NodeIterator nodes = queryResult.getNodes();
        while (nodes.hasNext()) {
            Node node = nodes.nextNode();
            Property title = node.getProperty("defaultcontent:title");
            Property introduction = node.getProperty("defaultcontent:introduction");
            Property body = node.getProperty("defaultcontent:body");
            Property uuid = node.getProperty("jcr:uuid");

            Element articleElement = new Element("Article", namespace);
            articleElement.setAttribute("uuid",uuid.getString());
            Element titleElement = new Element("Title", namespace);
            Element introductionElement = new Element("Introduction", namespace);
            Element bodyElement = new Element("Body", namespace);

            titleElement.setText(title.getString());
            introductionElement.setText(introduction.getString());
            bodyElement.setText(body.getString());

            articleElement.addContent(titleElement);
            articleElement.addContent(introductionElement);
            articleElement.addContent(bodyElement);
            searchResponse.addContent(articleElement);
        }

        return searchResponse;

All the Elements are JDom elements and will be transformed into a valid response. You can see the first element SearchResponse, which will be given multiple Article elements, and so on. The repoSessionTemplate is used to execute the query and in the end obtain the Nodes containing the articles with a title containing the entered text. Using the getProperty methods I can obtain the actual data and create a response out of it.

That is about it, now you can fire up your web project containing the spring-ws project. If your repository is still running you should be able to send a request and get a response. For those of you not familiar with a webservice client, I recommend using SoapUI.

When soapui is running, go to File > New Project. A wizzard will appear. Enter the following url into the Initial wsdl/wadl box.

http://localhost:8081/searchService/search.wsdl

The result should be a Request 1, double click it to open. Change the value of SearchText into title, push the run button and you should receive the following response.

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
   <SOAP-ENV:Header/>
   <SOAP-ENV:Body>
      <grid:SearchResponse xmlns:grid="http://gridshore.nl/schemas">
         <grid:Article uuid="118b876b-fc73-4400-89b8-5a0e2153628d">
            <grid:Title>title published version</grid:Title>
            <grid:Introduction>introduction</grid:Introduction>
            <grid:Body>body</grid:Body>
         </grid:Article>
         <grid:Article uuid="2b2c3f3c-a738-4ca6-a0d6-30eac3ca8c55">
            <grid:Title>title</grid:Title>
            <grid:Introduction>introduction</grid:Introduction>
            <grid:Body>body</grid:Body>
         </grid:Article>
         <grid:Article uuid="db1bddc5-d29f-47a1-ac12-b34d97a82715">
            <grid:Title>title</grid:Title>
            <grid:Introduction>introduction</grid:Introduction>
            <grid:Body>body</grid:Body>
         </grid:Article>
         <grid:Article uuid="b363e8be-2ec7-4f62-8ba0-2f9c7a335b17">
            <grid:Title>title</grid:Title>
            <grid:Introduction>introduction</grid:Introduction>
            <grid:Body>body</grid:Body>
         </grid:Article>
      </grid:SearchResponse>
   </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Wow, cool isn’t it? That is about it. Hope you liked it and can use it. Thanks to Jeroen Reijn from Hippo for helping with well euh Hippo and Allard for the thinking with me on the Sessions and pooling stuff.

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.