MessageTransportHeaders (Talon 3.14.19 API)

java.lang.Object
- com.neeve.sma.MessageTransportHeaders

All Implemented Interfaces:: XIterator<MessageTransportHeaders.Header>, UtlPool.Item<MessageTransportHeaders>, Iterable<MessageTransportHeaders.Header>, Iterator<MessageTransportHeaders.Header>

public class MessageTransportHeaders
extends Object
implements UtlPool.Item<MessageTransportHeaders>, XIterator<MessageTransportHeaders.Header>, Iterable<MessageTransportHeaders.Header>

A view into message transport headers.

This class is used to hold a list of message transport headers and provides efficient iteration and serialization for them.

Simple Usage Pattern

Applications that are not performance sensitive and are tolerant of object allocation, may use the toMap() method to retrieve a map representation of the transport headers, which provides a mechanism for working with transport headers the map will contain a String key for each header and the (possibly autoboxed) value of the header.

 MessageTransportHeaders transportHeaders = message.getMetadata().getTransportHeadersMap();
 Long sequenceNumber = transportHeaders.get("msgid");
 String wireChannel = transportHeaders.get("rcvdChannel");

Zero Garbage Message Transport Header Access (advanced usage)

This class serves as a lightweight view into binary header content and presents an Iterable view of the Headers that it contains. However it is important to note that the same Header object is returned by each call to the transport header's iterator. Which means that while iterating headers, one must not retain instances of MessageTransportHeaders.Header objects.

 MessageTransportHeaders transportHeaders = message.getMetadata().getTransportHeaders();
 if(transportHeaders != null) {
   for(Header header : transportHeaders) {
     if(header.getNameUnsafe().compareTo("SomeHeader") == 0) {
        if(header.getType() == HeaderType.String) {
          XString headerValue = header.getStringValueUnsafe();
          // header.getStringValueUnsafe() and header.getNameUnsafe() must not be mutated.
        }
        else if (header.getType() == HeaderType.Long) {
           long val = header.getLongValue();
           // do something. 
        }
     }
   }
 }

MessageTransportHeaders implements Iterable

and returns the same Iterator on each call to iterator(). Consequently, it can be used in a zero garbage fashion using the enhanced for loop syntax, but 2 threads must not call iterator() concurrently, nor should an attempt be made to call iterator() from within an iterative loop.

Serialization Format

MessageTransportHeaders are encoded as follows (with big endian byte order): >>>

