Skip Headers
Oracle® Coherence Developer's Guide
Release 3.5

Part Number E14509-01
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
View PDF

I Initialization Parameter Settings

The <init-param> element in the Coherence operational configuration deployment descriptor defines initialization parameters for a service or filter. The parameters that appear under init-param will be different, depending on the service or filter you are working with.

The following sections describe the parameters that can be configured for these services and filters:

The tables in each section describe the specific <param-name><param-value> pairs that can be configured for various elements. The Parameter Name column refers to the value of the param-name element and Value Description column refers to the possible values for the corresponding param-value element.

For example, the sample entry in Table I-1 means that the init-params element may look like the configuration in Example I-1 or Example I-2.

Table I-1 Sample Table Entry

Parameter Value Value Description

local-storage

Specifies whether this member of the DistributedCache service enables the local storage. Legal values are true or false. Default value is true. Preconfigured value is tangosol.coherence.distributed.localstorage. See Appendix L, "Command Line Overrides" for more information.


Example I-1 Sample init-param Configuration

...
<init-params>
  <init-param>
    <param-name>local-storage</param-name>
    <param-value>false</param-value>
  </init-param>
</init-params>
...

or as follows:

Example I-2 Another Sample init-param Configuration

...
<init-params>
  <init-param>
    <param-name>local-storage</param-name>
    <param-value>true</param-value>
  </init-param>
</init-params>
...

DistributedCache Service Parameters

DistributedCache <services> elements support the parameters described in Table I-2. These settings may also be specified as part of the <distributed-scheme> element in the Cache Configuration Elements descriptor coherence-cache-config.xml.

Table I-2 DistributedCache Service Parameters

Parameter Name Value, Description

backup-count

Specifies the number of members of the DistributedCache service that hold the backup data for each unit of storage in the cache. Value of 0 means that in the case of abnormal termination, some portion of the data in the cache will be lost. Value of N means that if up to N cluster nodes terminate immediately, the cache data will be preserved. To maintain the distributed cache of size M, the total memory usage in the cluster does not depend on the number of cluster nodes and will be in the order of M*(N+1).

Recommended values are 0, 1 or 2.

Default value is 1.

backup-storage/class-name

Only applicable with the custom type. Specifies a class name for the custom storage implementation. If the class implements com.tangosol.run.xml.XmlConfigurable interface then upon construction the setConfig method is called passing the entire backup-storage element.

backup-storage/directory

Only applicable with the file-mapped type. Specifies the path name for the directory that the disk persistence manager (com.tangosol.util.nio.MappedBufferManager) will use as "root" to store files in. If not specified or specifies a non-existent directory, a temporary file in the default location is used.

Default value is the default temporary directory designated by the Java runtime.

backup-storage/initial-size

Only applicable with the off-heap and file-mapped types.Specifies the initial buffer size in bytes.The value of this element must be in the following format: [\d]+[[.][\d]]?[K|k|M|m|G|g]?[B|b]? where the first non-digit (from left to right) indicates the factor with which the preceding decimal value should be multiplied:

  • K or k (kilo, 210)

  • M or m (mega, 220)

  • G or g (giga, 230)

If the value does not contain a factor, a factor of mega is assumed.

Legal values are positive integers between 1 and Integer.MAX_VALUE - 1023 (that is, 2,147,482,624 bytes).

Default value is 1MB.

backup-storage/maximum-size

Only applicable with the off-heap and file-mapped types.Specifies the maximum buffer size in bytes.The value of this element must be in the following format: [\d]+[[.][\d]]?[K|k|M|m|G|g]?[B|b]? where the first non-digit (from left to right) indicates the factor with which the preceding decimal value should be multiplied:

  • K or k (kilo, 210)

  • M or m (mega, 220)

  • G or g (giga, 230)

If the value does not contain a factor, a factor of mega is assumed.

Legal values are positive integers between 1 and Integer.MAX_VALUE - 1023 (that is, 2,147,482,624 bytes).

Default value is 1024MB.

backup-storage/scheme-name

Only applicable with the scheme type. Specifies a scheme name for the ConfigurableCacheFactory.

backup-storage/type

Specifies the type of the storage used to hold the backup data. Legal values are:

Default value is on-heap.

Preconfigured value is tangosol.coherence.distributed.backup. See Appendix L, "Command Line Overrides" for more information.

key-associator/class-name

Specifies the name of a class that implements the com.tangosol.net.partition.KeyAssociator interface. This implementation must have a zero-parameter public constructor.

