This feature supports many Oracle Tuxedo buffer types so that you do not need to manage to match your data with the data types that Oracle Tuxedo supports. The supported Tuxedo buffer types are CARRAY,
FML,
FML32,
MBSTRING,
STRING,
VIEW,
VIEW32,
XML,
RECORD,
X_C_TYPE, and
X_COMMON.
This feature supports many Oracle Tuxedo buffer types so that you do not need to manage to match your data with the data types that Oracle Tuxedo supports. The supported Tuxedo buffer types are CARRAY,
FML,
FML32,
MBSTRING,
STRING,
VIEW,
VIEW32,
XML,
RECORD,
X_C_TYPE, and
X_COMMON.
Figure 13‑1 illustrates a typical deployment in an Oracle Tuxedo MP domain to use TDC based on Oracle Coherence.
java -server -showversion $JAVA_OPTS -Dtangosol.coherence.mode=prod -cp $APPDIR/config: ${COHERENCE_HOME}/lib/coherence.jar com.tangosol.net.DefaultCacheServer
Listing 13‑2 is an example; note the properties in bold. In this example,
coherence_tux is the name of the Oracle Coherence cluster whose multicast port number is
51697 and unicast port number is
51687.
Listing 13‑3 is an example; note the properties in bold. In this example, we create an Oracle Coherence cache named
tux_distributed.
Listing 13‑4 is an example of Oracle Tuxedo Java Server Configuration File that enables TDC. For more information, see
Java Server Configuration Schema File for version 2.0.
<jvm-options>-XX:MaxPermSize=192m</jvm-options>
<classpath>${TUXDIR}/udataobj/tuxj/tdc/com.oracle.tuxedo.tdcj.jar</classpath>
Listing 13‑5 shows a template of the property file. You can find this template in
$TUXDIR/udataobj/tuxj/tdc/tdcsvr_coh.conf.template. In this template, two Oracle Tuxedo cache names are configured:
tc1 and
tc2.
tc1 uses Oracle Coherence cache
tux_distributed and
tc2 uses Oracle Coherence cache
tux2_distributed.
Configure TMJAVASVR on
UBBCONFIG.
TMJAVASVR uses multi-threaded configuration to improve performance. Multi-instances configuration is also used to gain higher availability.
Suppose ${APPDIR} is
/home/scott/tuxedo/dom1.
java -server -showversion $JAVA_OPTS -Dtangosol.coherence.mode=prod -cp ${APPDIR}/config: ${COHERENCE_HOME}/lib/coherence.jar com.tangosol.net.DefaultCacheServer
Preparing tdcsvr_coh.xml for Oracle Tuxedo java server in
${APPDIR}/config.
See Listing 13‑11, where the
<server-clopt>-f /home/scott/tuxedo/dom1/config/tdcsvr_coh.conf</server-clopt> property specifies the TDC property file.
<jvm-options>-XX:MaxPermSize=192m</jvm-options>
<classpath>${TUXDIR}/udataobj/tuxj/tdc/com.oracle.tuxedo.tdcj.jar</classpath>
<classpath>${COHERENCE_HOME}/lib/coherence.jar</classpath>
<classpath>${APPDIR}/config</classpath>
<server-class name="com.oracle.tuxedo.tdc.TCache4Coherence">
Prepare tdcsvr_coh.conf for TDC property file in
${APPDIR}/config.
See Listing 13‑12, where it configures Oracle Tuxedo cache
tc, which actually uses Oracle Coherence cache
tux_distributed.
See Listing 13‑13, where multi-threaded configuration is enabled and
TMJAVASVR configuration file
tdcsvr_coh.xml is set.
databuf = tpalloc("STRING", NULL, 256);
mycache = tpgetcache("tc");
strcpy(databuf, "scott");
tpcacheput(mycache, mykey, databuf, 0, 0L);
databuf = tpalloc("STRING", NULL, 256);
mycache = tpgetcache("tc");
tpcacheget(mycache, mykey, &databuf, NULL, 0L);
|
•
|
Svccache1 uses Oracle Tuxedo cache tc1. Other configurations are default. (It means KEY=$service+$request and KEY_BUFTYPE=STRING).
|
|
•
|
Svccache2 uses Oracle Tuxedo cache tc1. The request is used to figure out the key when caching the response data. Other configurations are default. (It means KEY_BUFTYPE=STRING).
|
|
•
|
Svccache3 uses Oracle Tuxedo cache tc1. The fixed string key1 is used as the key. Other configurations are default.
|
|
•
|
Svccache4 uses Oracle Tuxedo cache tc1. The buffer type of the request message to the service is VIEW32 whose subtype is mystruct1. The value of the field name in the subtype mystruct1 is used as the key.
|
|
•
|
Svccache5 uses Oracle Tuxedo cache tc1. The buffer types of the FML32 and VIEW32: mystruct1 have the same field1 and field2 (name and data type should be the same; value can be different); the request message will use the values of field1 and field2 as the key.
|
Oracle Tuxedo service mysvc1 uses caching entry
svccache1 to improve performance.
svccache1 uses Oracle Tuxedo cache
tc1 to cache the service result. The corresponding key of the response is the value of the request data.
At the first time where Scott is taken as the request,
mysvc1 is invoked and the response is sent back and the response is cached into Oracle Tuxedo cache
tc1 with a key
Scott. As long as the data in the cache
tc1 is not expired, all following requests for
Scott to service
mysvc1 will get response from the cache
tc1 instead of invoking the service itself.
If the identifier ECID_USERLOG is set and the ECID is not a null string, ECID will be appended to the userlog.
Prepare tangosol-coherence-override.xml in
${APPDIR}/config. More specifically,
|
•
|
<destination> element is used to configure path and file name for emitting log messages to a file. The specified path must already exist.
|
|
•
|
Add ecid into < message-format > element to enable ECID.
|
tpgetcache - Get an Oracle Tuxedo Cache handle according to the configuration
tpgetcache(3c) gets an Oracle Tuxedo cache handle according to Oracle Tuxedo cache name, which indicates the name of Oracle Tuxedo cache to be retrieved. The name must be 78 characters or less in length.
tpgetcache(3c) is a thread-level API. The return handle
TCACHE can only be used in the same thread.
Upon success, tpgetcache(3c) returns a handle typed
TCACHE while is an internal structure.
Upon failure, tpgetcache(3c) returns
NULL and sets
tperrno to indicate the error condition. If a call fails with a particular
tperrno value, a subsequent call to
tperrordetail(3c), with no intermediate ATMI calls, may provide more detailed information about the generated error. Refer to the
tperrordetail(3c) reference page for more information.
tpcacheput - put an Oracle Tuxedo typed buffer into a cache, associating that buffer with a key
tpcacheput(3c) puts an Oracle Tuxedo typed buffer into a cache, associating that buffer with a key.
tc is returned by
tpgetcache(3c).
data points to the tuxedo typed buffer allocated by
tpalloc(3c).
len is the length of the data. If the type of the data does not require a length to be specified (for example, an FML fielded buffer),
len is ignored (and may be 0).
flags is reserved and must be
0L.
Upon failure, tpcacheput(3c) returns -1 and sets
tperrno to indicate the error condition. If a call fails with a particular
tperrno value, a subsequent call to
tperrordetail(3c), with no intermediate ATMI calls, may provide more detailed information about the generated error. Refer to the
tperrordetail(3c) reference page for more information.
tpcacheget - get the Oracle Tuxedo typed buffer associated with the key from a cache
tpcacheget(3c) gets the Oracle Tuxedo typed buffer associated with the key from a cache.
tc is returned by
tpgetcache(3c).
odata is the address of a pointer to the buffer where the data of the key is read into. It must point to a buffer originally allocated by
tpalloc(3c).
olen points to the length of the data.
flags is reserved and must be
0L.
Upon failure, tpcacheget(3c) returns -1 and sets
tperrno to indicate the error condition. If a call fails with a particular
tperrno value, a subsequent call to
tperrordetail(3c), with no intermediate ATMI calls, may provide more detailed information about the generated error. Refer to the
tperrordetail(3c) reference page for more information.
tpcacheremove - remove the cache entry associated with the parameter key from a cache
tpcacheremove(3c) removes the cache entry associated with the parameter key from a cache.
tc is returned by
tpgetcache(3c).
flags is reserved and must be
0L.
Upon failure, tpcacheremove(3c) returns -1 and sets
tperrno to indicate the error condition. If a call fails with a particular
tperrno value, a subsequent call to
tperrordetail(3c), with no intermediate ATMI calls, may provide more detailed information about the generated error. Refer to the
tperrordetail(3c) reference page for more information.
tpcachemremove - remove cache entries associated with the parameter keyarray from a cache
tpcachemremove(3c) removes cache entries associated with the parameter keyarray from a cache.
tc is returned by
tpgetcache(3c).
keyarray is an array of keys to be removed.
size is the size of the keyarray.
flags is reserved and must be
0L.
Upon failure, tpcachemremove(3c) returns -1 and sets
tperrno to indicate the error condition. If a call fails with a particular
tperrno value, a subsequent call to
tperrordetail(3c), with no intermediate ATMI calls, may provide more detailed information about the generated error. Refer to the
tperrordetail(3c) reference page for more information.
tpcacheremoveall - remove all cache entries from a cache
tpcacheremoveall(3c) removes all entries from a cache.
tc is returned by
tpgetcache(3c).
flags is reserved and must be
0L.
Upon failure, tpcacheremoveall(3c) returns -1 and sets
tperrno to indicate the error condition. If a call fails with a particular
tperrno value, a subsequent call to
tperrordetail(3c), with no intermediate ATMI calls, may provide more detailed information about the generated error. Refer to the
tperrordetail(3c) reference page for more information.
A natural line that contains only white space characters is considered blank and is ignored. A comment line has an ASCII '#' or
'!' as its first non-white space character; the key contains all of the characters in the line starting with the first non-white space character and up to, but not including, the first unescaped
'=', ':'. Any white space after the key is skipped; if the first non-white space character after the key is
'=' or
':', then it is ignored and any white space characters after it are also skipped. All remaining characters on the line become part of the associated element string; if there are no remaining characters, the element is the empty string
"".
Table 13‑2 lists the supported TDC property file properties.
|
|
|
|
|
|
•
|
yes (all caching data must be encoded)
|
This value can be overridden by cache.options.encode.[cachename].
|
|
|
yes indicates all caching data in Oracle Tuxedo cache [cachename] must be encoded. It should be enabled when caching users are located in machines that have different data representation.
If this property is not set, options.encoding value is used.
|
|
|
|
|
|
|
|
|
The string_value should be the CACHING_CRITERIA_NAME defined in the CACHING section. You must specify this parameter; otherwise, service caching will not be enabled. The string_value must be 127 characters or less in length.
|
|
|
|
|
|
CACHING_CRITERIA_NAME ( string_value) is the name assigned to the CACHING parameter for a particular service entry in the SERVICES section. CACHING_CRITERIA_NAME must be 127 characters or less in length.
|
|
|
Specifies the name of Oracle Tuxedo cache to be used. string_value must be 78 characters or less in length.
|
|
|
This parameter is optional. If not specified, the key is generated as a combination of the service name and the serialized user data in the request. string_value can import the built-in variables to compose key by $. The variable request indicates to use part of or total user data in the request.
For example, mykey_$request indicates the key's format is mykey_servicename_[user data in request].
KEY_BUFTYPE and KEY_FIELD parameters can help to specify which part of the user data will be used.
|
|
|
The type must be one of the following: STRING, CARRAY, FML, FML32, XML, VIEW, VIEW32, RECORD, MBSTRING, X_C_TYPE, or X_COMMON. No subtypes can be specified for types STRING, CARRAY, FML, FML32, MBSTRING, or XML. Subtypes are required for type VIEW, VIEW32, RECORD, X_C_TYPE, and X_COMMON ( * is not allowed). Subtype name should not contain semicolon, colon, comma, or asterisk characters. Duplicate type/subtype pairs cannot be specified for the same caching criteria name; more than one caching entry can have the same criteria name as long as the type/subtype pairs are unique. If multiple buffer types are specified for a single caching entry, the data types of the caching field for each buffer type must be the same.
STRING is used if this parameter is not specified.
|
|
|
Each field can be an XML element, element attribute, or field name in an FML field table (using FLDTBLDIR and FIELDTBLS environment variables, or FLDTBLDIR32 and FIELDTBLS32 environment variables), or an FML view table (using VIEWDIR and VIEWFILES environment variables, or VIEWDIR32 and VIEWFILES32 environment variables). This information is used to get the associated field value for service caching when sending a message.
If KEY_BUFTYPE is set to STRING or CARRAY, define the field with the following syntax:
Index1 indicates the beginning index of the field in the buffer and index2 indicates the ending index of the field. The whole buffer is taken as the key if this parameter is not defined. The index should be set from 1.
This parameter is ignored if KEYBUFTYPE is not set or KEY is not set to request.
|
This T_SERVICE object indicates the caching criteria name. Any updates on this attribute will be reflected in all associated
T_SVCGRP objects.
This T_CACHING class represents configuration attributes of caching specifications for an application. These attribute values identify and characterize application caching criteria (such as buffer types, field names and caching definitions).
|
•
|
(*) GET/SET key, one or more required for SET operations
|
|
•
|
The specified u (uniqueness) permission means aht the combination of TA_CACHING_NAME and TA_CACHING_KEY_BUFTYPE must be unique.
|
Specifies a list of types and subtypes of data buffers for which this caching entry is valid to use to generate the key. This parameter can be up to 255 characters in length and a maximum of 32 type/subtype combinations.
The type must be one of the following: STRING,
CARRAY,
FML,
FML32,
XML,
VIEW,
VIEW32,
RECORD,
MBSTRING,
X_C_TYPE, or
X_COMMON. No subtypes can be specified for types
STRING,
CARRAY,
FML,
FML32,
MBSTRING, or
XML. Subtypes are required for type
VIEW,
VIEW32,
RECORD,
X_C_TYPE, and
X_COMMON (
* is not allowed). Subtype name should not contain semicolon, colon, comma, or asterisk characters. Duplicate type/subtype pairs cannot be specified for the same routing caching criteria name; more than one routing caching entry can have the same criteria name as long as the type/subtype pairs are unique.
If multiple buffer types are specified for a single caching entry, the data types of the caching field for each buffer type must be the same.
Specifies the name of the fields in the buffer used to generate the key. It must be 255 characters or less and a maximum of 8 fields are allowed.
Each field can be an XML element, element attribute, or field name in an FML field table (using FLDTBLDIR and
FIELDTBLS environment variables, or
FLDTBLDIR32 and
FIELDTBLS32 environment variables), or an FML view table (using
VIEWDIR and
VIEWFILES environment variables, or
VIEWDIR32 and
VIEWFILES32 environment variables). This information is used to get the associated field value for service caching when sending a message.
For XML element content or element attribute in the XML buffer, define the name of the field with the following syntax:
root_element[/child_element][/child_element][/. . .][/@attribute_name]
The element name and attribute name combined may contain no more than 35 characters. Oracle Tuxedo recognizes only the first occurrence of a given element type when processing an XML buffer for service caching. XML strictly defines the set of characters that may be used in an attribute name. An attribute name must be a string consisting of a single letter, underscore, or colon followed by one or more name characters. Both element names and attribute names are case-sensitive. See XML documentation for more information.
If
KEY_BUFTYPE is set to
STRING or
CARRAY, define the field with the following syntax:
[index1, index2]
Index1 indicates the beginning index of the field in the buffer and
index2 indicates the ending index of the field. The whole buffer is taken as the key if this parameter is not defined. The index should be set from 1.
A GET operation will retrieve configuration information for the selected
T_CACHING object(s). The following state indicates the meaning of a
TA_STATE returned in response to a
GET request. States not listed will not be returned.
VALid:
T_CACHING object is defined. Note that this is the only valid state for this class.
A SET operation will update configuration information for the selected
T_CACHING object. The following states indicate the meaning of a
TA_STATE set in a
SET request. States not listed may not be set.
NEW: Create
T_CACHING object for application. State change allowed only when in the
INValid state. Successful return leaves the object in the
VALid state.
INValid: Delete
T_CACHING object for application. State change allowed only when in the
VALid state. Successful return leaves the object in the
INValid state.
