eXtreme Scale user exit descriptor file

The configuration attributes that define the behavior of the eXtreme Scale CDC adapter.

For attributes that specify file locations like securityProps, overrideXML and clientProps, the following look-up precedence is used:
  1. Load the file from the system class path.
  2. Load the file from the file system.
Important: The path does not support Windows operating systems backslashes. If you use backslashes, you must escape any backslash ( \ ) characters in the path. For example, if you want to use the path, C:\opt\ibm, enter C:\\opt\\ibm. Windows directories with spaces are not supported. You can specify environment variables in the path using ${variable}; for example:
 ${APP_LOC}/config/userexit.xml

wxsUserExitConfig element

The wxsUserExitConfig element is the top-level element of the XML file. Write this element in your eXtreme Scale XML document as shown in the previous example. This element sets up the namespace of the file and the schema location.

  • Number of occurrences: One
  • Child elements: domains and tableMappings elements

domains element

The domains element is a container for all the domain elements.

  • Number of occurrences: One
  • Child elements: domain element

domain element

Use the domain element to define the connection to a remote ObjectGrid cluster.

  • Number of occurrences: One or many
  • Child elements: clientProperties element
Attributes
name

Identifies the domain, and is referenced by the domainRef attribute of the tableMapping element. Each NAME must be unique. If the value of a domainRef attribute does not match the NAME of one of the domain elements, XML validation fails. Any number of tableMapping elements can reference a single domain element. (Required)

catalogEndPoints

Specifies the catalog server that is contacted to obtain a client-side ObjectGrid instance. The value must be of the form host:port<,host:port>. The host is the listener host on which the catalog server is running. The port is the listener port for that catalog server process. (Required)

securityProps
Specifies the path to the security properties file to be used for this domain.
Important: The path does not support Windows operating systems backslashes. If you have used backslashes, you must escape any backslash ( \ ) characters in the path. For example, if you want to use the path, C:\opt\ibm, enter C:\\opt\\ibm. Windows directories with spaces are not supported. You can specify environment variables in the path using ${variable}; for example:
 ${APP_LOC}/config/userexit.xml
overrideXML

Specifies the path to the object grid override xml to be used for this domain. (Optional)

Important: The path does not support Windows operating systems backslashes. If you have used backslashes, you must escape any backslash ( \ ) characters in the path. For example, if you want to use the path, C:\opt\ibm, enter C:\\opt\\ibm. Windows directories with spaces are not supported. You can specify environment variables in the path using ${variable}; for example:
 ${APP_LOC}/config/userexit.xml
writeBehindConfig
Specifies that all events to all ObjectGrid instances in this domain are run asynchronously. Write-behind parameters consist of a maximum update time and a maximum key update count. The format of the write-behind parameter is "[T(time)][;][C(count)]". The remote data grid is updated when one of the following events occurs:
  • The maximum update time, which is specified in seconds, has passed since the last update.
  • The number of available updates in the queue map has reached the maximum update count.

clientProperties element

The clientProperties element is a container for all the objectGrid elements

  • Number of occurrences: Zero or one
  • Child element: objectGrid element

objectGrid element

Use the objectGrid element to specify any client properties for this object grid instance.

  • Number of occurrences: One or many
  • Child element: None
Attributes
name

Name of the data grid that apply these properties. (Required)

clientPropertyFile
Specifies the path to the client properties file to be used by this object grid. (Required)
Important: The path does not support Windows operating systems backslashes. If you have used backslashes, you must escape any backslash ( \ ) characters in the path. For example, if you want to use the path, C:\opt\ibm, enter C:\\opt\\ibm. Windows directories with spaces are not supported. You can specify environment variables in the path using ${variable}; for example:
 ${APP_LOC}/config/userexit.xml

tableMappings element

The tableMappings element is a container for all the tableMapping elements.

  • Number of occurrences: One
  • Child element: tableMapping element

tableMapping element

