Setting up Wandora Piccolo server

Revision as of 14:20, 24 January 2007

Wandora comes with a Java servlet based web application that can be used to publish a topic map created with Wandora. The samples folder contains a SampleWebApp. This page will describe how to setup your own simple web application using it as a starting point and how to customize the web application to suit your needs.

Requirements

You will need to setup and configure Apache Tomcat server. You will also need most of the external libraries needed by Wandora (see How to install Wandora).

Setting up the web application

Create a new folder for your web application in the webapps folder inside the Tomcat folder. Name it Wandora or whatever you want your web application to be called. Copy the contents in the SampleWebApp folder in the webapp folder you created. You will find SampleWebApp folder inside wandora samples folder.

Next you will have to edit several of the files you copied to match your system. If you named your web application something else that Wandora you will need to put this name in META-INF/context.xml file and WEB-INF/web.xml file. Also update all paths found in WEB-INF/web.xml and WEB-INF/classes/piccoloconfig.xml to match your environment.

Create a lib folder under WEB-INF folder and copy there all external libraries, i.e. all files, from the lib folder of Wandora installation directory. Also copy build/classes/com folder from Wandora installation folder under WEB-INF folder. That is, you should have a WEB-INF/com folder which will contain gripstudios folder which in turn will contain a complex directory structure with the compiled Java classes.

Now you should be able to start Tomcat and use the web application.

Details of Piccolo framework and the sample web application

Piccolo is the framework that runs on top of Apache Tomcat and is used to run the Wandora web application. Piccolo is the servlet that receives the http requests. It then invokes an action handler of another Java class based on what action was specified in the http parameters. In case of Wandora that is usually an action to view a topic, perform a search or view some other page but specialized applications may have many more actions. Actions will usually have one or more Apache Velocity templates associated with them. These are used to do the final output of the action, for example the html layout of a page.

Important part of Piccolo is its xml configuration processor that is used to configure Piccolo and the web application and nearly everything related to the web application. The processor is basically a Java based scripting language in xml format. In the configuration file you can do nearly anything you could do in any normal Java class. This means that you can use new actions, utility classes, topic map implementations, services etc. without any changes to the core Piccolo classes. For more information read the detailed XML processor description.

piccoloconfig.xml in WEB-INF/classes folder is the configuration file processed with Piccolo xml processor and it contains all configuration of Piccolo, actions, templates, topic maps etc.

<!-- init velocity -->
<velocity xp:static="org.apache.velocity.app.Velocity" xp:method="init">
  <properties>
    <!-- directory for velocity templates -->
    <property><key>file.resource.loader.path</key>
              <value>C:/Program Files/Apache Software Foundation/Tomcat 5.5/webapps/wandora/WEB-INF/classes/templates</value></property>
    <!-- print stack traces for debugging -->
    <property><key>runtime.log.error.stacktrace</key><value>true</value></property>
    <property><key>runtime.log.warn.stacktrace</key><value>true</value></property>
    <!-- other velocity settings -->
    <property><key>file.resource.loader.cache</key><value>false</value></property>
    <property><key>velocimacro.permissions.allow.inline.local.scope</key><value>false</value></property>            
    <property><key>velocimacro.permissions.allow.inline.to.replace.global</key><value>true</value></property>
    <property><key>velocimacro.library.autoreload</key><value>true</value></property>
  </properties>
</velocity>

This is the code to setup Velocity engine and you will find it allmost at the beginning of the file. Important here is the path to Velocity templates. You can also turn off printing of stack traces here and change other velocity specific settings (see Velocity documentation for details).

<service xp:id="wandora" xp:class="com.gripstudios.applications.wandora.WandoraService">
  <param xp:idref="logger"/>
  <param xp:class="com.gripstudios.piccolo.MapParser" xp:method="getProperties">
    <property><key>wandora.projectfile</key><value>C:/Program Files/Apache Software Foundation/Tomcat 5.5/webapps/wandora/WEB-INF/classes/base.wpr</value></property>
    <property><key>wandora.projectfile.autoupdate</key><value>true</value></property>
  </param>
</service>

Next part configures Wandora as a service used in the web application. You need to set the file used to setup the topic map. This file should be a project file saved with the Wandora application. Note that possible database configuration is in this file. If the autoupdate property is set to true, the project file automatically reloaded when it changes.

<!-- The Piccolo application -->
<application xp:id="tmbrowser" xp:class="com.gripstudios.piccolo.Application">
  <!-- location where pages are cached, viewtopic action will use caching if a cache service is configured 
  <service xp:id="pagecache" xp:class="com.gripstudios.piccolo.services.FileSystemCache">
    <cachedir>C:/Program Files/Apache Software Foundation/Tomcat 5.5/webapps/wandora/WEB-INF/classes/cachedir</cachedir>
  </service> -->
  <service xp:idref="wandora"/>

