4 User Payload Collection

This chapter contains the following topics:

• Overview
  
• Supported User Payload Buffer Types
  
• Determine User Payload Storage
  
• Configuring User Payload Collection
  
• Exporting Collected User Payload Data
  

4.1 Overview

Oracle Tuxedo applications send and receive their data in typed buffers. The input message and output message of a Tuxedo service are described in Tuxedo buffer types. TSAM Plus can collect the user payload encapsulated in the Tuxedo service input and output buffer, store the collected payload in Oracle Database, Hadoop or local file, and provide a series of APIs and tools to export the payload for further aggregation and analysis.

4.2 Supported User Payload Buffer Types

The following table lists the supported Oracle Tuxedo buffer types for user payload.

Table 4-1 Supported Oracle Tuxedo Buffer Types in User Payload

Type Name	Description
CARRAY	Character array (possibly containing NULL characters) that is neither encoded nor decoded during transmission
X_OCTET	Equivalent to CARRAY; provided for XATMI compatibility
STRING	NULL-terminated character array
FML	FML fielded buffer
VIEW	C structure or FML view
X_C_TYPE	Equivalent to VIEW; provided for XATMI compatibility
X_COMMON	Equivalent to VIEW; provided for XATMI compatibility
FML32	FML32 fielded buffer, using 32-bit identifiers and offsets
VIEW32	C structure or FML32 view, using 32-bit identifiers, counter variables, and size variables
XML	Buffer for XML documents

4.3 Determine User Payload Storage

TSAM Plus supports different kinds of storage for the collected user payload, which include Oracle Database, Hadoop, and local file.

• User Payload Record in Oracle Database
  
• User Payload Record in Hadoop
  
• User Payload Record in Local File
  
• Specifying User Payload Storage from TSAM Plus Console
  

4.3.1 User Payload Record in Oracle Database

User payload data is stored in the table MON_PAYLOAD in TSAM plus Database, as listed in the table below.

Table 4-2 User Payload Data in MON_PAYLOAD

COLUMN	TYPE	Nullable	Constraints	Since Version	Description
ID	NUMBER	NO		12.2.2	auto-generated ID
DOMAINID	VARCHAR2(30)	YES		12.2.2	Domain ID, it is null when no DOMAINID is set in UBBCONFIG
LMID	VARCHAR2(30)	YES		12.2.2	Machine LMID
GROUPID	SMALLINT	YES		12.2.2	Tuxedo group number
SERVERID	SMALLINT	YES		12.2.2	Server ID
SVCNAME	VARCHAR2(127)	YES		12.2.2	Service name
CORRELATIONID	VARCHAR2(255)	YES		12.2.2	Call path CORRELATIONID
ECID	VARCHAR2(1024)	YES		12.2.2	Tuxedo call ECID
TPERRNO	SMALLINT	YES		12.2.2	tperrno
VALUETYPEINDEX	SMALLINT	YES		12.2.2	Tuxedo buffer type index, defined in weblogic.wtc.jatmi.StandardTypes CARRAY : 16 STRING : 17 FML : 18 VIEW : 19 X_OCTET : 20 X_C_TYPE : 21 X_COMMON : 22 FML32 : 23 VIEW32 : 24 XML : 25
VALUESUBTYPE	VARCHAR2(127)	YES		12.2.2	Tuxedo sub buffer type. It is the view or view32 name
PAYLOADTYPE	SMALLINT	YES		12.2.2	1 means request; 2 means reply
VALUE	BLOB	YES		12.2.2	User payload value
LOGTIME	TIMESTAMP	YES		12.2.2	The timestamp when this record is reported from TSAM Plus Agent.

4.3.2 User Payload Record in Hadoop

User payload data can be stored in HDFS. It requires JRE 1.7 or above.

To store the payload into the Hadoop file system, you must set the environments JAVA_HOME and library path before starting LMS. Additionally, the LMS -T option must not be set or set to 1.

For Linux systems, the library path LD_LIBRARY_PATH must include the libjvm.so

Following is an example for Linux:

export JAVA_HOME=/home/user1/jdk1.7.0_21

export HADOOP_HOME=/home/user1/hadoop-2.6.0

