Please direct all discussion about this page to the jspwiki-dev! This page should reflect the current state of the design, so please do not add any discussion to this page. Any attempts at discussion shall be deleted promptly.
The contents of this page are still very much subject to change, even though some of the language is rather assertive. But it is really meant to be a specification - or an internal notebook - to us developers.

Backend change#

The backend will be replaced by JSR-170. This means roughly the following changes are needed:

  • PageManager shall still stay as the main interface into the underlying repository. PageManager shall own the Repository object.
  • AttachmentManager will still provide some features (like DynamicAttachments), but mostly all access to the Repository should go through the PageManager.
  • WikiPage shall become an interface. A new class, WikiNode, will implement the javax.jcr.Node interface as well as the WikiPage interface. The Node will redirect directly to the internal Node.
  • WikiPage will gain a number of new methods, including String getContentType(). Regular JSPWiki markup will be denoted as text/x-wiki.jspwiki; WikiCreole as text/x-wiki.creole. According to this information, RenderingManager is then able to figure out which Renderer to use.
  • Attachment shall also be an interface, extending from the WikiPage IF
  • WikiNode shall also implement the old Attachment interface.

Open questions#

Should the WikiPage still stay a concrete class? That might help in some cases, actually.

Renderer separation#

One of the main tasks in 3.0 is to make sure that the Renderer can be embedded separately. Currently, this is not really possible due to the tight coupling of the WikiEngine and JSPWikiMarkupParser. Also, there is a problem with plugins, which expect to get a handle to the WikiEngine object.

Therefore, it makes sense to make WikiEngine and WikiContext an interface, which can therefore be implemented by others.

The good thing is that this means that since WikiEngine and WikiContext become interfaces, it’s going to be a lot easier to stabilize their APIs and provide a better toolkit to 3rd party developers a nice development interface. The roles of the different classes shall therefore be

  • WikiEngine shall provide the interface to the permanent state of the system. It provides methods like getPage(), putPage(), pageExists().
  • WikiContext provides the current state of the request, which is being processed.
  • WikiPage provides access to the page and it’s content.

Some changes#

Previously, getting the page content happened with WikiEngine.getPageText(). In 3.0, page content is an attribute of the WikiNode (or WikiPage). There will be a convenience method for getting the page content getText(), (and getHTML()) but it's fine to call the new getProperty("wiki:content") as well, but you will need to figure out the proper type.

As WikiContext will no longer be instantiable, there needs to be a WikiContextFactory (or something similar, WikiActionBeanFactory?) for getting yourself a new WikiContext.

New templating engine#

TBD by Andrew; see JSPWiki3.

Repository Content Model#

Each WikiNode is represented by one JCR Node in the Repository.

MultiWikis aka WikiSpaces#

With 3.0, JSPWiki should finally gain the ability to host a number of wikis (in this case, called WikiSpaces) from a single WikiEngine. JSPWiki also gains the ability to do subpages, which is conceptually a different thing. For example, attachments are currently for all intents and purposes subpages - it's just that they're not wiki markup! Subpages should nest indefinitely.

There will be two fixed WikiSpaces, while the others are reserved for free use.

  • System The system wikispace will house a number of default pages, like System, LoginError, TextFormattingRules, etc. If we can figure out a way to localize these pages properly, then we could provide localized content.
  • Main The main wikispace is the default space in case there is no wikispace in the request defined. This is to provide URL compatibility. (This should probably be settable.)
URLs should be in the form $baseURL/Wiki.jsp?page=<space>:<page>/<subpage>. For example: System:System/attachment.jpg. Or, Main:Information/MoreInfo/ArbitraryPage.

The intent is to make sure that WikiSpaces are unique even across all WikiEngines which share the same repository. This allows relatively simple page identifiers of the form <space>:<page>, which should be independent of the actual WikiEngine (therefore hopefully being more amenable to e.g. load-balancing).

Structure of the repository#

JSPWiki will use a single Workspace for all its WikiSpaces. The name of this Workspace shall be user-configurable, but by default, it is "jspwiki". In the Repository, the structure will look something like this (Arbitrary <x> are just additional WikiSpaces):

  • jcr:system - the regular JCR storage
  • System - the System WikiSpace
    • wiki:system
    • System - The System page
  • Main - the Main WikiSpace
  • Arbitrary 1
  • Arbitrary 2
    • wiki:system
  • Arbitrary 3
    • wiki:system

Page properties#

The page properties RFC 4287 and existing attributes, as they are more web-savvy. As Murray is bound to ask about this - it does not appear that the Dublin Core metadata really offers anything that we could use easily, or which wouldn't have a more web-savvy version available with RFC 4287. While we should use standards, wherever possible, it seems like most of these metadata schemes are not really designed for wikis in mind. However, storing arbitrary metadata should be possible with the new content model to all developers - which should be really cool.

