Transaction (NetPhantom® 7.7 Java API Specification)

java.lang.Object
- se.entra.phantom.common.Transaction

```
public class Transaction
extends Object
```
This transaction class is used for all communication between the Server, Client and Remote Administration programs. It is used to stream out transaction specific data that is streamed in on the other end.
Note: All "synchronization" calls are now removed for performance reasons, so threaded access to a transaction instance should be synchronized by the calling threads.

See Also:

WriteCache

Constructor Summary

Constructors
Constructor and Description
`Transaction()` Creates a new empty transaction that will be filled with streamed data using the append methods.
`Transaction(byte[] data)` Creates a new transaction that has been received from another part.
`Transaction(byte[] data, Map<Integer,String> readCache)` Creates a transaction with a read cache.
`Transaction(InputStream in, Map<Integer,String> readCache, DefaultCrypto crypto)` Creates a transaction from the input stream, supporting InterruptedIOException (from socket.setSoTimeout), supporting a read cache.
`Transaction(WriteCache writeCache)` Creates a new empty transaction that will be filled with streamed data using the append methods.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods
Modifier and Type	Method and Description
`void`	`append(byte[] appendData)` Appends a byte array to the outgoing transaction.
`void`	`append(byte[] appendData, int len)` Appends a byte array of a certain length to the outgoing transaction.
`void`	`append(byte[] appendData, int offset, int len)` Appends a byte array of a certain length to the outgoing transaction.
`void`	`append(Document document)` Appends an XML document to the transaction.
`void`	`append(Transaction t)` Appends a sub-transaction to the outgoing transaction.
`void`	`appendBoolean(boolean b)` Appends a boolean.
`void`	`appendByte(int val)` Appends an unsigned byte to the outgoing transaction.
`void`	`appendChar(char ch)` Appends a character to the outgoing transaction.
`void`	`appendDataFromTransaction(Transaction t)` Appends a byte array from an existing transaction.
`void`	`appendDouble(double val)` Appends a 64 bit double value to the outgoing transaction.
`void`	`appendFloat(float val)` Appends a float value to the outgoing transaction.
`void`	`appendLong(int val)` Appends a 32 bit signed value to the outgoing transaction.
`void`	`appendLong64(long val)` Appends a 64 bit signed value to the outgoing transaction.
`void`	`appendLongString(String str)` Deprecated. since NetPhantom 4.0, use appendString instead.
`void`	`appendLongUnicodeString(String str)` Deprecated. since NetPhantom 4.0, use appendString instead.
`void`	`appendShort(int val)` Appends a 16 bit signed value to the outgoing transaction.
`void`	`appendSigned(int val)` Appends an signed integer with the range -0x1FFFFFFF to 0x1FFFFFFF.
`void`	`appendString(String str)` Appends a String to the outgoing transaction.
`void`	`appendString(String str, boolean useStringCache)` Appends a String to the outgoing transaction.
`void`	`appendSubTransaction(Transaction t)` Appends a sub transaction to the current transaction.
`void`	`appendUnicodeString(String str)` Deprecated. since NetPhantom 4.0, use appendString instead.
`void`	`appendUnicodeString(String str, boolean useStringCache)` Deprecated. since NetPhantom 4.0, use appendString instead.
`void`	`appendUnsigned(int val)` Appends an unsigned integer with the range 0x00000000 to 0x3FFFFFFF.
`void`	`appendUShort(int val)` Appends a 16 bit unsigned value to the outgoing transaction.
`Transaction`	`createTransaction()` Create and return a new transaction with the same write cache as the previous transaction.
`int`	`getByte()` Get an unsigned byte from the incoming data without moving the read position.
`byte[]`	`getData()` Gets the byte data of the transaction.
`byte[]`	`getData0()` Gets the byte data of the transaction.
`static byte[]`	`getLongData(int val)` Static helper method to get the 4-byte representation of a 32 bit signed value.
`int`	`getRemainingReadSize()` Gets the remaining size in bytes for read methods in the transaction.
`int`	`getSize()` Gets the size of the transaction.
`int`	`getSizeNoHeader()` Gets the size of the transaction without the header.
`boolean`	`hasAppendedData()` Checks if this transaction has any data in it.
`void`	`makeUnsent()` Called when a transaction's data has been retrieved using `getData()` and the transaction failed to be sent and must be reinitialized for appending more data or sending again later.
`boolean`	`readBoolean()` Reads a boolean from incoming data.
`int`	`readByte()` Reads an unsigned byte from the incoming data.
`byte[]`	`readBytes(int count)` Reads a byte array from the incoming data.
`char`	`readChar()` Reads an encoded character in a byte from the incoming data.
`byte[]`	`readData(int count)` Reads a set of bytes from the incoming data.
`Document`	`readDocument()` Reads an XML document from the transaction.
`double`	`readDouble()` Reads a 64 bit double value from the incoming data.
`float`	`readFloat()` Reads a float value from the incoming data.
`int`	`readIntelLong()` Reads an Intel format encoded 32 bit signed value from the incoming data.
`int`	`readIntelUShort()` Reads an Intel format encoded 16 bit unsigned value from the incoming data.
`int`	`readLong()` Reads a 32 bit signed value from the incoming data.
`long`	`readLong64()` Reads a 64 bit signed value from the incoming data.
`String`	`readLongString()` Deprecated. since NetPhantom 4.0, use readString instead.
`String`	`readNullTerminatedString()` Reads a null character Ansi string (typically a C string) from the incoming data.
`int`	`readShort()` Reads a 16 bit signed value from the incoming data.
`int`	`readSigned()` Reads a signed integer of the range -0x1FFFFFFF to 0x1FFFFFFF.
`String`	`readString()` Reads a string from the incoming data.
`Transaction`	`readSubTransaction()` Retrieves a sub-transaction from an incoming transaction.
`Transaction`	`readTransaction()` Retrieves a sub-transaction from an incoming transaction.
`int`	`readUnsigned()` Reads an unsigned integer of the range 0x00000000 to 0x3FFFFFFF.
`int`	`readUShort()` Reads a 16 bit unsigned value from the incoming data.
`void`	`send(OutputStream out, DefaultCrypto crypto)` Sends the transaction on the output stream using a possible encryption (if not null).
`void`	`setLong(int val, int pos)` Sets a 32 bit signed value to the outgoing transaction at the specified position.
`static int`	`setLongData(int val, int pos, byte[] data)` Fills an array with the long data (4 bytes).
`void`	`skipBytes(int count)` Skips a number of bytes for reading.
`void`	`unreadBytes(int count)` Unreads a count of bytes.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Constructor Detail
  - Transaction