export LD_LIBRARY_PATH=$JAVA_HOME/jre/lib/amd64/server/:$LD_LIBRARY_PATH

For AIX systems, set LIBPATH instead of LD_LIBRARY_PATH.

For example:

export LIBPATH=/usr/$JAVA_HOME/jre/lib/ppc64/classic:$JAVA_HOME/jre/libppc64:$JAVA_HOME/jre/lib/ppc64/j9vm

• File Naming
  
• Content Format
  

4.3.2.1 File Naming

If you choose to output the payload data to Hadoop file system, TSAM Plus generates a payload file to store the payload key and data. Each machine writes a distinct file every day.

The format is <domain>_<machine>_<yyyymmdd>.payload. The new hadoop file is produced every day and there is no file size limit.

4.3.2.2 Content Format

TSAM Plus uses the Hadoop SequenceFile format (Hadoop 2.6 ver=6) to store the payload in HDFS. Each payload record includes the key and value data. The record (org.apache.hadoop.io.BytesWritable) can be parsed using the Java class com.oracle.tsam.payload.PayloadRecord.

The record key class is org.apache.hadoop.io.LongWritable and the value class is org.apache.hadoop.io.BytesWritable. Both are stored as the record.

Following is the payload SequenceFile format:

• Header
  • version - 3 bytes of the magic header SEQ, followed by 1 byte of actual version number (e.g. SEQ4 or SEQ6)
  • keyClassName - Key class
  • valueClassName - Value class
  • compression - A boolean that specifies if compression is turned on for keys/values in this file. 0 is used for payload file.
  • blockCompression - A boolean that specifies if block compression is turned on for keys/values in this file. 0 is used for payload file.
  • metadata - SequenceFile.Metadata for this file. 0x0,0x0,0x0,0x0
  • sync - A sync marker that denotes the end of the header.
• Record
  • Record length
  • Key length
  • Key
  • Value length
  • Value - Payload record that includes the payload key and value
• A sync-marker.

4.3.3 User Payload Record in Local File

The naming and content format of the user payload record in local file are same as rules on Hadoop.

You can specify the local file directory where the payload data will be stored using the LMS server CLOPT parameter in UBBCONFIG. For example, to store the payload data in the file at /u01/common/patches/oracle/payload, configure the following in the UBBCONFIG file:

LMS SRVGRP=LMSGRP SRVID=2 CLOPT="-A -- -l <tsam_manager_host>:7001/tsam -p /u01/common/patches/oracle/payload"

For more information, refer to Local Monitor Server in Oracle TSAM Plus Server, Command, and API Reference Guide.

4.3.4 Specifying User Payload Storage from TSAM Plus Console

To specify the storage method for the user payload data, do the following:

1. From the TSAM Plus console top menu bar, click Management -> Global Parameters
2. In the TSAM Plus Global Properties tab, select one of the storage: Database, Hadoop, or local file.
3. If Hadoop is selected, continue specifying the following fields:
   • Hadoop URL:

     Specify the Hadoop URL where you want to store the user payload data. The Hadoop URL must include the hostname, port, and payload file directory. For example: hdfs://localhost:8080/tmp/tuxPayload/

4. Click Modify.

4.4 Configuring User Payload Collection

You can define user payload data collection policies for services or call path. Take call path for example, to configure collection policies, follow the steps below:

1. From the TSAM Plus console top menu bar, click Policy-> Tuxedo Monitoring Policy.
2. In the Monitoring Policy List page, click Add to enter the Edit Policy page.
3. In the left Tuxedo Component filter area, select the Tuxedo domain to monitor.
4. In the Call path tab, select Enable to enable the call path metrics collection.
5. Click the Define Payload Collection button to configure payload collection rules.
6. In the Define Payload Collection page, you can enable request and/or response payload collection by selecting the corresponding checkbox. If request payload collection is enabled, you can decide if only collecting the payload for initial called service by selecting Initial Called Service Only or not.
7. Click OK. Then enable the policy.

   Note:

   The call path user payload data collection policies cannot be propagated to other domains.

   Now you have completed the definition of a most general user payload collection policy. All the payload belonging to the defined scope will be collected and saved to the designated payload storage.

   You can also narrow down the payload data collection scope by defining collection data criteria or result filter. For more information, see Defining Payload Collection Data Criteria and Defining Payload Collection Result Filter .

