ERXCompilerProxy

(c) 2001,2002, Anjo Krank (ak@prnet.de), all rights reserved

About

Ever got tired of the long time WO 5 takes to rebuild your project after every tiny change you make? Ever got really tired because you had to build/install those frameworks every ten minutes? Not afraid of living on the edge? Then this hack is for you!

ERXCompilerProxy is a class that creates a rapid-turnaround mode for WebObjects 5 for Java similar to how you use WebScript with WO 4.5.1. Instead of recompiling your Application or Frameworks, you simply change the source code in question and reload your page. In some cases, you may also have to restart your Application but you won't have to rebuild it.

ERXCompilerProxy is especially well suited for DirectToWeb applications. The restrictions of Java's classloading are partially compensated by the highly dynamic nature of D2W apps.

Installation

Check if you have jikes installed in /usr/bin.

Usage

To use this framework you must complete a few easy steps and you will very seldom have to rebuild or even restart your project again:

• Add ERExtensions.framework and ERJars.framework to your project. You do not need to add the ERExtensions.framework to your framework projects if you only want to use the ERXCompilerProxy, but you need to add it to the application.
  
• In your ~/WebObjects.properties file add a line

  er.extensions.ERXCompilerProxyEnabled=true

• Then either create a file named CPFileList.txt in your project's and your framework's root directory. This file should contain lines with "./project_relative_path_to_Someclass.java:package_of_SomeClass_or_empty<return>" for every file you want to get recompiled.
  
• or create a new shell build phase right after the "Frameworks & Libraries":
  1. Set the current target to your app
  2. Click on "Files & Build Phases" tab
  3. Choose "Project/New Build Phase/New Shell Script Build Phase" from the Menu and drag the build phase right after the "Frameworks & Libraries"
  4. Insert the code

     sh "${TARGET_BUILD_DIR}/ERExtensions.framework/Resources/InstallCompilerProxySupport.sh"

  Now, everytime you build this project, every source file directly under the project directory will be put into the CPFileList.txt file.
  

What it does

The ERXCompilerProxy does several things to works it's magic. First, on startup, it registers for the ApplicationDidFinishLaunching Notification. When the App starts, it reads the CPFileList.txt files from your currently opened projects to find out about the files to watch. So remember to have your framework projects open in PB.

It also registers for the ApplicationWillDispatchRequest Notification, which gets triggered whenever a page is requested. It tries to compile the files that have changed and throws an Exception describing the errors if there where any and then aborts further handling of the request - you will get an error from your browser. However, if everything went well, it creates a new ClassLoader and throws away the component definition cache and a few other things. Then, when the next "pageWithName" is called, the updated class will be used.

This is slightly different from how WebScript handled things. In Java, you simply can't change an Object's class implementation at runtime - so if you already have a page (or any other Object) this object will not use the newer class. Only Objects created after the compilation will have new behaviour.

The freshly compiled files will be put into your App's Resources/Java directory into the proper package hierarchy. So, if you simply restart your App, the newer files will be used. When you re-build your project, your normal .jar will contains the correct classes anyway.

NOTE: Since all new class files end up in Resources/Java, when you clean-build your App, you also need to recompile your frameworks when you have changed classes there! A normal build will not delete the files, so recompilation of the frameworks is not needed.

Knows bugs and limitations

• Since Java can't redefine objects, the new code will get used only for new objects. You may either have to reload multiple times or start a new session to get things to work.
• You may see an error "IllegalAccess in KeyValueCodingProtectedAccessor". You will probably have defined a new variable in your component with protected access. Either set the scope of the variable to public or restart your app. The number of these messages is greatly reduced if your components and EOs are in a package hierarchy and you have a KeyValueCodingProtectedAccessor subclass for this package.
• You must have the respective projects opened in Project Builder. If you don't, ERXCompilerProxy can't find the sources. Alternately, you can set the NSProjectSearchPath argument.
• You must reload after making changes and before stopping your application, because the file modification times are read only at start. If you stop the application before reloading, your last changes will not be recognized.
• If you change a class in a framework, the compiled file still ends up in your app's Java/ directory. This is intentional, but means that you should clean-rebuild your app if you rebuild your framework.
• Changes in the Application class (among others) will not be recognized before a restart. They are only read once, due to the nature of Java's class loading and can't be fixed. If you cache your classes, you need to register for CompilerProxyDidCompileClassesNotification and reset the cache when you recieve it.
• If you make changes in your EO's classes, you should definitely restart your application after pressing reload. You may seriously mess up your data if you have a mix of previously instaniated Objects and new ones.
• Try not to use casts, use WOComponents and KeyValueCoding instead. Say you have a List page and a Detail page and you change the Detail page. Further you have code like:
  

      public WOComponent detailsAction() {
      	Details newPage = (Details)pageWithName("Details");
      	newPage.setObject(currentObject);
      	return newPage;
      } 

  
  This doesn't work because List and the reference to Details is in the old class loader, but pageWithName() instantiates from the new class loader. Rather use this code:

      public WOComponent detailsAction() {
      	WOComponent newPage = pageWithName("Details");
      	newPage.takeValueForKey(currentObject, "object");
      	return newPage;
      } 

Of course, this code is highly experimental. It may toast your goldfish for all I know, so you are on your own if you run into trouble.

Version History

24/07/07 - 1.4 included in ERExtensions, renamed to ERXCompilerProxy.

12/06/01 - 1.3 fixed several bugs, added framework turnaround support.

07/26/01 - 1.2 fixed several bugs, vastly simplified installation. Removed the need to clean your project.

07/08/01 - 1.0 initial release