```
public Transaction(byte[] data)
```
    Creates a new transaction that has been received from another part. The data can then be extracted by means of the read methods. This method causes no read cache to be available.
  - Transaction
```
public Transaction(byte[] data,
                   Map<Integer,String> readCache)
```
    Creates a transaction with a read cache.
  - Transaction
```
public Transaction(InputStream in,
                   Map<Integer,String> readCache,
                   DefaultCrypto crypto)
            throws IOException
```
    Creates a transaction from the input stream, supporting InterruptedIOException (from socket.setSoTimeout), supporting a read cache.
    
    Throws:
    
    IOException - for read errors, or InterruptedIOException for timeout.
  - Transaction
```
public Transaction()
```
    Creates a new empty transaction that will be filled with streamed data using the append methods. This transaction will then be sent on to the other part.
    This method does not use a write cache.
  - Transaction
```
public Transaction(WriteCache writeCache)
```
    Creates a new empty transaction that will be filled with streamed data using the append methods. This transaction will then be sent on to the other part.
    The writeCache parameter can be null.
- Method Detail
  - setLongData
```
public static int setLongData(int val,
                              int pos,
                              byte[] data)
```
    Fills an array with the long data (4 bytes).
  - getLongData
```
public static byte[] getLongData(int val)
```
    Static helper method to get the 4-byte representation of a 32 bit signed value.
  - readTransaction
```
public Transaction readTransaction()
```
    Retrieves a sub-transaction from an incoming transaction.
    
    Returns:
    
    null if no more sub-transactions exist.
  - readSubTransaction
```
public Transaction readSubTransaction()
```
    Retrieves a sub-transaction from an incoming transaction.
    Note: Use this method to read sub-transactions added to a send transaction using appendSubTransaction.
    
    Returns:
    
    The sub-transaction instance. If this call is done when there are no sub-transactions available, it will throw an InternalError.
  - getRemainingReadSize
```
public int getRemainingReadSize()
```
    Gets the remaining size in bytes for read methods in the transaction. This is useful to see if a transaction has read all its data.
  - skipBytes
```
public void skipBytes(int count)
```
    Skips a number of bytes for reading.
  - readByte
```
public int readByte()
```
    Reads an unsigned byte from the incoming data.
  - readChar
```
public char readChar()
```
    Reads an encoded character in a byte from the incoming data. If the transactions use Unicode only, two bytes are read, otherwise just one using the codepage conversion or the default ISO 8859-1 character set. A unicode character is preceded with the '\xFF' character, meaning that 3 bytes are used for the Unicode character.
    
    Returns:
    
    the character read.
  - readBoolean
```
public boolean readBoolean()
```
    Reads a boolean from incoming data.
  - readBytes
```
public byte[] readBytes(int count)
```
    Reads a byte array from the incoming data.
  - readData
```
public byte[] readData(int count)
```
    Reads a set of bytes from the incoming data.
  - unreadBytes