• Defining Payload Collection Data Criteria
  
• Defining Payload Collection Result Filter
  

4.4.1 Defining Payload Collection Data Criteria

When a data criteria is defined, TSAM Plus collects the payload only if the typed buffer value fulfills the criteria. For example, when a STRING typed buffer starts with the word Hello, or a FML32 typed buffer whose ACCOUNT_ID field has a value larger than 1000, the system collects the payload.

To define the data criteria, do the following steps:

1. Go to the Data Criteria tab in the Define Payload Collection dialog. All the supported buffer types are listed in the drop down list.
2. Select the buffer type you want to define a criteria against and then click Add.
   A table with the title Add one or multiple data criteria entries is displayed.

   Table 4-3 Data Criteria Table

   Column Name	Visible for Buffer Type	Description
   Field Name	FML/FM32VIEW/VIEW32X_COMMON/X_C_TYPE	A single selection drop down list. For FML/FML32, it is the field name in the FML field table definition file. The supported field types are: short, long, float, double, char, and string. Fields with other types are hidden from the drop down list. For all VIEW liked buffer types, it is the VIEW name defined after the VIEW keyword in the VIEW table definition file.
   Sub Field Name	VIEW/VIEW32X_COMMON/X_C_TYPE	A single selection drop down list. The value is the VIEW field name (CNAME) in the VIEW table definition file. The supported field types are same with the FML fields.
   Occurrence	FML/FML32	The specific occurrence of a FML field.
   Operator	All buffer types	A single selection drop down list. For numeric fields, the options are: >, >=, <, <=, ==, !=For alphabetic fields, the options are: ==, !=, %%, !%
   Value	All buffer types except XML	A text input box. It is the value part (after the operator) of a FML Boolean Expression. No operators are allowed here.It must fit all the syntax defined by the FML Boolean Expression. For more information about FML Boolean Expression, refer to the online Oracle Tuxedo Documentation. Examples of the value are: 'Hello.*' (Note the single quote) 'Hello.*' (Note the single quote) 1000
   Expression	XML	A text input box. A valid XPath expression is expected here.
   Direction	All buffer types	This area is made up of three mutually exclusive radio buttons. If both request and response payload collection are enabled in the General tab, all the three radio buttons - Inout, In, and Out are enabled. Otherwise only the corresponding radio button is enabled. If Inout is selected, current criteria expression takes effect for both request and response buffers. If In or Out is selected, only request or response buffer is evaluated against current criteria.
   Actions	All buffer types	This column contains one add button and one remove button. Multiple data criteria expression entries can be added to the table. On saving of the policy, each entry forms a FML Boolean expression and different entries in the same table are of the logical AND relationship.

3. Once all the criteria expression entries are defined, click Submit to save your configurations.

   After returning to the data criteria listing page, you can find the new-created data criteria in the listing table.

Note:

• You can add multiple data criteria for the same buffer type. They are of logical OR relationship. It means that any of the data criteria is satisfied when the payload is collected.
• For the buffer type FML32/FML/VIEW32/VIEW/X_C_TYPE/X_COMMON, the field table definition files must be uploaded in the Data Management -> Field Tables Management tab page before defining the data criteria.

4.4.2 Defining Payload Collection Result Filter

The result filter defines for each buffer type, for example, which fields or the char sequence ranges are collected, regardless of the runtime payload data value. Compared to data criteria, it is a relative static definition to filter unnecessary fields out.

Defining the result filter are very similar to the operations of defining data criteria. The differences are:

In the result filter listing page, each buffer type can only be defined with one result filter.

In the result filter entries definition page, different filter entries are of logical OR relationship. This means in the runtime, TSAM Plus tries to collect all the defined entries of a result filter.

Note:

If both the result filters for call path and services are enabled on a Tuxedo service call, the filters on the call path take effect.

4.5 Exporting Collected User Payload Data

The user payload data stored in Oracle TSAM Plus database, local file, or Hadoop is in binary format. For ease of data analysis, you can export the data to text format or XML format using the export APIs or payload dump tool.

• APIs for Data Export
  
• Payload Dump Tool
  

4.5.1 APIs for Data Export

