Using the Command-Line Interface
We previously mentioned one challenge when building web applications: the offline generation of web sites. You start a process, and this process builds the whole web site into a directory. You can then put it on your web server or on a CD.
This generated web site then does not need sophisticated software components on the server to run. It only needs a simple web server that can serve static files from the filesystem. All the real work is already done in the generation process.
That's where Cocoon's Command-Line Interface (CLI) comes into play. You can utilize it to generate a whole web site. This might seem like a great idea, but there are limitations. You can generate an offline version only if the content conforms to certain rules.
All the documents need to be static, which means that each time a document is requested, the content should be the same. For example, if you want to create a document that always displays the current stock account, this cannot be generated for offline viewing. If your documents are personalized, this is not possible with offline generation either.
So if you look at the challenges for current web applications, there seem to be only rare cases in which offline generation is really useful.
The Cocoon CLI can be used for other purposes as well. Invoking the CLI is nearly the same as requesting a document from Cocoon using the servlet engine. For example, it could be used to generate invoices offline as PDF files. Rather than having someone invoke a web page that generates bills, save them to disk, and then mail them to the customers, you can write a script that is invoked periodically to fulfill the same task using the CLI.
We have shown you how the Cocoon documentation is built using Cocoon itself. In addition, the Cocoon developers use the CLI to generate this documentation and put it on the Apache web server. All the offline generated images and HTML files must be put on the server, because it currently does not run a servlet engine where Cocoon could be installed. Listing 6.23 shows the Cocoon CLI.
Listing 6.23 Cocoon's Command-Line Interface
Usage: java org.apache.cocoon.Main [options] [targets] Options: -h, --help print this message and exit -u, --logLevel <argument> choose the minimum log level for logging (DEBUG, INFO, WARN, ERROR, FATAL_ERROR) for startup logging -c, --contextDir <argument> use given dir as context, this defaults to ./webapp -d, --destDir <argument> use given dir as destination -w, --workDir <argument> use given dir as working directory -r, --followLinks <argument> process pages linked from starting page or not (boolean argument is expected, default is true)
The CLI is implemented by a Java class (org.apache.cocoon.Main). So the CLI is started by starting this Java class. Because this class is contained in a JAR file, the command looks like this if you are inside the directory where all JAR files for Cocoon are stored: java -jar cocoon.jar followed by the options.
The most important option is -c. It defines where the Cocoon context directory can be found. This directory must contain cocoon.xconf. With the option -u, you set the log level. The destination directory (option -d) defines the location where the generated documents are stored. The work directory holds temporary files (option -w).
After the options, you define the documents you want to generate. Cocoon then processes these documents one after the other and saves them to the destination directory.
If followLinks is turned on (which is the default), Cocoon processes not only the documents you gave as input but also all documents referred by this one. So it crawls the whole web site. This is in fact used for the Cocoon Documentation System. Only the starting URL is specified (index.html). Because this document includes the navigation bar, all other documents are referenced by this document.
The crawling is done using views. The CLI first gets the link view of a document. This returns all the document's links and references (including images). Then the document is processed and saved to the destination directory. Afterwards, all collected links are processed, one after the other. Of course, the CLI makes sure that each document is processed only once and that no infinite recursion occurs.
After the CLI is finished, you have the whole web site in your destination directory. This includes all HTML documents, all images, all rendered SVG graphics, and so on. You could then copy this directory to a CD or to a web server for publishing.
For your first steps with Cocoon, the CLI might not be that important, but as you learn more and more about Cocoon, sooner or later you might need it. But you don't have to worry. Just start creating your own web site, documents, and so on and learn the Cocoon way. The following practical examples and tips will help you build more-advanced applications with Cocoon.