```
public void unreadBytes(int count)
```
    Unreads a count of bytes. This is useful for reading e.g. a sub-transaction code, then deciding that the transaction should be read at a later stage.
  - readUnsigned
```
public int readUnsigned()
```
    Reads an unsigned integer of the range 0x00000000 to 0x3FFFFFFF. The space occupied in the transaction is 1 to 4 bytes.
    
    Returns:
    
    the unsigned integer.
  - readSigned
```
public int readSigned()
```
    Reads a signed integer of the range -0x1FFFFFFF to 0x1FFFFFFF. The space occupied in the transaction is 1 to 4 bytes.
    
    Returns:
    
    the signed integer.
  - readShort
```
public int readShort()
```
    Reads a 16 bit signed value from the incoming data.
  - readUShort
```
public int readUShort()
```
    Reads a 16 bit unsigned value from the incoming data.
  - readLong
```
public int readLong()
```
    Reads a 32 bit signed value from the incoming data.
  - readLong64
```
public long readLong64()
```
    Reads a 64 bit signed value from the incoming data.
  - readFloat
```
public float readFloat()
```
    Reads a float value from the incoming data.
  - readDouble
```
public double readDouble()
```
    Reads a 64 bit double value from the incoming data.
  - readString
```
public String readString()
```
    Reads a string from the incoming data. The string may be encoded in Ansi or Unicode formats.
    
    Returns:
    
    the string read, possibly using a read cache.
  - readLongString
```
@Deprecated
public String readLongString()
```
    Deprecated. since NetPhantom 4.0, use readString instead.
    
    Reads a long string from the incoming data. The string may be encoded in Ansi or Unicode formats.
  - readIntelUShort
```
public int readIntelUShort()
```
    Reads an Intel format encoded 16 bit unsigned value from the incoming data.
  - readIntelLong
```
public int readIntelLong()
```
    Reads an Intel format encoded 32 bit signed value from the incoming data.
  - readNullTerminatedString
```
public String readNullTerminatedString()
```
    Reads a null character Ansi string (typically a C string) from the incoming data. It doesn't work with Unicode strings!
  - getByte
```
public int getByte()
```
    Get an unsigned byte from the incoming data without moving the read position.
  - readDocument
```
public Document readDocument()
                      throws IOException
```
    Reads an XML document from the transaction.
    
    Throws:
    
    IOException - for document read errors.
  - createTransaction
```
public Transaction createTransaction()
```
    Create and return a new transaction with the same write cache as the previous transaction.
  - getSize
```
public int getSize()
```
    Gets the size of the transaction.
  - getSizeNoHeader
```
public int getSizeNoHeader()
```
    Gets the size of the transaction without the header.
  - hasAppendedData
```
public boolean hasAppendedData()
```
    Checks if this transaction has any data in it.
  - getData
```
public byte[] getData()
```
    Gets the byte data of the transaction. The data is a copy of the internal data in the transaction and is of the exact size of the entire transaction package.
  - getData0
```
public byte[] getData0()
```
    Gets the byte data of the transaction. The data is THE INTERNAL data and can contain more bytes than the real transaction to be sent. Use "getSize()" to find the real size. Do NOT modify the byte buffer. This method is intended to keep garbage collection down...
  - appendByte
```
public void appendByte(int val)
```
    Appends an unsigned byte to the outgoing transaction.
  - send
```
public void send(OutputStream out,
                 DefaultCrypto crypto)
          throws IOException
```
    Sends the transaction on the output stream using a possible encryption (if not null).
    
    Throws:
    
    IOException - for write errors.
  - appendChar
```
public void appendChar(char ch)
```
    Appends a character to the outgoing transaction. If the transactions are in Unicode, two bytes are added.
  - appendBoolean
```
public void appendBoolean(boolean b)
```
    Appends a boolean.
  - appendUnsigned
```
public void appendUnsigned(int val)
```
    Appends an unsigned integer with the range 0x00000000 to 0x3FFFFFFF. The amount of bytes appended to the transaction varies from 1 to 4 bytes if the value is larger than 0x3F (2 bytes), 0x3FFF (3 bytes) or 0x3FFFFF (4 bytes). If the range is wrong, IllegalArgumentException is thrown.
    
    Parameters:
    
    val - the unsigned integer to append.
  - appendSigned
```
public void appendSigned(int val)
```
    Appends an signed integer with the range -0x1FFFFFFF to 0x1FFFFFFF. The amount of bytes appended to the transaction varies from 1 to 4 bytes if the absolute value is larger than 0x1F (2 bytes), 0x1FFF (3 bytes) or 0x1FFFFF (4 bytes). If the range is wrong, IllegalArgumentException is thrown.
    
    Parameters:
    
    val - the signed integer to append.
  - appendShort
```
public void appendShort(int val)
```
    Appends a 16 bit signed value to the outgoing transaction.
  - appendUShort
