6.10. Java (Legacy API)¶

6.10.1. Introduction¶

Warning

You’re looking at our deprecated, legacy Java API

This documment is about our deprecated Java API that is for customers that were on our old, < 2.2.0 API. Please see our Java documentation.

This document is an introduction to the quasardb Java API.

You can see this code in action in this sample project: https://github.com/bureau14/qdb-api-java-example

6.10.2. Installation¶

The quasardb Java API is available in our Maven repositiory.

To use it in your project, you need to add the repository maven.quasardb.net

Then, you must add a dependency to net.quasardb:qdb

For example, if you’re using Maven, your pom.xml should look like:

<project>
[...]
<repositories>
<repository>
<id>quasardb</id>
<name>Quasardb Official Repository</name>
<url>http://maven.quasardb.net</url>
</repository>
</repositories>
<dependencies>
<dependency>
<groupId>net.quasardb</groupId>
<artifactId>qdb</artifactId>
<version>2.0.0rc5</version>
</dependency>
</dependencies>
</project>


Or, if you use Gradle, your build.gradle should look like:

apply plugin: 'java'

repositories {
maven {
url "http://maven.quasardb.net"
}
}

dependencies {
compile 'net.quasardb:qdb:2.0.0rc5'
}


6.10.3. Connecting to the database¶

You connect to a quasardb database by creating an instance of QdbCluster. The address of the clutser (the URI) must be given as an argument to the constructor.

For example, to connect to a quasardb node running on the local machine:

QdbCluster db = new QdbCluster("qdb://127.0.0.1:2836");


The constructor of QdbCluster will throw an exception if the connection cannot be established.

6.10.4. Manipulating “blobs”¶

Blob stands for Binary Large Object, it’s the term in quasardb for unstructured data. A blob is a finite sequence of bytes, of any size. In Java, a blob is materialized by an instance of java.nio.ByteBuffer.

To perform operations on a blob, you need to get an instance of QdbBlob like this:

QdbBlob blob = db.blob("name of the blob");


The String that is passed to QdbCluster.blob() is called the “alias” of the blob. It’s the identifier of the blob in the database and it must be unique. See aliases for more information.

Then, you can perform operations on the blob.

First, there is the put() operation, that creates a blob:

ByteBuffer someData = getSomeData();
blob.put(someData);


Then, there is the update() operation, which is exactly like put() excepts that it doesn’t throw if the entry already exists:

ByteBuffer someNewData = getSomeData();
blob.update(someData);


Reading the content of the blob is done by the get() operation:

try (QdbBuffer content = blob.get()) {
ByteBuffer someData = content.toByteBuffer();
// ...
}


As you see, QdbBlob.get() doesn’t return a ByteBuffer, but a QdbBuffer which implements AutoCloseable. You’ll find an entire section dedicated to QdbBuffer later in this document.

To delete the blob, you can call:

blob.remove();


We just saw the main four operations on blobs: put(), update(), get() and remove().

There are four other operations for blobs:

• compareAndSwap()
• getAndRemove()
• getAndUpdate()
• removeIf()

You’ll find the details in the Javadoc.

6.10.5. Manipulating “deques”¶

Deque stands for “double-ended queue”. There are queues that can be used in both directions: forward and backward.

A deque can be seen as a list of blob.

To perform operations on a deque, you need to get an instance of QdbDeque like this:

QdbDeque deque = db.deque("name of the deque");


As for the blob, the alias of the deque is passed to QdbCluster.deque().

To create a deque, you just need to enqueue an item.

For example, to enqueue at the end of the deque:

ByteBuffer someData = someData();
deque.pushBack(someData);


And to enqueue at the beginning of the deque:

ByteBuffer someData = someData();
deque.pushFront(someData);


Then, to dequeue an item from the beginning:

try (QdbBuffer content =  deque.popFront()) {
ByteBuffer someData = content.toByteBuffer();
// ...
}


or from the end:

try (QdbBuffer content = deque.popBack()) {
ByteBuffer someData = content.toByteBuffer();
// ...
}


These two methods extract the item from the deque and return the content in a QdbBuffer. You’ll find an entire section dedicated to QdbBuffer later in this document.

You can also read the content of the first or last item with out removing them from the deque:

QdbBuffer firstItem = deque.front();
QdbBuffer lastItem = deque.back();


It’s also possible to read any item of the deque by it’s position:

int index = getPosition();
QdbBuffer item = deque.get(index);


The position is a zero-based index, ie the first item is at index 0 and the last at index N-1.

If the position is negative, then the deque is read from the back, ie the last item is at index -1 and the first at -N-1.

As a consequence, QdbDeque.front() is equivalent to QdbDeque.get(0) and QdbDeque.back() is equivalent to QdbDeque.get(-1).

To known the actual number of item in the deque, call QdbDeque.size():

int numberOfItem = deque.size();


Lastly, you can delete a deque, just like a blob:

deque.remove();


6.10.6. Manipulating integers¶

Although it’s possible to store integer in blobs, it’s not very convenient. For that reason, quasardb has a dedicated type for storing 64-bit integers.

To perform operations on an integer, you need to get an instance of QdbInteger like this:

QdbInteger integer = db.integer("name of the integer");


As for blobs and deques, the alias of the integer is passed to QdbCluster.integer().

Just like blobs, integers support put(), update(), get() and remove() operations:

integer.put(10);
integer.update(20);
long value = integer.get();
integer.remove();


And there is a special function for performing atomic additions:

long result = integer.add(30);


QdbInteger.add() increments (or decrements if the argument is negative) the value in the database and returns the new value.

6.10.7. Manipulating tags¶

In quasardb, tags are strings that you can attach to entries. There are used as a kind of lightweight index.

To add a tag to an entry, just call QdbEntry.attachTag():

blob.attachTag("name of the tag");


A tag is also an entry, that you can manipulate through an instance of QdbTag:

QdbTag tag = db.tag("name of the tag");


From here, you can tag entries:

tag.addEntry("name of the blob");


which is exactly the same as calling QdbEntry.attachTag().

It was also possible to use the handles instead of the alias, like this:

tag.addEntry(blob);
blob.attachTag(tag);


All of these constructions are synonym.

Like adding a tag, there are four ways to remove a tag from an entry:

