Java

template<T> class Channel

A generic channel for sending and receiving data over a network connection to TStorage.

This class manages the lifecycle of a network connection and supports operations like get, put, puta, getAcq, and streaming data with getStream.

It is strongly recommended that the Channel be promptly closed if an error occurs.

Template Parameters:: T – The payload type for communication.

Public Functions

inline Channel(String host, int port, int timeout, PayloadType<T> payloadType, ByteOrder order)

Constructs a Channel with connection parameters.

Parameters:

host – The remote host.
port – The remote port.
timeout – Connection timeout in milliseconds.
payloadType – The payload type handler.
order – The byte order for communication.

Throws:

UnknownHostException – If the host is unknown.
IllegalArgumentException – If arguments are invalid.

inline ByteOrder getOrder()

Gets the current byte order.

Returns:: The byte order.

inline void setOrder(ByteOrder order)

Sets the byte order.

Parameters:: order – The byte order to use.

inline Response connect()

Opens the network connection.

Returns:: Response indicating success or failure.

inline Response close()

Closes the network connection.

Returns:: Response indicating success or failure.

inline ResponseGet<T> get(Key min, Key max, int responseBytesLimit)

Retrieves records within a key range.

Parameters:

min – The minimum key.
max – The maximum key.
responseBytesLimit – The byte limit of the TStorage response.

Throws:

IllegalArgumentException – If parameters are invalid.

Returns:

A ResponseGet containing the result or an error.

inline Response put(RecordsSet<T> data)

Sends records to TStorage using safe PUT.

Parameters:: data – The records to be sent.
Returns:: Response indicating success or failure.

inline Response puta(RecordsSet<T> data)

Sends records to TStorage using safe PUTA.

Parameters:: data – The records to be sent.
Returns:: Response indicating success or failure.

inline ResponseAcq getAcq(Key min, Key max)

Gets acquisition value within a key range.

Parameters:

min – Minimum key.
max – Maximum key.

Returns:

ResponseAcq containing result or error.

inline ResponseAcq getStream(Key min, Key max, int responseBytesLimit, Function<RecordsSet<T>, Void> callback)

Gets streaming data in chunks from TStorage with a callback on each chunk.

The chunk size is limited by responseBytesLimit. When this limit is reached, the callback is invoked with the current chunk. If the limit is too small to deliver even a single valid chunk, an error response is returned.

Parameters:

min – Minimum key.
max – Maximum key.
responseBytesLimit – Maximum size in bytes for each chunk (including protocol overhead).
callback – User-defined function called with each received chunk.

Returns:

ResponseAcq containing result or error.

Package Functions

inline Channel(__net_Connection connection, PayloadType<T> payloadType, ByteOrder order)

Constructs a Channel with an existing connection.

Parameters:

connection – The underlying network connection.
payloadType – The payload type handler.
order – The byte order for communication.

inline ResponseGet<T> get(__proto_GET<T> get, Key min, Key max)

Internal GET execution with provided protocol.

Parameters:

get – The GET protocol instance.
min – Minimum key.
max – Maximum key.

Returns:

The result of the operation.

inline Response put(__proto_PUTs<T> put, RecordsSet<T> data)

Internal PUT execution with provided protocol.

Parameters:

put – The PUT protocol instance.
data – The records to send.

Returns:

The result of the operation.

inline Response puta(__proto_PUTs<T> puta, RecordsSet<T> data)

Internal PUTA execution with provided protocol.

Parameters:

puta – The PUTA protocol instance.
data – The records to send.

Returns:

The result of the operation.

inline ResponseAcq getAcq(__proto_GETAcq getAcq, Key min, Key max)

Internal GETAcq execution with provided protocol.

Parameters:

getAcq – The acquisition protocol instance.
min – Minimum key.
max – Maximum key.

Returns:

The result of the operation.

inline ResponseAcq getStream(__proto_GETStream<T> getStream, Key min, Key max)

Internal GETStream execution with provided protocol.

Parameters:

getStream – The GETStream protocol instance.
min – Minimum key.
max – Maximum key.

Returns:

The result of the streaming operation.

Private Members

final __net_Connection connection

final PayloadType< T > payloadType

ByteOrder order

class Key

Represents a unique identifier used in TStorage addressing.

A Key consists of five components:

cid: Client ID
mid: Meter ID
moid: Meter Object ID
cap: Capture timestamp
acq: Acquisition timestamp

Note

The cid must be greater than or equal to 0.

class NotImplementedException : public RuntimeException

Package Functions

inline NotImplementedException()

template<T> interface PayloadType

Defines serialization and deserialization logic for a payload of type T.

This interface is used to convert objects of type T to and from byte arrays for transmission over a network or storage. Implementations must ensure that the conversion is reversible where applicable.

Template Parameters:: T – The type of the payload to be serialized/deserialized.

Public Functions

byte[] toBytes (T value)

Serializes a value of type T into a byte array.

Parameters:: value – The value to serialize.
Returns:: A byte array representing the serialized form of the value.

Optional< T > fromBytes (byte[] buffer)

Deserializes a byte array into a value of type T.

Parameters:: buffer – The byte array to deserialize.
Returns:: An Optional containing the deserialized value if successful, or empty if the input is invalid.

class Record

Represents a single data entry in TStorage, consisting of a key and a value.

Each Record contains:

A Key used for identifying and ordering the record.
A value of type T, which holds the actual payload.

Both key and value must be non-null.

Template Parameters:: T – The type of the value stored in the record.

template<T> interface RecordsSet

Represents a collection of records, each consisting of a Key and a value of type T.

Provides methods for appending records, iterating over them, and querying the size of the collection.

Template Parameters:: T – The type of values stored in the records.

Public Functions

void append(Key key, T value)

Appends a new record with the given key and value to the set.

