Thursday Sep 26, 2013

How-To: Start a CMSDK Node in a custom application

With the removal of the DomainController concept in CMSDK, it is important to know that the CMSDK Node itself now manages the Service, Servers and possible failovers to another Node.

Recently I have encountered a number of customers that have never ran a CMSDK Node in the past. That is somehow worrisome, as a CMSDK Node plays a key role in the whole CMSDK architecture. Although CMSDK is an SDK, there are some required background processes running as Agents, Servers and Handlers. These Agents and Handlers are responsible for cleanup tasks, lifecycle management, and among others, the underlying event system.

The whole Node management in CMSDK might be a blog topic of its own, but I would like to give at least an example of how to run a CMSDK Node within your own custom application, so you can take advantage of a real managed CMSDK environment.

This custom Node does not replace the CMSDK Node that you create when you deploy the cmsdk.ear file, which is mandatory. It furthermore extends the environment and helps your application to take advantage of the built-in Node management.

  1. First create a custom NodeConfiguration, as we don't want to run all servers and agents by default in our custom Node. This can be done by executing a script. An example can be found at $CMSDK_HOME/install/config/CreateNodeConfiguration.def.
    The minimum required agents needed to run inside any custom Node are:
    • EventHandlerAgent using IFS.SERVER.EventHandlerAgentConfiguration
    • StatisticsAgent using IFS.SERVER.StatisticsAgentConfiguration

    To only inherit those from the SuperNodeConfiguration you can insert the following line after line

    ; inherit all the servers

    m += addDefinitionStringArrayProperty  defTag  IFS.NODE.EnabledInheritedServerNames "{EventHandlerAgent, StatisticsAgent}"

    You should create your own .def that contains the custom NodeConfiguration. To execute that script run the
    following command:

    $CMSDK_HOME/bin/ CustomNodeConfiguration.def

  2. Make sure that your custom application contains a web.xml. This is required for the following instructions.
    If a web.xml is not possible to add, you need to follow different instructions. Let me know if this is the case and I will publish the other instructions as well (might be a rare case, though).

  3. Register a new Servlet Context Listener to your custom application, by adding the following entries to the web.xml. If listeners are already part of the web.xml make sure that the new one will be listed first.

      <description>Starts and Stops the Node in this JVM</description>

  4. The new Servlet Context Listener makes use of several configuration parameters that you need to specify in the web.xml as well. You can use the defaults for most of them, but should make sure that the corresponding param-values for

    • IFS.NODE.DataSourceName
    • IFS.NODE.Service
    • IFS.NODE.NodeConfigurationName
    • IFS.NODE.ServiceConfigurationName

    match your specific configuration.

    Add the following context-params to your web.xml:

      <description>The name of the DataSource for the CMSDK repository</description>

      <description>The class name of CMSDK Node instance running in this JVM</description>

      <description>The unique name of CMSDK Node running in this JVM</description>

      <description>The name of the Service this Node is running with</description>

      <description>The name of the node configuration for this CMSDK Node</description>

      <description>The name of the service configuration the service is running with</description>

      <description>Time in seconds the shutdown process should wait for the service to disappear.</description>

      <!-- Options: OFF, SEVERE, WARNING, INFO (default), CONFIG, FINE, FINER, FINEST, ALL -->
      <description>The overall LogLevel of the Node.</description>

      <description>The filename of the logfile for this Node.</description>

    <!-- Optional, per default the logfile will be written to your runtime directory
      <description>The absolute path of the logfile location for this Node.</description>

      <!-- Options: Defines the top level package name for logging  -->
      <description>The name of the root logger.</description>

      <!-- Options: text (default), xml -->
      <description>The format of the logfile for this Node.</description>

      <!-- Options: true, false (default) -->
      <description>Routes logging to console (stdout) AND to a logfile.</description>

      <!-- Options: 5MB (default), 0 means no limit, other number in bytes -->
      <description>Defines the maximum size in bytes of a logfile before creating the next one.</description>

      <description>Defines the maximum number of logfiles to keep before overwriting the oldest one.</description>

      <!-- Options: 1d (default), 0 indicates no time based rotation
       Allowed values are a number followed by either D (days), H (hours), M (minutes) and S (seconds)
       If no postfix is specified the provided number is assumed to be in milliseconds.
       Examples are: 12H = 12 hours; 3D = 3 days; 35M = 35 minutes; 86400000 = 86,400,000 milliseconds
      <description>Defines the log period in milliseconds before rotating the logfile.</description>

       Syntax: oracle.ifs.examples : FINE, oracle.ifs.core.runtime.NodeManager : INFO
       The list of overrides should be seperated by a comma ','
       The override is defined as 'class/package : LogLevel'
      <description>Implements LogLevel overrides at class or package level</description>

    NOTE: Each CMSDK should have a unique name. So make sure that the param-value for IFS.NODE.NodeName is different in each web.xml if you are planning to run a multi-Node environment.

  5. In your code you can now use the following way of connecting to CMSDK via a managed service:

      service = LibraryService.findService(SERVICE_NAME);
      // This should not be necessary, as the Node should have already started the Service by now.
      // Just in case he didn't, we can start a Service the old fashion way as unmanaged. The Node will
      // find it later and manage it from then on.
      service = LibraryService.startService(SERVICE_NAME, CMSDK_SCHEMA_PWD, SERVICE_CONFIG_NAME, DOMAIN_URL);
    LibrarySession session = service.connect(credentials, null);

Monday Aug 26, 2013

Easy upgrade path from CMSDK to

Each Oracle CMSDK release comes with three different installation options.
  1. Create a new Oracle CMSDK schema
  2. Upgrade from an existing Oracle CMSDK installation
  3. Patch an existing installation

The upgrade process is divided into three phases: the Pre-SchemaUpgrade, Offline-SchemaUpgrade and Post-SchemaUpgrade phases.

Within each of these phases, a list of upgrade actions are performed in a specific sequence. The time required to complete the entire upgrade process depends on the size and complexity of the existing Oracle CMSDK schema. To minimize the down time of a production system, most of the long running actions are executed during either the Pre-SchemaUpgrade or the Post-SchemaUpgrade phase, because during these phases the system can remain in production. It is only during the Offline-SchemaUpgrade phase that the Oracle CMSDK system must be completely shut down.

Here is a brief overview of the three phases.


  • Executes while system is running
  • Performs a number of long running actions
  • Can be executed multiple times before beginning next phase
  • system must be shut down as this phase begins
  • Optimized to complete in a relatively short period of time
  • Pre-SchemaUpgrade actions are executed again, to process any "deltas" since the last time that phase completed
  • Offline-SchemaUpgrade actions are executed only once
  • Can execute while system is running
  • Performs actions which are largely optimizations
Our internal tests showed that a CMSDK system with 10 million documents required an actual down time of less than 15 minutes and a total upgrade time of roughly 25 hours. Again, this can vary based on other factors.

Detailed upgrade and installation instructions can be found in the Readme bundled with each release.


Latest news, best practices, examples and product updates for CMSDK.


« March 2015