blob.detachTag("name of the tag");
blob.detachTag(tag);
tag.removeEntry("name of the blob");
tag.removeEntry(blob);


From a QdbTag, you can enumerate all tagged entries:

Iterable<QdbEntry> taggedEntries = tag.entries();


And, from a QdbEntry, you can enumerate all tags:

Iterable<QdbTag> tagsOfEntry = blob.tags();


Like any other entry, a tag can be tagged and be removed:

tag.attachTag("name of another tag");
tag.remove();


6.10.8. Manipulating streams¶

In quasardb, a stream is like a blob, except that it’s distributed and can grow indefinitely.

As for the other types of entry, you get a handle via the QdbCluster:

QdbStream stream = db.stream("name of the stream");


Then you can do the common things you do with other entries:

stream.attachTag("name of the tag");
stream.remove();


But when you want to write to the stream, you need to open it:

SeekableByteChannel channel = stream.open(QdbStream.Mode.Append);
channel.write(someByteBuffer);
channel.close();


Which, once again, should be used in a try-with-resource block:

try (SeekableByteChannel channel = stream.open(QdbStream.Mode.Append)) {
channel.write(someByteBuffer);
}


The mode QdbStream.Mode.Append allows to read and write to the stream. Only one client can open the stream in this mode at a given type. In other words, the write access to the stream is exclusive.

The SeekableByteChannel returned by open() allows to seek and truncate the stream.

In a similar fashion, you can open the stream in read-only mode:

try (SeekableByteChannel channel = stream.open(QdbStream.Mode.Read)) {
}


Except that there can be any number of clients reading the stream at the same time.

6.10.9. Batching operation¶

When manipulating a lot of small blobs, the network can become a bottleneck. To improve performance, quasardb allows to group operations together in a “batch”.

A batch is created from the QdbCluster:

QdbBatch batch = db.createBatch();


Then, you queue the operations, just like you did before:

batch.blob("name of the blob").put(someData);


For operations that returns a value, the return type is wrapped in a “future”:

QdbFuture<ByteBuffer> content = batch.blob("name of the blob").get();


A QdbFuture will contain the result of the operation, but only after running the batch:

batch.run();


To read the result of the future, just call QdbFuture.get():

ByteBuffer bb = content.get();


As you can see, the return value is a ByteBuffer, and not a QdbBuffer. This is because the memory is held by the QdbBatch, until close() is called. For this reason, it’s recommended to use a batch in a try-with-resource statement:

try (QdbBatch batch = db.createBatch()) {
batch.blob("blob1").put(contentOfBlob1);
QdbFuture<ByteBuffer> contentOfBlob2 = batch.blob("blob2").get();
batch.run();
doSomething(contentOfBlob2.get());
}


6.10.10. Why QdbBuffer instead of ByteBuffer?¶

Some operations return a buffer that is allocated in non-managed memory. This memory is out-side of the Java heap, and is not handled by the garbage collector.

QdbBuffer responsible for releasing this memory.

The memory is released by QdbBuffer.close():

QdbBuffer buffer = db.blob("name of the blob").get();
try {
ByteBuffer data = buffer.toByteBuffer();
}
finally {
buffer.close();
}


Or, better, by using the try-with-resource statement introduced in Java 7:

try (QdbBuffer buffer = db.blob("name of the blob").get()) {
ByteBuffer data = buffer.toByteBuffer();
}


If you don’t call QdbBuffer.close(), the memory will be released by the finalizer. However, this is a bad practice because you would waste a lot of memory and ultimately be out of memory. The best is to close the QdbBuffer as soon as possible.

Warning

ByteBuffer and QdbBuffer life spans

It’s very important that you never have a reference to the ByteBuffer with a longer life span than the QdbBuffer.

Indeed, if you don’t hold a reference to the QdbBuffer, the garbage collector might decide to destroy it, thereby releasing the non-managed memory.

As a result, ByteBuffer would point to invalid location in memory and your program would crash in an unpredictable manner.

So, in a nutshell:

1. don’t keep the result of QdbBuffer.toByteBuffer()
2. call QdbBuffer.close() as soon as possible

Aggregation¶

template <T>
class net::quasardb::qdb::QdbAggregation

Batch¶

class net::quasardb::qdb::QdbBatch

A batch containing a list of operation.

Batches are used to reduce the number of requests by performing several operations in one request.

Inherits from AutoCloseable

Public Functions

QdbBatchBlob net.quasardb.qdb.QdbBatch.blob(String alias)

Add blob operations to the batch.

A call to this method is usually followed by a call to an operation. For example:

QdbFuture<ByteBuffer> result = myBatch.blob("myBlob").get();


Return
A handle to a virtual blob on with to perform the operation.
Parameters
• alias: The alias of the blob you want to add operations for.
Exceptions
• BatchClosedException: If close() has been called.
• BatchAlreadyRunException: If the run() has been called.

void net.quasardb.qdb.QdbBatch.run()

Executes all operations in the batch.

A batch can only be run once. Once a batch is run, most method will throw a BatchAlreadyRunException.

Exceptions
• BatchClosedException: If close() has been called.
• BatchAlreadyRunException: If the run() has been called.

void net.quasardb.qdb.QdbBatch.close()

Release the memory allocated by quasardb.

Once this method has been called, most other methods will throw BatchClosedException.

boolean net.quasardb.qdb.QdbBatch.success()

Check if all operations executed successfully.

Return
true if all operations succeeded, false if any operation failed.
Exceptions
• BatchClosedException: If close() has been called.
• BatchNotRunException: If run() has not been called.

int net.quasardb.qdb.QdbBatch.operationCount()

Gets the total number of operations in the batch

Return
The number of operations that the batch contains.
Exceptions
• BatchClosedException: If close() has been called.

int net.quasardb.qdb.QdbBatch.successCount()

Gets the number of successful operations

Return
The number of successful operations
Exceptions
• BatchClosedException: If close() has been called.
• BatchNotRunException: If run() has not been called.

boolean net.quasardb.qdb.QdbBatch.isClosed()

Checks if close() has been called.

Return
true if batch has been closed, false if not

BatchBlob¶

class net::quasardb::qdb::QdbBatchBlob

Add blob operations in a batch.

Inherits from net.quasardb.qdb.QdbBatchEntry

