XMLC 2.2 Release Note

New features in 2.2

Note on Page Reloading

Page reloading in XMLC has gone through several different revision. The following is trying to clearify how XMLC handling the page loading.

Note on Setting up Deferred Parsing

This is a step by step instruction to set up the build and deployment environment to utilize deferred parsing reloading.

  1. Compile the pages with '-for-deferred-parsing' argument for XMLC.

    For those who's using XMLC taskdef, add this to your options.xmlc file and supply the task with the path to this file in the "options" attribute or use the <arg> in the xmlc task.

    
    	  <xmlc ...>
    	     <arg value="-for-deferred-parsing"/>
    	  </xmlc>
    	

    In addition to the class/java file for the document, XMLC will also generate a '.xmlc' files for per file meta files. These generated .xmlc files are placed in the same location as the class files unless the source is kept, in which case, they are placed in the same location as the generated source files.

  2. Replace org.enhydra.xml.xmlc.XMLCStdFactory

    The deferred parsing is performed by the new factory class org.enhydra.xml.xmlc.deferredparsing.XMLCDeferredParsingFactory. XMLCDeferredParsingFactory extends XMLCStdFactory and should be a drop in replacement in the existing codes.

    It should be noted that XMLCStdFactory object only serves as a document class loader and document object initializer while XMLCDeferredParsingFactory perform additional caching operation on the parsed html pages. If the program creates a new Factory object to load documents every time, it should be changed to share Factory to avoid performance penalty while using reloading.

  3. Deploying HTML pages.

    The new Factory requires locating the HTML pages used to generate the XMLC document class. This would probably be the most confusing part for the reloading.

    The following is the search argorithm of the html pages

    1. Load from configured resource paths by default and fall back to the classpath if the files are not found

      it's using the original file name in the package directory of the class. For example, foo.html is compiled to com.foo.bar.testHTML. By default, the Factory is looking for the file at com/foo/bar/test.html relative to the configured resource paths or the class path. The generated file com/foo/bar/testHTML.xmlc will also be searched for. Both the markup and .xmlc files are required to exist for deferred parsing reloading to work.

      Because you might not always want to manually configure resource paths (see below), it is a good idea to provide for loading resources from the classpath as fallback. As such, you should copy markup source files and the generated .xmlc source files to the package in which your XMLC classes are compiled. However, the advantage of configuring resource paths is that you can update the markup and generated .xmlc files at runtime, where you generally don't have access to changing files in the classpath. Read on for information on this...

    2. Additional configuration

      • addPackagePrefix(String pkg)

        this adds a package prefix to be stripped while searching for markup and generated .xmlc files. This has the reverse effect as the packagedir in the XMLC taskdef. It takes out the prefix from the path of the markup file.

        For example, if com.foo is added as a package prefix, the Factory willl search for com/foo/bar/test.html as well as bar/test.html.

      • addResourceDir(String dir)

        Add additional directory to search for the markup and generated .xmlc files.

Note on Setting up Dyanmic document loading

A new method createFromFile(String path) has been added to the XMLCDeferredParsingFactory. This method lets the program to load xml/html pages into the system as org.w3c.dom.Document/org.w3c.dom.html.HTMLDocument wihtout having to pre-compile them using XMLC. For example factory.createFromFile("bar/test.html") will try to load the document from resource directories as well as the class path.

Dynamic loading of new page requires a meta file to be spcified using the setMetaDataFile(String path) of the factory. Searching for the meta file follows the same rule as the xml/html files. Obviously, there are no generated .xmlc files to be searched for here as there are in deferred parsing reloading.