View source for 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.

== Requirements ==

You will need to setup and configure [http://tomcat.apache.org/ 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


[[Image:sample_web_app.png|center]]

== Web Service ==

The sample web application is configured to offer a SOAP based web service. This is implemented with [http://ws.apache.org/axis/ 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 [[Piccolo XML processor | 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. 

 &lt;!-- init velocity -->
 <velocity xp:static="org.apache.velocity.app.Velocity" xp:method="init">
   <properties>
     &lt;!-- 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>
     &lt;!-- 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>
     &lt;!-- 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. 

 &lt;!-- The Piccolo application -->
 <application xp:id="tmbrowser" xp:class="org.wandora.piccolo.Application">
   &lt;!-- 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>
   &lt;!-- 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>
   &lt;!-- template for startpage -->
   <template>
     &lt;!-- template key -->
     <key>startpage</key> 
     &lt;!-- 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>
     &lt;!-- template file location -->
     <template>index.vhtml</template>
     &lt;!-- 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>
   &lt;!-- 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.