Cycle Overview

Cycle System Levels

When using OIPA Cycle for pending activity processing, activities may be configured to process according to OIPA system levels. Applicable levels for processing batch activities are:

• Company
• Client
• Plan
• Policy

Architecture

The Cycle subsystem drives processing of transactions through a Cycle Grid, which is comprised of a set of Cycle Agents. Each Cycle Agent is a separate JVM instance, which acts as a processing node in the Grid. A special application called a Cycle Client submits tasks to the Cycle Grid to direct what type of Cycle processing the group is to work on. The following is a high-level diagram showing how the different collaborators work together to start processing a Cycle run.

Cycle Agents

Cycle Agents are the programs that execute the tasks that comprise the Cycle batch process. Each Cycle Agent runs in its own Java Virtual Machine (JVM). Depending on the number of tasks that must be executed during Cycle processing, any number of JVMs may be used to run the desired number of Cycle Agents. The JVMs may be started on one or more physical machines. If more than one machine is used, they will be effectively clustered via the Coherence clustered caching and messaging system.

The following conceptual deployment diagram shows how the Cycle Agents may be distributed between multiple machines and JVMs. The boxes labeled "T" represent the threads controlled by the Agents to perform the units of work.

Cycle Client

Cycle Client is a standalone command line application used to control the Cycle process. It allows you to commands to all the Cycle Agents in order to start and stop the process.

Main Database Tables

Deployment

Cycle Agent operates inside a web container, like WebLogic or WebSphere. The Cycle Client still operates as a standalone application.

Configuration Files

Cycle.properties – Refer to the Client Cycle.properties section below for the properties related to the Cycle Client. Refer to the Agent Cycle.properties section below for the properties related to the Cycle Agent.

cycle-coherence-config.xml – This file controls the coherence cluster. Do not alter this file unless you have an in-depth understanding of coherence. The information in this file is based on how the installation was performed. The well-known-address is how you specify what machines are allowed to join the Cycle cluster.

Note: If you try to access a machine/IP address which is not in the cluster, you will get an error.

cycle-coherence-cache-config.xml – This is a default file that defines how coherence caches are configured in terms of best practices.

log4j.xml – This file controls the log files' level of detail. Do not alter this file unless you have an in-depth understanding of this technology.

client-appContext.xml – Only used for Cycle Client. This is used to auto-wire data access layer and business logic layer classes. This file should not be modified.

cycle-spring-beans.xml – Only used for Cycle Web/Agent. This is used to auto-wire data access layer and business logic layer classes. This file should not be modified.

Client Cycle.properties

cycle.period is the number of seconds that the Cycle Agent will wait before checking for additional work.

• Set it higher in order to avoid pinging the database too frequently for work. Frequent trips to the database, especially across multiple Cycle Agents, can impact performance.
• Set it low enough that you do not starve the Cycle Agent. If the threads in the Cycle Agent run out of work, they will not do anything until cycle.period expires and work is checked again.

cycle.batchSize is the maximum number of Cycle tasks that will process in the Cycle Grid. Consider the following:

• The batchSize should minimally be the sum total of all of the threads available across all Cycle Agents in the grid. For example, if there are four Cycle Agents, each with 10 threads, the minimum batch size should be 40 threads.
• For performance reasons, you may want to make sure that the threads are always running. To ensure that the threads are always running, set the batchSize to twice the number of threads in the Cycle Grid. For example, if there are four Cycle Agents running 10 threads each, set the batchSize to 80.
• If you have a cycle.groupSize greater than 1, multiply the previous result by the groupSize to determine the batchSize. For example, if there are four Cycle Agents running 10 threads each, and the groupSize is 10, set the batchSize to 800.
• The limitation on the number of tasks running in the cluster is dependent on the available memory in the cluster, not the thread pool sizes. The number of threads in the grid is only a theoretical estimate of how many tasks will be running at one time in the grid. Increasing the batchSize has the added benefit of reducing locking in the database when retrieving new tasks, which will increase performance. Setting the batchSize to 1000, 10000 or more is possible, depending on the memory in the cluster.

cycle.groupSize determines the number of Cycle work items to group together and execute on a single thread in the cluster.

• The groupSize has an impact on the number of tasks that are submitted to the grid for processing. If the batchSize is set to 10000, and the groupSize is set to 10, then 1000 actual tasks will be submitted to the grid for processing, each task containing 10 work items to be completed. Consider the groupSize value when determining the batchSize.
• Increase this value in order to group together tasks and speed up task submission and processing. The grid will process 10000 work items grouped in sets of 10 faster than 10000 individual work items.

grid.taskSubmissionThreadPoolSize is the number of threads dedicated to submitting tasks to the grid for processing. Increasing this number can speed up how quickly tasks are distributed to the grid.

• Increase this value in relation to the batchSize. The larger the batchSize, the more threads that should be dedicated to task submission.

isSharedCluster specifies if Cycle and OIPA are configured to run on the same Coherence Cluster.

oipaUrl

