wiki:DocumentationForDeveloping

Development Setup

Setting Everything Up

Requirements:

Build Kaukolu (see below). For configuration:

  • Add attribute URIEncoding="UTF-8" to the appropriate connector section in Tomcat's server.xml - otherwise non-ASCII characters in page names will break.
  • Configure Kaukolu/JSPWiki. Either:
    • Edit jspwiki.properties. All paths (search for data/) and baseURL need to be adjusted.
    • Go to http://localhost:8080/kaukolu/Install.jsp for configuration. An admin account will get created then, too. The Kaukolu installation script is not well tested though.
  • Go to http://localhost:8080/kaukolu .

Building

Hint (for DFKI-KM): To install a readily configured Eclipse, just follow the instructions on http://wiki.km.opendfki.de/wiki/HowToEclipseSchnellInstallation

Having done that, check out the project from https://kaukoluwiki.opendfki.de/repos/trunk.

There might be a problem with an AJDT library: If the library "org.eclipse.ajdt.core.ASPECTJRT_CONTAINER" cannot be found, just remove it and add the external jar-file "eclipse/plugins/org.eclipse.ajdt.core_[xx].jar" of the AJDT plugin instead ([xx] is the version number).

You have to do a little extra work though. As said before, with the new project structure in place, Kaukolu is developed independently of a specific servlet container. In particular, no Ant-buildscript is required anymore for development. Instead, a separate WTP Server-project is used to run web applications. A server project only acts as a generic container though: A concrete server runtime (i.e., a local installation of a servlet container or application server software) has to be provided in order to deploy Kaukolu in the context of the Eclipse workbench. Possible runtimes include Apache Tomcat up to version 5.5, BEA Weblogic, JBoss, and others.

By default, the Kaukolu project is linked to a Tomcat 5.5 Server-project named "Tomcat 5.5 Default Runtime". You will have to create this server project locally and adapt it to your likes. Of course you can drop this reference in favor of a custom one alltogether, too (see the WTP docs for detailed information). The next two paragraphs outline two different scenarios how to run Kaukolu in a WTP Server. Hint: By connecting a servlet container runtime to the Kaukolu project, deployment can be managed through the "Server" view in the "J2EE" perspective.

1) Installing a Tomcat runtime for the default config

If you haven't already set up a server runtime in Eclipse, do so by visiting 'Window --> Perferences --> Servers --> Installed Runtimes' and click "Add". Follow the instructions on the screen to create a new Tomcat 5.5 server runtime definition. The server has to be named "Tomcat 5.5 Default Runtime". The next step is to connect the newly defined runtime to the Kaukolu server project. Do so by opening the "Servers" view and create a new server instance by right-click --> "New" --> "Server" --> "Apache Tomcat v5.5 Server" --> "Finish". Then add the kaukolu project to the server by right-clicking on the newly created server --> "Add and remove projects". Now, add the kaukolu project.

2) Installing an all different server runtime

You may also decide to run Kaukolu in a servlet container or application server other than Tomcat. This means however, that you have to create an all new server project and modify the Kaukolu project to link to that new server configuration. To create a new server project, run the server wizard from 'File --> New --> Project' and follow the instructions. You now have to a) tell Kaukolu to associate to this new server project and b) tell the new server project to manage Kaukolu as one of its web applications. For a), open the project properties window and select the 'Server' pane. From there you can define to which server project Kaukolu is associated. As for b), if you haven't already told the server to manage Kaukolu as one of its web apps during the server creation wizard, double click the server project in the navigator or from the Server view and select the "Modules" tab. Select "Add Web Module", select Kaukolu and set the document base and path to 'kaukolu' and '/kaukolu' respectively. You're done now.

Hints

Here are some useful hints I discovered while working with WTP:

Server Timeouts

When debugging Kaukolu in Tomcat, you may occasionally get messages about the server being restarted due to a timeout. This is because Eclipse thinks the server would hang (yeah, not very smart), but you can easily fix this by disabling server timeouts: Go to 'Window --> Preferences --> Server --> Server Timeout Delay' and set it to 'Unlimited' (or at least a sane value).

Tomcat Debug Mode Bug

