Package com.iizix

Class SendTransaction

java.lang.Object
com.iizix.SendTransaction
All Implemented Interfaces:
ITransaction
public final class SendTransaction extends Object implements ITransaction
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.

Author:
Christopher Mindus
See Also:

  • Field Details

    • MAX_TRANSACTION_SIZE

      public static final int MAX_TRANSACTION_SIZE
      Maximum transaction size in bytes = 0x1FFF_FFFF.
      See Also:

  • Constructor Details

    • SendTransaction

      public SendTransaction()
      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.

    • SendTransaction

      public SendTransaction(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.
      Parameters:
      writeCache - The writeCache, or null for none.

  • Method Details

    • isDatatypeIncluded

      public static boolean isDatatypeIncluded()
      Returns if data types are to be included in transactions. This requires an extra byte per data type indicating the type.
      Returns:
      true if data types should be added, false otherwise.

    • setDatatypeIncluded

      public static void setDatatypeIncluded(boolean on)
      Returns if data types are to be included in transactions. This requires an extra byte per data type indicating the type.
      Parameters:
      on - true if data types should be added, false otherwise.

    • setLongData

      public static int setLongData(int val, int pos, byte[] data)
      Fills an array with the long data (4 bytes).
      Parameters:
      val - The 32 bit value to set in the data.
      pos - The position (offset) in the data.
      data - The byte array of data.
      Returns:
      The new position, i.e. pos+4.

    • close

      public boolean close()
      Closes the send transaction.
      Returns:
      Previous closed state, i.e. false if transaction was not closed, or true if transaction was already closed.

    • finalize

      @Deprecated protected void finalize() throws Throwable
      Deprecated.
      Finalized transaction. Log an error if the transaction has a write cache but has not been closed. This is a situation that is not acceptable. If so, the transaction is closed after logging.
      Overrides:
      finalize in class Object
      Throws:
      Throwable - Exception in the superclass finalizer.
      See Also:

    • getTotalSendSize

      public int getTotalSendSize()
      Gets the size of the transaction when appending or sending the transaction.
      Returns:
      The total bytes count appended.

    • hasAppendedData

      public boolean hasAppendedData()
      Checks if this transaction has any data in it.
      Returns:
      true if any data has been appended, false if transaction is new without appended data.

    • 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.

      When calling this method, the SendTransaction is automatically closed, so no further additions to it can be done, otherwise an IllegalStateException will be thrown.

      Returns:
      The entire transaction byte array.

    • getData

      public byte[] getData(int serial)
      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.

      When calling this method, the SendTransaction is automatically closed, so no further additions to it can be done, otherwise an IllegalStateException will be thrown.

      Parameters:
      serial - The serial number 0x0000 to 0xFFFF, -1 for none.
      Returns:
      The byte array of the transaction with an optional serial number.
      Throws:
      IllegalArgumentException - If serial value not -1 or not in range between 0x0000 and 0xFFFF.

    • appendByte

      public void appendByte(int val)
      Appends an unsigned byte to the outgoing transaction.
      Parameters:
      val - The 8-bit value to append. Values outside of range are stripped to the 8 first bits, i.e. doing "and 0xFF" on it.
      Throws:
      IllegalStateException - If the transaction is closed or if the transaction has been sealed for further append of new data of it. A transaction becomes sealed if you call getData() or getData(int). A call to append(SendTransaction) will seal the current transaction and the transaction being appended.

    • appendChar

      public void appendChar(char ch)
      Appends a character to the outgoing transaction as a one-character wide string encoded to bytes as described below. The character has, due to Java itself, a code point between U+0000 and U+FFFF, i.e. 16 bits. The additional so called "surrogate pair characters" (two "char" in an array) having the code points U+000000 to U+10FFFF cannot be used here.

      The range of legal code points is now U+0000 to U+10FFFF, known as Unicode scalar value. The set of characters from U+0000 to U+FFFF is sometimes referred to as the Basic Multilingual Plane (BMP). Characters whose code points are greater than U+FFFF are called supplementary characters, and not supported here.

      Encoding: if the character ASCII (code point) value is up to 254 inclusive (i.e. smaller than 0xFF), a single byte is added, otherwise 3 character.

      Parameters:
      ch - The character to append.
      Throws:
      IllegalStateException - If the transaction is closed or if the transaction has been sealed for further append of new data of it. A transaction becomes sealed if you call getData() or getData(int). A call to append(SendTransaction) will seal the current transaction and the transaction being appended.

    • appendBoolean

      public void appendBoolean(boolean b)
      Appends a boolean as an 8-bit value.
      Parameters:
      b - The boolean value.
      Throws:
      IllegalStateException - If the transaction is closed or if the transaction has been sealed for further append of new data of it. A transaction becomes sealed if you call getData() or getData(int). A call to append(SendTransaction) will seal the current transaction and the transaction being appended.

    • appendShort

      public void appendShort(int val)
      Appends a 16 bit signed value to the outgoing transaction.
      Parameters:
      val - The value.
      Throws:
      IllegalArgumentException - If value range not between -0x8000 and 0x7FFF.
      IllegalStateException - If the transaction is closed or if the transaction has been sealed for further append of new data of it. A transaction becomes sealed if you call getData() or getData(int). A call to append(SendTransaction) will seal the current transaction and the transaction being appended.

    • appendUShort

      public void appendUShort(int val)
      Appends a 16 bit unsigned value to the outgoing transaction.
      Parameters:
      val - The value.
      Throws:
      IllegalArgumentException - If value range not between 0x0000 and 0xFFFF.
      IllegalStateException - If the transaction is closed or if the transaction has been sealed for further append of new data of it. A transaction becomes sealed if you call getData() or getData(int). A call to append(SendTransaction) will seal the current transaction and the transaction being appended.

    • appendLong

      public int appendLong(int val)
      Appends a 32 bit signed value to the outgoing transaction.
      Parameters:
      val - The value.
      Returns:
      The position in which the long value was written in, in case the value must be filled in afterwards using a call to setLong(size,pos) used for skipping data in case of a transaction part that must be ignored.
      Throws:
      IllegalStateException - If the transaction is closed or if the transaction has been sealed for further append of new data of it. A transaction becomes sealed if you call getData() or getData(int). A call to append(SendTransaction) will seal the current transaction and the transaction being appended.

    • 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.
      Throws:
      IllegalStateException - If the transaction is closed or if the transaction has been sealed for further append of new data of it. A transaction becomes sealed if you call getData() or getData(int). A call to append(SendTransaction) will seal the current transaction and the transaction being appended.

    • appendLong64

      public void appendLong64(long val)
      Appends a 64 bit signed value to the outgoing transaction.
      Parameters:
      val - The value.
      Throws:
      IllegalStateException - If the transaction is closed.

    • 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 0x1F FFFF (4 bytes). If the range is wrong, IllegalArgumentException is thrown.
      Parameters:
      val - the signed integer to append.
      Throws:
      IllegalArgumentException - If value is not in range -0x1FFF_FFFF to 0x1FFF_FFFF.
      IllegalStateException - If the transaction is closed or if the transaction has been sealed for further append of new data of it. A transaction becomes sealed if you call getData() or getData(int). A call to append(SendTransaction) will seal the current transaction and the transaction being appended.

    • 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.
      Throws:
      IllegalStateException - If the transaction is closed.
      IllegalArgumentException - If value is not in range -0x1FFF_FFFF to 0x1FFF_FFFF.

    • appendFloat

      public void appendFloat(float val)
      Appends a float value to the outgoing transaction (32 bits or 4 bytes).
      Parameters:
      val - The value.
      Throws:
      IllegalStateException - If the transaction is closed or if the transaction has been sealed for further append of new data of it. A transaction becomes sealed if you call getData() or getData(int). A call to append(SendTransaction) will seal the current transaction and the transaction being appended.

    • appendDouble

      public void appendDouble(double val)
      Appends a double value to the outgoing transaction (64 bits or 8 bytes).
      Parameters:
      val - The value.
      Throws:
      IllegalStateException - If the transaction is closed or if the transaction has been sealed for further append of new data of it. A transaction becomes sealed if you call getData() or getData(int). A call to append(SendTransaction) will seal the current transaction and the transaction being appended.

    • appendNumber

      public void appendNumber(double n)
      Appends a Number (JavaScript) as the shortest possible String.
      Parameters:
      n - The number.
      Throws:
      IllegalStateException - If the transaction is closed or if the transaction has been sealed for further append of new data of it. A transaction becomes sealed if you call getData() or getData(int). A call to append(SendTransaction) will seal the current transaction and the transaction being appended.

    • 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).
      Parameters:
      str - The string.
      Throws:
      IllegalArgumentException - If the string length is longer than 0xFF_FFFF (268_435_455), or the UTF-8 encoded string is longer than 0xFF_FFFF (268_435_455 bytes).
      IllegalStateException - If the transaction is closed or if the transaction has been sealed for further append of new data of it. A transaction becomes sealed if you call getData() or getData(int). A call to append(SendTransaction) will seal the current transaction and the transaction being appended.

    • 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).

      Parameters:
      str - The string.
      useStringCache - Flag to avoid using the cache if false, true to use the write cache (if present).
      Throws:
      IllegalArgumentException - If the string length is longer than 0xFF_FFFF (268_435_455), or the UTF-8 encoded string is longer than 0xFF_FFFF (268_435_455 bytes).
      IllegalStateException - If the transaction is closed or if the transaction has been sealed for further append of new data of it. A transaction becomes sealed if you call getData() or getData(int). A call to append(SendTransaction) will seal the current transaction and the transaction being appended.

    • append

      public void append(SendTransaction t)
      Appends a sub-transaction to this send transaction. The send transaction as parameter will first be closed, so no further writing to it is possible.
      Parameters:
      t - Another transaction to append.
      Throws:
      IllegalArgumentException - If the transaction appended does not contain data, or if the total length of the resulting transaction data exceeds 0x3FFF_FFFF.

    • append

      public void append(byte[] appendData)
      Appends a byte array to the outgoing transaction.
      Parameters:
      appendData - The array of bytes to append.
      Throws:
      IllegalStateException - If the transaction is closed or if the transaction has been sealed for further append of new data of it. A transaction becomes sealed if you call getData() or getData(int). A call to append(SendTransaction) will seal the current transaction and the transaction being appended.

    • append

      public void append(byte[] appendData, int len)
      Appends a byte array of a certain length to the outgoing transaction.
      Parameters:
      appendData - The array of bytes to append.
      len - The length to append (can be less than the total length of the array).
      Throws:
      IllegalStateException - If the transaction is closed or if the transaction has been sealed for further append of new data of it. A transaction becomes sealed if you call getData() or getData(int). A call to append(SendTransaction) will seal the current transaction and the transaction being appended.

    • append

      public void append(byte[] appendData, int offset, int len)
      Appends a byte array of a certain length to the outgoing transaction.
      Parameters:
      appendData - The array of bytes to append.
      offset - Starting offset for append in the array.
      len - The byte length to append.
      Throws:
      IllegalStateException - If the transaction is closed or if the transaction has been sealed for further append of new data of it. A transaction becomes sealed if you call getData() or getData(int). A call to append(SendTransaction) will seal the current transaction and the transaction being appended.

    • dumpWriteCache

      public String dumpWriteCache(String indent)
      Dumps the write cache to a String formatted with a certain indent.
      Parameters:
      indent - The string indent for each line. The indent is preceded with '\n' for each line not being the first line.
      Returns:
      A formatted string for the write cache, or *** NO WRITE CACHE *** when a WriteCache instance is not assigned to the transaction.