Public Functions

QdbFuture<ByteBuffer> net.quasardb.qdb.QdbBatchBlob.compareAndSwap(ByteBuffer newContent, ByteBuffer comparand)

Adds a “compareAndSwap” operation to the batch: “Atomically compares the content of the blob and replaces it, if it matches.”

Return
A future that will contain the result of the operation after the batch is run.
See
QdbBlob::compareAndSwap(ByteBuffer, ByteBuffer)
Parameters
• newContent: The content to be updated to the server in case of match.
• comparand: The content to be compared to.

QdbFuture<ByteBuffer> net.quasardb.qdb.QdbBatchBlob.compareAndSwap(ByteBuffer newContent, ByteBuffer comparand, QdbExpiryTime expiryTime)

Adds a “compareAndSwap” operation to the batch: “Atomically compares the content of the blob and replaces it, if it matches.”“

Return
A future that will contain the result of the operation after the batch is run.
See
QdbBlob::compareAndSwap(ByteBuffer, ByteBuffer, QdbExpiryTime)
Parameters
• newContent: The content to be updated to the server, in case of match.
• comparand: The content to be compared to.
• expiryTime: The new expiry time of the blob, in case of match

QdbFuture<ByteBuffer> net.quasardb.qdb.QdbBatchBlob.get()

Adds a “get” operation to the batch: “Read the content of the blob.”

Return
A future that will contain the result of the operation after the batch is run.
See
QdbBlob::get()

QdbFuture<ByteBuffer> net.quasardb.qdb.QdbBatchBlob.getAndUpdate(ByteBuffer content)

Adds a “getAndUpdate” operation to the batch: “Atomically reads and replaces (in this order) the content of blob.”

Return
A future that will contain the result of the operation after the batch is run.
See
QdbBlob::getAndUpdate(ByteBuffer)
Parameters
• content: The content of the blob to be set, before being replaced.

QdbFuture<ByteBuffer> net.quasardb.qdb.QdbBatchBlob.getAndUpdate(ByteBuffer content, QdbExpiryTime expiryTime)

Adds a “getAndUpdate” operation to the batch: “Atomically reads and replaces (in this order) the content of blob.”

Return
A future that will contain the result of the operation after the batch is run.
See
QdbBlob::getAndUpdate(ByteBuffer,QdbExpiryTime)
Parameters
• content: The content of the blob to be set, before being replaced.
• expiryTime: The new expiry time of the blob.

QdbFuture<Void> net.quasardb.qdb.QdbBatchBlob.put(ByteBuffer content)

Adds a “put” operation to the batch: “Create a new blob with the specified content. Fails if the blob already exists.”

Return
A future that will contain the result of the operation after the batch is run.
See
QdbBlob::put(ByteBuffer)
Parameters
• content: The content of the blob to be created.

QdbFuture<Void> net.quasardb.qdb.QdbBatchBlob.put(ByteBuffer content, QdbExpiryTime expiryTime)

Adds a “put” operation to the batch: “Create a new blob with the specified content. Fails if the blob already exists.”

Return
A future that will contain the result of the operation after the batch is run.
See
QdbBlob::put(ByteBuffer,QdbExpiryTime)
Parameters
• content: The content of the blob to be created.
• expiryTime: The expiry time of the blob.

QdbFuture<Void> net.quasardb.qdb.QdbBatchBlob.update(ByteBuffer content)

Adds an “update” operation to the batch: “Replaces the content of the blob.”

Return
A future that will contain the result of the operation after the batch is run.
See
QdbBlob::update(ByteBuffer)
Parameters
• content: The content of the blob to be set.

QdbFuture<Void> net.quasardb.qdb.QdbBatchBlob.update(ByteBuffer content, QdbExpiryTime expiryTime)

Adds an “update” operation to the batch: “Replaces the content of the blob.”

Return
A future that will contain the result of the operation after the batch is run.
See
QdbBlob::update(ByteBuffer,QdbExpiryTime)
Parameters
• content: The content of the blob to be set.
• expiryTime: The new expiry time of the blob.

BatchEntry¶

class net::quasardb::qdb::QdbBatchEntry

Subclassed by net.quasardb.qdb.QdbBatchBlob

BatchFuture¶

template <T>
class net::quasardb::qdb::QdbBatchFuture

Inherits from net::quasardb::qdb::QdbFuture< T >

BatchOperation¶

class net::quasardb::qdb::QdbBatchOperation

Cluster¶

class net::quasardb::qdb::QdbCluster

A connection to a quasardb cluster.

Inherits from AutoCloseable

Public Functions

net.quasardb.qdb.QdbCluster.QdbCluster(String uri)

Connects to a quasardb cluster through the specified URI. Requires security settings to be disabled. The URI contains the addresses of the bootstrapping nodes, other nodes are discovered during the first connection. Having more than one node in the URI allows to connect to the cluster even if the first node is down.

Parameters
• uri: a string in the form of qdb://<address1>:<port1>[,<address2>:<port2>...]
Exceptions
• ConnectionRefusedException: If the connection to the cluster is refused.
• InvalidArgumentException: If the syntax of the URI is incorrect.

net.quasardb.qdb.QdbCluster.QdbCluster(String uri, Session.SecurityOptions securityOptions)

Connects to a quasardb secure cluster through the specified URI. The URI contains the addresses of the bootstrapping nodes, other nodes are discovered during the first connection. Having more than one node in the URI allows to connect to the cluster even if the first node is down.

Parameters
• uri: a string in the form of qdb://<address1>:<port1>[,<address2>:<port2>...]
• securityOptions: An instance of QdbCluster.SecurityOptions for authentication.
Exceptions
• ConnectionRefusedException: If the connection to the cluster is refused.
• InvalidArgumentException: If the syntax of the URI is incorrect.

void net.quasardb.qdb.QdbCluster.close()

Closes the connection to the cluster.

Session net.quasardb.qdb.QdbCluster.getSession()

Returns the active Session.

boolean net.quasardb.qdb.QdbCluster.isLegacySessionInitialised()

Returns true if a the legacy session object is initialised and in used by other objects.

QdbBlob net.quasardb.qdb.QdbCluster.blob(String alias)

Gets a handle to a blob in the database.