The following table lists the APIs for exporting the user payload data.

Table 4-4 APIs for Data Export

Category	API	Description
Interface	PayloadRepository	Payload metrics storage interface
Class	FilePayloadIterator	Payload record iterator of file storage
	FilePayloadRepository	File storage of payload metrics
	HadoopPayloadIterator	Payload record iterator of Hadoop storage
	HadoopPayloadRepository	Hadoop storage of payload metrics
	payloaddump	A command line tool dumping payload metrics
	PayloadRecord	Payload record in the storage
	PayloadValue	Payload metrics.
	TSAMDBPayloadIterator	Payload record iterator of TSAM Plus database storage
	TSAMDBPayloadRepository	TSAM Plus database storage of payload metrics
Enum	Enum PayloadType	Payload metrics type

When using API for data export, you must include the following jar in CLASSPATH under $TSAMDIR/lib: CLASSPATH=payloadapi.jar:com.bea.core.jatmi_2.0.0.0.jar:com.oracle.tuxedo.tjatmi_12.1.3.0.jar:commons-cli-1.2.jar

If you want to export the payload from Hadoop dfs, set the HADOOP_HOME:

HADOOP_HOME=/home/user/hadoop-2.6.0/

If you want to export the payload from Oracle Database, include ojdbc6.jar in CLASSPATH.

• PayloadRepository
  
• FilePayloadIterator
  
• FilePayloadRepository
  
• HadoopPayloadIterator
  
• HadoopPayloadRepository
  
• payloaddump
  
• PayloadRecord
  
• PayloadValue
  
• TSAMDBPayloadIterator
  
• TSAMDBPayloadRepository
  
• Enum PayloadType
  
• Payload API Samples
  

4.5.1.1 PayloadRepository

All Superinterfaces java.lang.AutoCloseable, java.io.Closeable, java.lang.Iterable<PayloadRecord>

All Known Implementing Classes FilePayloadRepository, HadoopPayloadRepository,TSAMDBPayloadRepository

Description public interface PayloadRepository extends java.lang.Iterable<PayloadRecord>,java.io.Closeable

Payload metrics storage interface

4.5.1.2 FilePayloadIterator

java.lang.Object

com.oracle.tsam.payload.FilePayloadIterator

All Implemented Interfaces

java.util.Iterator<PayloadRecord>

Description

public class FilePayloadIterator extends java.lang.Object implements java.util.Iterator<PayloadRecord>

Payload record iterator of file storage.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

FilePayloadIterator

public FilePayloadIterator(org.apache.hadoop.io.SequenceFile.Reader reader)

Constructs a FilePayloadIterator with a reader

Method Detail

hasNext

public boolean hasNext()

Specified by:

hasNext in interface java.util.Iterator<PayloadRecord>

next

public PayloadRecord next()

Specified by:

next in interface java.util.Iterator<PayloadRecord>

remove

public void remove()

Specified by:

remove in interface

java.util.Iterator<PayloadRecord>

4.5.1.3 FilePayloadRepository

FilePayloadRepository

java.lang.Object

com.oracle.tsam.payload.FilePayloadRepository

All Implemented Interfaces

PayloadRepository, java.io.Closeable,

java.lang.AutoCloseable, java.lang.Iterable<PayloadRecord>

Description

public class FilePayloadRepository

extends java.lang.Object

implements PayloadRepository

File storage of payload metrics.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

FilePayloadRepository

            public FilePayloadRepository(java.lang.String path)

             throws java.io.IOException      

              Constructs a FilePayloadRepository with a path

              Throws:

      java.io.IOException

Method Detail

iterator

public java.util.Iterator<PayloadRecord> iterator()

Specified by:

iterator in interface java.lang.Iterable<PayloadRecord>

close

public void close()

throws java.io.IOException

Specified by:

close in interface java.io.Closeable

Specified by:

close in interface java.lang.AutoCloseable

Throws:

java.io.IOException

getFile

public java.io.File getFile()

Returns the File object

4.5.1.4 HadoopPayloadIterator

HadoopPayloadIterator

java.lang.Object

com.oracle.tsam.payload.HadoopPayloadIterator

All Implemented Interfaces

java.util.Iterator<PayloadRecord>

Description

public class HadoopPayloadIterator

