public class SCAMPIMessage
extends java.lang.Object
Message format used in Scampi networking. Message content is a typed key-value map, with string keys and integer, float, string or binary values. In addition, metadata can be attached to the message.
Message instances are constructed with the builder()
method,
which allows the configuration of general message settings,
including the AppTag, lifetime and persistence. Once the application is
done using a message it must call close()
to free any resources
used to back the message content.
Message content is modified with the put*()
methods. There can be
at most one content item for each key, and subsequent put*()
calls
will overwrite existing ones. The content items can be accessed with the
get*()
methods.
Modifier and Type | Class and Description |
---|---|
static class |
SCAMPIMessage.Builder
Builder for constructing
SCAMPIMessage instances. |
Modifier and Type | Field and Description |
---|---|
static int |
DEFAULT_LIFETIME
Default lifetime for messages in seconds (43200).
|
static int |
METADATA_TYPE
Metadata extension block type code for scampi metadata.
|
static java.util.Random |
RNG
RNG for use with messages.
|
Constructor and Description |
---|
SCAMPIMessage()
Deprecated.
use the builder mechanism instead
builder() |
SCAMPIMessage(java.lang.String appTag)
Deprecated.
use the builder mechanism instead
builder() |
Modifier and Type | Method and Description |
---|---|
static SCAMPIMessage.Builder |
builder()
Returns a builder instance to generate a new SCAMPIMessage instance.
|
void |
close()
Closes the message.
|
void |
copyBinary(java.lang.String name,
java.io.File destination)
Copies the content item with the given name to a file.
|
java.lang.String |
getAppTag()
Returns the AppTag of the message.
|
java.io.InputStream |
getBinary(java.lang.String name)
Returns an input stream to binary content item of the given name.
|
byte[] |
getBinaryBuffer(java.lang.String name)
Returns a copy of the content item value in a new memory buffer.
|
long |
getBinarySize(java.lang.String name)
Returns the size of the binary content value.
|
java.util.Collection<fi.tkk.netlab.dtn.scampi.applib.impl.message.ContentType> |
getContent()
Returns an unmodifiable view to all the content.
|
double |
getFloat(java.lang.String name)
Returns a floating point content item of the given name.
|
long |
getInteger(java.lang.String name)
Returns an integer content item of the given name.
|
long |
getLifetime()
Returns the message lifetime in seconds.
|
java.util.Map<java.lang.String,java.util.Map<java.lang.String,java.lang.Object>> |
getMetadata()
Returns the full metadata map:
Namespace -> metadata: key -> value
|
java.lang.Double |
getMetadataDouble(java.lang.String namespace,
java.lang.String key)
Get a metadata value as a Double.
|
java.lang.Long |
getMetadataLong(java.lang.String namespace,
java.lang.String key)
Get a metadata value as a Long.
|
java.lang.String |
getMetadataString(java.lang.String namespace,
java.lang.String key)
Get a metadata value as a String.
|
java.lang.String |
getString(java.lang.String name)
Returns a string content item of the given name.
|
boolean |
hasBinary(java.lang.String name)
Returns
true if the message has a binary type content item
with the given name, false otherwise (i.e.,
if the content item does not exist or exists but is not a binary type). |
boolean |
hasFloat(java.lang.String name)
Returns
true if the message has a floating point type content item
with the given name, false otherwise (i.e.,
if the content item does not exist or exists but is not a floating point
type). |
boolean |
hasInteger(java.lang.String name)
Returns
true if the message has an integer type content item
with the given name, false otherwise (i.e.,
if the content item does not exist or exists but is not an integer type). |
boolean |
hasString(java.lang.String name)
Returns
true if the message has a string type content item
with the given name, false otherwise (i.e.,
if the content item does not exist or exists but is not a string type). |
boolean |
isPersistent()
Checks if the message is marked as persistent.
|
void |
moveBinary(java.lang.String name,
java.io.File destination)
Moves the binary data to the destination file,
and sets it as the backing resource for the message.
|
void |
putBinary(java.lang.String name,
byte[] value)
Sets the binary content value for the given name.
|
void |
putBinary(java.lang.String name,
java.io.File value)
Sets the binary content value for the given name.
|
void |
putBinary(java.lang.String name,
java.io.File value,
boolean deleteOnClose)
Sets the binary content value for the given name.
|
void |
putFloat(java.lang.String name,
double value)
Sets the floating point content value for the given name.
|
void |
putInteger(java.lang.String name,
long value)
Sets the integer content value for the given name.
|
void |
putString(java.lang.String name,
java.lang.String value)
Sets the string content value for the given name.
|
void |
removeContent(java.lang.String name)
Removes a content item from the message.
|
void |
setLifetime(long lifetime)
Set the lifetime for the message.
|
void |
setMetadata(java.util.Map<java.lang.String,java.util.Map<java.lang.String,java.lang.Object>> metadata)
Set the whole metadata map.
|
void |
setMetadata(java.lang.String namespace,
java.lang.String key,
java.lang.Double value)
Set metadata as a Double.
|
void |
setMetadata(java.lang.String namespace,
java.lang.String key,
java.lang.Long value)
Set metadata as a Long.
|
void |
setMetadata(java.lang.String namespace,
java.lang.String key,
java.lang.String value)
Set metadata as a String.
|
void |
setPersistent(boolean persistent)
If message is marked as persistent, it will be held in a permanent cache
by the router.
|
java.lang.String |
toString() |
public static final int DEFAULT_LIFETIME
public static final int METADATA_TYPE
public static final java.util.Random RNG
@Deprecated public SCAMPIMessage()
builder()
@Deprecated public SCAMPIMessage(java.lang.String appTag)
builder()
appTag
- AppTag that identifies the messagepublic static SCAMPIMessage.Builder builder()
public void setPersistent(boolean persistent)
persistent
- true
for persistent message,
false
otherwisepublic boolean isPersistent()
public void setLifetime(long lifetime)
Set the lifetime for the message. This maps directly to the underlying bundle lifetime, routers will delete the bundle after the lifetime has expired.
This mechanism can be disable on per-cache basis through the router
configuration by setting disableTTL = true
.
lifetime
- lifetime in seconds.public long getLifetime()
public java.lang.String getAppTag()
public final void close()
public java.lang.String toString()
toString
in class java.lang.Object
public final java.util.Collection<fi.tkk.netlab.dtn.scampi.applib.impl.message.ContentType> getContent()
UnsupportedOperationException
.public final boolean hasInteger(java.lang.String name)
true
if the message has an integer type content item
with the given name, false
otherwise (i.e.,
if the content item does not exist or exists but is not an integer type).name
- name of the content itemtrue
if the message contains an integer content item
with the given name, false
otherwise.public final long getInteger(java.lang.String name) throws ApiException
name
- name of the content itemApiException
- if an item with the given name does not exist or is
not an integer.to check if the message contains an integer
content item.
public final void putInteger(java.lang.String name, long value)
name
- name of the content item, cannot be null
value
- value to setpublic final boolean hasFloat(java.lang.String name)
true
if the message has a floating point type content item
with the given name, false
otherwise (i.e.,
if the content item does not exist or exists but is not a floating point
type).name
- name of the content itemtrue
if the message contains a floating point content item
with the given name, false
otherwise.public final double getFloat(java.lang.String name) throws ApiException
name
- name of the content itemApiException
- if an item with the given name does not exist or is
not a floating point type.to check if the message contains a floating point
content item.
public final void putFloat(java.lang.String name, double value)
name
- name of the content item, cannot be null
value
- value to setpublic final boolean hasString(java.lang.String name)
true
if the message has a string type content item
with the given name, false
otherwise (i.e.,
if the content item does not exist or exists but is not a string type).name
- name of the content itemtrue
if the message contains a string content item
with the given name, false
otherwise.public final java.lang.String getString(java.lang.String name) throws ApiException
name
- name of the content itemApiException
- if an item with the given name does not exist or is
not a string.to check if the message contains a string
content item.
public final void putString(java.lang.String name, java.lang.String value)
name
- name of the content item, cannot be null
value
- value to set, cannot be null
public final boolean hasBinary(java.lang.String name)
true
if the message has a binary type content item
with the given name, false
otherwise (i.e.,
if the content item does not exist or exists but is not a binary type).name
- name of the content itemtrue
if the message contains a binary content item
with the given name, false
otherwise.public final java.io.InputStream getBinary(java.lang.String name) throws ApiException
name
- name of the content itemApiException
- if an item with the given name does not exist or is
not a binary.to check if the message contains a binary
content item.
public final long getBinarySize(java.lang.String name) throws ApiException
name
- name of the content itemApiException
public final void copyBinary(java.lang.String name, java.io.File destination) throws java.io.IOException, ApiException
name
- name of the content itemdestination
- destination file, must not exist and must be writablejava.io.IOException
- if the copy failsApiException
- if an item with the given name does not exist or is
not a binary.for possibly avoiding a copy
when dealing with large binary content items
public final void moveBinary(java.lang.String name, java.io.File destination) throws ApiException, java.io.IOException
Moves the binary data to the destination file,
and sets it as the backing resource for the message. The destination file
will not be deleted when the message is close()
d.
This is intended for efficient handling of large binary content items.
If the received message contains a large binary content item backed by a
file, this method can be used to move that file to a location where the
application has direct access to it, possibly avoiding a copy that would
result when using copyBinary(String, java.io.File)
.
The actual behavior depends on the backing resource and the destination location: 1) If the backing resource is a file, try to move the file to the given destination, 2) if the move fails (e.g., destination is on a different volume), copy the binary to the destination and delete the old backing file, 3) if the backing resource is a memory buffer, it is written to the destination file.
name
- name of the content itemdestination
- destination file, must not exist and must be writableApiException
- if the content item
does not exist, or is not a binaryjava.io.IOException
- if the move failsjava.lang.IllegalArgumentException
- if the destination file
already existspublic final byte[] getBinaryBuffer(java.lang.String name) throws ApiException, java.io.IOException
name
- name of the content itemApiException
java.io.IOException
get the size of the content item (amount of
memory that will be allocated for the copy)
public final void putBinary(java.lang.String name, java.io.File value)
name
- name of the content item, cannot be null
value
- value to set, cannot be null
for a variant that
deletes the file when the message is closed.
public final void putBinary(java.lang.String name, java.io.File value, boolean deleteOnClose)
name
- name of the content item, cannot be null
value
- value to set, cannot be null
deleteOnClose
- true
to delete the file when
close()
is called.public final void putBinary(java.lang.String name, byte[] value)
name
- name of the content item, cannot be null
value
- value to set, cannot be null
public final void removeContent(java.lang.String name)
name
- name of the content item, cannot be null
public void setMetadata(java.util.Map<java.lang.String,java.util.Map<java.lang.String,java.lang.Object>> metadata)
metadata
- metadata map to setpublic void setMetadata(java.lang.String namespace, java.lang.String key, java.lang.Double value)
namespace
- namespace for the metadata entrykey
- key for the metadata entryvalue
- value for the metadata entrypublic void setMetadata(java.lang.String namespace, java.lang.String key, java.lang.String value)
namespace
- namespace for the metadata entrykey
- key for the metadata entryvalue
- value for the metadata entrypublic void setMetadata(java.lang.String namespace, java.lang.String key, java.lang.Long value)
namespace
- namespace for the metadata entrykey
- key for the metadata entryvalue
- value for the metadata entrypublic java.util.Map<java.lang.String,java.util.Map<java.lang.String,java.lang.Object>> getMetadata()
public java.lang.Double getMetadataDouble(java.lang.String namespace, java.lang.String key)
null
will be returned.namespace
- namespace for the metadata entrykey
- key for the metadata entrypublic java.lang.Long getMetadataLong(java.lang.String namespace, java.lang.String key)
null
will be returned.namespace
- namespace for the metadata entrykey
- key for the metadata entrypublic java.lang.String getMetadataString(java.lang.String namespace, java.lang.String key)
null
will be returned.namespace
- namespace for the metadata entrykey
- key for the metadata entry