Using the NetBeans Platform on the Server with Wicket on the Client

Step 1: Prepare the Wrapper Modules

Since you are going to completely develop a web application as a componentized NetBeans Platform application, all of the required libraries and frameworks need to be placed in NetBeans Module Wrappers. These are the ones I prepared for blueOcean (you can see them in the Libraries folder):

1. ServletAPI (servlet-api.jar) for the basic web functions.
2. Wicket and WicketExtensions for the Wicket framework.
3. JSR311, Jersey and Jettison for REST features (plus JSON support).
4. Milton for the WebDAV interface.
5. Libraries required by the above listed stuff (e.g. SLF4J, ASM, GlazedLists, Apache Commons Fileupload etc..., as specified by each framework documentation).

Be especially careful in step #5, that is, make sure that all the dependencies are satisfied (so, for instance, the Wicket Module declares a dependency on SLF4J, Jersey on JSR311 and ASM, etc), otherwise you'll get some ClassNotFound exceptions / errors that can be tricky to understand (they will refer to classes that actually are in the classpath, but have missing dependencies).

For reasons that will be explained soon, you need an extra thing for each framework: any framework-relevant Servlet or Filter (usually one per framework, described in their documentation) must be registered as a META-INF service. To accomplish that, you need to create a META-INF/services directory with the following files (for Wicket, Jersey and Milton):

org.apache.wicket.protocol.http.WicketFilter

com.bradmcevoy.http.MiltonServlet 

com.sun.jersey.spi.container.servlet.ServletContainer 

Each file must be composed of a single line containing the same text as the file name. 

Step 2: Develop Your Application

Now you can create your application as usual, using the required APIs as appropriate. That is, for creating the User Interface you create new Modules that declare a dependency on Servlet API and Wicket, and so on. A potential source of troubles is where to place the HTML files for the UI: with Wicket (that I like for many reasons, including the one I'm telling you now) they can stay in the same folder as .java sources and get packed into Java binaries, since they will be accessed at runtime as resources. I didn't investigate other scenarios, for instance JSPs, where the web pages must be placed in a specific directory separate from code.

Step 3: Create a Web Application Wrapper

Now, the most interesting part. You need to create the "glue" between Tomcat and your Platform based application; and since I like to do things in the standard way, I like to have this glue to take the form of a regular .war application, that can be deployed as usual. Keep in mind that you have many variants: the .war could be all-inclusive, that is it would include your application AND the platform, or it could merely point to a platform that is placed in some other place. The latter solution, for instance, would allow to add and remove modules by means of the NetBeans Update Centers, instead of redeploying a new .war. It's up to you. As a starting point, and also because at the moment I don't need Update Centers, I've gone the way of the all-inclusive .war file.

The basic point of "glueing" is about class loaders: both Tomcat and the Platform have their own class loaders. How to connect them? The lucky thing is that the interface between Tomcat and a Web Application is mainly composed of only two things: Servlets and/or Filters. Most of the web frameworks around just need to declare a Servlet or a Filter in the web.xml file, and those components will act as a single "front controller" from the framework.

So my solution is to provide a pair of universal decorators (a Servlet and a Filter) that create a bridge between the two worlds. I've put them in a very small JSE library that, as you'll see later, just needs to be included in a .war project and configured (the sources can be checked out from https://blueocean.dev.java.net/svn/blueocean/trunk/src/NetBeansPlatformWebAdapter, revision 11).