extends java.lang.Object

implements java.util.Iterator<PayloadRecord>

Payload record iterator of Hadoop storage.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

HadoopPayloadIterator

public HadoopPayloadIterator(java.lang.String HadoopURL,

java.lang.String[] MatchFiles)

throws java.io.IOException

Throws:

java.io.IOException

Method Detail

hasNext

public boolean hasNext()

next

public PayloadRecord next()

Specified by:

next in interface java.util.Iterator<PayloadRecord>

close

public void close()

throws java.io.IOException

Throws:

java.io.IOException

remove

public void remove()

Specified by:

remove in interface java.util.Iterator<PayloadRecord>

4.5.1.5 HadoopPayloadRepository

HadoopPayloadRepository

java.lang.Object

com.oracle.tsam.payload.HadoopPayloadRepository

All Implemented Interfaces

PayloadRepository, java.io.Closeable, java.lang.AutoCloseable,

java.lang.Iterable<PayloadRecord>

Description

public class HadoopPayloadRepository

extends java.lang.Object

implements PayloadRepository

Hadoop storage of payload metrics.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

HadoopPayloadRepository

HadoopPayloadIterator

public HadoopPayloadRepository(java.lang.String HadoopURL,
java.lang.String Domain,
java.lang.String Machine,
java.util.Date StartDate,
java.util.Date EndDate)
throws java.io.IOException

Constructs a HadoopPayloadRepository with a Hadoop URL and filters of domain name, machine name, start date, and end date

Throws:

java.io.IOException

Method Detail

iterator

public java.util.Iterator<PayloadRecord> iterator()

Specified by:

iterator in interface java.lang.Iterable<PayloadRecord>

close

public void close()

throws java.io.IOException

Specified by:

close in interface java.io.Closeable

Specified by:

close in interface java.lang.AutoCloseable

Throws:

java.io.IOException

payloaddump

java.lang.Object

com.oracle.tsam.payload.payloaddump

Description

public class payloaddump

extends java.lang.Object

Constructor Detail

4.5.1.6 payloaddump

java.lang.Object

com.oracle.tsam.payload.payloaddump

Description

public class payloaddump

extends java.lang.Object

A command line tool dumping payload metrics.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

payloaddump

public payloaddump()

Method Detail

main

public static void main(java.lang.String[] args)

throws org.apache.commons.cli.ParseException,

java.lang.ClassNotFoundException,

java.sql.SQLException,

java.io.IOException,

javax.xml.parsers.ParserConfigurationException,

java.text.ParseException,

java.lang.Exception

Parameters:

args

-url

Mandatory parameter. Payload repository URL. It can be a database URL, Hadoop URL, or a file path

-username

Database user name

-password

Database password

-payloadtype

Mandatory parameter. Request or reply

-wherecondition

SQL query condition. It is available only when the URL is specified to a Database URL.

-domainid

The domain ID used to filter the results

-servicename

The service name used to filter the results

-outputtype

XML or text. The default output type is xml.

-fieldnames

Expected field names when the output type is text. For the Tuxedo type CARRAY, X_OCTET, and STRING, the fieldnames is the aliasNames specified in the result filter of the user payload policy. If url is specified to a Database URL and servicename is specified, the default fieldnames is from the service contract information. If url is specified to a Database URL and policyname and servicename are both specified, the default fieldnames is the join result of the service contract information and the result filter of the policy.

-O

Output file name. The default output is standard output.

Throws:

org.apache.commons.cli.ParseException

java.lang.ClassNotFoundExceptionjava.sql.SQLException

java.io.IOException

javax.xml.parsers.ParserConfigurationException

java.text.ParseException

java.lang.Exception

4.5.1.7 PayloadRecord

java.lang.Object

com.oracle.tsam.payload.PayloadRecord

Description

public class PayloadRecord

extends java.lang.Object

Payload record in the storage.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

PayloadRecord

public PayloadRecord(java.lang.String dOMAINID,

java.lang.String LMID,

short groupID,

short serverID,

java.lang.String serviceName,

java.lang.String correlationID,

java.lang.String ECID,

java.lang.Short errno,

PayloadType payloadType,

java.util.Date logtime,

PayloadValue payloadValue)

Method Detail