key-partitioning/class-name

Specifies the name of a class that implements the com.tangosol.net.partition.KeyPartitioningStrategy interface. This implementation must have a zero-parameter public constructor.

lease-granularity

Specifies the lease ownership granularity. Available since release 2.3.Legal values are:

  • thread

  • member

A value of thread means that locks are held by a thread that obtained them and can only be released by that thread. A value of member means that locks are held by a cluster node and any thread running on the cluster node that obtained the lock can release it.

Default value is thread.

local-storage

Specifies whether this member of the DistributedCache service enables local storage.

Normally this value should be left unspecified within the configuration file, and instead set on a per-process basis using the tangosol.coherence.distributed.localstorage system property. This allows cache clients and servers to use the same configuration descriptor.

Legal values are true or false. Default value is true.

Preconfigured value is tangosol.coherence.distributed.localstorage. See Appendix L, "Command Line Overrides" for more information.

partition-count

The partition-count element specifies the number of partitions that a partitioned (distributed) cache will be "chopped up" into. Each member running the partitioned cache service that has the local-storage option set to true will manage a "fair" (balanced) number of partitions.

The number of partitions should be a prime number and sufficiently large such that a given partition is expected to be no larger than 50MB in size.

Good defaults for example service storage sizes are provided below:

service storage       parition-count
_______________       ______________
   100M                    257
     1G                    509
    10G                   2039
    50G                   4093
   100G                   8191

A list of first 1,000 primes can be found at:

http://primes.utm.edu/lists/small/1000.txt

Valid values are positive integers.

Default value is the value specified in the tangosol-coherence.xml descriptor.

partition-listener/class-name

Specifies the name of a class that implements the com.tangosol.net.partition.PartitionListener interface. This implementation must have a zero-parameter public constructor.

request-timeout

Specifies the maximum amount of time a client will wait for a response before abandoning the original request. The request time is measured on the client side as the time elapsed from the moment a request is sent for execution to the corresponding server node(s) and includes the following:

  • the time it takes to deliver the request to an executing node (server)

  • the interval between the time the task is received and placed into a service queue until the execution starts

  • the task execution time

  • the time it takes to deliver a result back to the client

Legal values are positive integers or zero (indicating no default timeout).

standard-lease- milliseconds

Specifies the duration of the standard lease in milliseconds. When a lease has aged past this number of milliseconds, the lock will automatically be released. Set this value to zero to specify a lease that never expires. The purpose of this setting is to avoid deadlocks or blocks caused by stuck threads; the value should be set higher than the longest expected lock duration (for example, higher than a transaction timeout). It's also recommended to set this value higher then packet-delivery/timeout-milliseconds value.

Legal values are from positive long numbers or zero. Default value is 0.

task-hung-threshold

Specifies the amount of time in milliseconds that a task can execute before it is considered "hung".

Note: a posted task that has not yet started is never considered as hung. This attribute is applied only if the Thread pool is used (the thread-count value is positive).

Legal values are positive integers or zero (indicating no default timeout).

task-timeout

Specifies the default timeout value in milliseconds for tasks that can be timed-out (for example, implement the com.tangosol.net.PriorityTask interface), but don't explicitly specify the task execution timeout value. The task execution time is measured on the server side and does not include the time spent waiting in a service backlog queue before being started. This attribute is applied only if the thread pool is used (the thread-count value is positive).

Legal values are positive integers or zero (indicating no default timeout).

thread-count

Specifies the number of daemon threads used by the distributed cache service. If zero, all relevant tasks are performed on the service thread.

Legal values are from positive integers or zero.

Default value is 0. Preconfigured value is tangosol.coherence.distributed.threads. See Appendix L, "Command Line Overrides" for more information.

transfer-threshold

Specifies the threshold for the primary buckets distribution in kilobytes. When a new node joins the distributed cache service or when a member of the service leaves, the remaining nodes perform a task of bucket ownership re-distribution. During this process, the existing data gets rebalanced along with the ownership information. This parameter indicates a preferred message size for data transfer communications. Setting this value lower will make the distribution process take longer, but will reduce network bandwidth utilization during this activity.

Legal values are integers greater then zero.

Default value is 512 (0.5MB). Preconfigured value is tangosol.coherence.distributed.transfer. See Appendix L, "Command Line Overrides" for more information.



ReplicatedCache Service Parameters

ReplicatedCache services elements support the parameters described in Table I-3. These settings may also be specified as part of the replicated-scheme element in the Cache Configuration Elements descriptor coherence-cache-config.xml.

