If you are a Java shop looking to build web sites on top of Pazpar2 or our MasterKey platform, then MasterKey JSF (mkjsf) could be just the tool to kick-start your project.

You know your J2EE and Ajax, and you might be considering JavaServer Faces for your UI development. Or maybe you have already developed a Faces application and would like to integrate metasearch into it.

You may also know about Pazpar2, but, exactly how do you get your JSF application wired up with Pazpar2’s protocol – the commands, the parameter settings, the session handling, and the polling? MasterKey JSF addresses those questions by putting the power of Pazpar2 at the UI developer’s fingertips.

We have just released MasterKey JSF as open source in its first version, and we’re hoping you will take it for a spin and let us know what you think.

Here is how it works:

MasterKey JSF is a library (mkjsf.jar) that you include in your JSF project, and after a bare minimum of configuration, you should be good to go.

The mkjsf.jar exposes the Pazpar2 protocol to the page author in the form of two named objects pzreq (requests) and pzresp (responses). Using the pzreq object, the page author selects commands and sets command parameters for execution. The Pazpar2 responses can then be retrieved from pzresp for display in the page.

Let’s take a code example: in your Faces page, you create the HTML form that will communicate with Pazpar2. Make a JSF input field that sets the query parameter of your search command. The reference to that parameter would be pzreq.search.query.

Next, to display the results, render data from the ‘show’ results to the page by iterating over pzresp.show.hits and writing out data elements like hit.title or hit.author. Here is the entire form:

#{(pzresp.show.start)+loop.index+1}.
#{hit.title} #{hit.author} #{hit.date}
#{hit.description}

 

That’s _almost_ it. Once the user clicks “Execute My Search”, the components should send the query to Pazpar2, start polling for results and continue until Pazpar2 says it’s done.

The mechanism that ensures that the search is executed, that the polling actually takes place, and that the element myshow will in fact be rendered on each poll, is invoked by the instruction



To enable this mechanism in the page, you need to add one more tag than shown above. This tag must be present too:




With the parameter renderWhileActiveclients=”myshow”, you are instructing the component to render the UI element myshow on each poll to Pazpar2. The tag is a wrapper around a JavaScript that repeatedly invokes a Java method, which in turn makes requests to Pazpar2 to retrieve show, termlist, stat, and bytarget data.

So far the page in this example only uses show data, but you will probably want to add other stuff, to make a rich user experience. As you add more elements to your page – for instance facets or pagination – you would also want to add more of your UI elements to the pz2watch tag – as in renderWhileActiveclients=”myshow myfacets”.

We have written a tutorial describing this example and more. The tutorial comes with a web application (a war file) with a set of pages demonstrating step by step how to add functionality to your Pazpar2 application. The tutorial also describes the initial configuration to be done. For the examples above, you would also need to add the right namespaces on top of your XHTML – like pz2utils. That’s in the tutorial too.

You can use mkjsf against our cloud-hosted back-end. You can use the guest account to try it out against a selection of open access resources without having to install any other software than mkjsf itself, or you can contact us for a hosted MasterKey account to get access to virtually any imaginable set of searchable resources. However, you can also install Pazpar2 on your own and use it to search any combination of Solr indexes, Z39.50 servers, and SRU servers, possibly supplementing these with MasterKey Connect to get access to more difficult resources.

We built the mkjsf jar for Tomcat 7, so it contains all the J2EE support — for JSF 2, EL expressions and dependency injection — the stuff that doesn’t come with the Tomcat Servlet container itself. The jar will thus contain too much for deployment to application servers like Glassfish or JBoss. We’ve made separate builds and tested them on those two as well, so it should work. Let us know if Tomcat 7 is not your thing, and we might assist with J2EE application server deployment.

Here is the PDF tutorial: mkjsf-tutorial.pdf

On our ftp server you will also find the sample application used throughout the tutorial, for Tomcat7 and for GlassFish/JBoss respectively. It should be ready to drop in the auto-deploy directory of your server. That was the intention anyway, so let us know if that gives you any issues.

You can also find more documentation in the Javadoc.

Finally, for a demonstration of the capabilities of the library, take a look at our demo at http://jsfdemo.indexdata.com/.