getdOMAINID

public java.lang.String getdOMAINID()

setdOMAINID

public void setdOMAINID(java.lang.String dOMAINID)

getLMID

public java.lang.String getLMID()

setLMID

public void setLMID(java.lang.String lMID)

getGroupID

public short getGroupID()

setGroupID

public void setGroupID(short groupID)

getServerID

public short getServerID()

setServerID

public void setServerID(short serverID)

getServiceName

public java.lang.String getServiceName()

setServiceName

public void setServiceName(java.lang.String serviceName)

getCorrelationID

public java.lang.String getCorrelationID()

setCorrelationID

public void setCorrelationID(java.lang.String correlationID)

getECID

public java.lang.String getECID()

setECID

public void setECID(java.lang.String eCID)

getTperrno

public PayloadType getPayloadType()

setTperrno

public void setTperrno(java.lang.Short tperrno)

getPayloadType

public PayloadType getPayloadType()

setPayloadType

public void setPayloadType(PayloadType payloadType)

getPayloadValue

public PayloadValue getPayloadValue()

setPayloadValue

public void setPayloadValue(PayloadValue payloadValue)

getLogtime

public java.util.Date getLogtime()

setLogtime

public void setLogtime(java.util.Date logtime)

4.5.1.8 PayloadValue

java.lang.Object

com.oracle.tsam.payload.PayloadValue

Description

public class PayloadValue

extends java.lang.Object

Payload metrics. It has two kinds of output formats:

• Text: It is same to the Database export format in "text" mode so that it can be imported into a Database table as the BI data source.

  Note:

  You can define the sequence of the output data using String [] fieldNames. If no fieldnames are provided, the fields are outputted in the default order. None of the embedded buffer is outputted.
• XML: The formatter can convert the typed buffer CARRAY, X_OCTET, STRING, FML, FML32, VIEW, VIEW32, X_C_TYPE, X_COMMON, and XML to XML format. If the buffers are nested, all the nested buffers are also converted.

  For CARRAY/X_OCTET/STRING, the payload is converted to an element in XML format. CARRAY is encoded to a base64 string. The element name is the value specified to the parameter elemName.

  For FML/FML32/VIEW/VIEW32/X_C_TYPE/X_COMMON, the formatter converts all the fields in the typed buffer. If these kinds of typed buffers are nested, all the nested buffers are also converted.

  For XML, the formatter makes no change.

  Methods inherited from class java.lang.Object

  equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  Constructor Detail

  PayloadValue

  public PayloadValue(short valueTypeIndex,

  byte[] payloadValue)

Method Detail

getFieldNames

public java.lang.String[] getFieldNames()

Returns:

The field names in this object

toXMLString

public java.lang.String toXMLString(java.lang.String encoding)

throws java.io.IOException, javax.xml.parsers.ParserConfigurationException,

org.xml.sax.SAXException convert payload value to a XML string. Parameters:

encoding

Parameters:

encoding

Throws:

java.io.IOException

javax.xml.parsers.ParserConfigurationException

org.xml.sax.SAXException

toText

public java.lang.String toText(char delimiter,

char enclosure)

throws java.io.IOException,

javax.xml.parsers.ParserConfigurationException,

org.xml.sax.SAXException

convert payload value to text, which can be imported into a Database table. The embedded fields are not in the returned value. Characters equaling to the enclosure are duplicated

Parameters:

delimiter - delimiter character

enclosure - enclosure character

Returns:

text

Throws:

java.io.IOException

javax.xml.parsers.ParserConfigurationException

org.xml.sax.SAXException

toText

public java.lang.String toText()

throws java.io.IOException,

javax.xml.parsers.ParserConfigurationException,

org.xml.sax.SAXException

convert payload value to text, which can be imported into a Database table, which the default setting of delimiter=tab and enclosure='"'. the embedded fields are not in the returned value.

Parameters:

delimiter -

enclosure -

fieldNames -

Returns:

text

Throws:

java.io.IOException

javax.xml.parsers.ParserConfigurationException

4.5.1.9 TSAMDBPayloadIterator

java.lang.Object

com.oracle.tsam.payload.TSAMDBPayloadIterator

All Implemented Interfaces

java.util.Iterator<PayloadRecord>