Table I-3 ReplicatedCache Service Parameters

Parameter Name Value Description

lease-granularity

Specifies the lease ownership granularity. Available since release 2.3.Legal values are:

  • thread

  • member

A value of thread means that locks are held by a thread that obtained them and can only be released by that thread. A value of member means that locks are held by a cluster node and any thread running on the cluster node that obtained the lock can release it.

Default value is thread.

mobile-issues

Specifies whether lease issues should be transferred to the most recent lock holders.

Legal values are true or false.

Default value is false.

standard-lease- milliseconds

Specifies the duration of the standard lease in milliseconds. When a lease has aged past this number of milliseconds, the lock will automatically be released. Set this value to zero to specify a lease that never expires. The purpose of this setting is to avoid deadlocks or blocks caused by stuck threads; the value should be set higher than the longest expected lock duration (for example, higher than a transaction timeout). It's also recommended to set this value higher then packet-delivery/timeout-milliseconds value.

Legal values are from positive long numbers or zero.

Default value is 0.



InvocationService Parameters

InvocationService services elements support the following parameters listed in Table I-4. These settings may also be specified as part of the invocation-scheme element in the Cache Configuration Elements descriptor coherence-cache-config.xml.

Table I-4 InvocationService Parameters

Parameter Name Value, Description

request-timeout

Specifies the default timeout value in milliseconds for requests that can time-out (for example, implement the com.tangosol.net.PriorityTask interface), but don't explicitly specify the request timeout value. The request time is measured on the client side as the time elapsed from the moment a request is sent for execution to the corresponding server node(s) and includes the following:

  • the time it takes to deliver the request to an executing node (server)

  • the interval between the time the task is received and placed into a service queue until the execution starts

  • the task execution time

  • the time it takes to deliver a result back to the client

Legal values are positive integers or zero (indicating no default timeout).

task-hung-threshold

Specifies the amount of time in milliseconds that a task can execute before it is considered "hung". Note: a posted task that has not yet started is never considered as hung. This attribute is applied only if the Thread pool is used (the thread-count value is positive).

task-timeout

Specifies the default timeout value in milliseconds for tasks that can be timed-out (for example, implement the com.tangosol.net.PriorityTask interface), but don't explicitly specify the task execution timeout value. The task execution time is measured on the server side and does not include the time spent waiting in a service backlog queue before being started. This attribute is applied only if the thread pool is used (the thread-count value is positive).

Legal values are positive integers or zero (indicating no default timeout).

thread-count

Specifies the number of daemon threads to be used by the invocation service. If zero, all relevant tasks are performed on the service thread.

Legal values are from positive integers or zero. Preconfigured value is tangosol.coherence.invocation.threads. See Appendix L, "Command Line Overrides" for more information.

Default value is 0.



ProxyService Parameters

ProxyService services elements support the parameters described in Table I-5. These settings may also be specified as part of the proxy-scheme element in the Cache Configuration Elements descriptor coherence-cache-config.xml.

Table I-5 ProxyService Parameters

Parameter Name Value Description

thread-count

Specifies the number of daemon threads to be used by the proxy service. If zero, all relevant tasks are performed on the service thread.

Legal values are from positive integers or zero.

Default value is 0.

task-hung-threshold

Specifies the amount of time in milliseconds that a task can execute before it is considered "hung".

Note: a posted task that has not yet started is never considered as hung. This attribute is applied only if the Thread pool is used (the thread-count value is positive).

Legal values are positive integers or zero (indicating no default timeout).

task-timeout

Specifies the default timeout value in milliseconds for tasks that can be timed-out (for example, implement the com.tangosol.net.PriorityTask interface), but don't explicitly specify the task execution timeout value. The task execution time is measured on the server side and does not include the time spent waiting in a service backlog queue before being started. This attribute is applied only if the thread pool is used (the thread-count value is positive).

Legal values are positive integers or zero (indicating no default timeout).



Compression Filter Parameters

The compression filters (com.tangosol.net.CompressionFilter), supports the parameters described in Table I-6 (see java.util.zip.Deflater for details).

Table I-6 Compression Filter Parameters

Parameter Name Value Description

buffer-length

Specifies compression buffer length in bytes.

Legal values are positive integers or zero.

Default value is 0.

level

Specifies the compression level. Legal values are:

  • default

  • compression

  • speed

  • none

Default value is default.

strategy

Specifies the compressions strategy. Legal values are:

  • gzip

  • huffman-only

  • filtered

  • default

Default value is gzip.