Return
A handle to perform operations on the blob.
Parameters
• alias: The entry unique key/identifier in the database.
Exceptions

QdbDeque net.quasardb.qdb.QdbCluster.deque(String alias)

Gets a handle to a deque (double-ended queue) in the database.

Return
A handle to perform operations on the deque.
Parameters
• alias: The entry unique key/identifier in the database.
Exceptions

QdbEntry net.quasardb.qdb.QdbCluster.entry(String alias)

Gets a handle to an entry in the database, the entry must exist.

Return
A subclass of QdbEntry depending on the type of entry currently in the database.
Parameters
• alias: The entry unique key/identifier in the database.
Exceptions
• AliasNotFoundException: If the entry does not exist.
• ClusterClosedException: If QdbCluster.close() has been called.

QdbInteger net.quasardb.qdb.QdbCluster.integer(String alias)

Gets a handle to an integer in the database.

Return
A handle to perform operations on the integer.
Parameters
• alias: The entry unique key/identifier in the database.
Exceptions

QdbNode net.quasardb.qdb.QdbCluster.node(String uri)

Gets a handle to a node (i.e. a server) in the cluster.

Return
The node
Parameters
• uri: The URI of the node, in the form qdb://10.0.0.1:2836
Exceptions

QdbStream net.quasardb.qdb.QdbCluster.stream(String alias)

Gets a handle to a stream in the database.

Return
A handle to perform operations on the stream.
Parameters
• alias: The entry unique key/identifier in the database.
Exceptions

QdbTag net.quasardb.qdb.QdbCluster.tag(String alias)

Get a handle to a tag to in the database

Return
A handle to perform operations on the tag.
Parameters
• alias: The entry unique key/identifier in the database.
Exceptions

QdbTimeSeries net.quasardb.qdb.QdbCluster.timeSeries(String alias)

Gets a handle to a timeseries in the database.

Return
A handle to perform operations on the timeseries.
Parameters
• alias: The timeseries unique key/identifier in the database.
Exceptions

QdbTimeSeries net.quasardb.qdb.QdbCluster.createTimeSeries(String alias, long shardSize, Column[] columns)

Gets creates a new timeseries in the database and returns handle.

Return
A handle to perform operations on the timeseries.
Parameters
• alias: The timeseries unique key/identifier in the database.
Exceptions

QdbNode net.quasardb.qdb.QdbCluster.findNodeFor(String alias)

Retrieve the location for a provided alias.

Return
the location, i.e. node’s address and port, on which the entry with the provided alias is stored.
Parameters
• alias: The entry unique key/identifier in the database.
Exceptions

void net.quasardb.qdb.QdbCluster.purgeAll(int timeoutMillis)

Remove all data from the cluster.

Parameters
• timeoutMillis: The timeout of the operation, in milliseconds
Exceptions
• ClusterClosedException: If QdbCluster.close() has been called.
• OperationDisabledException: If the operation has been disabled on the server.

void net.quasardb.qdb.QdbCluster.trimAll(int timeoutMillis)

Trim data from the cluster, that is, remove dead references and old versions.

Parameters
• timeoutMillis: The timeout of the operation, in milliseconds
Exceptions

QdbBatch net.quasardb.qdb.QdbCluster.createBatch()

Create an empty batch.

Return
An empty batch.

void net.quasardb.qdb.QdbCluster.setTimeout(int timeoutMillis)

Set network timeout for this client.

Parameters
• timeoutMillis: The timeout of the operation, in milliseconds
Exceptions

Public Static Functions

static String net.quasardb.qdb.QdbCluster.build()

Retrieve the build version of the quasardb API

Return
build version of the quasardb API

static String net.quasardb.qdb.QdbCluster.version()

Retrieve the version of the quasardb API

Return
The version of the quasardb API.

Blobs¶

class net::quasardb::qdb::QdbBlob

A blob in the database. Blob stands for “Binary Large Object”, it’s an entry which store binary data.

Inherits from net.quasardb.qdb.QdbExpirableEntry

Public Functions

Buffer net.quasardb.qdb.QdbBlob.compareAndSwap(ByteBuffer newContent, ByteBuffer comparand)

Atomically compares the content of the blob and replaces it, if it matches.

Return
Returns The original content if comparand doesn’t match. Returns null otherwise.
Parameters
• newContent: The content to be updated to the server in case of match.
• comparand: The content to be compared to.
Exceptions
• AliasNotFoundException: If an entry matching the provided alias cannot be found.
• ClusterClosedException: If QdbCluster.close() has been called.
• IncompatibleTypeException: If the alias has a type incompatible for this operation.
• ReservedAliasException: If the alias name or prefix is reserved for quasardb internal use.

Buffer net.quasardb.qdb.QdbBlob.compareAndSwap(ByteBuffer newContent, ByteBuffer comparand, QdbExpiryTime expiryTime)

Atomically compares the content of the blob and replaces it, if it matches.

Return
Returns The original content if comparand doesn’t match. Returns null otherwise.
Parameters
• newContent: The content to be updated to the server, in case of match.
• comparand: The content to be compared to.
• expiryTime: The new expiry time of the blob, in case of match
Exceptions
• AliasNotFoundException: If an entry matching the provided alias cannot be found.
• ClusterClosedException: If QdbCluster.close() has been called.
• IncompatibleTypeException: If the alias has a type incompatible for this operation.
• InvalidArgumentException: If the expiry time is in the past (with a certain tolerance)
• ReservedAliasException: If the alias name or prefix is reserved for quasardb internal use.

Buffer net.quasardb.qdb.QdbBlob.get()

Read the content of the blob.

Return
The current content.
Exceptions
• AliasNotFoundException: If an entry matching the provided alias cannot be found.
• IncompatibleTypeException: If the alias has a type incompatible for this operation.
• ReservedAliasException: If the alias name or prefix is reserved for quasardb internal use.

Buffer net.quasardb.qdb.QdbBlob.getAndRemove()

Atomically reads the content of the blob and removes it.

Return
The content of the blob, before being removed.
Exceptions
• AliasNotFoundException: If an entry matching the provided alias cannot be found.
• ClusterClosedException: If QdbCluster.close() has been called.
• IncompatibleTypeException: If the alias has a type incompatible for this operation.
• ReservedAliasException: If the alias name or prefix is reserved for quasardb internal use.