Description

public class TSAMDBPayloadIterator

extends java.lang.Object

implements java.util.Iterator<PayloadRecord>

Payload record iterator of TSAM Plus database storage.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

TSAMDBPayloadIterator

public TSAMDBPayloadIterator(java.lang.String whereConditionalExpression,

java.sql.Connection con)

throws java.sql.SQLException

Throws:

java.sql.SQLException

Method Detail

hasNext

public boolean hasNext()

Specified by:

hasNext in interface java.util.Iterator<PayloadRecord>

next

public PayloadRecord next()

Specified by:

next in interface java.util.Iterator<PayloadRecord>

remove

public void remove()

Specified by:

remove in interface java.util.Iterator<PayloadRecord>

4.5.1.10 TSAMDBPayloadRepository

java.lang.Object

com.oracle.tsam.payload.TSAMDBPayloadRepository

All Implemented Interfaces

PayloadRepository, java.io.Closeable, java.lang.AutoCloseable, java.lang.Iterable<PayloadRecord>

Description

public class TSAMDBPayloadRepository

extends java.lang.Object

implements PayloadRepository

TSAM Plus database storage of payload metrics.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

TSAMDBPayloadRepository

public TSAMDBPayloadRepository(java.lang.String TSAMDBURL)

throws java.sql.SQLException,

java.lang.ClassNotFoundException

Constructs a TSAMDBPayloadRepository with a TSAM Plus database URL

Throws:

java.sql.SQLException

java.lang.ClassNotFoundException

TSAMDBPayloadRepository

public TSAMDBPayloadRepository(java.sql.Connection connection)

Constructs a TSAMDBPayloadRepository with a TSAM Plus database connection

Method Detail

iterator

public java.util.Iterator<PayloadRecord> iterator()

Specified by:

iterator in interface java.lang.Iterable<PayloadRecord>

iterator

public java.util.Iterator<PayloadRecord> iterator(java.lang.String WhereConditionalExpression)

throws java.sql.SQLException

Gets an iterator from the input SQL query condition

Parameters:

whereConditionalExpression - SQL query condition, for an example, "where DOMAINID='DOMAIN1' and LMID='L1' and GROUPID=1 and SERVERID=1 and SVCNAME='toupper' and PAYLOADTYPE=1"

for an example, "where DOMAINID='DOMAIN1' and LMID='L1' and GROUPID=1 and SERVERID=1 and SVCNAME='toupper' and PAYLOADTYPE=1"

Note:

for the field PAYLOADTYPE, 1 means request, 2 means reply

Returns:

An iterator

Throws:

java.sql.SQLException

close

public void close()

throws java.io.IOException

Specified by:

close in interface java.io.Closeable

Specified by:

close in interface java.lang.AutoCloseable

Throws:

java.io.IOException

getConnection

public java.sql.Connection getConnection()

Returns:

TSAM Plus database connection

getFieldNames

public java.lang.String[] getFieldNames(java.lang.String domainID, java.lang.String serviceName, PayloadType payloadType) throws java.lang.Exception

Parameters:

domainID - domain ID

serviceName - service name

payloadType - payload type

Returns:

Field names

Throws:

java.lang.Exception

4.5.1.11 Enum PayloadType

java.lang.Object

java.lang.Enum<PayloadType>

com.oracle.tsam.payload.PayloadType

All Implemented Interfaces

java.io.Serializable, java.lang.Comparable<PayloadType>

Description

public enum PayloadType

extends java.lang.Enum<PayloadType>

Payload metrics type.

Methods inherited from class java.lang.Enum

compareTo, equals, getDeclaringClass, hashCode, name, ordinal, toString, valueOf

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Enum Constant Detail

request

public static final PayloadType request

Request of a Tuxedo call

Method Detail

values

public static PayloadType[] values()

Returns an array containing the constants of this enum type, in the order they are declared. This method may be used to iterate over the constants as follows:

for (PayloadType c : PayloadType.values())

System.out.println(c);

Returns:

an array containing the constants of this enum type, in the order they are declared

valueOf

public static PayloadType valueOf(java.lang.String name)

Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (Extraneous whitespace characters are not permitted.)

Parameters:

name - the name of the enum constant to be returned.