• OIPA URL to keep the System date in Sync on OIPA and Cycle cluster if they are different
• OIPA URL is mandatory if isSharedCluster is either not defined or set to false.

Web/Agent Cycle.properties

For the explanation of other properties related to Cycle Agent, refer to the OIPA System Properties document available in the current release Documentation Library under Policy Administration Libraries of Oracle Help Center.

NOTE: In order for the Cycle Agent to be used in conjunction with Scheduled Valuation, two other options must be set in the Agent's Cycle.properties file.

• scheduledValuation.batchSize – This is the batch size for processing scheduled valuation or scheduled computation.
• scheduledValuation.period – This is the number of seconds that the scheduled valuation or scheduled computation monitor task will sleep before waking up and checking on the status of queued tasks.

Coherence

The Coherence cluster configuration in cycle-coherence-config.xml must be modified to include each Cycle Client and Agent that will participate in the Cycle group.

Since each Cycle member exists in its own JVM process and each member may be spread across multiple machines, the Cycle members in the same Cycle group must communicate. The messaging functionality of Coherence is used to accomplish this communication.

It is required that all Cycle members in the same Cycle group be configured in the same Coherence cluster.

The top of the file contains a section that allows for the addition of each machine that will participate in the Cycle group. Every Cycle Client and Agent that participates in a given Cycle group must be contained in this section. Also, each OIPA instance, if used for cycle processing, should also be listed in this section, as OIPA has the ability to submit work to the Cycle group. In the case that a machine is not included in the Coherence configuration, the machine will not be able to join the Cycle group and will encounter issues starting up.

When configuring the well-known-address list, keep the following in mind:

• Every Cycle Client, Cycle Agent, and OIPA instance (if participating in cycle) must be listed in the well-known-address list
• The well-known-address list must be exactly the same across all members (Cycle Clients, Cycle Agents, and OIPA instances)
• If all members do not have the same well-known-address list, some may not start up properly or run at all.
• Incorrect configuration of the well-known-address list is the most common source of Cycle and OIPA problems. Ensure the list is configured correctly and shared by all members.
• If you use a member-identity section like the example below, make sure that the member-name is unique in the cluster, and that the cluster-name is the same for all members of the cluster. If the cluster-name is not the same, members may not be allowed to join the Coherence cluster, causing startup issues for the OIPA instance, Cycle Agent, or Cycle Client.

A sample configuration:

<?xml version="1.0" encoding="UTF-8"?>

<cluster-config>

<member-identity>

<cluster-name>PRODCLUSTER</cluster-name>

<member-name>CYCLEAGENT1</member-name>

</member-identity>

<unicast-listener>

<address>123.456.78.10</address>

<port>42222</port>

<port-auto-adjust>false</port-auto-adjust>

<well-known-addresses>

<socket-address id="1">

<address>123.456.78.10</address>

<port>42222</port>

</socket-address>

<socket-address id="2">

<address>123.456.78.11</address>

<port>42222</port>

</socket-address>

<socket-address id="3">

<address>123.456.78.12</address>

<port>42222</port>

</socket-address>

</well-known-addresses>

</unicast-listener>

</cluster-config>

The Coherence cache configuration in cycle-coherence-cache-config.xml configures the processing configuration on each Cycle Agent. This file must be modified only for each Cycle Agent, in order to uniquely identify the task processors that will be working in the Cycle Cluster. If the identifiers are not unique across all Agents in the cluster, the Agents with duplicate identifiers will not process any work.

The cache configuration only needs to be configured for Cycle Agents. It does not need to be modified for OIPA instances or Cycle Clients.

The following section highlights the most significant change for the cache config file. This is an example of the cache config file for a Grid Processing node (a Cycle Agent).

<processing:task-dispatcher displayname="Task Dispatcher" priority="1" />

<processing:logging-dispatcher displayname="Logging Dispatcher" />

<processing:local-executor-dispatcher displayname="Local Dispatcher" />

<processing:taskprocessordefinition id="CycleTaskProcessor" displayname="Cycle Task Processor" type="SINGLE" taskpattern="SingleTask">

<processing:default-taskprocessor id="CycleTaskProcessor" threadpoolsize="15"></processing:default-taskprocessor>

</processing:taskprocessordefinition>

1. Make sure that each Cycle Agent/Cycle Web instance is using its own cycle-coherence-cache-config.xml file. You cannot share a single cycle-coherence-cache-config.xml file.
2. Make sure the ID attributes in the processing:taskprocessors XML section are unique across the entire cluster. In the example above, you must have a unique identifier for all items that are underlined and highlighted. There are six identifiers in total.

NOTE: If your identifiers are not unique across ALL Cycle Agents in the cluster, those Agents with duplicate identifiers will not process work. There will be no obvious exception in this instance.

The following are possible changes to this file:

Change the threadpoolsize attribute on the processing:default-taskprocessor element with the ID "CycleTaskProcessor". This includes processing activities on a policy or a plan, or performing scheduled valuation/scheduled computation on a single policy (or segment for scheduled computation). Its a generic tasks tend to be more processing intensive, it is recommended that more threads are given to this thread pool.