The "wiki" namespace will be defined as "". User-defined attributes are then stored in the default namespace.

  • atom:updated As in RFC 4287. This is a DATE.
  • atom:published As in RFC 4287. As JSPWiki does not yet support "draft" -pages, this is essentially a creation date. NB: This cannot be checked from page version #1, because that might be deleted. This is a DATE.
  • atom:id As in RFC 4287. This has some advantages, and can easily be tied to the JCR jcr:uuid. This is a STRING.
  • wiki:author Denotes the Identity of the user who saved this version of the page. This should probably be a reference to the user identity. It should also have a useful value in case the modification is done by the system automatically. This value should never be anything meaningless - in fact, I think that PageManager should throw an Exception if there is an missing attribute when saved. This is TBD.
  • wiki:creator As in atom_published, the creator probably needs to be stored separately. Though on wikipages it might not be that useful. This is TBD.
  • wiki:ipaddr The IP address where the last change occurred. The SpamFilter might then add some additional tags (in its own namespace). This is a STRING
  • wiki:content The actual content as a binary stream (BINARY)
  • wiki:contentType The MIME type of the content. JSPWiki markup shall be denoted as "text/x-wiki.jspwiki". Creole as "text/x-wiki.creole". Other types are also allowed, e.g. "text/html" or "image/jpeg".
  • wiki:acl The access control list for this page. Format TBD.
  • wiki:changenote A simple, text/plain description of the note of the change. STRING.
  • wiki:state Essentially an Enum defining the state of the page. Can be EXISTS or DELETED. Format TBD.
  • wiki:minorchange This change is minor, and should not be shown in the changelog, though an actual change has been made.

In addition, the JCR built-in types are available as well.

It is yet uncertain what the relation of the attributes SET on the wikipage is really to these attributes.


Still under discussion. While JCR does define a versioning system, it may be just too complicated for us to use. It might be easier just to use a simple "wiki:versions" subtree. The easiest way would be to define it like this


And then versioning would be simply just moving the content from one Node to other. Unfortunately, this does skip quite a lot of the property definitions of JCR, but on the other hand, their management is not really property standardized anyway, and therefore is really quite unusable (unless you want to go and tie yourself to a specific repository).

Using a separate subtree would also make it easy to optimize it in e.g. a JDBC provider.

Some new properties might also be needed:

  • wiki:version The version identifier of the current page.
  • wiki:previous The version identifier of the previous page. Might not exist.
  • wiki:next The version identifier of the next page. Might not exist.

Change tracking#

The interesting side effect of using something like JCR is that every time there is a change to a piece of metadata (not just content), it would create a new version, and would show up in the repository.

It might also be useful to adopt the TWiki way of replacing the last version on save, if the modification is no older than one hour, and the authenticated author is the same as the previous version. This prevents multiple changes from accumulating in the workspace when the user keeps pressing save.

Page deletion#

It is an interesting question how page deletion should be managed. Current proposal is to add a "DELETED" state to the page, which allows us to essentially mark the page removed from the repository - but not actually delete it. This means that page deletion would show up in the repository.

Page renaming#

It is often useful to track page renames as well. However, we need to figure out how that would be best marked in the repository.

AAA changes#

A couple of small changes: Changing the ACLs should become the job of a dedicated UI instead of typing in ACLs onto the pages, as this makes it very error-prone. I can't count the number of times I've had to go back and change the ACL because someone managed to prevent everyone from viewing the page by accident. Or, they cut-n-pasted some ACL code from a page, and forgot to escape it.

The other thing that also will need some scrutiny is how the WikiSpaces should work out their default permissions. Editing the jspwiki.policy is probably not a good idea - so maybe the policy file should be stored as an attribute in each WikiSpace?

Miscallaneous issues#

Most of these things probably won't end up in 3.0 (might end up in 3.1). Nevertheless, they're added here.

Page Templates#

It would be relatively easy to add a "page templating" function by creating a template page set in a WikiSpace called "Template". It would be very usable when rapid-deploying new websites.

Localization on the page level#

This is a bit complicated. It might make sense to define a sub-Node (e.g. wiki:translations) from the main Node to provide a translated version of a page, but that needs some complicated handling.

Referencing an URL shall stay the same, you can now prefix it just with the space name. Relative addressing is supported, so you can always say [Main] when you mean the Main page of the current wiki. If you want to reference to a particular page, use [Main:Main] to reference that.

Add new attachment

Only authorized users are allowed to upload new attachments.
« This page (revision-13) was last changed on 15-Nov-2011 11:51 by xiaochang619