Tuesday Oct 29, 2013

How-To: Run CMSDK against a RAC cluster

Using CMSDK in a production environment often requires a robust, reliable and failover enabled repository. When using Oracle Real Application Cluster (RAC) with your CMSDK repository you need to have a specific configuration in place to support such a setup. This post will explain the configuration steps required when running CMSDK 9.0.4.6 with Oracle WebLogic Server (WLS).

In the previous CMSDK 9.0.4.2 version a RAC enabled connect string looked like this:

(DESCRIPTION =
(ADDRESS = (PROTOCOL = TCP)(HOST = rac1)(PORT = 1521))
(ADDRESS = (PROTOCOL = TCP)(HOST = rac2)(PORT = 1521))
(LOAD_BALANCE = NO)
(FAILOVER = ON)
(CONNECT_DATA =
(SERVICE_NAME = rac)
(failover_mode = (type=select)(method=basic))
)

CMSDK 9.0.4.6 makes use of data sources to connect to the underlying database. These data sources are configured inside your Application Server, such as Oracle WebLogic Server.
In Oracle WebLogic Server 10.3.4, a single data source implementation has been introduced to support an RAC cluster. It responds to Fast Application Notification (FAN) events to provide Fast Connection Failover (FCF), Runtime Connection Load-Balancing (RCLB), and RAC instance graceful shutdown. XA affinity is supported at the global transaction Id level. The new feature is called WebLogic Active GridLink for RAC; which is implemented as the GridLink data source within WebLogic Server.
This GridLink data source also works with Oracle Single Client Access Name (SCAN). SCAN is a feature used in RAC environments that provides a single name for clients to access any Oracle Database running in a cluster. You can think of SCAN as a cluster alias for databases in the cluster. The benefit is that the client’s connect information does not need to change if you add or remove nodes or databases in the cluster.

The CMSDK 9.0.4.6 documentation describes how to create a regular JDBC data source named jdbc/OracleDS. Please refer to the following document which describes in detail how to create a GridLink data source in WLS.

Thursday Sep 26, 2013

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

With the removal of the DomainController concept in CMSDK 9.0.4.6, 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 9.0.4.6 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/scriptrunner.sh 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.

    <listener>
      <description>Starts and Stops the Node in this JVM</description>
      <display-name>NodeManager</display-name>
      <listener-class>oracle.ifs.core.runtime.NodeManager</listener-class>
    </listener>

  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:

    <context-param>
      <description>The name of the DataSource for the CMSDK repository</description>
      <param-name>IFS.NODE.DataSourceName</param-name>
      <param-value>jdbc/OracleDS</param-value>
    </context-param>

    <context-param>
      <description>The class name of CMSDK Node instance running in this JVM</description>
      <param-name>IFS.NODE.Class</param-name>
      <param-value>oracle.ifs.core.runtime.Node</param-value>
    </context-param>

    <context-param>
      <description>The unique name of CMSDK Node running in this JVM</description>
      <param-name>IFS.NODE.NodeName</param-name>
      <param-value>DefaultNode</param-value>
    </context-param>

    <context-param>
      <description>The name of the Service this Node is running with</description>
      <param-name>IFS.NODE.Service</param-name>
      <param-value>DefaultService</param-value>
    </context-param>

    <context-param>
      <description>The name of the node configuration for this CMSDK Node</description>
      <param-name>IFS.NODE.NodeConfigurationName</param-name>
      <param-value>IFS.NODE.DefaultNodeConfiguration</param-value>
    </context-param>

    <context-param>
      <description>The name of the service configuration the service is running with</description>
      <param-name>IFS.NODE.ServiceConfigurationName</param-name>
      <param-value>IFS.SERVICE.SmallServiceConfiguration</param-value>
    </context-param>

    <context-param>
      <description>Time in seconds the shutdown process should wait for the service to disappear.</description>
      <param-name>IFS.NODE.ShutdownWaitTime</param-name>
      <param-value>30</param-value>
    </context-param>

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

    <context-param>
      <description>The filename of the logfile for this Node.</description>
      <param-name>LogFileName</param-name>
      <param-value>DefaultNode.log</param-value>
    </context-param>

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

    <context-param>
      <!-- Options: Defines the top level package name for logging  -->
      <description>The name of the root logger.</description>
      <param-name>RootLoggerName</param-name>
      <param-value>oracle.ifs</param-value>
    </context-param>

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

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

    <context-param>
      <!-- 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>
      <param-name>MaxLogFileSize</param-name>
      <param-value>5242880</param-value>
    </context-param>

    <context-param>
      <description>Defines the maximum number of logfiles to keep before overwriting the oldest one.</description>
      <param-name>MaxLogFileCount</param-name>
      <param-value>30</param-value>
    </context-param>

    <context-param>
      <!-- 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>
      <param-name>LogFileRotationPeriod</param-name>
      <param-value>1d</param-value>
    </context-param>

    <context-param>
      <!--
       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>
      <param-name>LogLevelOverrides</param-name>
      <param-value></param-value>
    </context-param>

    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:

    if(LibraryService.isServiceStarted(SERVICE_NAME))
    {
      service = LibraryService.findService(SERVICE_NAME);
    }
    else
    {
      // 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 9.0.4.2 to 9.0.4.6

Each Oracle CMSDK 9.0.4.6.x release comes with three different installation options.
  1. Create a new Oracle CMSDK 9.0.4.6 schema
  2. Upgrade from an existing Oracle CMSDK 9.0.4.2 installation
  3. Patch an existing 9.0.4.6.x 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.

Pre-SchemaUpgrade

  • Executes while 9.0.4.2 system is running
  • Performs a number of long running actions
  • Can be executed multiple times before beginning next phase
Offline-SchemaUpgrade
  • 9.0.4.2 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
Post-SchemaUpgrade
  • Can execute while 9.0.4.6 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.

Friday Aug 16, 2013

Still on CMSDK 9.0.4.2 ?

CMSDK version 9.0.4.2 was released back in January 2005. This and every subsequent 9.0.4.2.x CMSDK version requires Oracle Application Server 10gR2 (10.1.2.0.2) for its run-time environment. This version of Oracle Application Server and the Java version it depends on (JDK 1.4) have already reached its end-of-life on Extended Support. See Oracle Application Server 10g certification information for more information.

So what now?

Let me explain to you how you can move your existing CMSDK environment to the latest Oracle stack.

In March 2012 we released a new version of CMSDK (version 9.0.4.6.3), which corrects two major issues that existed in CMSDK version 9.0.4.2:

  • Removing the dependency on Oracle Application Server 10g.
  • Making CMSDK compatible with the latest Java versions.

Since then, we have released a new CMSDK 9.0.4.6.x patch every four months. The most recent one, version 9.0.4.6.7, has been released to My Oracle Support as Patch 16465003 in July 2013. This patch includes a number of bug fixes that have been found by customers and partners during their testing of the earlier CMSDK 9.0.4.6.x versions. The Readme that is bundled with the patch contains the list of bugs fixed as well as the installation and upgrade instructions and the list of deprecated features.

CMSDK 9.0.4.6 is certified on current middleware products such as Oracle WebLogic Server or Oracle GlassFish Server and is available for download on My Oracle Support.

The following documents contain some further general information about CMSDK 9.0.4.6:

Wednesday Aug 14, 2013

Welcome CMSDK to the blogsphere!

The first entry.

The development of Oracle Content Management SDK (CMSDK) began back in 1998. It was initially sold as a pure SDK product and its potential was quickly recognized both inside and outside the company. Oracle used CMSDK internally as the foundation for several content management products. Today hundreds of customers are using the core CMSDK and its complete development and run-time environment to rapidly build their own enterprise content management applications.

I have been working with CMSDK since 2001, initially as a Consultant in many customer projects, where we leveraged the robust and extensible platform for developing custom content management solutions. Later I joined Oracle Global Sales Support and traveled around the globe to teach internal classes about the latest products in the areas Content and Records Management, Database Security, Auditing and Compliance. In 2007 I joined Oracle Product Development and became responsible for five different content management and archiving products.

I want to share my acquired knowledge and experience from the last decade, in particular about CMSDK, with you in this blog. Feel free to comment on posts or suggest CMSDK topics that you would like to have covered in this blog.

About

My name is Frank Closheim. I lead Development for CMSDK at Oracle and want to share the latest news, best practices, examples and product updates about CMSDK with the Blogsphere.

Search

Archives
« April 2014
SunMonTueWedThuFriSat
  
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
   
       
Today