Use the tableMapping element to specify the eXtreme Scale data grid and map where the change data capture event is applied.

  • Number of occurrences: One or many
  • Child element: keyMetaData and valueMetaData elements
Attributes
mapName
Specifies the backing map where these change data capture events are applied. (Required)
objectGridName
Name of the object grid instance where the backing map resides. (Required)
domainRef
Specifies a reference to a domain element. The value of this attribute must match the NAME attribute of a domain element. Validation fails if no matching NAME exists. (Required)
convertToUpsert
Specifies whether an upsert operation is run instead of an insert or update operation. (Optional)

Default: False

mode

Specifies how the change events are handled. Valid modes are PUSH, INVALIDATE, and REFRESH. (Optional)

PUSH: Change data capture events are applied as is. See the following table for the mappings. If convertToUpsert is set to true, then insert and update operations are changed to upsert.

INVALIDATE: Change data capture events, Update and Delete, are mapped to an INVALIDATE operation. Insert change data capture events are ignored. The next get operation on the key by the application organically populates the key from the loader. Use this mode if you have a Loader implementation and want to maintain a sparse cache.

REFRESH: This mode is the same as the INVALIDATE mode except that a get operation is performed after the INVALIDATE operation for an update change data capture event.

The following table highlights what type of data grid operation is run by each mode for the change capture events:
Table 1. Data grid operations for CDC
  AFTER_INSERT Event AFTER_UPDATE Event AFTER_DELETE Event
PUSH (default) Insert or Upsert Update or Upsert Remove
INVALIDATE None Invalidate Invalidate
REFRESH None Invalidate and Get Invalidate
Important: Maps that use a Loader implementation use the INVALIDATE or REFRESH mode only; otherwise, they might risk encountering the infinite inline-cache closed loop. For more information about the infinite inline-cache closed loop scenarios, see WebSphere eXtreme Scale change data capture adapter for InfoSphere Data Replication.
maxRetryAttempts

Specifies the number of times a change data capture event is retried before a failure is returned. (Optional)

Default: 0

transactionTimeout

Specifies the amount of time in seconds that a transaction is allowed for completion. If a transaction does not complete in this amount of time, the transaction is marked for rollback and a TransactionTimeoutException exception results. (Optional)

Default: the txTimeout value that is specified in the remote grid objectgrid.xml file

transactionIsolation

Sets the default transaction isolation level for all sessions that are created by the ObjectGrid. (Optional)

Default: the txIsolation value that is specified in the remote grid objectgrid.xml file

keyMetaData element

Use the keyMetaData element to specify the meta data that represents the key.

  • Number of occurrences: One
  • Child element: column element
Attributes
className
Specifies the name of the class to instantiate that represents the key instance (Optional). If specified, then one of the following conditions must exist:
  • The class must be annotated with the javax.persistence column to specify which column data binds to the field or method in this class instance.
  • The column element's name and propertyName attributes must be specified to determine which column binds to which field or method in this class instance.
methodAccess

Specifies whether the adapter uses field or method access to introspect and set the persistent data in the key object instance.

If you set the value to false, the class fields are introspected. If the value is set to true, the class methods are introspected.

valueMetaData element

Use the valueMetaData element to specify the meta data that represents the value object.
  • Number of occurrences: One
  • Child element: column element
Attributes
className
Specifies the name of the class to instantiate that represents the value instance (Optional). If specified, then one of the following conditions must exist:
  • The class must be annotated with the javax.persistence column to specify which column data binds to the field or method in this class instance.
  • The column element's name and propertyName attributes must be specified to determine which column binds to which field or method in this class instance.
methodAccess

Specifies whether the adapter uses field or method access to introspect and set the persistent data in the key object instance.

If you set the value to false, the class fields are introspected. If the value is set to true, the class methods are introspected.

column element

Use the column element to specify which column data is used to represent the key or value object instances.
  • Number of occurrences: Zero to many
  • Child element: None
Attributes
name

Name of the column that is used as the key or value object instance. (Optional)

propertyName

Name of the field or method that this column is mapped to. (Optional)