XMLC Automatic Recompilation

Automatic XMLC re-compilation enables you to change the HTML in a web application at runtime. So if you want a new look on a page, you can swap in a new HTML page. The application detects the new timestamp on the file, recompiles the page, and uses it in the application. Configuring autorecompilation to work is also simple once you understand the details behind it.


What the Options Do

There are three ideas you need to understand to make recompilation work.
  1. The application cannot deploy in a jar file.

  2. Enhydra applications typically deploy as a single Java Archive File with all of the necessary classes. However, updating a jar file at runtime with new classes does not make sense, so the application's classes must be in a regular directory structure. The root directory is defined in with the directive Server.ClassPath[] = ./lib/classes in the app.conf file. The he HTML files must be in the same directories as the corresponding compiled java classes. The good news is that this is all handled for you by setting the option XMLC_AUTO_COMP=YES in config.mk . After compiling look for the directory app/output/lib/classes to make sure the XMLC_AUTO_COMP option generated the classes directory under output/lib.

  3. Pages must be instantiated with the xmlcFactory. In general, XMLC page objects can be instantiated with either new or the xmlcFactory as shown in the following code:
  4.  WelcomeHTML welcome = new WelcomeHTML();
     WelcomeHTML welcome = (WelcomeHTML)comms.xmlcFactory.create(WelcomeHTML.class);
    However with autorecompilation, you must instantiate a page with the create method of xmlcFactory. The factory does the work of checking the timestamps on the files and recompiling an HTML page if it has changed. Note that the factory must work with interfaces not directly on Java classes. Taking the example above, Welcome.html must be compiled with an option so WelcomeHTML.class is an interface not a class. So Welcome.html has an interface WelcomeHTML.class, and an implementation of that interface in WelcomeHTMLImpl.class. The options to generate interfaces are described below. On a final note, it's a better programming practice to always use xmlcFactory to instantiate pages. By default, it simply does a new on the page, and using it gives you the option of turning on recompilation or other factory features at a later date.
  5. Either the class file or HTML file can be updated at runtime.

  6. Consider the following :

    1. The source HTML file is compiled . . . .
    2. into a Java class file that is . . .
    3. loaded by the server at runtime.
    To replace the Java class representing a page at runtime, you can replace either the original HTML file or the class file compiled from the page. For example, a running application has loaded WelcomeHTMLImpl.class. To change the look of the page it generates, you could either replace the file Welcome.html or recompile Welcome.html yourself and replace the file WelcomeHTMLImpl.class.

    The options you specify in config.mk and app.conf reflect these two possibilities. To only reload classes invoke XMLC with the -generate both option. This generates both an interface and an implementation class. To reload from classes and HTML use the XMLC option -for-recomp. This option tells XMLC to generate an interface, an implmentation class, and an *.xmlc file. The *.xmlc file includes the options used to compile the page so the same options are called when it is dynamically recompiled.

    There are also options set in app.conf to turn on reloading and recompilation at runtime. Specifiy Server.AutoReload = true to enable class reloading and Server.XMLC.AutoRecompilation = true to enable both class and page reloading.

    Note that the autorecompilation capability comes at the cost of checking the timestamp on either the class file or the class and HTML files each time the page is instantiated at runtime.

An Example

This example demonstrates how to configure autorecompilation. It is written against the 3.0 version of Enhydra. Create a new application called testApp with newapp.

By default, the application creates a new WelcomeHTML object using the xmlcFactory class. The option XMLC_HTML_OPTS += -generate both is set in the file config.mk. To use the old-style new operator, comment out the XMLC_HTML_OPTS line in testApp.conf and replace the xmlcFactory code with the new code in Welcome.java. Verify it works and run make clean.

To implement page recompilation, you may want to see the classes XMLC is using. Run xmlc on the command line with the -for-recomp option on Welcome.html with the following command:

xmlc -keep -class WelcomeHTML -for-recomp Welcome.html
You will see the following generated files:
Welcome.html ( the original file )
WelcomeHTML.java ( the text version of the interface )
WelcomeHTML.class ( the class file for the interface )
WelcomeHTMLImpl.java ( the text version of the interface implementation )
WelcomeHTMLImpl.class ( the class file for the implementation )
WelcomeHTML.xmlc ( an options file for future compilations )

To run the example do the following:

  1. Set the code in Welcome.java to use the xmlcFactory syntax like it does by default.
  2. In config.mk, set the option XMLC_HTML_OPTS += -for-recomp .
  3. In config.mk, add the option XMLC_AUTO_COMP=YES. Be sure to spell it exactly. Even a blank space after the YES will throw the compiler off.
  4. In testApp.conf set Server.ClassPath[] = ./lib/classes .
  5. In testApp.conf add Server.XMLC.AutoRecompilation = true .
  6. Run make clean and then make .
  7. After starting the application, test the functionality by adding a word like "howdy" in the body section of testApp/output/lib/classes/testApp/presentation/Welcome.html. Hit shift-refresh on your web-browser and you should see the changes.