```
public void appendUShort(int val)
```
    Appends a 16 bit unsigned value to the outgoing transaction.
  - appendLong
```
public void appendLong(int val)
```
    Appends a 32 bit signed value to the outgoing transaction.
  - setLong
```
public void setLong(int val,
                    int pos)
```
    Sets a 32 bit signed value to the outgoing transaction at the specified position. This method is used in conjunction with getSize() in an outgoing transaction when the long value is used for skipping a transaction on the other end (the long value is the size of data to skip, but the size is not known until all sub-transactions are appended).
    
    Parameters:
    
    val - the long value.
    
    pos - position to write the long value.
  - appendLong64
```
public void appendLong64(long val)
```
    Appends a 64 bit signed value to the outgoing transaction.
  - appendFloat
```
public void appendFloat(float val)
```
    Appends a float value to the outgoing transaction.
  - appendDouble
```
public void appendDouble(double val)
```
    Appends a 64 bit double value to the outgoing transaction.
  - appendString
```
public void appendString(String str)
```
    Appends a String to the outgoing transaction. The appended string will use the String Cache (if present, and if the String meets the cache conditions).
  - appendString
```
public void appendString(String str,
                         boolean useStringCache)
```
    Appends a String to the outgoing transaction. The appended string will use the String Cache depending on the "useStringCache" flag (and if the String Cache present, and the String meets the cache conditions).
  - appendUnicodeString
```
@Deprecated
public void appendUnicodeString(String str)
```
    Deprecated. since NetPhantom 4.0, use appendString instead.
    
    Appends a String in Unicode format to the outgoing transaction. The appended string will use the String Cache (if present, and if the String meets the cache conditions).
  - appendUnicodeString
```
@Deprecated
public void appendUnicodeString(String str,
                                             boolean useStringCache)
```
    Deprecated. since NetPhantom 4.0, use appendString instead.
    
    Appends a String in Unicode format to the outgoing transaction. The appended string will use the String Cache depending on the "useStringCache" flag (and if the String Cache present, and the String meets the cache conditions).
  - appendLongString
```
@Deprecated
public void appendLongString(String str)
```
    Deprecated. since NetPhantom 4.0, use appendString instead.
    
    Appends a long String in Ansi format to the outgoing transaction.
  - appendLongUnicodeString
```
@Deprecated
public void appendLongUnicodeString(String str)
```
    Deprecated. since NetPhantom 4.0, use appendString instead.
    
    Appends a String in Unicode format to the outgoing transaction.
  - append
```
public void append(Document document)
            throws TransformerException
```
    Appends an XML document to the transaction.
    
    Parameters:
    
    document - the Document to append to the transaction.
    
    Throws:
    
    TransformerException - When there is a error in the transformation.
  - append
```
public void append(Transaction t)
```
    Appends a sub-transaction to the outgoing transaction.
  - appendSubTransaction
```
public void appendSubTransaction(Transaction t)
```
    Appends a sub transaction to the current transaction.
    Note: Use the method readSubTransaction to extract a transaction appended using appendDataFromTransaction, not readTransaction.
  - appendDataFromTransaction
```
public void appendDataFromTransaction(Transaction t)
```
    Appends a byte array from an existing transaction. This is not the same as appending a sub-transaction.
  - append
```
public void append(byte[] appendData)
```
    Appends a byte array to the outgoing transaction.
  - append
```
public void append(byte[] appendData,
                   int len)
```
    Appends a byte array of a certain length to the outgoing transaction.
  - append
```
public void append(byte[] appendData,
                   int offset,
                   int len)
```
    Appends a byte array of a certain length to the outgoing transaction.
  - makeUnsent
```
public void makeUnsent()
```
    Called when a transaction's data has been retrieved using getData() and the transaction failed to be sent and must be reinitialized for appending more data or sending again later.

Class Transaction

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

Transaction

Transaction

Transaction

Transaction

Transaction

Method Detail

setLongData

getLongData

readTransaction

readSubTransaction

getRemainingReadSize

skipBytes

readByte

readChar

readBoolean

readBytes

readData

unreadBytes

readUnsigned

readSigned

readShort

readUShort

readLong

readLong64

readFloat

readDouble

readString

readLongString

readIntelUShort

readIntelLong

readNullTerminatedString

getByte

readDocument

createTransaction

getSize

getSizeNoHeader

hasAppendedData

getData

getData0

appendByte

send

appendChar

appendBoolean

appendUnsigned

appendSigned

appendShort

appendUShort

appendLong

setLong

appendLong64

appendFloat

appendDouble

appendString

appendString

appendUnicodeString

appendUnicodeString

appendLongString

appendLongUnicodeString

append

append

appendSubTransaction

appendDataFromTransaction

append

append

append

makeUnsent