Buffer net.quasardb.qdb.QdbBlob.getAndUpdate(ByteBuffer content)

Atomically reads and replaces (in this order) the content of blob.

Return
A buffer representing the content of the blob, before the update.
Parameters
• content: The content of the blob to be set, before being replaced.
Exceptions
• AliasNotFoundException: If an entry matching the provided alias cannot be found.
• ClusterClosedException: If QdbCluster.close() has been called.
• IncompatibleTypeException: If the alias has a type incompatible for this operation.
• ReservedAliasException: If the alias name or prefix is reserved for quasardb internal use.

Buffer net.quasardb.qdb.QdbBlob.getAndUpdate(ByteBuffer content, QdbExpiryTime expiryTime)

Atomically reads and replaces (in this order) the content of blob.

Return
The content of the blob to be set, before being replaced.
Parameters
• content: The content of the blob to be set, before being replaced.
• expiryTime: The new expiry time of the blob.
Exceptions
• AliasNotFoundException: If an entry matching the provided alias cannot be found.
• ClusterClosedException: If QdbCluster.close() has been called.
• IncompatibleTypeException: If the alias has a type incompatible for this operation.
• InvalidArgumentException: If the expiry time is in the past (with a certain tolerance)
• ReservedAliasException: If the alias name or prefix is reserved for quasardb internal use.

void net.quasardb.qdb.QdbBlob.put(ByteBuffer content)

Create a new blob with the specified content. Fails if the blob already exists.

Parameters
• content: The content of the blob to be created.
Exceptions
• AliasAlreadyExistsException: If an entry matching the provided alias already exists.
• ClusterClosedException: If QdbCluster.close() has been called.
• ReservedAliasException: If the alias name or prefix is reserved for quasardb internal use.

void net.quasardb.qdb.QdbBlob.put(ByteBuffer content, QdbExpiryTime expiryTime)

Create a new blob with the specified content. Fails if the blob already exists.

Parameters
• content: The content of the blob to be created.
• expiryTime: The expiry time of the blob.
Exceptions
• AliasAlreadyExistsException: If an entry matching the provided alias already exists.
• ClusterClosedException: If QdbCluster.close() has been called.
• InvalidArgumentException: If the expiry time is in the past (with a certain tolerance)
• ReservedAliasException: If the alias name or prefix is reserved for quasardb internal use.

boolean net.quasardb.qdb.QdbBlob.removeIf(ByteBuffer comparand)

Removes the blob if its content matches comparand.

Return
true if the blob was actually removed, false if not.
Parameters
• comparand: The content to be compared to.
Exceptions
• AliasNotFoundException: If an entry matching the provided alias cannot be found.
• ClusterClosedException: If QdbCluster.close() has been called.
• IncompatibleTypeException: If the alias has a type incompatible for this operation.
• ReservedAliasException: If the alias name or prefix is reserved for quasardb internal use.

boolean net.quasardb.qdb.QdbBlob.update(ByteBuffer content)

Replaces the content of the blob.

Return
true if the blob was created, or false it it was updated.
Parameters
• content: The content of the blob to be set.
Exceptions
• ClusterClosedException: If QdbCluster.close() has been called.
• IncompatibleTypeException: If the alias has a type incompatible for this operation.
• ReservedAliasException: If the alias name or prefix is reserved for quasardb internal use.

boolean net.quasardb.qdb.QdbBlob.update(ByteBuffer content, QdbExpiryTime expiryTime)

Replaces the content of the blob.

Return
true if the blob was created, or false it it was updated.
Parameters
• content: The content of the blob to be set.
• expiryTime: The new expiry time of the blob.
Exceptions
• ClusterClosedException: If QdbCluster.close() has been called.
• IncompatibleTypeException: If the alias has a type incompatible for this operation.
• InvalidArgumentException: If the expiry time is in the past (with a certain tolerance)
• ReservedAliasException: If the alias name or prefix is reserved for quasardb internal use.

BlobAggregation¶

class net::quasardb::qdb::QdbBlobAggregation

BlobAggregationCollection¶

class net::quasardb::qdb::QdbBlobAggregationCollection

Inherits from java::util::ArrayList< QdbBlobAggregation >

Blob Column Collection¶

class net::quasardb::qdb::QdbBlobColumnCollection

Blob Column Value¶

class net::quasardb::qdb::QdbBlobColumnValue

Inherits from net.quasardb.qdb.QdbColumnValue< ByteBuffer >

Column Collection¶

template <T>
class net::quasardb::qdb::QdbColumnCollection

Inherits from java::util::ArrayList< T >

Public Functions

TimeRange net.quasardb.qdb.QdbColumnCollection< T extends QdbColumnValue >.range()

Returns the interval that contains all values within this column.

Column Definition¶

class net::quasardb::qdb::ts::Column

Holds information about a single column.

Public Functions

net.quasardb.qdb.ts.Column.Column(String name, Value.Type type)

Create a column with a certain type.

String net.quasardb.qdb.ts.Column.getName()

Value.Type net.quasardb.qdb.ts.Column.getType()

class Blob

A blob column.

Inherits from net.quasardb.qdb.ts.Column

class Double

A double precision column.

Inherits from net.quasardb.qdb.ts.Column

class Int64

A 64 bit integer column.

Inherits from net.quasardb.qdb.ts.Column

class Timestamp

A timestamp column.

Inherits from net.quasardb.qdb.ts.Column

Column Value¶

template <T>
class net::quasardb::qdb::QdbColumnValue

Inherits from Serializable

Deque¶

class net::quasardb::qdb::QdbDeque

A deque in the database. Deque stands for “double-ended queue”, you can both enqueue and dequeue from the front and the back.

Inherits from net.quasardb.qdb.QdbEntry

Public Functions

Buffer net.quasardb.qdb.QdbDeque.back()

Retrieves the item at the back of the queue. The queue must already exist.

Return
The content of the item, or null if the deque was empty.
Exceptions
• AliasNotFoundException: If an entry matching the provided alias cannot be found.
• ClusterClosedException: If QdbCluster.close() has been called.
• IncompatibleTypeException: If the alias has a type incompatible for this operation.
• ReservedAliasException: If the alias name or prefix is reserved for quasardb internal use.