Parameters:

key – The Key identifying the record. Must not be null.
value – The value associated with the key. Must not be null.

Throws:

NullPointerException – if key or value is null.

Iterable<Record<T>> iterator()

Returns an iterable over all records in the set.

Returns:: An Iterable of Record instances.

int size()

Returns the number of records in the set.

Returns:: The size of the set.

class Response

Represents the result of an operation, encapsulating a status.

Used as a base response type for various operations, indicating success, failure, or other outcome as represented by ResponseStatus.

Subclassed by ResponseAcq

Public Functions

inline ResponseStatus getStatus()

Returns the status of the response.

Returns:: The ResponseStatus associated with this response.

Package Functions

inline Response(ResponseStatus status)

Constructs a new Response with the specified status.

Parameters:: status – The ResponseStatus of the operation. Must not be null.
Throws:: NullPointerException – if the status is null.

Private Members

final ResponseStatus status: The status of the response.

class ResponseAcq : public Response 

Represents the result of an getAcq operation, including acquisition timestamp.

Extends Response by adding an acquisition timestamp (acq).

Subclassed by ResponseGet< T >

Public Functions

inline long getAcq()

Returns the acquisition timestamp.

Returns:

The acquisition time, or

INVALID_ACQ

if unavailable.

Package Functions

inline ResponseAcq(ResponseStatus status, long acq)

Constructs a new ResponseAcq with the given status and acquisition time.

Parameters:

status – The ResponseStatus of the operation.
acq – The acquisition timestamp. May be
```
INVALID_ACQ 
```
if invalid.

inline ResponseAcq(ResponseStatus status)

Constructs a new ResponseAcq with the given status and an invalid acquisition time.

Parameters:: status – The ResponseStatus of the operation.

Package Static Attributes

static final long INVALID_ACQ = -1L: Special constant indicating an invalid or unavailable acquisition time.

Private Members

final long acq: Acquisition timestamp returned by the operation.

template<T> class ResponseGet : public ResponseAcq 

Represents the result of a GET operation, including acquired records.

Extends ResponseAcq by including a RecordsSet containing the retrieved data. Even if the operation is successful, the data set may be empty.

Template Parameters:: T – The type of values stored in the returned records.

Public Functions

inline RecordsSet<T> getData()

Returns the data retrieved by the GET operation.

Note

An empty data set is a valid result for a successful operation. Use Response#getStatus() to determine if the operation was successful.

Returns:: The RecordsSet of data.

Package Functions

inline ResponseGet(ResponseStatus status, long acq, RecordsSet<T> data)

Constructs a new ResponseGet with the specified status, acquisition time, and data.

Parameters:

status – The ResponseStatus of the operation.
acq – The acquisition timestamp associated with the data.
data – The RecordsSet of retrieved data. Must not be null.

Throws:

NullPointerException – if

data

is null.

inline ResponseGet(ResponseStatus status)

Constructs a new ResponseGet with the specified status and no data.

The acquisition timestamp is set to

INVALID_ACQ

, and the data is not initialized.

Parameters:: status – The ResponseStatus of the operation.

Private Members

RecordsSet<T> data: The data retrieved by the GET operation.

enum ResponseStatus

Public Functions

inline ResponseStatus(int value)

Constructs a ResponseStatus with the specified integer value.

Parameters:: value – The integer value associated with the status.

Public Members

OK =(0): Operation completed successfully.

ERROR =(-1): General error occurred during the operation.

LIMIT_TOO_LOW =(1): The limit provided for the GET* operation is too low.

CONVERSION_ERROR =(-2): An error occurred during payload data conversion.

class Timestamp

Utility class for converting between custom TStorage-resolution timestamps and Unix time.

This class provides static methods to convert between a nanosecond-resolution timestamp based on the epoch starting at 2001-01-01 (used in TStorage) and the standard Unix epoch (1970-01-01T00:00:00Z). The conversion uses java.time.Instant.

All timestamps are represented as

long

values in nanoseconds.

Public Static Functions

static inline Instant toUnix(long timestamp)

Converts a custom nanosecond-based timestamp (since 2001-01-01) to Unix Instant.

Parameters:: timestamp – The timestamp in nanoseconds since 2001-01-01.
Returns:: An Instant representing the same point in time in the Unix epoch.

static inline long fromUnix(Instant timestamp)

Converts a Unix Instant to a nanosecond-based timestamp since 2001-01-01.

Parameters:

timestamp – The Instant to convert.

Returns:

The equivalent timestamp as a

long

in nanoseconds since 2001-01-01.

static inline long now()

Returns the current timestamp in nanoseconds since 2001-01-01.

Returns:

The current timestamp as a

long

value.

Package Static Attributes

static final long DIFF_2001_1970_s = 978307200: The difference in seconds between 2001-01-01 and 1970-01-01.

static final long BILLION = 1_000_000_000L: Constant representing one billion, used for nanosecond-to-second conversion.

namespace industries

namespace atende

namespace ts

namespace driver

Functions

record Key(int cid, long mid, int moid, long cap, long acq)

template<> record Record<T>(Key key, T value)

file Channel.java

file Key.java

file NotImplementedException.java

file PayloadType.java

file Record.java

file RecordsSet.java

file Response.java

file ResponseAcq.java

file ResponseGet.java

file ResponseStatus.java

file Timestamp.java

dir tstorage_clients/java/src/main/java/industries/atende

dir tstorage_clients/java/src/main/java/industries/atende/ts/driver

dir tstorage_clients/java/src/main/java/industries

dir tstorage_clients/java

dir tstorage_clients/java/src/main/java

dir tstorage_clients/java/src/main

dir tstorage_clients/java/src

dir tstorage_clients/java/src/main/java/industries/atende/ts

dir tstorage_clients