This page is to outline how the jspwiki Wiki engine works - well atleast an outline of the flow and how it interacts with tomcat. I am writing this as I learn about the structure of the system

NOTE - I am not one of the developers (aspiring java enthusiast), who happens to listen in on the JSPWiki development mailing list mailto:jspwiki-dev@jspwiki.org

The environment#

I will be looking at 2.5.x series (usually from head). It will be running on Tomcat 5.5.20, using sun jre 1.5.11 (amd64) on debian amd64. Also test this on windows XP + sun jre 1.5.11 (32).

The eagle view #

This has been cut out of an email from Janne Jalkanen, straight from the horses mouth

• Request comes in, and is intercepted by WikiJSPFilter
• WikiJSPFilter does some magic, and then passes the request to Wiki.jsp
• Wiki.jsp figures out which template to use, and passes control to the ViewTemplate.jsp of that template.
• ViewTemplate.jsp then invokes the correct "part-jsp", which in case of Wiki.jsp is most likely PageContent.jsp
• PageContent.jsp then uses the ContentTag to insert the rendered page content using RenderingManager (via WikiEngine)
• The whole rendering magic is done here, including filter/plugin invocations
• Once the entire page is constructed by Wiki.jsp, the control is passed back to WikiJSPFilter
• At this stage, WikiJSPFilter gets the entire HTML document as a String. Then it replaces some magic markers in the document (as per TemplateManager.addResourceRequest()) as requested by plugins/filters.
• Then, WikiJSPFilter writes the resulting document to the servlet response.

The Environment#

• I have used eclipse to start a new project direct from the JSPWiki CVS
• I created build.properties.mine with my details (setups up where certain directories are
• create an external tool job, to run ant with -Dbuild.properties=build.properties.mine and target war. This creates a war file that you can upload to tomcat
• upload the war file to tomcat using the web manager page

my build.properties.mine

#
#  This file contains defaults for development.  If you are cross-
#  developing in multiple environments, just change the defaults
#  in this file.
#
#  Any changes in this file will be reflected in the default
#  jspwiki.properties-file when it is run.
#
@appname@=JSPWiki
@pagedir@=C:\\\\temp\\\\temp\\\\jspwiki\\\\wikipages
@logfile@=C:\\\\temp\\\\temp\\\\jspwiki\\\\log\\\\jspwiki.log
@securitylog@=C:\\\\temp\\\\temp\\\\jspwiki\\\\log\\\\security.log
@spamlog@=C:\\\\temp\\\\temp\\\\jspwiki\\\\log\\\\spamlog.log

@tests.pagedir@=C:\\\\temp\\\\temp\\\\jspwiki.test\\\\testrepository
@tests.workdir@=C:\\\\temp\\\\temp\\\\jspwiki.test\\\\testworkdir
@tests.logfile@=C:\\\\temp\\\\temp\\\\jspwiki.test\\\\jspwikitests.log

@tests.auth.filename=C:\\\\temp\\\\temp\\\\jspwiki.test\\\\testrepository/auth.txt
@tests.filter@=C:\\\\temp\\\\temp\\\\jspwiki.test\\\\etc/filters.xml

# JavaMail configuration
@mail.smtp.host@=127.0.0.1
@mail.smtp.port@=25
@mail.from@=JSPWiki <JSPWiki@localhost>
#@mail.smtp.account@=foo
#@mail.smtp.password@=foopassword

#  Enable these if you wish to create a static content tarball
#  for use with Apache or another front-end web server.
#  You should specify user and group names that make sense for
#  your environment.

static.user = apache
static.group = daemon
jks.password = jspwiki

#
#  If you are running web tests, these need to be set to your
#  Tomcat admin name and password.
#
tomcat.admin = admin
tomcat.password = greyroot

#
#  JDBC testing properties
#
jdbc.driver.id=hsql
jdbc.driver.jar=lib/hsqldb.jar
jdbc.driver.class=org.hsqldb.jdbcDriver
jdbc.driver.url=jdbc:hsqldb:hsql://localhost/jspwiki
jdbc.admin.id=SA
jdbc.admin.password=
jdbc.user.id=jspwiki
jdbc.user.password=password

Indepth#

Request comes in, and is intercepted by WikiJSPFilter#

Start by looking in web.xml - this is the recipe file for tomcat and the application. Here we can see the definition of the filter

<filter>
	<filter-name>WikiJSPFilter</filter-name>
	<filter-class>com.ecyrd.jspwiki.ui.WikiJSPFilter</filter-class>
</filter>

and here we can see the filter mappings

   <filter-mapping>
       <filter-name>WikiJSPFilter</filter-name>
       <url-pattern>/wiki/*</url-pattern>
   </filter-mapping>
   <filter-mapping>
       <filter-name>WikiJSPFilter</filter-name>
       <url-pattern>*.jsp</url-pattern>
   </filter-mapping>

Of interest (but I don't fully understand it yet) is this definition of a servlet

   <servlet>
       <servlet-name>WikiServlet</servlet-name>
       <servlet-class>com.ecyrd.jspwiki.WikiServlet</servlet-class>       
       <load-on-startup>1</load-on-startup>
   </servlet>

which I believe is attached via this servlet mapping

   <servlet-mapping>
       <servlet-name>WikiServlet</servlet-name>
       <url-pattern>/wiki/*</url-pattern>
   </servlet-mapping>

We seem to have 2 things looking after /wiki/* ? a servlet and a filter

After reading the servlet 2.3 fcs spec. That filters come first and last, servlets in the middle.

Filter

A filter is an object than perform filtering tasks on either the request to a resource (a servlet or static content), or on the response from a resource, or both.

WikiJSPFilter does some magic, and then passes the request to Wiki.jsp#

WikiJSPFilter is java object part of package com.ecyrd.jspwiki.ui;

public class WikiJSPFilter extends WikiServletFilter

doFilter is the method of interest#

• fireEvent PAGE_REQUESTED - this is part of the event system - as of 2.5.89 I don't see any consumers of this event
• super.doFilter Call parent do filter
  • this calls doFilter in com.ecyrd.jspwiki.ui.WikiServletFilter (public class WikiServletFilter implements Filter)
  • this checks to make sure the wikiengine is running
  • call's doFilter on the filter chain (if there are more filters it calls them, else it calls the target web resource -> the serlvet ={I think})
  • calls doGet (or doPost - but in WikiServlet doPost calls doGet)
    • DefaultURLConstructor.parsePageFromURL - get the pagename from the url
    • String jspPage = m_engine.getURLConstructor().getForwardPage( req ) - build the url (getURLConstructor - get its info from jspwiki.properties or uses DefaultURLConstructor by default)
    • RequestDispatcher dispatcher = req.getRequestDispatcher -
    • dispatcher.forward - for DefaultURLConstructor returns request.getPathInfo()
• filter do the filtering
• fireEvent PAGE_DELIVERED - this is part of the event system - as of 2.5.89 I don't see any consumers of this event