Buffer net.quasardb.qdb.QdbDeque.get(long index)

Retrieves the value of the queue at the specified index. The queue must already exist.

Return
The content of the item.
Parameters
• index: The zero-based index you wish to retrieve.
Exceptions
• AliasNotFoundException: If an entry matching the provided alias cannot be found.
• ClusterClosedException: If QdbCluster.close() has been called.
• IncompatibleTypeException: If the alias has a type incompatible for this operation.
• OutOfBoundsException: If the index is negative, or greater or equal than deque size.
• ReservedAliasException: If the alias name or prefix is reserved for quasardb internal use.

Buffer net.quasardb.qdb.QdbDeque.front()

Retrieves the item at the front of the queue. The queue must already exist.

Return
The content of the item, or null if the deque was empty.
Exceptions
• AliasNotFoundException: If an entry matching the provided alias cannot be found.
• ClusterClosedException: If QdbCluster.close() has been called.
• IncompatibleTypeException: If the alias has a type incompatible for this operation.
• ReservedAliasException: If the alias name or prefix is reserved for quasardb internal use.

Buffer net.quasardb.qdb.QdbDeque.popBack()

Removes and retrieves the item at the back of the queue. The queue must already exist.

Return
The content of the removed item, or null if the deque was empty.
Exceptions
• AliasNotFoundException: If an entry matching the provided alias cannot be found.
• ClusterClosedException: If QdbCluster.close() has been called.
• IncompatibleTypeException: If the alias has a type incompatible for this operation.
• ReservedAliasException: If the alias name or prefix is reserved for quasardb internal use.

Buffer net.quasardb.qdb.QdbDeque.popFront()

Removes and retrieves the item at the front of the queue. The queue must already exist.

Return
The content of the removed item, or null if the deque was empty.
Exceptions
• AliasNotFoundException: If an entry matching the provided alias cannot be found.
• ClusterClosedException: If QdbCluster.close() has been called.
• IncompatibleTypeException: If the alias has a type incompatible for this operation.
• ReservedAliasException: If the alias name or prefix is reserved for quasardb internal use.

void net.quasardb.qdb.QdbDeque.pushBack(ByteBuffer content)

Inserts the content at the back of the queue. Creates the queue if it does not exist.

Parameters
• content: The content that will be added to the queue.
Exceptions
• ClusterClosedException: If QdbCluster.close() has been called.
• IncompatibleTypeException: If the alias has a type incompatible for this operation.
• ReservedAliasException: If the alias name or prefix is reserved for quasardb internal use.

void net.quasardb.qdb.QdbDeque.pushFront(ByteBuffer content)

Inserts the content at the front of the queue. Creates the queue if it does not exist.

Parameters
• content: The content that will be added to the queue.
Exceptions
• ClusterClosedException: If QdbCluster.close() has been called.
• IncompatibleTypeException: If the alias has a type incompatible for this operation.
• ReservedAliasException: If the alias name or prefix is reserved for quasardb internal use.

long net.quasardb.qdb.QdbDeque.size()

Retrieves the size of the queue. The queue must already exist.

Return
The number of items in the deque.
Exceptions
• AliasNotFoundException: If an entry matching the provided alias cannot be found.
• ClusterClosedException: If QdbCluster.close() has been called.
• IncompatibleTypeException: If the alias has a type incompatible for this operation.
• ReservedAliasException: If the alias name or prefix is reserved for quasardb internal use.

Double Aggregation¶

class net::quasardb::qdb::QdbDoubleAggregation

Double Aggregation Collection¶

class net::quasardb::qdb::QdbDoubleAggregationCollection

Inherits from java::util::ArrayList< QdbDoubleAggregation >

Double Column Collection¶

class net::quasardb::qdb::QdbDoubleColumnCollection

Double Column Value¶

class net::quasardb::qdb::QdbDoubleColumnValue

Inherits from net.quasardb.qdb.QdbColumnValue< Double >

Entry¶

class net::quasardb::qdb::QdbEntry

An entry in the database.

Public Functions

String net.quasardb.qdb.QdbEntry.alias()

Gets the alias (i.e. its “key”) of the entry in the database.

Return
The alias.

boolean net.quasardb.qdb.QdbEntry.attachTag(QdbTag tag)

Attaches a tag to the entry. The tag is created if it does not exist.

Return
true if the tag has been attached, false if it was already attached
Parameters
• tag: The tag to attach.
Exceptions
• AliasNotFoundException: If an entry matching the provided alias cannot be found.
• ClusterClosedException: If QdbCluster.close() has been called.
• ReservedAliasException: If the alias name or prefix is reserved for quasardb internal use.

boolean net.quasardb.qdb.QdbEntry.attachTag(String tag)

Attaches a tag to the entry. The tag is created if it does not exist.

Return
true if the tag has been attached, false if it was already attached
Parameters
• tag: The alias of the tag to attach.
Exceptions
• AliasNotFoundException: If an entry matching the provided alias cannot be found.
• ClusterClosedException: If QdbCluster.close() has been called.
• ReservedAliasException: If the alias name or prefix is reserved for quasardb internal use.

boolean net.quasardb.qdb.QdbEntry.equals(Object obj)

Checks if a QdbEntry points to the same entry in the database.

Return
true if entry type and alias are equals, false otherwise

boolean net.quasardb.qdb.QdbEntry.equals(QdbEntry entry)

Checks if a QdbEntry points to the same entry in the database.

Return
true if entry type and alias are equals, false otherwise.
Parameters
• entry: An entry to compare to.

int net.quasardb.qdb.QdbEntry.hashCode()

Gets alias hash code.

Return
A hash-code based on the entry alias.

boolean net.quasardb.qdb.QdbEntry.hasTag(QdbTag tag)

Checks if a tag is attached to the entry.

Return
true if the entry has the provided tag, false otherwise
Parameters
• tag: The tag to check
Exceptions
• AliasNotFoundException: If an entry matching the provided alias cannot be found.
• ClusterClosedException: If QdbCluster.close() has been called.
• ReservedAliasException: If the alias name or prefix is reserved for quasardb internal use.

boolean net.quasardb.qdb.QdbEntry.hasTag(String tag)

Checks if a tag is attached to the entry.

