Setting up Wandora Piccolo server
This documentation is deprecated! Although the functionality is still in Wandora application, the piccolo_sample_web_app has been removed from Wandora distribution packages. See Wandora modules framework or Embedded HTTP server for similar features.
Wandora comes with a Java servlet based web application that can be used to publish a topic map created with Wandora. The extras folder of Wandora source code distribution package contains a SampleWebApp in piccolo_sample_web_app folder. 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.
Contents |
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 piccolo_sample_web_app folder in the webapp folder you created. You will find piccolo_sample_web_app folder inside wandora extras folder of Wandora source code distribution package.
Next you will have to edit several of the files you copied to match your system. If you named your web application something else than 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 all external libraries (i.e. all files and folders) from the lib folder of Wandora installation directory there. Also copy build/classes/org folder from Wandora installation folder under WEB-INF/classes folder. That is, you should have a WEB-INF/classes/org folder which will contain a wandora folder (and possibly others) 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. Application is browsable at
http://MY_HTTP_ADDRESS:8080/wandora/ http://MY_HTTP_ADDRESS:8080/wandora/flash/
The WWW version of sample application should look something like this
Web Service
The sample web application is configured to offer a SOAP based web service. This is implemented with Apache Axis web service toolkit. WEB-INF/web.xml contains definition for the web service servlet. The section is marked with comments and you can remove it if you don't need web service interface. WEB-INF/server-config.wsdd contains the web service deployment definition for Axis. Finally, the Axis servlet needs access to the topic map. This is done in WEB-INF/classes/piccoloconfig.xml by adding the topic map in the servlet context. If everything is configured correctly and you use the default settings you should be able to get the web service definition file from
http://localhost:8080/wandora/services/WandoraService?wsdl
See Wandora Web Service for more details and Sample Flash Application for information about how to setup the sample Flash application that utilizes the web service interface.
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 almost 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="org.wandora.piccolo.services.WandoraService">
<param xp:idref="logger"/>
<properties>
<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>
</properties>
</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="org.wandora.piccolo.Application">
<!-- location where pages are cached, viewtopic action will use caching if a cache service is configured
<service xp:id="pagecache" xp:class="org.wandora.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="org.wandora.piccolo.actions.ViewTopic"/></mapentry>
<mapentry><key>search</key><action xp:class="org.wandora.piccolo.actions.Search"/></mapentry>
<mapentry><key>startpage</key>
<action xp:class="org.wandora.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.
Optional file server
The sample piccoloconfig.xml file contains basic settings for a Wandora file server service. This section is in a comment section in the sample file and you need to remove the comment characters to enable it.
<fileserver xp:class="org.wandora.piccolo.services.FileServerService" xp:id="fileserver">
<port>8898</port>
<param xp:class="org.wandora.utils.fileserver.SimpleVirtualFileSystem">
<mountPoint>/</mountPoint>
<dir>C:/Program Files/Apache Software Foundation/Tomcat 5.5/webapps/wandora/repository/</dir>
<mountURL>http://127.0.0.1/wandora/repository/</mountURL>
</param>
<useSSL>false</useSSL>
<login>user:password</login>
</fileserver>
<fileServerStart xp:idref="fileserver" xp:method="start" />
<shutdownhook xp:id="fileservershutdown" xp:idref="fileserver"/>
You can change several settings here including port the server is listening to, directory where the file system is mounted, URL to access the file repository, SSL and login details. See MoveSubjectLocators for details about how to use the file server.
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 org.wandora.piccolo.Action interface which only has one method
package org.wandora.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 org.wandora.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 response properties and then processes the 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.
Troubleshooting
Windows Vista
It seems that Windows Vista maps localhost to an IPv6 address "::1" which may cause problems various problems unless you change all references to localhost to 127.0.0.1 or some other IP address. You can change this behavior by editing "C:\Windows\System32\drivers\etc\hosts" file and making localhost resolve to 127.0.0.1, note that you will need to do this as an administrator user.