This starts the Piccolo web application configuration. First service a page caching service which will cache pages created with templates. If you want to use it you need to uncomment it. The other service is the Wandora service that was configured outside the application element.

<actionmap>
  <!-- Viewtopic action displays one topic. It uses templates with keys viewtopic and invalidtopic. -->
  <mapentry><key>viewtopic</key><action xp:class="com.gripstudios.applications.wandora.actions.ViewTopic"/></mapentry>
  <mapentry><key>search</key><action xp:class="com.gripstudios.applications.wandora.actions.Search"/></mapentry>
  <mapentry><key>startpage</key>
    <action xp:class="com.gripstudios.piccolo.actions.ViewPage">
      <templatekey>startpage</templatekey>
      <usecache>true</usecache>
    </action>
  </mapentry>
</actionmap>

This confugures all different actions in the web application. The key is the string used to identify the action. Action is performed in response to an http request when its key matches the action http parameter received. The action xml element specifies the Java class used to perform the action. Depending on the class, it may require additional configuration. ViewTopic and Search classes don't need any other configuration, but the ViewPage class (startpage action) needs a template it uses as well as a boolean specifying if page caching should be used. The other two actions have template key hard coded in the class and they will automatically use caching if page caching service has been specified.

<templates>
  <!-- template for startpage -->
  <template>
    <!-- template key -->
    <key>startpage</key> 
    <!-- template language, you can create multiple templates with same key but different laguage -->
    <version>en</version> 
    <mimetype>text/html</mimetype>
    <encoding>ISO-8859-1</encoding>
    <!-- template file location -->
    <template>index.vhtml</template>
    <!-- caching of template (NOT caching of the page created with the template, caching service does this for some actions) -->
    <caching>false</caching>
  </template>

This specifies the first Velocity template. Here the key is the same as templatekey in startpage action which means that startpage action will be using this template. You can have multiple templates with same key as long as they have different version identifier. You can use different versions to make templates with different languages. Piccolo will automatically use the correct template based on the lang http parameter received or the default language of the application. The next two elements specify what mime type should be set in the http response and what encoding the template is in. After this is the actual filename of the template. This is a relative path with the templates directory specified in Velocity initialization earlier as the base directory. Last element specifies if template caching should be used. If this is true then templates won't be reloaded and preprocessed for each http request. Other templates are configured similarily.

<properties>
  <!-- default template language to use if user doesn't specify anything else -->
  <property><key>defaultlang</key><value>en</value></property>
</properties>

This sets other application specific options. The sample app only sets default language to be used if user doesn't specify any other language. Action Java classes can access these parameters so if you use custom action classes you could specify settings used by several classes here instead of in the action configuration.

<contextobject key="topicmap" xp:idref="wandora" xp:method="getTopicMap"/>

Rest of the piccoloconfig.xml file specifies context objects passed to Velocity templates. The key attribute is always the variable identifier in the Velocity template. The example line adds the actual topic map with variable name topicmap in the Velocity context. This way the templates may access the topic map.

Configuring and customizing Piccolo framework and the sample web application

You can change the layout of all pages by editing the Velocity templates. Note that in addition to all context objects specified in the piccoloconfig.xml file, you can also access the Piccolo application and the http request in the template. This means that you can do relatively complex modifications to the sample web application by only changing templates and possibly adding some utility classes as context objects. For example you could have a class that retrieves information from a (non topic map related) database. Then use this class from the Velocity template.

You may also want to make new actions or extend existing actions. All actions need to implement the com.gripstudios.piccolo.Action interface which only has one method

package com.gripstudios.piccolo;
import javax.servlet.*;
public interface Action {
   public void doAction(User user,ServletRequest request,ServletResponse response,Application application);
}

A very simple doAction implementation could look something like this:

import com.gripstudios.piccolo.*;
import java.util.*;
import java.io.*;
// ...
    public void doAction(User user, javax.servlet.ServletRequest request, javax.servlet.ServletResponse response, Application application) {
        Template template=application.getTemplate(templateKey,user);
        HashMap context=new HashMap();
        context.put("request",request);
        context.putAll(application.getDefaultContext(user));
        response.setContentType(template.getMimeType());
        response.setCharacterEncoding(template.getEncoding());
        try{
            template.process(context,response.getOutputStream());
        }catch(IOException ioe){
            logger.writelog("WRN","ViewPage couldn't generate page. IOException "+ioe.getMessage());
        }
    }

This gets the appropriate template with templateKey (you need to specify this somewhere in the class) and the user. Sets up the template context with default context and the http request. Sets resporse properties and then processes teh template. The default context contains all objects specified in piccoloconfig.xml, the user language with variable name lang and the application with variable name application.