HOWTO Xindice 1.1b and Cocoon 2

by Barzilai Spinak barspi@internet.com.uy

April 6th, 2003

Disclaimer: This How-To reflects only my experience trying to make Xindice 1.1b work with Cocoon 2.0.4 within the environment mentioned below. I cannot guarantee your results with different versions of the packages. Consider that, as of this writing, Xindice 1.1b is just that... a project in a beta state. I'm not involved in the development of neither Xindice, nor Cocoon. In fact, I'm pretty much a newbie at both so I may be doing some things wrong, or in a way that is different from what the developers intend or consider "best practices".

All in all, I'm writing this because I had a problem to solve and could not find a single tutorial explaining the subject. Then, many people on the Xindice list asked me to post my solution... so here it is.

Have fun!!

Tested platform:

I will explain everything according to my platform but that doesn't mean it won't work under Windows or with a different Java version, etc. Just make adjustments to fit your setup.

Assumptions:

I asssume that the following is true:

CVS checkout

Now we need to get the complete CVS repository for Xindice 1.1b. The reason for this is that, as of this writing, none of the 3 pre-built .zip or .tar.gz distributions (jar, war, src) are complete. In particular, you won't be able to build Xindice from the src distribution because it's missing the config directory and maybe other stuff...

So go ahead, make a new directory, and checkout the whole thing as explained here (the module name is  xml-xindice )

Building

  1. Now everything has been downloaded to a directory called xml-xindice. Rename the file  build.properties.sample  to  build.properties  and edit it so the  tomcat.home  property is set to whatever your  TOMCAT_HOME  is.

(This step I'm not sure whether it's necessary but it didn't hurt to do it. Please comment :-)

  1. Let's build it:  ./build.sh 

(The CVS checkout already includes a version of Ant but if you have your own installed then you can just use the command  ant  and it will build from the  build.xml  file)

If everything went OK, you have compiled all the source and samples, and generated the war and jar releases which are in the  dist  directory.

Note: Since we're working with a beta version, the packages may not compile because someone is working on them. As a matter of fact, everything I explained here worked last night but as I write this someone has been modifying code that has been untouched for a few months and now it won't build!!! Let's hope this is solved promptly :-)

The new Xindice

In version 1.0, Xindice comes as an independent service listening on port 4080. It also has a couple of command line tools called  xindice  and  xindiceadmin  which, for the most part, overlap in their functionality.

In version 1.1, Xindice has become a servlet, or webapp, which runs under a servlet engine like Tomcat or JBoss. There's also a command line tool called  xindice  which does the job of the two old command line tools.

So, in my understanding, there are two parts to a Xindice installation: war webapp, and command-line administration tool.

Installing the Xindice ''war''

Now we're going to install the Xindice webapp under Tomcat. It comes in a war file which was generated by the building step and put into the  dist  directory of the CVS checkout. It will probably be called  xindice-1.1b.war  but it needs to be renamed to  Xindice.war  (that's a capital X) because that's what Xindice expects to be called...

  1. Copy the newly renamed  dist/{ { { Xindice.war } } }  to  $TOMCAT_HOME/webapps 

  2. Start Tomcat, and it should expand and deploy  Xindice.war  into a directory called  $TOMCAT_HOME/webapps/Xindice 

  3. Test that everything is working by browsing to http://yourhost:8080/Xindice We should get the THIS IS AN UGLY DEBUG TOOL! page.

Installing the Xindice command line tool

For this, I used my personal preferences, as I did not find guildelines as to what the best practices are. I decided to install the command line tool and libraries under /usr/java/xindice and make that directory my XINDICE_HOME. Also I wanted to share the database root (/db) with the webapps installation.

Now you can try the command  xindice lc -c /db  to see if everything works. You should get a listing of collections under  /db  (usually just  system  since you haven't added anything yet)

If this doesn't work then use the full path for the -c switch e.g.; xindice lc -c xmldb:xindice://localhost:8080/db

Preparing Cocoon

Now we have to provide a protocol handler for Cocoon. Edit the file  $TOMCAT_HOME/webapps/cocoon/WEB_INF/cocoon.xconf  and look for the  <source-handler>  tag. If you had been using Cocoon with Xindice 1.0 then you probably have a section that says: 

    <protocol class="org.apache.cocoon.components.source.XMLDBSourceFactory" name="xmldb"> 
      <!-- Xindice driver --> 
      <driver class="org.apache.xindice.client.xmldb.DatabaseImpl" type="xindice"/> 
      <!-- Add here other XML:DB compliant databases drivers --> 
    </protocol>

If not, just add that new protocol inside the  <source-handler>  and  </source-handler>  tags.

Before, in your Cocoon sitemap you used source URI's that looked like this:

Now you should change them to the following:

That's all I know!!

HowToXindice1o1bCocoon2 (last edited 2009-09-20 23:32:40 by localhost)