Enabling the 'debug' mode in the Tomcat server settings does NOT work. Actually, it will even break your run configuration, because WTP inserts the '-debug' flag in a wrong position thereby breaking the start procedure. As if this wasn't already enough, there is a second bug related to this: Disabling debug mode again using the graphical Server editor will NOT revert the changes (it will actually do nothing). You have to manually edit your run config and remove the offending flag. Bottom line: Don't fiddle around with this setting, it will only make things worse. I heard that this will be fixed in the upcoming WTP 2.0 release.

Server Working Directory

If you wonder where WTP deploys your web apps: workspace/.metadata/.plugins/org.eclipse.wst.server.core/tmpX

Terminating Tomcat after Eclipse Crash

If Eclipse/WTP should crash while a server was running (which happens every so often) , it will not be correctly terminated but continue to listen for requests. When restarting Eclipse and trying to restart the server, you will therefore get an error message indicating that a process is already listening on the respective port. To manually shutdown Tomcat, telnet to 'localhost 8005' and say 'SHUTDOWN' (all upper case). This will terminate Tomcat and you can start it using Eclipse again.

Stability/Out-of-memory Issues

It may happen that you experience frequent crashes with Eclipse and WTP, which as I observed are probably a result of out-of-memory situations. Eclipse itself is very resource hungry and installing yet another toolset with WTP can make for a sluggish and unstable experience. The problem is that the JVM Eclipse runs in is only granted a certain maximum amount of your RAM, but the default settings are rather conservative here, so you may want to grant Eclipse a couple hundred MBytes extra memory.

You basically have to consider two types of memory pools: The heap space and the perm space. The latter is used to store static information such as classes themselves. Remember that only because you're not getting any explicit out-of-memory errors doesn't mean you don't have resource problems. Since I changed my settings to grant Eclipse a fixed 768 MBytes of my precious RAM, it runs much more stable.

To do that, go to your Eclipse directory and edit eclipse.ini. Each line takes a VM argument, so in order to grant Eclipse 128MB perm space and 512MB heap space, edit it like this:

-vmargs
-Xms512m
-Xmx512m
-XX:PermSize=128m
-XX:MaxPermSize=128m 

You can set the min/max values to distinct values of course, but chosing a fixed value for both eliminates memory resizing. If you want to keep an eye on memory usage, go to 'Preferences --> General' and activate 'Show Heap Status'. A toolbar widget will appear showing the current memory consumption and a small trashcan icon which allows you to trigger the garbage collector manually.

Known Issues

JAR signing

Because JSPWiki uses custom Permission classes which -- under certain circumstances -- have to be loaded at runtime, JSPWiki usually signs the JAR file it produces with a self-issued certificate in its build.xml deployment script. This is a problem for us, since we don't have a build script anymore, at least not for development. Since using certificates during development seemed pointless anyway, I removed all 'signedBy' references from jspwiki.policy. However, if we need to deploy Kaukolu outside Eclipse, we will have to write a build script which performs this JAR signing. Such a script does not yet exist.

JSP debugging

For some strange reason, debugging JSPs does not seem to work for me. Please tell everyone if you experience the same problems or find a solution.

UPDATE: I discussed this issue on the WTP mailing list, and I found a partial solution which at least lets you finally debug JSPs and custom tag implementations. The problem for me was that a) simply setting breakpoints in a JSP and starting the server does not work and b) explicitly saying "Debug on server" in a JSPs context menu threw an error at me indicating that "the current selection is not within a valid module". As I have learned on the mailing list, this error message means that WTP can't associate the JSP with a web module as connected to a Server project. This is a bug (which also happens in other circumstances), but there is a workaround to still be able to debug the JSP: Instead of selecting "debug on server" select "debug ..." and manually select the run config. Now all breakpoints will be correctly reached. I was told that the "not within a valid module" bug only appears when selecting "debug on server" through the editor context menu. It should work however when doing the same through the navigator on the left hand side of the workbench.

History

  • Kaukolu has been ported to WTP in the beginning of 2007. Read more concerning changes on WebToolsPlatformNotes.
Last modified 8 years ago Last modified on 11/30/09 10:38:49