Package com.igormaznitsa.jbbp.io

Class JBBPOut

java.lang.Object
com.igormaznitsa.jbbp.io.AbstractMappedClassFieldObserver
com.igormaznitsa.jbbp.io.JBBPOut
public class JBBPOut extends AbstractMappedClassFieldObserver
The Class implements some kind of DSL to form binary blocks. The Class is not a thread-safe one.
Since:
1.0

  • Field Details

    • DEFAULT_BYTE_ORDER

      public static final JBBPByteOrder DEFAULT_BYTE_ORDER
      The Default byte outOrder.

    • DEFAULT_BIT_ORDER

      public static final JBBPBitOrder DEFAULT_BIT_ORDER
      The Default bit outOrder.

  • Method Details

    • BeginBin

      public static JBBPOut BeginBin(JBBPByteOrder byteOrder, JBBPBitOrder bitOrder)
      Start a DSL session for defined both byte outOrder and bit outOrder parameters.
      Parameters:
      byteOrder - the byte outOrder to be used for the session
      bitOrder - the bit outOrder to be used for the session
      Returns:
      the new DSL session generated with the parameters and inside byte array stream.

    • BeginBin

      public static JBBPOut BeginBin(OutputStream out, JBBPByteOrder byteOrder, JBBPBitOrder bitOrder)
      Start a DSL session for a defined stream with defined parameters.
      Parameters:
      out - the defined stream
      byteOrder - the byte outOrder for the session
      bitOrder - the bit outOrder for the session
      Returns:
      the new DSL session generated for the stream with parameters

    • BeginBin

      public static JBBPOut BeginBin()
      Start a DSL session for default parameters and inside byte array stream.
      Returns:
      the new DSL session generated with the default parameters and inside byte array stream.

    • BeginBin

      public static JBBPOut BeginBin(int initialSize)
      Start a DSL session for default parameters and inside byte array stream with defined start size.
      Parameters:
      initialSize - the start size of inside buffer of the byte array output stream, must be positive
      Returns:
      the new DSL session generated with the default parameters and inside byte array stream.

    • BeginBin

      public static JBBPOut BeginBin(OutputStream out)
      Start a DSL session for a defined output stream and default parameters.
      Parameters:
      out - an output stream to write session data, must not be null.
      Returns:
      the new DSL session generated for the default parameters and the output stream.

    • BeginBin

      public static JBBPOut BeginBin(JBBPByteOrder byteOrder)
      Start a DSL session for default bit outOrder and defined byte outOrder. It will be using inside byte array stream.
      Parameters:
      byteOrder - the byte outOrder for the session, it must not be null.
      Returns:
      the new DSL session

    • BeginBin

      public static JBBPOut BeginBin(JBBPBitOrder bitOrder)
      Start a DSL session for default byte outOrder and defined bite outOrder. It will be using inside byte array stream.
      Parameters:
      bitOrder - the bite outOrder for the session, it must not be null.
      Returns:
      the new DSL session

    • Align

      public JBBPOut Align() throws IOException
      Align the current stream for 1 byte. If there are any bites inside bit cache then they will be saved and the stream will be positioning to the next byte. It works relative to the byte output counter.
      Returns:
      the DSL session
      Throws:
      IOException - it will be thrown for transport errors
      See Also:

    • Align

      public JBBPOut Align(int value) throws IOException
      Align number of bytes in the stream to the value. It works relative to the byte output counter.
      Parameters:
      value - the byte border to align the stream.
      Returns:
      the DSL session
      Throws:
      IOException - it will be thrown for transport errors
      See Also:

    • Skip

      public JBBPOut Skip(int numberOfBytes) throws IOException
      Skip number of bytes in the stream, zero bytes will be written and also will be aligned inside bit cache even if the value is 0.
      Parameters:
      numberOfBytes - the number of bytes to be skipped
      Returns:
      the DSL session
      Throws:
      IOException - it will be thrown for transport errors
      IllegalArgumentException - it will be thrown if the value is negative one

    • ByteOrder

      public JBBPOut ByteOrder(JBBPByteOrder value)
      Define the byte outOrder for next session operations.
      Parameters:
      value - the byte outOrder to be used in next operations, must not be null
      Returns:
      the DSL session

    • Bit

      public JBBPOut Bit(boolean value) throws IOException
      Write a bit into the session.
      Parameters:
      value - true if the bit is 1, 0 otherwise
      Returns:
      the DSL session
      Throws:
      IOException - it will be thrown for transport errors

    • Bit

      public JBBPOut Bit(byte value) throws IOException
      Write the lowest bit from a byte value.
      Parameters:
      value - the byte value which lowest bit will be written into the stream
      Returns:
      the DSL session
      Throws:
      IOException - it will be thrown for transport errors

    • Bit

      public JBBPOut Bit(byte[] value) throws IOException
      Write the lowest bits of bytes from an array.
      Parameters:
      value - a byte array, lowest bit of each byte will be saved as a bit into the output stream, it must not be null
      Returns:
      the DSL session
      Throws:
      IOException - it will be thrown for transport errors

    • Bit

      public JBBPOut Bit(int... value) throws IOException
      Write the lowest bits of integers from an array.
      Parameters:
      value - an integer array, lowest bit of each integer value will be saved as a bit into the output stream, it must not be null
      Returns:
      the DSL session
      Throws:
      IOException - it will be thrown for transport errors

    • Bit

      public JBBPOut Bit(boolean... value) throws IOException
      Write bits represented as boolean flags into the output stream.
      Parameters:
      value - a boolean array which values will be saved into the output stream as bits, true is a bit on, false is bit off. It must not be null
      Returns:
      the DSL session.
      Throws:
      IOException - it will be thrown for transport errors

    • Bits

      public JBBPOut Bits(JBBPBitNumber numberOfBits, int value) throws IOException
      Write bits from a value into the output stream
      Parameters:
      numberOfBits - the number of bits to be saved
      value - the value which bits must be saved
      Returns:
      the DSL session
      Throws:
      IOException - it will be thrown for transport errors

    • Bits

      public JBBPOut Bits(JBBPBitNumber numberOfBits, int... value) throws IOException
      Write bits of each integer value from an array into the output stream.
      Parameters:
      numberOfBits - the number of bits to be saved
      value - an integer array which elements will be used as sources of bits, it must not be null
      Returns:
      the DSL session
      Throws:
      IOException - it will be thrown for transport errors

    • Bits

      public JBBPOut Bits(JBBPBitNumber numberOfBits, byte[] value) throws IOException
      Write bits of each byte value from an array into the output stream.
      Parameters:
      numberOfBits - the number of bits to be saved
      value - a byte array which elements will be used as sources of bits, it must not be null
      Returns:
      the DSL session
      Throws:
      IOException - it will be thrown for transport errors

    • Byte

      public JBBPOut Byte(int value) throws IOException
      Write the lower byte of an integer value into the session stream.
      Parameters:
      value - an integer value which byte should be written into
      Returns:
      the DSL session
      Throws:
      IOException - it will be thrown for transport errors

    • Byte

      public JBBPOut Byte(int... value) throws IOException
      Write the lower byte of an integer value into the session stream.
      Parameters:
      value - an integer array which values will be byte sources to write their lower byte into the stream
      Returns:
      the DSL session
      Throws:
      IOException - it will be thrown for transport errors

    • Byte

      public JBBPOut Byte(byte[] value) throws IOException
      Write a byte array into the session stream.
      Parameters:
      value - a byte array to be written
      Returns:
      the DSL session
      Throws:
      IOException - it will be thrown for transport errors

    • Byte

      public JBBPOut Byte(String str) throws IOException
      Write String chars trimmed to bytes, only the lower 8 bit will be saved per char code.
      Parameters:
      str - a String which chars should be trimmed to bytes and saved
      Returns:
      the DSL session
      Throws:
      IOException - it will be thrown for transport errors

    • Byte

      public JBBPOut Byte(String str, JBBPBitOrder bitOrder) throws IOException
      Write String chars trimmed to bytes, only the lower 8 bit will be saved per char code.
      Parameters:
      str - a String which chars should be trimmed to bytes and saved
      bitOrder - the bit outOrder to save bytes
      Returns:
      the DSL session
      Throws:
      IOException - it will be thrown for transport errors
      Since:
      1.1

    • Utf8

      public JBBPOut Utf8(String str) throws IOException
      Write chars of a String as encoded Utf8 byte array. There will not be aby information about string length.
      Parameters:
      str - a String which bytes should be written as Utf8, must not be null
      Returns:
      the DSL session
      Throws:
      IOException - it will be thrown for transport errors

    • String

      public JBBPOut String(String str) throws IOException
      Write string into output stream with length information. the byte order in saved char data will be BIG_ENDIAN
      Parameters:
      str - string to be written, it can be null
      Returns:
      the DSL session
      Throws:
      IOException - it will be thrown for transport errors
      Since:
      1.4.0
      See Also:

    • Strings

      public JBBPOut Strings(String... strings) throws IOException
      Write string array as sequence of strings with information about string length. the byte order in saved char data will be BIG_ENDIAN
      Parameters:
      strings - array of strings, must not be null but can contain null
      Returns:
      the DSL session
      Throws:
      IOException - it will be thrown for transport errors
      Since:
      1.4.0
      See Also:

    • Bool

      public JBBPOut Bool(boolean value) throws IOException
      Write a boolean value into the session stream as a byte.
      Parameters:
      value - a boolean value to be written, true is 1, false is 0
      Returns:
      the DSL session
      Throws:
      IOException - it will be thrown for transport errors

    • Bool

      public JBBPOut Bool(boolean value, JBBPBitOrder bitOrder) throws IOException
      Write a boolean value into the session stream as a byte.
      Parameters:
      value - a boolean value to be written, true is 1, false is 0
      bitOrder - bit outOrder for saving data
      Returns:
      the DSL session
      Throws:
      IOException - it will be thrown for transport errors
      Since:
      1.1

    • Bool

      public JBBPOut Bool(boolean... value) throws IOException
      Write boolean values from an array into the session stream as bytes.
      Parameters:
      value - a boolean array to be saved as bytes, true is 1, false is 0. It must not be null
      Returns:
      the DSL session
      Throws:
      IOException - it will be thrown for transport errors

    • Short

      public JBBPOut Short(int value) throws IOException
      Write lower pair of bytes of an integer value into the session stream as a short value.
      Parameters:
      value - an integer value which lower pair of bytes will be written into
      Returns:
      the DSL session
      Throws:
      IOException - it will be thrown for transport errors

    • Short

      public JBBPOut Short(String str) throws IOException
      Write codes of chars as 16 bit values into the stream.
      Parameters:
      str - the string which chars will be written, must not be null
      Returns:
      the DSL session
      Throws:
      IOException - it will be thrown for transport errors
      Since:
      1.1

    • Short

      public JBBPOut Short(String str, JBBPBitOrder bitOrder) throws IOException
      Write codes of chars as 16 bit values into the stream.
      Parameters:
      str - the string which chars will be written, must not be null
      bitOrder - the bit outOrder
      Returns:
      the DSL session
      Throws:
      IOException - it will be thrown for transport errors
      Since:
      1.1

    • Short

      public JBBPOut Short(short[] value) throws IOException
      Write short values from an array
      Parameters:
      value - a short value array which values should be written into, it must not be null
      Returns:
      the DSL session
      Throws:
      IOException - it will be thrown for transport errors

    • Short

      public JBBPOut Short(char[] value) throws IOException
      Write short values from a char array
      Parameters:
      value - a char array which values should be written into, it must not be null
      Returns:
      the DSL session
      Throws:
      IOException - it will be thrown for transport errors
      Since:
      1.3

    • Short

      public JBBPOut Short(int... value) throws IOException
      Write lower pair of bytes of each integer value from an integer array into the session stream as a short value.
      Parameters:
      value - an integer array which values will be written into
      Returns:
      the DSL session
      Throws:
      IOException - it will be thrown for transport errors

    • Int

      public JBBPOut Int(int value) throws IOException
      Write an integer value into the session stream.
      Parameters:
      value - an integer value to be written into
      Returns:
      the DSl session
      Throws:
      IOException - it will be thrown for transport errors

    • Int

      public JBBPOut Int(int... value) throws IOException
      Write each integer value from an integer array into the session stream.
      Parameters:
      value - an integer array which values should be written into
      Returns:
      the DSl session
      Throws:
      IOException - it will be thrown for transport errors

    • onFieldUInt

      protected void onFieldUInt(Object obj, Field field, Bin annotation, int value)
      Description copied from class: AbstractMappedClassFieldObserver
      Notification about unsigned integer field.
      Overrides:
      onFieldUInt in class AbstractMappedClassFieldObserver
      Parameters:
      obj - the object instance, must not be null
      field - the field, must not be null
      annotation - the annotation for field, must not be null
      value - the value of the field

    • Float

      public JBBPOut Float(float... value) throws IOException
      Write a float value array as integer bits into the stream.
      Parameters:
      value - a float array which values will be written into
      Returns:
      the DSL session
      Throws:
      IOException - it will be thrown for transport errors
      Since:
      1.4.0
      See Also:

    • Long

      public JBBPOut Long(long value) throws IOException
      Write a long value into the session stream.
      Parameters:
      value - a long value to be written into
      Returns:
      the DSL session
      Throws:
      IOException - it will b e thrown for transport errors

    • Double

      public JBBPOut Double(double... value) throws IOException
      Write a double value array as long bits into the stream.
      Parameters:
      value - a double array which values will be written into
      Returns:
      the DSL session
      Throws:
      IOException - it will be thrown for transport errors
      Since:
      1.4.0
      See Also:

    • ResetCounter

      public JBBPOut ResetCounter()
      Reset the byte counter and the inside bit buffer of the output stream. it is useful to align command because the command makes alignment for the counter.
      Returns:
      the DSL context
      See Also:

    • Long

      public JBBPOut Long(long... value) throws IOException
      Write each long value from a long value array into the session stream.
      Parameters:
      value - a long value array which values will be written into
      Returns:
      the DSL session
      Throws:
      IOException - it will be thrown for transport errors

    • Var

      public JBBPOut Var(JBBPOutVarProcessor processor, Object... args) throws IOException
      Output data externally.
      Parameters:
      processor - a processor which will get the stream to write data, must not be null
      args - optional arguments to be provided to the processor
      Returns:
      the DSL context
      Throws:
      IOException - it will be thrown for transport errors
      NullPointerException - it will be thrown for null as a processor

    • Flush

      public JBBPOut Flush() throws IOException
      Flush inside buffers into the stream. Be careful with bit operations because the operation will flush the inside bit buffer.
      Returns:
      the DSL session
      Throws:
      IOException - it will be thrown for transport errors

    • End

      public ByteArrayOutputStream End() throws IOException
      Flush the stream and end the session.
      Returns:
      if the session output stream is based on a byte array output stream then the stream will be returned, null otherwise
      Throws:
      IOException - it will be thrown for transport errors.

    • getByteCounter

      public long getByteCounter()
      get the current byte counter value for the underlying stream. it has appropriate value only if it was not reset.
      Returns:
      the current byte counter for the underlying stream.

    • assertNotEnded

      protected void assertNotEnded()
      Assert that the session has not ended.
      Throws:
      IllegalStateException - if the session has been ended

    • Bin

      public JBBPOut Bin(Object object) throws IOException
      Save fields of an object marked by Bin annotation. Fields will be ordered through Bin.order() field, NB! By default, Java doesn't keep field outOrder. Ordered fields of class will be saved into internal cache for speed but the cache can be reset through JBBPMapper.clearFieldCache() Warning! it doesn't affect byte order provided in Bin annotations of object.
      Parameters:
      object - an object to be saved into stream, must not be null
      Returns:
      the context
      Throws:
      IOException - it will be thrown for any transport error
      Since:
      1.1
      See Also:

    • Bin

      public JBBPOut Bin(Object object, BinFieldFilter binFieldFilter) throws IOException
      Save fields of an object marked by Bin annotation. Fields will be ordered through Bin.order() field, NB! By default, Java doesn't keep field outOrder. Ordered fields of class will be saved into internal cache for speed but the cache can be reset through JBBPMapper.clearFieldCache() Warning! it doesn't affect byte order provided in Bin annotations of object.
      Parameters:
      object - an object to be saved into stream, must not be null
      binFieldFilter - filter to exclude some fields from process, can be null
      Returns:
      the context
      Throws:
      IOException - it will be thrown for any transport error
      Since:
      2.0.4
      See Also:

    • Bin

      public JBBPOut Bin(Object object, JBBPCustomFieldWriter customFieldWriter)
      Save fields of an object marked by Bin annotation. Fields will be ordered through Bin.order() field, NB! By default, Java doesn't keep field outOrder. Ordered fields of class will be saved into internal cache for speed but the cache can be reset through JBBPMapper.clearFieldCache() Warning! it doesn't affect byte order provided in Bin annotations of object.
      Parameters:
      object - an object to be saved into stream, must not be null
      customFieldWriter - a custom field writer to be used for saving of custom fields of the object, it can be null
      Returns:
      the context
      Since:
      1.1
      See Also:

    • Bin

      public JBBPOut Bin(Object object, JBBPCustomFieldWriter customFieldWriter, BinFieldFilter binFieldFilter)
      Save fields of an object marked by Bin annotation. Fields will be ordered through Bin.order() field, NB! By default, Java doesn't keep field outOrder. Ordered fields of class will be saved into internal cache for speed but the cache can be reset through JBBPMapper.clearFieldCache() Warning! it doesn't affect byte order provided in Bin annotations of object.
      Parameters:
      object - an object to be saved into stream, must not be null
      customFieldWriter - a custom field writer to be used for saving of custom fields of the object, it can be null
      binFieldFilter - filter to exclude fields from process, can be null
      Returns:
      the context
      Since:
      2.0.4
      See Also:

    • Bin

      public JBBPOut Bin(Object object, BinAnnotationWrapper binAnnotationWrapper, JBBPCustomFieldWriter customFieldWriter)
      Save fields of object but bin annotation wrapper can be provided to replace some annotation field values in all field annotations.
      Parameters:
      object - an object to be saved into stream, must not be null
      binAnnotationWrapper - wrapper for all bin annotations, can be null
      customFieldWriter - a custom field writer to be used for saving of custom fields of the object, it can be null
      Returns:
      the context
      Since:
      2.0.2

    • Bin

      public JBBPOut Bin(Object object, BinAnnotationWrapper binAnnotationWrapper, JBBPCustomFieldWriter customFieldWriter, BinFieldFilter binFieldFilter)
      Save fields of object but bin annotation wrapper can be provided to replace some annotation field values in all field annotations.
      Parameters:
      object - an object to be saved into stream, must not be null
      binAnnotationWrapper - wrapper for all bin annotations, can be null
      customFieldWriter - a custom field writer to be used for saving of custom fields of the object, it can be null
      binFieldFilter - filter to exclude some fields from process, can be null
      Returns:
      the context
      Since:
      2.0.4

    • BinForceByteOrder

      public JBBPOut BinForceByteOrder(Object object) throws IOException
      Works like Bin(Object) but forcing override of all annotation byte order values by the JBBPOut byte order.
      Parameters:
      object - an object to be saved into stream, must not be null
      Returns:
      the context
      Throws:
      IOException - it will be thrown for any transport error
      Since:
      2.0.2
      See Also:

    • BinForceByteOrder

      public JBBPOut BinForceByteOrder(Object object, JBBPCustomFieldWriter customFieldWriter)
      Works like Bin(Object, JBBPCustomFieldWriter) but forcing override of all annotation byte order values by the context byte order.
      Parameters:
      object - an object to be saved into stream, must not be null
      customFieldWriter - a custom field writer to be used for saving of custom fields of the object, it can be null
      Returns:
      the context
      Since:
      2.0.2
      See Also:

    • onFieldFloat

      protected void onFieldFloat(Object obj, Field field, Bin annotation, float value)
      Description copied from class: AbstractMappedClassFieldObserver
      Notification about float field.
      Overrides:
      onFieldFloat in class AbstractMappedClassFieldObserver
      Parameters:
      obj - the object instance, must not be null
      field - the field, must not be null
      annotation - the annotation for field, must not be null
      value - the value of the field

    • onFieldString

      protected void onFieldString(Object obj, Field field, Bin annotation, String value)
      Description copied from class: AbstractMappedClassFieldObserver
      Notification about string field.
      Overrides:
      onFieldString in class AbstractMappedClassFieldObserver
      Parameters:
      obj - the object instance, must not be null
      field - the field, must not be null
      annotation - the annotation for field, must not be null
      value - the value of the field

    • onFieldDouble

      protected void onFieldDouble(Object obj, Field field, Bin annotation, double value)
      Description copied from class: AbstractMappedClassFieldObserver
      Notification about double field.
      Overrides:
      onFieldDouble in class AbstractMappedClassFieldObserver
      Parameters:
      obj - the object instance, must not be null
      field - the field, must not be null
      annotation - the annotation for field, must not be null
      value - the value of the field

    • onFieldLong

      protected void onFieldLong(Object obj, Field field, Bin annotation, long value)
      Description copied from class: AbstractMappedClassFieldObserver
      Notification about long field.
      Overrides:
      onFieldLong in class AbstractMappedClassFieldObserver
      Parameters:
      obj - the object instance, must not be null
      field - the field, must not be null
      annotation - the annotation for field, must not be null
      value - the value of the field

    • onFieldInt

      protected void onFieldInt(Object obj, Field field, Bin annotation, int value)
      Description copied from class: AbstractMappedClassFieldObserver
      Notification about integer field.
      Overrides:
      onFieldInt in class AbstractMappedClassFieldObserver
      Parameters:
      obj - the object instance, must not be null
      field - the field, must not be null
      annotation - the annotation for field, must not be null
      value - the value of the field

    • UInt

      public JBBPOut UInt(long... value) throws IOException
      Write each long value as unsigned integer one into the session stream.
      Parameters:
      value - a long value array which values should be written into
      Returns:
      the DSl session
      Throws:
      IOException - it will be thrown for transport errors
      Since:
      2.0.4

    • onFieldShort

      protected void onFieldShort(Object obj, Field field, Bin annotation, boolean signed, int value)
      Description copied from class: AbstractMappedClassFieldObserver
      Notification about short field.
      Overrides:
      onFieldShort in class AbstractMappedClassFieldObserver
      Parameters:
      obj - the object instance, must not be null
      field - the field, must not be null
      annotation - the annotation for field, must not be null
      signed - flag shows that the field id signed
      value - the value of the field

    • onFieldByte

      protected void onFieldByte(Object obj, Field field, Bin annotation, boolean signed, int value)
      Description copied from class: AbstractMappedClassFieldObserver
      Notification about byte field.
      Overrides:
      onFieldByte in class AbstractMappedClassFieldObserver
      Parameters:
      obj - the object instance, must not be null
      field - the field, must not be null
      annotation - the annotation for field, must not be null
      signed - flag shows that the field id signed
      value - the value of the field

    • onFieldBool

      protected void onFieldBool(Object obj, Field field, Bin annotation, boolean value)
      Description copied from class: AbstractMappedClassFieldObserver
      Notification about boolean field.
      Overrides:
      onFieldBool in class AbstractMappedClassFieldObserver
      Parameters:
      obj - the object instance, must not be null
      field - the field, must not be null
      annotation - the annotation for field, must not be null
      value - the value of the field

    • onFieldBits

      protected void onFieldBits(Object obj, Field field, Bin annotation, JBBPBitNumber bitNumber, int value)
      Description copied from class: AbstractMappedClassFieldObserver
      Notification about bit field.
      Overrides:
      onFieldBits in class AbstractMappedClassFieldObserver
      Parameters:
      obj - the object instance, must not be null
      field - the field, must not be null
      annotation - the annotation for field, must not be null
      bitNumber - number of bits for the field, must not be null
      value - the value of the field

    • onFieldCustom

      protected void onFieldCustom(Object obj, Field field, Bin annotation, Object customFieldProcessor, Object value)
      Description copied from class: AbstractMappedClassFieldObserver
      Notification about custom field.
      Overrides:
      onFieldCustom in class AbstractMappedClassFieldObserver
      Parameters:
      obj - the object instance, must not be null
      field - the custom field, must not be null
      annotation - the annotation for the field, must not be null
      customFieldProcessor - processor for custom fields, must not be null
      value - the value of the custom field