Return
true if the entry has the provided tag, false otherwise
Parameters
• tag: The alias to the tag to check.
Exceptions
• AliasNotFoundException: If an entry matching the provided alias cannot be found.
• ClusterClosedException: If QdbCluster.close() has been called.
• ReservedAliasException: If the alias name or prefix is reserved for quasardb internal use.

void net.quasardb.qdb.QdbEntry.remove()

Removes the entry from the database.

Exceptions
• AliasNotFoundException: If an entry matching the provided alias cannot be found.
• ClusterClosedException: If QdbCluster.close() has been called.
• ReservedAliasException: If the alias name or prefix is reserved for quasardb internal use.

boolean net.quasardb.qdb.QdbEntry.detachTag(QdbTag tag)

Detaches a tag from the entry.

Return
true if the tag has been detached, false if the tag was not attached
Parameters
• tag: The tag to detach.
Exceptions
• AliasNotFoundException: If an entry matching the provided alias cannot be found.
• ClusterClosedException: If QdbCluster.close() has been called.
• ReservedAliasException: If the alias name or prefix is reserved for quasardb internal use.

boolean net.quasardb.qdb.QdbEntry.detachTag(String tag)

Detaches a tag from the entry.

Return
true if the tag has been detached, false if the tag was not attached
Parameters
• tag: The alias of the tag to detach.
Exceptions
• AliasNotFoundException: If an entry matching the provided alias cannot be found.
• ClusterClosedException: If QdbCluster.close() has been called.
• ReservedAliasException: If the alias name or prefix is reserved for quasardb internal use.

Iterable<QdbTag> net.quasardb.qdb.QdbEntry.tags()

Retrieves the tags attached to the entry.

Return
The tags attached to the entry.
Exceptions
• AliasNotFoundException: If an entry matching the provided alias cannot be found.
• ClusterClosedException: If QdbCluster.close() has been called.

Entry Factory¶

class net::quasardb::qdb::QdbEntryFactory

class net::quasardb::qdb::QdbEntryMetadata

Entry Tags¶

class net::quasardb::qdb::QdbEntryTags

Inherits from Iterable< QdbTag >

Expirable Entry¶

class net::quasardb::qdb::QdbExpirableEntry

An entry that has the ability to expire.

Inherits from net.quasardb.qdb.QdbEntry

Subclassed by net.quasardb.qdb.QdbBlob, net.quasardb.qdb.QdbInteger

Public Functions

void net.quasardb.qdb.QdbExpirableEntry.expiryTime(QdbExpiryTime expiryTime)

Sets the expiry time of an existing entry.

Parameters
• expiryTime: The new expiry time of the entry.
Exceptions
• AliasNotFoundException: If the entry does not exist.
• ClusterClosedException: If QdbCluster.close() has been called.
• InvalidArgumentException: If the expiry time is in the past (with a certain tolerance)

QdbExpiryTime net.quasardb.qdb.QdbExpirableEntry.expiryTime()

Retrieves the expiry time of the entry. A value of zero means the entry never expires.

Return
The expiry time of the entry.
Exceptions
• AliasNotFoundException: If the entry does not exist.
• ClusterClosedException: If QdbCluster.close() has been called.

Expiry Time¶

class net::quasardb::qdb::QdbExpiryTime

Id¶

class net::quasardb::qdb::QdbId

Integer¶

class net::quasardb::qdb::QdbInteger

A signed 64-bit integer in the database.

Inherits from net.quasardb.qdb.QdbExpirableEntry

Public Functions

long net.quasardb.qdb.QdbInteger.add(long delta)

Atomically adds the given value to the current value.

Return
The resulting value after the operation.
Parameters
• delta: The increment to add to the current value.
Exceptions
• AliasNotFoundException: If an entry matching the provided alias cannot be found.
• ClusterClosedException: If QdbCluster.close() has been called.
• IncompatibleTypeException: If the alias has a type incompatible for this operation.
• ReservedAliasException: If the alias name or prefix is reserved for quasardb internal use.

long net.quasardb.qdb.QdbInteger.get()

Reads the current value of the integer.

Return
The current value
Exceptions
• AliasNotFoundException: If an entry matching the provided alias cannot be found.
• ClusterClosedException: If QdbCluster.close() has been called.
• IncompatibleTypeException: If the alias has a type incompatible for this operation.
• ReservedAliasException: If the alias name or prefix is reserved for quasardb internal use.

void net.quasardb.qdb.QdbInteger.put(long initialValue)

Creates a new integer. Errors if the integer already exists.

Parameters
• initialValue: The value of the new integer.
Exceptions
• AliasAlreadyExistsException: If an entry matching the provided alias already exists.
• ClusterClosedException: If QdbCluster.close() has been called.
• ReservedAliasException: If the alias name or prefix is reserved for quasardb internal use.

void net.quasardb.qdb.QdbInteger.put(long initialValue, QdbExpiryTime expiryTime)

Creates a new integer. Errors if the integer already exists.

Parameters
• initialValue: The value of the new integer.
• expiryTime: The expiry time of the entry.
Exceptions
• AliasAlreadyExistsException: If an entry matching the provided alias already exists.
• ClusterClosedException: If QdbCluster.close() has been called.
• ReservedAliasException: If the alias name or prefix is reserved for quasardb internal use.

boolean net.quasardb.qdb.QdbInteger.update(long newValue)

Updates an existing integer or creates one if it does not exist.

Return
true if the integer was created, or false it it was updated.
Parameters
• newValue: The new value of the integer.
Exceptions
• ClusterClosedException: If QdbCluster.close() has been called.
• IncompatibleTypeException: If the alias has a type incompatible for this operation.
• ReservedAliasException: If the alias name or prefix is reserved for quasardb internal use.

boolean net.quasardb.qdb.QdbInteger.update(long newValue, QdbExpiryTime expiryTime)

Updates an existing integer or creates one if it does not exist.

Return
true if the integer was created, or false it it was updated.
Parameters
• newValue: The new value of the integer.
• expiryTime: The expiry time of the entry.
Exceptions
• ClusterClosedException: If QdbCluster.close() has been called.
• IncompatibleTypeException: If the alias has a type incompatible for this operation.
• ReservedAliasException: If the alias name or prefix is reserved for quasardb internal use.

