Getting Started with JCR (Content Repository for Java, JSR-170) Page: 2
Setup the web project
First, unzip the tomcat install somewhere. Add a reference to it in the preferences (window->preferences->Server->Installed Runtimes). Now create a new server project using the fresh tomcat. With Eclipse WTP create a new "Dynamic Web Project" called jcrWeb. In the "Java Build Path" for the project, ensure the library for the server runtime is present, if not, add it. This will give access to the basic J2EE classes. Add a file named index.html to the "WebContent" directory, just place some hello world txt in it. Next, right click the file, index.html. Select "Run As" -> "Run on Server". The server should start and you should now see the output of your file. Now, shutdown the server.
The objective of the above was to create a very simple scenario to verify that the development environment is configured for the server correctly. The next step, just verifies the setup one step further. So, let's create a 'hello world' servlet.
Next up, just map it in the web.xml to /jcrDemo.
Starting the server and pointing your browser to http://127.0.0.1:8080/jcrWeb/jcrDemo should display "Hello from the servlet".
I know that these last few steps have been pretty basic but, often problems are found late, after a lot of code has been written. Once there is a large amount of code it may be hard to pinpoint exactly where things went wrong. So, we'll just code a little and test a little, or in this case; configure a little, test a little. Ideally, we want to discover problems as early as possible.
Configuring the server
After having run, there should now be a "Servers" project in the workspace. Our next step is to configure the content repository as a JNDI resource. Note: this step is different for each app server out there. These instructions are specific to Tomcat 5.5. If there is interest, I'll post instructions for other app servers.
First up, the server.xml. In the GlobalNamingResources, add a Resource entry. The name attribute will be set to "jcr/globalRepository", auth to "Container" and the type as "javax.jcr.Repository". The factory attribute (that returns the repository reference) should be set to "org.apache.jackrabbit.core.jndi.BindableRepositoryFactory", and the next two attributes (be very careful): configFilePath and repHomeDir; should be set to the location of the configuration file (the repository.xml file created in the earlier JUnit test) and to the repository home, respectively.
Time to add the reference to the Web Deployment Descriptor (web.xml). Note: The change in this file should be standard across application servers.
Now, you will notice that in one place we define the reference as "jcr/globalRepository" and in the web.xml expect is as "jcr/repository". Normally, tying these together is the job of the system administrator. Well, in th development environment, you are you own administrator. With Tomcat 5.5 there are several ways to do this: create an xml file with the same name as the web application, define the references in the server.xml file or, create a context.xml file within the META_INF directory. For now, we are going to do the last one.
In the context.xml file, we will simply define a resource link mapping the global name to the local one.
If you try to start the server now, its going to fail to start. The factory class and resource type defined in the server.xml file are not in the server's classpath. In the tomcat installation directory, locate the common/lib directory. Copy the following libraries into it: jcr-1.0.jar, jackrabbit-core-1.0.jar, commons-collections-3.1.jar, slf4j-log4j12-1.0.jar, log4j-1.2.8.jar, xercesImpl-2.6.2.jar, xmlParserAPIs-2.0.2.jar, derby-10.1.3.1.jar, lucene-1.4.3.jar and concurrent-1.3.4.jar. These are the libraries that were downloaded for the original test.
Once all of that has been finished, let's find out if it worked. Edit the JcrDemoServlet so that instead of saying hello, it should conduct the JNDI look-up and test the type of the object returned to ensure that it is an instance of a javax.jcr.Repository object. The code follows.
Now, when the server is fired up, and the browser pointed to: http://127.0.0.1:8080/jcrWeb/jcrDemo "Success" should be displayed. If not, time to back-track and ensure all of the parts are in place.
Next up, let's go one step further, and create another servlet to connect to the repository and perform the same functions as the 'hello world' test.
Now, pointing the browser to http://127.0.0.1:8080/jcrWeb/jcrHello will exercise the new servlet. If all goes well, you should see the node path and the "Hello, World!" text. Congratulations, you have created a web application that connects to a repository successfully as a Model 2 deployment.