Bytes	Description
Fixed Length Portion
0	Version (1)
1-4	Serialized Length. The length of the encoded transport headers inclusive of fixed length and variable length values described here.
Variable Length Portion Each map entry is written as key folllowed by a value as follows: key length (short) K key bytes of ascii characters specified by key length. 1 byte type identifier [1=byte, 2=boolean, 3=utf char, 4=short, 5=int, 6=float, 7=long, 8=double, 9=str, 10=binary bytes] value length (only for variable length str and binary bytes) V value bytes (1 byte for byte,boolean, 1-3 bytes for char, 2 bytes for short, 4 bytes for int or float, 8 bytes for long or double otherwise the number of specified by the value length.
keyLen1 (2 bytes)	key (keyLen1 bytes)	type1 (1 byte)	valueLen1 (2 bytes ... only if variable length)	value (valueLen1 bytes)
keyLen2 (2 bytes)	key (keyLen2 bytes)	type2 (1 byte)	valueLen2 (2 bytes ... only if variable length)	value (valueLen2 bytes)
keyLenN (2 bytes)	key (keyLenN bytes)	typeN (1 byte)	valueLenN (2 bytes ... only if variable length)	value (valueLenN bytes)

Threading:: This class is not safe for concurrent access by multiple threads. Of particular note it it is generally not safe to iterate the header in 2 threads.

Nested Class Summary

Nested Classes
Modifier and Type	Class and Description
`class`	`MessageTransportHeaders.Header` Represent a message transport header name/value pair.
`static class`	`MessageTransportHeaders.HeaderType` Enumerates possible header types.

Method Summary

Methods
Modifier and Type	Method and Description
`void`	`addHeader(CharSequence name, boolean value)` Adds the provided boolean transport header.
`void`	`addHeader(CharSequence name, byte value)` Adds the provided byte transport header.
`void`	`addHeader(CharSequence name, byte[] src, int srcOffset, int length)` Adds the provided byte[] transport header.
`void`	`addHeader(CharSequence name, char value)` Adds the provided char transport header.
`void`	`addHeader(CharSequence name, CharSequence value)` Adds the provided String transport header.
`void`	`addHeader(CharSequence name, double value)` Adds the provided double transport header.
`void`	`addHeader(CharSequence name, float value)` Adds the provided float transport header.
`void`	`addHeader(CharSequence name, int value)` Adds the provided int transport header.
`void`	`addHeader(CharSequence name, com.neeve.io.IOBuffer src, int srcOffset, int length)` Adds the provided IOBuffer as a binary transport header.
`void`	`addHeader(CharSequence name, long value)` Adds the provided long transport header.
`MessageTransportHeaders`	`addHeader(CharSequence name, Object value)` Adds the provided header if it is of a supported data type.
`void`	`addHeader(CharSequence name, short value)` Adds the provided short transport header.
`void`	`addHeader(XString name, boolean value)` Adds the provided boolean transport header.
`void`	`addHeader(XString name, byte value)` Adds the provided byte transport header.
`void`	`addHeader(XString name, byte[] src, int srcOffset, int length)` Adds the provided byte [] as a binary transport header.
`void`	`addHeader(XString name, char value)` Adds the provided char transport header.
`void`	`addHeader(XString name, double value)` Adds the provided double transport header.
`void`	`addHeader(XString name, float value)` Adds the provided float transport header.
`void`	`addHeader(XString name, int value)` Adds the provided int transport header.
`void`	`addHeader(XString name, com.neeve.io.IOBuffer src, int srcOffset, int length)` Adds the provided IOBuffer as a binary transport header.
`void`	`addHeader(XString name, long value)` Adds the provided long transport header.
`MessageTransportHeaders`	`addHeader(XString name, Object value)` Adds the provided header if it is of a supported data type.
`void`	`addHeader(XString name, short value)` Adds the provided short transport header.
`void`	`addHeader(XString name, String value)` Adds the provided transport header.
`void`	`addHeader(XString name, XString value)` Adds the provided transport header.
`MessageTransportHeaders`	`copy()` Creates a copy of this object.
`static MessageTransportHeaders`	`create()` Creates an empty set of `MessageTransportHeaders`.
`int`	`deserialize(ByteBuffer src)` Deserializes transport headers from a give source buffer.
`int`	`deserialize(com.neeve.io.IOBuffer src, int offset)` Deserializes transport headers from a give source buffer.
`int`	`deserialize(com.neeve.io.IOElasticBuffer src, int offset)` Deserializes transport headers from a give source buffer.
`void`	`dispose()` Returns this `MessageTransportHeaders` to its pool.
`void`	`getAllTo(Map<String,Object> to)` Add all of the headers to the provided map.
`static short`	`getLatestVersion()` Get the latest transport headers version.
`UtlPool<MessageTransportHeaders>`	`getPool()` Get a pool item's pool.
`static int`	`getSerializedLength(com.neeve.io.IOBuffer buffer, int offset)` Determines the serialized length of message transport headers that are serialized in a given buffer.
`static int`	`getSerializedLength(com.neeve.io.IOElasticBuffer buffer, int offset)` Determines the serialized length of message transport headers that are serialized in a given buffer.
`Object`	`getValue(String key)` Iterates through the headers and returns the matching header value if present.
`boolean`	`hasNext()`
`MessageTransportHeaders`	`init()` Initialize an item.
`boolean`	`isReadOnly()` Tests if the transport headers are readonly.
`Iterator<MessageTransportHeaders.Header>`	`iterator()` Returns these headers as an iterator.
`static void`	`main(String[] args)`
`MessageTransportHeaders.Header`	`next()` Invalidates any previously returned `MessageTransportHeaders.Header` and returns the next header.
`void`	`remove()` Remove is not supported for this iterator.
`int`	`serialize(ByteBuffer dest)` Serializes transport headers to a given ByteBuffer
`int`	`serialize(com.neeve.io.IOBuffer dest, int offset)` Serializes transport headers to a given IOBuffer
`int`	`serialize(com.neeve.io.IOElasticBuffer dest, int offset)` Serializes transport headers to a given IOElasticBuffer
`int`	`serializedLength()` Returns the serialized length of this `MessageTransportHeaders`.
`MessageTransportHeaders`	`setPool(UtlPool<MessageTransportHeaders> pool)` Set a pool item's pool.
`XIterator<MessageTransportHeaders.Header>`	`toFirst()` Reset the `MessageTransportHeaders.Header` iterator view to the first Header position.
`void`	`toJsonString(boolean indent, int indentDepth, boolean noSpaces, StringBuilder sb)` Writes transport headers as a json string.
`void`	`toJsonString(StringBuilder sb)` Writes transport headers as a json string.
`Map<String,Object>`	`toMap()` Return all of the transport headers in a map.
`String`	`toString()`

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

- Method Detail
  - getLatestVersion
```
public static final short getLatestVersion()
```
    Get the latest transport headers version.
  - create
```
public static MessageTransportHeaders create()
```
    Creates an empty set of MessageTransportHeaders.
  - isReadOnly
```
public boolean isReadOnly()
```
    Tests if the transport headers are readonly.
    
    Returns:
    True if transport headers are readonly.
  - serializedLength
```
public final int serializedLength()
```
    Returns the serialized length of this MessageTransportHeaders.
    
    Returns:
    The serialized length of this MessageTransportHeaders.
  - deserialize
```
public final int deserialize(com.neeve.io.IOElasticBuffer src,
              int offset)
```
    Deserializes transport headers from a give source buffer.
    
    Parameters:
    src - The source buffer from which to deserialize.
    offset - The offset in the source buffeer from which to deserialize.
    
    Returns:
    the number of bytes deserialized.
  - deserialize
```
public final int deserialize(com.neeve.io.IOBuffer src,
              int offset)
```
    Deserializes transport headers from a give source buffer.
    
    Parameters:
    src - The source buffer from which to deserialize.
    offset - The offset in the source buffeer from which to deserialize.
    
    Returns:
    the number of bytes deserialized.
  - deserialize
```
public final int deserialize(ByteBuffer src)
```
    Deserializes transport headers from a give source buffer.
    
    Parameters:
    src - The source buffer from which to deserialize.
    
    Returns:
    the number of bytes deserialized.
  - serialize
```
public final int serialize(com.neeve.io.IOBuffer dest,
            int offset)
```
    Serializes transport headers to a given IOBuffer
    
    Parameters:
    dest - The buffer into which to serialize the headers
    offset - The offset into the dest buffer at which to serialize.
    
    Returns:
    the number of bytes deserialized.
  - serialize
```
public final int serialize(com.neeve.io.IOElasticBuffer dest,
            int offset)
```
    Serializes transport headers to a given IOElasticBuffer
    
    Parameters:
    dest - The buffer into which to serialize the headers
    offset - The offset into the dest buffer at which to serialize.
    
    Returns:
    the number of bytes deserialized.
  - serialize
```
public final int serialize(ByteBuffer dest)
```
    Serializes transport headers to a given ByteBuffer
    
    Parameters:
    dest - The buffer into which to serialize the headers
    
    Returns:
    the number of bytes deserialized.
  - getSerializedLength
```
public static final int getSerializedLength(com.neeve.io.IOElasticBuffer buffer,
                      int offset)
```
    Determines the serialized length of message transport headers that are serialized in a given buffer.
    
    Parameters:
    buffer - The buffer holding serialized message transport headers.
    offset - The offset into the buffer.
    
    Returns:
    The serialized length of the transport headers.
  - getSerializedLength
```
public static final int getSerializedLength(com.neeve.io.IOBuffer buffer,
                      int offset)
```
    Determines the serialized length of message transport headers that are serialized in a given buffer.
    
    Parameters:
    buffer - The buffer holding serialized message transport headers.
    offset - The offset into the buffer.
    
    Returns:
    The serialized length of the transport headers.
  - copy
```
public final MessageTransportHeaders copy()
```
    Creates a copy of this object.
    
    Returns:
    The returned copy will be writeable.
  - hasNext
```
public final boolean hasNext()
```
    Specified by:
    
    hasNext in interface Iterator<MessageTransportHeaders.Header>
  - next
```
public final MessageTransportHeaders.Header next()
```
    Invalidates any previously returned MessageTransportHeaders.Header and returns the next header.
    Additionally, it if very important to note that each returned header is only valid until the next call is made to next() because the same MessageTransportHeaders.Header instance is reused during the iteration.
    
    Specified by:
    
    next in interface Iterator<MessageTransportHeaders.Header>
  - remove
```
public final void remove()
```
    Remove is not supported for this iterator.
    
    Specified by:
    
    remove in interface Iterator<MessageTransportHeaders.Header>
  - toFirst
```
public final XIterator<MessageTransportHeaders.Header> toFirst()
```
    Reset the MessageTransportHeaders.Header iterator view to the first Header position.
    
    Specified by:
    
    toFirst in interface XIterator<MessageTransportHeaders.Header>
    
    Returns:
    A MessageTransportHeaders.Header iterator reset to the first header.
  - iterator
```
public final Iterator<MessageTransportHeaders.Header> iterator()
```
    Returns these headers as an iterator.
    Note that this operation does not allocate a new iterator, but instead just returns this object after calling toFirst().
    Additionally, it if very important to note that each returned headers is only valid until the next call is made to next() because the same Header instance is reused during the iteration.
    
    Specified by:
    
    iterator in interface Iterable<MessageTransportHeaders.Header>
  - addHeader
```
public final void addHeader(CharSequence name,
             byte value)
```
    Adds the provided byte transport header.
    
    Parameters:
    name - The header name.
    value - The header value.
  - addHeader
```
public final void addHeader(CharSequence name,
             boolean value)
```
    Adds the provided boolean transport header.
    
    Parameters:
    name - The header name.
    value - The header value.
  - addHeader
```
public final void addHeader(CharSequence name,
             char value)
```
    Adds the provided char transport header.
    
    Parameters:
    name - The header name.
    value - The header value.
  - addHeader
```
public final void addHeader(CharSequence name,
             short value)
```
    Adds the provided short transport header.
    
    Parameters:
    name - The header name.
    value - The header value.
  - addHeader
```
public final void addHeader(CharSequence name,
             int value)
```
    Adds the provided int transport header.
    
    Parameters:
    name - The header name.
    value - The header value.
  - addHeader
```
public final void addHeader(CharSequence name,
             float value)
```
    Adds the provided float transport header.
    
    Parameters:
    name - The header name.
    value - The header value.
  - addHeader
```
public final void addHeader(CharSequence name,
             long value)
```
    Adds the provided long transport header.
    
    Parameters:
    name - The header name.
    value - The header value.
  - addHeader
```
public final void addHeader(CharSequence name,
             double value)
```
    Adds the provided double transport header.
    
    Parameters:
    name - The header name.
    value - The header value.
  - addHeader
```
public final void addHeader(XString name,
             byte value)
```
    Adds the provided byte transport header.
    
    Parameters:
    name - The header name.
    value - The header value.
  - addHeader
```
public final void addHeader(XString name,
             boolean value)
```
    Adds the provided boolean transport header.
    
    Parameters:
    name - The header name.
    value - The header value.
  - addHeader
```
public final void addHeader(XString name,
             char value)
```
    Adds the provided char transport header.
    
    Parameters:
    name - The header name.
    value - The header value.
  - addHeader
```
public final void addHeader(XString name,
             short value)
```
    Adds the provided short transport header.
    
    Parameters:
    name - The header name.
    value - The header value.
  - addHeader
```
public final void addHeader(XString name,
             int value)
```
    Adds the provided int transport header.
    
    Parameters:
    name - The header name.
    value - The header value.
  - addHeader
```
public final void addHeader(XString name,
             float value)
```
    Adds the provided float transport header.
    
    Parameters:
    name - The header name.
    value - The header value.
  - addHeader
```
public final void addHeader(XString name,
             long value)
```
    Adds the provided long transport header.
    
    Parameters:
    name - The header name.
    value - The header value.
  - addHeader
```
public final void addHeader(XString name,
             double value)
```
    Adds the provided double transport header.
    
    Parameters:
    name - The header name.
    value - The header value.
  - addHeader
```
public final void addHeader(CharSequence name,
             CharSequence value)
```
    Adds the provided String transport header.
    
    Parameters:
    name - The header name.
    value - The header value.
  - addHeader
```
public final void addHeader(CharSequence name,
             byte[] src,
             int srcOffset,
             int length)
```
    Adds the provided byte[] transport header.
    
    Parameters:
    name - The header name.
    src - The header value.
    srcOffset - The offeset into the buffer from which to copy.
    length - The number of bytes to copy.
  - addHeader
```
public final void addHeader(CharSequence name,
             com.neeve.io.IOBuffer src,
             int srcOffset,
             int length)
```
    Adds the provided IOBuffer as a binary transport header.
    
    Parameters:
    name - The header name.
    src - The header value.
    srcOffset - The offeset into the buffer from which to copy.
    length - The number of bytes to copy.
  - addHeader
```
public MessageTransportHeaders addHeader(CharSequence name,
                                Object value)
```
    Adds the provided header if it is of a supported data type.
    
    Parameters:
    name - the header name.
    value - the header value.
    
    Throws:
    
    NullPointerException - if name or value is null.
    
    IllegalArgumentException - if the value type is unsupported.
  - addHeader
```
public MessageTransportHeaders addHeader(XString name,
                                Object value)
```
    Adds the provided header if it is of a supported data type.
    
    Parameters:
    name - the header name.
    value - the header value.
    
    Throws:
    
    NullPointerException - if name or value is null.
    
    IllegalArgumentException - if the value type is unsupported.
  - addHeader
```
public final void addHeader(XString name,
             XString value)
```
    Adds the provided transport header.
    
    Parameters:
    name - The header name.
    value - The header value.
  - addHeader
```
public final void addHeader(XString name,
             String value)
```
    Adds the provided transport header.
    
    Parameters:
    name - The header name.
    value - The header value.
  - addHeader
```
public final void addHeader(XString name,
             com.neeve.io.IOBuffer src,
             int srcOffset,
             int length)
```
    Adds the provided IOBuffer as a binary transport header.
    
    Parameters:
    name - The header name.
    src - The header value.
    srcOffset - The offeset into the buffer from which to copy.
    length - The number of bytes to copy.
    
    Throws:
    
    IllegalArgumentException - if the provided length is greater than Short.MAX_VALUE
  - addHeader
```
public final void addHeader(XString name,
             byte[] src,
             int srcOffset,
             int length)
```
    Adds the provided byte [] as a binary transport header.
    
    Parameters:
    name - The header name.
    src - The header value.
    srcOffset - The offeset into the buffer from which to copy.
    length - The number of bytes to copy.
    
    Throws:
    
    IllegalArgumentException - if the provided length is greater than Short.MAX_VALUE
  - toMap
```
public Map<String,Object> toMap()
```
    Return all of the transport headers in a map.
    Notes:
    Returns:
    The transport headers as a map.
  - getAllTo
```
public void getAllTo(Map<String,Object> to)
```
    Add all of the headers to the provided map.
    Note: this is not a zero garbage operation
    
    Parameters:
    to - the Map into which to add all of the headers.
  - getValue
```
public Object getValue(String key)
```
    Iterates through the headers and returns the matching header value if present.
    Note: this is not a zero garbage operation
    
    Parameters:
    key - The key to seach for.
    
    Returns:
    The value if present or null if there is no header with the given key.
  - dispose
```
public final void dispose()
```
    Returns this MessageTransportHeaders to its pool.
  - init
```
public final MessageTransportHeaders init()
```
    Description copied from interface: UtlPool.Item
    
    Initialize an item.
    This method is invoked by an item pool very time an item is put into the pool. The method should wipe the contents of the item so as to present a fresh instance of the item to the caller when retrieved from the pool.
    
    Specified by:
    
    init in interface UtlPool.Item<MessageTransportHeaders>
    
    Returns:
    Return 'this' object for method invocation chaining.
  - setPool
```
public final MessageTransportHeaders setPool(UtlPool<MessageTransportHeaders> pool)
```
    Description copied from interface: UtlPool.Item
    
    Set a pool item's pool.
    This method is invoked by an item pool at the time an item is added to the pool. The intent is to record the item's source pool in the item so it can be disposed back into the pool when the user is done working with it.
    
    Specified by:
    
    setPool in interface UtlPool.Item<MessageTransportHeaders>
    
    Returns:
    Return 'this' object for method invocation chaining.
  - getPool
```
public final UtlPool<MessageTransportHeaders> getPool()
```
    Description copied from interface: UtlPool.Item
    
    Get a pool item's pool.
    This method should return the pool set using UtlPool.Item.setPool(com.neeve.util.UtlPool<T>)
    
    Specified by:
    
    getPool in interface UtlPool.Item<MessageTransportHeaders>
    
    Returns:
    the pool set using UtlPool.Item.setPool(com.neeve.util.UtlPool<T>)
  - toString
```
public String toString()
```
    Overrides:
    
    toString in class Object
    
    Returns:
    a String representation of the transport headers.
  - toJsonString
```
public void toJsonString(StringBuilder sb)
```
    Writes transport headers as a json string.
    If the XRuntime value "nv.indent.json" is true, the value is pretty printed.
    
    Parameters:
    sb - The builder to write json to.
  toJsonString
  
  public void toJsonString(boolean indent, int indentDepth, boolean noSpaces, StringBuilder sb)
  
  Writes transport headers as a json string.
  
  Parameters:
  indent - If true pretty print with newlines and a 2 space indent.
  indentDepth - The the indent depth to prefix for each line.
  noSpaces - When true, no spaces are inserted between key/value pairs.
  sb - The builder to append to.
  
  main
  
  public static void main(String[] args)

Class MessageTransportHeaders

Simple Usage Pattern

Zero Garbage Message Transport Header Access (advanced usage)

Nested Class Summary

Method Summary

Methods inherited from class java.lang.Object

Method Detail

getLatestVersion

create

isReadOnly

serializedLength

deserialize

deserialize

deserialize

serialize

serialize

serialize

getSerializedLength

getSerializedLength

copy

hasNext

next

remove

toFirst

iterator

addHeader

addHeader

addHeader

addHeader

addHeader

addHeader

addHeader

addHeader

addHeader

addHeader

addHeader

addHeader

addHeader

addHeader

addHeader

addHeader

addHeader

addHeader

addHeader

addHeader

addHeader

addHeader

addHeader

addHeader

addHeader

toMap

getAllTo

getValue

dispose

init

setPool

getPool

toString

toJsonString

toJsonString

main