Demystifying Docupresentment

It's no secret that Docupresentment (part of the Oracle Documaker suite) is powerful tool for integrating on-demand and interactive applications for publishing with the Oracle Documaker framework.  It's also no secret there are are many details with respect to the configuration of Docupresentment that can elude even the most erudite of of techies.  To be sure, Docupresentment will work for you right out of the box, and in most cases will suit your needs without toying with a configuration file.  But, where's the adventure in that?  

To get started, visit Oracle's E-Delivery site and acquire your properly-licensed version of Oracle Documaker.  Login to the e-delivery site, and accept the license terms and restrictions.  Then, you'll be able to select the Oracle Insurance Applications product pack and your appropriate platform.

Click Go and you will be presented with a list of applicable products.  For our purposes today you will click on Oracle Documaker Media Pack (as I went to press with this article the version is 11.4):

Finally, click the Download button next to Docupresentment (again, version at press time is 2.2 p5).

This should give you a ZIP file that contains the installation packages for the Docupresentment Server and Client -- somewhat cryptically named IDSServer22P05W32.exe and IDSClient22P05W32.exe.

At this time, I'd like to take a little detour and explain that the world of Oracle, like most technical companies, is rife with acronyms.  One of the reasons Skywire Software was appealing to Oracle was our creative if not confusing use of acronyms, including using multiple acronyms to refer to the same piece of software.  I apologize in advance and will try to point these out along the way, and hopefully you'll find some solace in the fact that I too must occasionally refer back to my cheat-sheet of products.  It's okay if you have a crib sheet, it can be our secret.  Here's the first entry on your sheet:

IDS = Internet Document Server = Docupresentment

Once you've completed the installation, you'll have a shiny new Docupresentment server and client, and if you installed the default location it will be living in c:\docserv. Unix users, I'm one of you!  You'll find it by default in  ~/docupresentment/docserv.  Take a few minutes to familiarize yourself with the documentation included with the download (specifically ids_book.pdf) which goes into some detail of the configuration file.  You'll be pleasantly surprised to find there's even a handy utility that provides an interface to the configuration file (see Running IDSConfig in the documentation).  As I mentioned before, I'm going to lift up the hood on Docupresentment, which means we're going to edit the file by hand!

I shall now proceed with the standard Information Technology Under the Hood Disclaimer: Please remember to back up any files before you make changes.  I am not responsible for any damage, outages, hair loss, stress fractures or anything else.  I may be guilty of bad puns, but that's about it.

Go to your installation directory, and locate your docserv.xml file.  Open it in your favorite XML editor.  I happen to be fond ofNotepad++ with the XML Tools plugin.  Almost immediately you will behold the splendor of the configuration file.  Just take a moment and let that sink in.  If you reviewed the documentation you know that inside the root <configuration> node there are multiple <section> nodes, each containing a specific group of settings.  Let's take a look at <section name="DocumentServer">:

There are a few entries I'd like to discuss.  First, <entry name="StartCommand">. This should be pretty self-explanatory; it's the name of the executable that's run when you fire up Docupresentment.  Immediately following that is <entry name="StartArguments"> and as you might imagine these are the arguments passed to the executable.  A few things to point out:

• The -Dids.configuration=docserv.xml parameter specifies the name of your configuration file.  You could change this if you like, but it's best to leave it alone.  Why?  Because, when operations personnel call in for support 5 years from now, they may have long-forgotten the original nomenclature of the configuration file, and when an Oracle Support technician asks for the docserv.xml file, the ops personnel may be left scratching their heads.
• The -Dlogging.configuration=logconf.xml parameter specifies the name of your logging configuration file (this uses log4j so bone up on that before you delve here).  You could rename it as well, but the same caveat mentioned above applies.
• The -Djava.endorsed.dirs=lib/endorsed parameter specifies the path where 3rd party Java libraries can be located for use with Docupresentment.  More on that in another post, and yes, you could change this, but see the caveat mentioned above.  Are you noticing a pattern here?
• The <entry name="Instances"> allows you to specify the number of instances of Docupresentment that will be started.  By default this is two, and generally two instances per CPU is adequate, however you will always need to perform load testing to determine thesweet spot based on your hardware and types of transactions.  You may have many, many more instances than 2.