Returns:

The enum constant with the specified name

Throws:

java.lang.IllegalArgumentException - if this enum type has no constant with the specified name java.lang.NullPointerException - if the argument is null

4.5.1.12 Payload API Samples

The following shows an example that reads payload metrics from TSAM Plus database, and exports the data to a text file.

Example 4-1 API Sample 1

public class DBPayloadSample {

  public static void main(String[] args) throws IOException {

    TSAMDBPayloadRepository tSAMDBPayloadRecordRepository = new TSAMDBPayloadRepository(
      "jdbc:oracle:thin:@localhost:1521:orcl",
      "tsam", "tsam");

    Iterator < PayloadRecord > iterator = tSAMDBPayloadRecordRepository
      .iterator("where DOMAINID='DOMAIN1' and svcname='toupper' and PAYLOADTYPE=1");

    String[] fieldNames = tSAMDBPayloadRecordRepository.getFieldNames(
      "DOMAIN1", "toupper", PayloadType.request);

    Writer writer = new FileWriter("payload.txt");

    for (int i = 0; i < fieldNames.length - 1; i++) {
      writer.append("\"" + fieldNames[i] + "\"\t");
    }
    writer.append("\"" + fieldNames[fieldNames.length - 1] + "\"");

    while (iterator.hasNext()) {
      {
        PayloadValue payloadValue = iterator.next().getPayloadValue();

        writer.append(payloadValue.toText(fieldNames));
        writer.append('\n');
      }
    }

    writer.close();

    tSAMDBPayloadRecordRepository.close();

  }
}

The output format of the file "payload.txt" is

"STRINGFIELD1 ""STRINGFIELD2 ""INTFIELD1 ""SHORTFIELD1"
"abc" "def" "10000" ""
"hij" "" "1" "2"

The following is an example that reads payload metrics from Hadoop, and exports the data to an XML file.

Example 4-2 Payload API Sample 2

public class HadoopPayloadSample {

  public static void main(String[] args) throws IOException {

    HadoopPayloadRepository hadoopPayloadRecordRepository = new HadoopPayloadRepository(
      "hdfs://localhost:8080/tmp/tuxPayload/");

    Iterator < PayloadRecord > iterator = hadoopPayloadRecordRepository
      .iterator();

    Writer writer = new FileWriter("payload.txt");

    while (iterator.hasNext()) {
      PayloadRecord payloadRecord = iterator.next();
      if ("DOMAIN1".equals(payloadRecord.getdOMAINID()) &&
        "toupper".equals(payloadRecord.getServiceName()) &&
        (payloadRecord.getPayloadType() == PayloadType.request)) {

        PayloadValue payloadValue = iterator.next().getPayloadValue();

        writer.append(payloadValue.toXml());
        writer.append('\n');

      }
    }

    writer.close();

    hadoopPayloadRecordRepository.close();
  }

}

4.5.2 Payload Dump Tool

Before running the payload dump tool, you must configure the following:

• Set the CLASS PATH as follows: CLASSPATH=payloadapi.jar:com.bea.core.jatmi_2.0.0.0.jar:com.oracle.tuxedo.tjatmi_12.1.3.0.jar:commons-cli-1.2.jar
• If you want to export the payload from Hadoop dfs, set the HADOOP_HOME:

  export HADOOP_HOME=/home/user/hadoop-2.6.0/

• If you want to export the payload from Oracle Database, include

  ojdbc6.jar in CLASSPATH.

The payload dump tool command is in the following format:

payloaddump -url <URL> [-username <username> -password <password>] -payloadtype request|reply
[-wherecondition <wherecondition>] [-domainid <domainid>] [-servicename <servicename>] 
[-outputtype xml|text] [-fieldnames <fieldnames>] [-o outputFile]

For each parameter description, refer to payloaddump.

For example, to export the payload from Hadoop, run the following command:

java com.oracle.tsam.payload.payloaddump -url
"hdfs://localhost:9000/data/" -payloadtype reply -outputtype xml

To export the payload from TSAM Plus Database, run the following command:

 
java com.oracle.tsam.payload.payloaddump -url
"jdbc:oracle:thin:@localhost:1521:tsam" -username tsam -password
tsam -payloadtype reply -outputtype xml