Resolve class conflict while deploying XMLC in environment containing Xerces implementation such as Tomcat and Ant.
XMLC reloading has been removed in 2.1 release due to its dependency on servlet containers. Richard Kunze has created a new paradigm for reloading based on deferred parsing. This change is independent of the containers.
The word reloading has been a confusing term regarding to XMLC. This note is trying to clearify the subjects.
The document of how to use the taskdef can be found in Java docs for org.enhydra.xml.xmlc.taskdef.XMLC. Thanks to Barracuda team.
Deferred parsing has been extended to load XMLCObject from *ML documents without compilation.
XHTML support has been improved including bug fixes and flexible OutputOptions to deal with certain browser quirks (See the OutputOptions javadoc for info). Note that quirks are off by default.
The dtd's have been updated including support for compiling against w3 XHTML1.0 (Strict, Transitional, and Frameset, and Basic), w3 XHTML1.1, wapforum 1.0 and 2.0, and openwave (the last two of which are reformulations of the original WAP standard in XHTML). Note that XMLC's XHTML support is based on the w3 XHTML1.0 dtds and the others haven't been very well tested.
Note that XMLC's proprietary wireless and xhtml dom implementations may be deprecated in the future in favor of something more standardized such as that provided by the HTML DOM Level2 spec. Unfortunately, there is no current implementation of this yet. Hopefully Xerces2 will support this soon!
There are also some new convenience '-dom' switches for using different dom factories. These include "generic", "xerces", "lazydom", "xml", "chtml", "voicexml", and "xhtml". The switches match up with the <documentClass> "domFactory" attribute and -domfactory flag for the various markup document types. Note that for those document types that have a couple different factories, the shorthand keywords only match up with one of them such as "xhtml" matching up with org.enhydra.xml.xhtml.XHTMLDomFactory instead of org.enhydra.xml.xhtml.HTMLDomFactory. Use -domfactory if -dom doesn't meet your needs.
There is a new flag called -ssibase which allows for resolving of ssi include paths to a specified physical directory of your choosing. This was contributed by Diez B. Roggisch. Thanks Diez!
There are 3 example applications demonstrating how XMLC can be used
Dynamic loading is experimental and is demonstrated in this example.
XMLC in a servlet environment is demonstrated in this example. Both deferred parsing and dynamic loading are utilized. The ease of use of XMLCContext is shown off and the setting up of external resource directories and the default meta data file via web.xml configuration is elucidated.
XPath support is under development. The examples directory has an example of XPath which shows how to query and modify the dom using the latest versions of JAXEN and JXPath.
Page reloading in XMLC has gone through several different revision. The following is trying to clearify how XMLC handling the page loading.
This is the default implementation of XMLC. It compile the *ML files into Java object with concrete codes/methods to build the DOM tree at runtime. New pages have to be recompiled and applications have to be restarted for the new presentation to take effect.
This is a feature specific to Enhydra Application Server. The page from which the Java PO is compiled from are monitor and, up one the update of the page, the system would perform the recompilation and reloading of the PO. This feature has been used in Enhydra Application Server but the feature was removed in XMLC 2.1 Standalone. In 2.2, this feature is replaced by the Deferred parsing reloading described below.
This is the new feature introduced in XMLC 2.2 to support runtime reloading of updated *ML files. Deferred parsing compiles ML files and creates stub PO objects to hold meta info about the documents to be processed. The document is parsed and loaded into system as DOM upon the request for the object. The ML files are monitored and reparsing/reloading is performed when the files are updated. See this note on setting up deferred parsing.
This is an experimental new feature introduced in XMLC 2.2. This feature allow XMLC runtime to load *ML files without prior compilation of the ML files. Additional note can be found here
This is a step by step instruction to set up the build and deployment environment to utilize deferred parsing reloading.
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.
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.
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
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...
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.
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.