Fork me on GitHub

Migrating JEE Servlet Application to OfficeFloor

This page describes the steps for migrating an existing JEE Servlet Application to run within OfficeFloor.

The steps focus on maintaining a working application throughout the migration. This is both to reduce risk and allow stopping at any point once enough incremental value is obtained from using the benefits of OfficeFloor.

Difference between JEE and OfficeFloor

The following background provides necessary context to better understand the reasons behind the migration steps. The main aspect to understand is that OfficeFloor provides more threading flexibility than a JEE Application Server and the resulting implication for accessing dependencies.

To be a compliant JEE Application Server, the Application Server must adhere to the thread-per-request architecture. This allows the use of ThreadLocal to provide access to the necessary dependencies (i.e. DataSource, EntityManager, Queues, EJB, etc). For example to maintain a transaction across multiple EJB's the same java.sql.Connection must be used. The JEE Application Server typically achieves this by accessing the java.sql.Connection via a ThreadLocal and as it follows a thread-per-request architecture everything works nicely together.

The thread-per-request however is a constraint as blocking I/O and long polling (Comet) tie up threads and at worst case leave no threads to service further requests. The Servlet AsyncContext has been added to reduce the impact of this constraint however it continues to rely on ThreadLocal access to dependencies. The result is that some flexibility is now available however the change has only increased the logical number of thread pools from one to two.

OfficeFloor has a thread-per-function architecture releasing it from the constraints of the thread-per-request architecture. OfficeFloor therefore can use as many thread pools as is necessary for the application and will allow the execution of each function (Job) to be by an appropriate thread pool. This however means that OfficeFloor no longer relies on ThreadLocal access to dependencies but rather manages this separate of the thread (see the Thread Injection tutorial for further details).

As OfficeFloor no longer uses ThreadLocals for access to dependencies, this needs to be taken into consideration for running OfficeFloor (WoOF) applications embedded within a JEE Application Server. The migration steps focus on tackling this incrementally so value is obtained after each step.


Step 1: WoofServlet

Introduce the WoofServlet into the JEE Servlet application to start using WoOF functionality.

The WoofServlet tutorial provides further details.

Benefit : Able to use WoOF templates along with the Eclipse plug-in for visual configuration.

Step 2: Accessing JEE dependencies

It is likely that functionality is contained within existing EJB's dependencies and as described in the background accessing dependencies is the underlying difference between JEE and OfficeFloor.

However it is also likely not feasible to migrate the EJB functionality in one step.

To allow an incremental migration and refactoring, the WoofServlet is able to access and use EJB dependencies. See the WoofServlet Dependency Injection tutorial for further details.

Benefit : Able to use existing Servlet / EJB functionality without change to build out WoOF templates.

Step 3: Using OfficeFloor dependency injection

At this point the migration of Servlets and EJBs by refactoring to WoOF templates and Managed Objects may occur. Typically pick an EJB one at a time and migrate the associated Servlets that use it to WoOF templates. The order of EJBs to migrate would typically be those with least dependencies first.

The EJB may be:

By the end of this step OfficeFloor is managing the dependencies for the application.

Benefit : Able to migrate to OfficeFloor (WoOF) dependency injection in small incremental changes.

Step 4: Running within OfficeFloor

Now that OfficeFloor is managing all the dependencies, the application may now be hosted within OfficeFloor.

There however may still be Servlets / JSPs that have not been migrated to WoOF templates (or for that fact is not beneficial to migrate). To enable re-using these within OfficeFloor, a WoOF extension is provided to run a Servlet container. Further details can be found in the WoOF Servlet Container tutorial.

Benefit : WoOF functionality can now take advantage of the threading flexibility of being run within OfficeFloor.

Step 5: Going beyond the thread-per-request limitations

Now that the application is hosted within OfficeFloor, the application is free of the thread-per-request limitations. This enables tuning threading to the hardware/environment leading to servicing a larger number of concurrent clients per server which subsequently allows for more ambitious solutions.

Benefit : Application can use Thread Injection.


Please see the other tutorials for further features of OfficeFloor.