Time for a sidebar on instances.  An instance is nothing more than a separate process of Docupresentment.  When you fire updocserver.bat (docserver.sh for you Unix folks), the process that is launched is the watchdog process, which is then responsible for starting up the actual Docupresentment processes.  Each of these processes act independently from one another, so if one crashes, it has no effect on the sibling process.  To illustrate my point in a real world scenario, consider a longboat manned by multiple oarsmen, directed by the coxswain.  If an oarsman goes overboard, passes out, or is otherwise unable to row, the rest of the oarsmen continue their work unabated, and a new oarsman is brought in to replace him, all under the watchful eye and leadership of the coxswain.  Such is the relationship of thewatchdog service and the Docupresentment instances.  In the case of a crashed process, the watchdog will start up another instance so the number of configured instances are always running.  The bottom line is an instance is a single Docupresentment process.

And now, finally, to the settings which gave me pause on a not-too-long-ago implementation, and the impetus for creating That's The Way.  One handy feature of Docupresentment is the file watcher.  This component keeps an eye on standard configuration files such as docserv.xml and logconf.xml.  If these files are modified, Docupresentment will automatically restart itself (and all the instances) to load the changes.  You can configure the time that Docupresentment waits to check these files using the setting <entry name="FileWatchTimeMillis">.  By default the number is 12000ms, or 12 seconds.  You can save yourself a few CPU cycles by extending this time, or by disabling  the check altogether by setting the value to 0.  This may or may not be appropriate for your environment; if you have 100% uptime requirements then you probably don't want to bring down an entire set of processes just to accept a new configuration value, so it's best to leave this somewhere between 12 seconds to a few minutes.  Another point to consider: if you are using Documaker real-time processing under Docupresentment the Master Resource Library (MRL) files and INI options are cached, and if you need to affect a change, you'll have to "restart" Docupresentment.  Touching the docserv.xml file is an easy way to do this (other methods including using the RSS request, but that's another post).

The next item up: <entry name="FilePurgeTimeSeconds">.  You may already know that the Docupresentment system can generate many temporary files based on certain request types that are processed through the system.  What you may not know is how those files are cleaned up.  There are many rules in Docupresentment that cause the creation of temporary files.  When these files are created, Docupresentment writes an entry into a properties file called the file cache.  This file contains the name, creation date, and expiration time of each temporary file created by each instance of Docupresentment.  Periodically Docupresentment will check the file cache to determine if there are files that are past the expiration time, not unlike that block of cheese festering away in the back of my refrigerator.  However, unlike my 'fridge cleaning tendencies, Docupresentment is quick to remove files that are past their expiration time.  You, my friend, have the power to control how often Docupresentment inspects the file cache.  Simply set the value for <entry name="FilePurgeTimeSeconds"> to the number of seconds appropriate for your requirements and you're set.  Note that file purging happens on a separate thread from normal request processing, so this shouldn't interfere with response times unless the CPU happens to be exceptionally taxed at the point of cache processing. 

Finally, after all of this, we get to the final setting I'm going to address in this post: <entry name="FilePurgeList">.  The default is "filecache.properties", which etablishes the root name for the Docupresentment file cache that I mentioned previously.  Docupresentment creates a separate cache file for each instance based on this setting.  If you have two instances, you'll see two files created:filecache.properties.1 and filecache.properties.2.  Feel free to open these up and check them out, but be careful not to delete or modify the files in any way. Otherwise, Docupresentment may lose track of some temporary files, and they'll be left to gather the dull fuzz of electronic dust in the lonely corners of your server, not unlike that block of cheese I mentioned.

I hope you've enjoyed this first foray into the configuration file of Docupresentment.  If you did enjoy it, feel free to drop a comment as I am most appreciative of feedback.  If you have ideas for other posts you'd like to see, please do let me know.  You can reach me at an andy.little@oracle.com.

'Til next time!