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? With this inaugural post to That's
The Way, I'm going to introduce myself, and what my aim is with this blog. If you didn't figure it out already by checking out my profile, my name is Andy and I've been with Oracle (nee Skywire Software nee Docucorp nee Formmaker) since
the formative years of 1998. Strangely, it doesn't seem that long ago, but it's certainly a lifetime in
the age of technology. I recall running a BBS from my parent's basement on a 1200 baud modem, and
the trepidation and sweaty-palmed excitement of upgrading to
the power and speed of 2400 baud! Fine, I'll admit that perhaps I'm inflating
the experience a bit, but I was kid! This is
the stuff of War Games and King's Quest I and
the demise of TI-99 4/A. Exciting times. So fast-forward a bit and I'm 12 years into a career in
the world of document automation and publishing working for
the best (IMHO) software company on
the planet. With That's
The Way I hope to shed a little light and peek under
the covers of some of
the more interesting aspects of implementations involving
the tech space within
the Oracle Insurance Global Business Unit (IGBU), which includes Oracle Documaker, Rating & Underwriting, and Policy Administration to name a few. I may delve off course a bit, and you'll likely get a dose of humor (at least in my mind) but I hope you'll glean at least a tidbit of usefulness with each post. Feel free to comment as I'm a fairly conversant guy and happy to talk -- it's stopping
the talking that's
the hard part... So, back to our regularly-scheduled post, already in progress. By this time you've visited Oracle's E-Delivery site and acquired your properly-licensed version of Oracle Documaker. Wait -- you didn't find it? Understandable -- navigating
the voluminous download library within Oracle can be a daunting task. It's pretty simple once you’ve done it a few times. 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’ll see a list of applicable products, and you’ll 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, 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 a appealing to Oracle was our use of many acronyms, including
the occasional use of multiple acronyms with
the same meaning. I apologize in advance and will try to point these out along
the way. Here’s your first sticky note to go along with that: 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. Forging onward with
the meat of this post is learning about some special configuration options. By now you’ve read
the documentation included with
the download (specifically ids_book.pdf) which goes into some detail of
the rubric of
the configuration file and in fact there’s even a handy utility that provides an interface to
the configuration file (see Running IDSConfig in
the documentation). But who wants to deal with a configuration utility when we have
the tools and technology to edit
the file <gasp> 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 havoc you may wreak! Go to your installation directory, and locate your docserv.xml file. Open it in your favorite XML editor. I happen to be fond of Notepad++ 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. Ok – moving on. 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.
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).
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.
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
the sweet 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.
The Docupresentment service that you fire up with docserver.bat or docserver.sh actually starts a watchdog process, which is then responsible for starting up
the actual Docupresentment processes. Each of these act independently from one another, so if one crashes, it does not affect any others. In
the case of a crashed process,
the watchdog will start up another instance so
the number of configured instances are always running. Bottom line: instance = Docupresentment process. And now, finally, to
the settings which gave me pause on an not-too-long-ago implementation! Docupresentment includes a feature that watches configuration files (such as docserv.xml and logconf.xml) and will automatically restart its 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 keep in mind: 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 really 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”. This establishes
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. 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, I welcome feedback. If you have ideas for other posts you’d like to see, please do let me know. You can reach me at
[email protected]. ‘Til next time! ###