Node¶

class net::quasardb::qdb::QdbNode

A node in the quasardb cluster.

Public Functions

String net.quasardb.qdb.QdbNode.hostName()

Get the hostname of the node.

Return
the hostname of the quasardb node

int net.quasardb.qdb.QdbNode.port()

Get the port of the node.

Return
the port of the quasardb node

String net.quasardb.qdb.QdbNode.config()

Retrieve the configuration node.

Return
A JSON string containing the configuration of the node.
Exceptions

String net.quasardb.qdb.QdbNode.status()

Retrieve the status of the node.

Return
A JSON string containing the status of the node.
Exceptions

void net.quasardb.qdb.QdbNode.stop(String reason)

Shutdown the node.

Parameters
• reason: A message that will be logged as the reason for the shutdown.

String net.quasardb.qdb.QdbNode.topology()

Retrieve the topology of the node.

Return
A JSON string containing the topology of the node.
Exceptions

Stream¶

class net::quasardb::qdb::QdbStream

Represents a stream in a quasardb database.

Inherits from net.quasardb.qdb.QdbEntry

Public Functions

SeekableByteChannel net.quasardb.qdb.QdbStream.open(Mode mode)

Opens a ByteChannel for the stream.

Return
A SeekableByteChannel
Parameters
• mode: How to open the stream: READ or APPEND
Exceptions

Stream Channel¶

class net::quasardb::qdb::QdbStreamChannel

Inherits from SeekableByteChannel

Tag¶

class net::quasardb::qdb::QdbTag

Represents a tag in a quasardb database.

Inherits from net.quasardb.qdb.QdbEntry

Public Functions

boolean net.quasardb.qdb.QdbTag.attachEntry(QdbEntry entry)

Attaches the tag to an entry. The tag is created if it does not exist.

Return
true if the tag has been attached, false if it was already attached
Parameters
• entry: The entry to attach.
Exceptions
• AliasNotFoundException: If an entry matching the provided alias cannot be found.
• ClusterClosedException: If QdbCluster.close() has been called.
• ReservedAliasException: If the alias name or prefix is reserved for quasardb internal use.

boolean net.quasardb.qdb.QdbTag.attachEntry(String entry)

Attaches the tag to an entry. The tag is created if it does not exist.

Return
true if the tag has been attached, false if it was already attached
Parameters
• entry: The alias of the entry to attach.
Exceptions
• AliasNotFoundException: If an entry matching the provided alias cannot be found.
• ClusterClosedException: If QdbCluster.close() has been called.
• ReservedAliasException: If the alias name or prefix is reserved for quasardb internal use.

Iterable<QdbEntry> net.quasardb.qdb.QdbTag.entries()

Gets the entries tagged with this tag.

Return
A collection of subclasses of QdbEntry, whose types depends on the actual type of the entries in the database.
Exceptions

boolean net.quasardb.qdb.QdbTag.detachEntry(QdbEntry entry)

Detaches the tag from an entry.

Return
true if the tag has been detached, false if the tag was not attached
Parameters
• entry: The entry to detach.
Exceptions
• AliasNotFoundException: If an entry matching the provided alias cannot be found.
• ClusterClosedException: If QdbCluster.close() has been called.
• ReservedAliasException: If the alias name or prefix is reserved for quasardb internal use.

boolean net.quasardb.qdb.QdbTag.detachEntry(String entry)

Detaches the tag from an entry.

Return
true if the tag has been detached, false if the tag was not attached
Parameters
• entry: The alias of the entry to detach.
Exceptions
• AliasNotFoundException: If an entry matching the provided alias cannot be found.
• ClusterClosedException: If QdbCluster.close() has been called.
• ReservedAliasException: If the alias name or prefix is reserved for quasardb internal use.

Tag Entries¶

class net::quasardb::qdb::QdbTagEntries

Inherits from Iterable< QdbEntry >

Time Series¶

class net::quasardb::qdb::QdbTimeSeries

Legacy interface to QdbTimeSeries, which provides legacy compatibility functions.

Public Functions

void net.quasardb.qdb.QdbTimeSeries.create(long millisecondsShardSize, Column[] columns)

Create new timeseries table with a collection of columns.

Writer net.quasardb.qdb.QdbTimeSeries.tableWriter()

Initializes new timeseries table writer.

Table writer should be periodically flushed by invoking the .flush() method, or create a new table writer using autoFlushTableWriter() instead.

AutoFlushWriter net.quasardb.qdb.QdbTimeSeries.autoFlushTableWriter()

Initializes new timeseries table writer with auto-flush enabled.

AutoFlushWriter net.quasardb.qdb.QdbTimeSeries.autoFlushTableWriter(long threshold)

Initializes new timeseries table writer with auto-flush enabled.

Parameters
• threshold: The amount of rows to keep in local buffer before automatic flushing occurs.

Reader net.quasardb.qdb.QdbTimeSeries.tableReader(TimeRange[] ranges)

QdbDoubleColumnCollection net.quasardb.qdb.QdbTimeSeries.getDoubles(String column, TimeRange[] ranges)

QdbBlobColumnCollection net.quasardb.qdb.QdbTimeSeries.getBlobs(String column, TimeRange[] ranges)

6.10.12. Appendix A: entry class hierarchy¶

• QdbEntry
• QdbDeque
• QdbExpirableEntry
• QdbBlob
• QdbInteger
• QdbStream
• QdbTag

6.10.13. Appendix B: exception class hierarchy¶

• RuntimeException
• QdbException
• QdbConnectionException
• QdbConnectionRefusedException
• QdbHostNotFoundException
• QdbInputException
• QdbInvalidArgumentException
• QdbOutOfBoundsException
• QdbReservedException
• QdbOperationException
• QdbAliasAlreadyExistsException
• QdbAliasNotFoundException
• QdbBatchAlreadyRunException
• QdbBatchCloseException
• QdbBatchNotRunException
• QdbBufferClosedException
• QdbIncompatibleTypeException
• QdbOperationDisabledException
• QdbOverflowException
• QdbResourceLockedException
• QdbUnderflowException
• QdbProtocolException
• QdbUnexpeectedReplyException
• QdbSystemException
• QdbLocalSystemException
• QdbRemoteSystemException