6.5. .NET

6.5.1. Quick Reference

Return Type Name Arguments
Handle Handle ()
void Close ()
bool Connected ()
void SetTimeout (System.TimeSpan timeout)
void Connect (System.Net.IPEndPoint host)
Exception[] Multiconnect (System.Net.IPEndPoint[] hosts)
void Put (System.String alias, System.Byte[] buffer)
void Put (System.String alias, System.Byte[] buffer, System.DateTime expiryTime)
void Update (System.String alias, System.Byte[] buffer)
void Update (System.String alias, System.Byte[] buffer, System.DateTime expiryTime)
System.Byte[] Get (System.String alias)
System.Byte[] GetRemove (System.String alias)
System.Byte[] GetUpdate (System.String alias, System.Byte[] buffer)
System.Byte[] GetUpdate (System.String alias, System.Byte[] buffer, System.DateTime expiryTime)
System.Byte[] CompareAndSwap (System.String alias, System.Byte[] newValue, System.Byte[] comparand)
System.Byte[] CompareAndSwap (System.String alias, System.Byte[] newValue, System.Byte[] comparand, System.DateTime expiryTime)
void Remove (System.String alias)
bool RemoveIf (System.String alias, System.Byte[] comparand)
void RemoveAll ()
qdb.BatchResult[] RunBatch (qdb.BatchRequest[] requests)
System.String[] PrefixGet (System.String prefix)
void ExpiresAt (System.String alias, System.DateTime expiryTime)
void ExpiresFromNow (System.String alias, System.TimeSpan expiryDelta)
bool GetExpiryTime (System.String alias, out System.DateTime expiryTime)
System.String NodeStatus (System.Net.IPEndPoint host)
System.String NodeConfig (System.Net.IPEndPoint host)
System.String NodeTopology (System.Net.IPEndPoint host)
void StopNode (System.Net.IPEndPoint host, System.String reason)

6.5.2. Introduction

The quasardb .NET API builds on the C++ API and delivers convenience and flexibility with great performance. The logic is similar to that of the C++ API (see C++).

6.5.3. DLL

All object definitions and functions are made available in the QdbNetApi.dll file. All classes and methods reside in the qdb namespace.

The library requires Visual Studio 2013 Update 4 redist to function properly.

6.5.4. Exceptions

The quasardb .NET API will collect and throw Exceptions when the Handle.Close() method is called, or the Handle object goes out of scope.

6.5.5. The handle object

Use the Handle object to interact with the cluster. Note that simply having a Handle object does not connect you to a cluster; you need to call Handle.Connect(). The following example shows creating a handle, connecting to a cluster, removing an entry, then handling errors:

try
{
    // Create a Handle.
    qdb.Handle h = new qdb.Handle();

    // Connect to the cluster.
    h.Connect(new System.Net.IPEndPoint(System.Net.IPAddress.Loopback, 2836));

    // Removes the entry "myalias" if it exists, errors otherwise
    h.Remove("myalias");

    // An explicit Close() is not mandatory but permits catching errors in the surrounding try-catch block.
    h.Close();
}
catch (qdb.Exception ex)
{
    Console.WriteLine("There is something rotten in the kingdom of Denmark: {0}", ex.ToString());
}

If the handle object goes out of scope, the connection will automatically be terminated and the handle will be garbage collected.

Caution

Concurrent calls to the Handle.Connect() method on the same handle object leads to undefined behaviour.

6.5.6. Adding and getting data to and from a cluster

To put and get an entry, the C# way:

try
{
    // Adds the entry "myalias" with the System.Byte[] value in_data, with no expiration time.
    h.Put("myalias", in_data, 0);
}
catch (qdb.Exception ex)
{
    Console.WriteLine("Putting entry 'myalias' failed: {0}", ex.ToString());
}

try
{
    // Gets the entry "myalias", with no expiration time.
    byte[] out_data = h.Get("myalias", out_data);
}
catch (qdb.Exception ex)
{
    Console.WriteLine("Getting entry 'myalias' failed: {0}", ex.ToString());
}

6.5.7. Closing a connection

A connection can be explicitly closed and the handle released with the Handle.Close() method:

h.Close();

Note that when the Handle object leaves scope, Handle.Close() is automatically called.

6.5.8. Expiry

Expiry is set with Handle.ExpiresAt() and Handle.ExpiresFromNow(). It is obtained with Handle.GetExpiryTime(). Expiry time is always in seconds, either relative to epoch (January 1st, 1970 00:00 UTC) when using Handle.ExpiresAt() or relative to the call time when using Handle.ExpiresFromNow().

Danger

The behavior of Handle.ExpiresFromNow() is undefined if the time zone or the clock of the client computer is improperly configured.

To set the expiry time of an entry to 1 minute, relative to the call time:

try
{
    // Sets the entry "myalias" to an expiry time of 60 seconds from the call time.
    h.ExpiresFromNow("myalias", TimeSpan(0, 1, 0));
}
catch (qdb.Exception ex)
{
    Console.WriteLine("Setting expiry time for 'myalias' failed: {0}", ex.ToString());
}

Set an absolute exipry:

try
{
    // Sets the entry "myalias" to never expire.
    h.ExpiresAt("myalias", System.DateTime(2020, 1, 1));
}
catch (qdb.Exception ex)
{
    Console.WriteLine("Setting expiry time for 'myalias' failed: {0}", ex.ToString());
}

If an expiry time is not set when the entry is made, entries do not expire. To obtain the expiry time of an existing entry:

try
{
    DateTime expiry;

    // Gets the expiry time for "myalias"
    if (!h.GetExpiryTime("myalias", expiry))
    {
        // no expiry
    }
    else
    {
        // expiry, datetime_of_myalias is updated
    }
}
catch (qdb.Exception ex)
{
    Console.WriteLine("Getting expiry time for 'myalias' failed: {0}", ex.ToString());
}

6.5.10. Batch operations

Batch operations are used similarly as in C, except a method Handle.RunBatch() is provided for convenience.

6.5.11. Reference

All classes and instance methods reside in the ‘qdb’ namespace.

class Handle
Handle()

Constructor. Creates a qdb.Handle object by which you can manipulate the cluster.

Returns:A qdb.Handle object.
void Close()

Terminates all connections and releases all client-side allocated resources.

bool Connected()

Tests if the current handle is properly connected to a quasardb cluster.

Returns:true if the handle is properly connected to a cluster.
void SetTimeout(System.TimeSpan timeout)

Sets the timeout for connections.

Parameters:timeout – The amount of time after which the connection should timeout.
void Connect(System.Net.IPEndPoint host)

Bind the client instance to a quasardb cluster and connect to the given node within the cluster.

Parameters:host – The remote host to connect to.
Exception[] Multiconnect(System.Net.IPEndPoint[] hosts)

Bind the client instance to a quasardb cluster and connect to multiple nodes within the cluster. If the same node (address and port) is present several times in the input array, it will count as only one successful connection. All hosts must belong to the same quasardb cluster. Only one connection to a listed node has to succeed for the connection to the cluster to be successful.

Parameters:hosts – an array of remote hosts to connect to.
Returns:an array, matching each provided endpoint, with an exception in case of error or null if no error occurred.
void Put(System.String alias, System.Byte[] buffer)

Adds an entry to the quasardb server. If the entry already exists the function will fail. Keys beginning with the string “qdb” are reserved and cannot be added to the cluster.

Parameters:
  • alias – The entry’s alias to create.
  • buffer – The entry’s content to be added to the server.
void Put(System.String alias, System.Byte[] buffer, System.DateTime expiryTime)

Adds an entry to the quasardb server. If the entry already exists the function will fail. Keys beginning with the string “qdb” are reserved and cannot be added to the cluster.

Parameters:
  • alias – The entry’s alias to create.
  • buffer – The entry’s content to be added to the server.
  • expiryTime – The absolute expiry time of the entry.
void Update(System.String alias, System.Byte[] buffer)

Updates an entry on the quasardb server. If the entry already exists, the content will be updated. If the entry does not exist, it will be created.

Parameters:
  • alias – The entry’s alias to update.
  • buffer – The entry’s content to be updated to the server.
void Update(System.String alias, System.Byte[] buffer, System.DateTime expiryTime)

Updates an entry on the quasardb server. If the entry already exists, the content will be updated. If the entry does not exist, it will be created.

Parameters:
  • alias – The entry’s alias to update.
  • buffer – The entry’s content to be updated to the server.
  • expiryTime – The absolute expiry time of the entry.
System.Byte[] Get(System.String alias)

Retrieves an entry’s content from the quasardb server. If the entry does not exist, the function will fail.

Parameters:alias – The entry’s alias whose content is to be retrieved.
Returns:The requested entry’s content.
System.Byte[] GetRemove(System.String alias)

Atomically gets an entry from the quasardb server and removes it. If the entry does not exist, the function will fail.

Parameters:alias – The entry’s alias whose content is to be retrieved.
Returns:The requested entry’s content.
System.Byte[] GetUpdate(System.String alias, System.Byte[] buffer)

Atomically gets and updates (in this order) the entry on the quasardb server. If the entry does not exist, the function will fail.

Parameters:
  • alias – The entry’s alias to update.
  • buffer – The entry’s content to be updated to the server.
Returns:

The requested entry’s content, before the update.

System.Byte[] GetUpdate(System.String alias, System.Byte[] buffer, System.DateTime expiryTime)

Atomically gets and updates (in this order) the entry on the quasardb server. If the entry does not exist, the function will fail.

Parameters:
  • alias – The entry’s alias to update.
  • buffer – The entry’s content to be updated to the server.
  • expiryTime – The absolute expiry time of the entry.
Returns:

The requested entry’s content, before the update.

System.Byte[] CompareAndSwap(System.String alias, System.Byte[] newValue, System.Byte[] comparand)

Atomically compares the entry with the comparand and updates it to newValue if, and only if, they match.

Parameters:
  • alias – The entry’s alias to update.
  • newValue – The entry’s content to be updated to the server in case of match.
  • comparand – The entry’s content to be compared to.
Returns:

The original content, before the update, if any.

System.Byte[] CompareAndSwap(System.String alias, System.Byte[] newValue, System.Byte[] comparand, System.DateTime expiryTime)

Atomically compares the entry with the comparand and updates it to newValue if, and only if, they match.

Parameters:
  • alias – The entry’s alias to update.
  • newValue – The entry’s content to be updated to the server in case of match.
  • comparand – The entry’s content to be compared to.
  • expiryTime – The absolute expiry time of the updated entry.
Returns:

The original content, before the update, if any.

void Remove(System.String alias)

Removes an entry from the quasardb server. If the entry does not exist, the function will fail.

Parameters:alias – The entry’s alias to delete.
bool RemoveIf(System.String alias, System.Byte[] comparand)

Atomically compares the entry with the comparand and removes it if, and only if, they match.

Parameters:
  • alias – The entry’s alias to delete.
  • comparand – The entry’s content to be compared to.
Returns:

True if the entry was successfully removed, false otherwise.

void RemoveAll()

Removes all the entries on all the nodes of the quasardb cluster. The function returns when the command has been dispatched and executed on the whole cluster or an error occurred.

qdb.BatchResult[] RunBatch(qdb.BatchRequest[] requests)

Runs the provided operations in batch on the cluster. The operations are run in arbitrary order.

Parameters:requests – An array of operations to run on the cluster in batch.
Returns:An array of results in the same order of the supplied operations.
System.String[] PrefixGet(System.String prefix)

Searches the cluster for all entries whose aliases start with “prefix”. The method will return an array of strings containing the aliases of matching entries.

Parameters:prefix – A string representing the search prefix.
Returns:An array of strings containing the aliases of matching entries.
void ExpiresAt(System.String alias, System.DateTime expiryTime)

Sets the expiry time of an existing entry from the quasardb cluster. A value of null means the entry never expires.

Parameters:
  • alias – A string representing the entry’s alias for which the expiry must be set.
  • expiryTime – The absolute time at which the entry expires.
void ExpiresFromNow(System.String alias, System.TimeSpan expiryDelta)

Sets the expiry time of an existing entry from the quasardb cluster, relative to the current time.

Parameters:
  • alias – A string representing the entry’s alias for which the expiry must be set.
  • expiryDelta – Time, relative to the call time, after which the entry expires.
bool GetExpiryTime(System.String alias, out System.DateTime expiryTime)

Retrieves the expiry time of an existing entry. A value of null means the entry never expires.

Parameters:
  • alias – A string representing the entry’s alias for which the expiry must be retrieved.
  • expiryTime – An DateTime that will be updated with the entry expiry time, if any.
Returns:

True if there is an expiry, false otherwise.

System.String NodeStatus(System.Net.IPEndPoint host)

Obtains a node status as a JSON string.

Parameters:host – The remote node to get the status from.
Returns:The status of the node as a JSON string.
System.String NodeConfig(System.Net.IPEndPoint host)

Obtains a node configuration as a JSON string.

Parameters:host – The remote node to get the configuration from.
Returns:The configuration of the node as a JSON string.
System.String NodeTopology(System.Net.IPEndPoint host)

Obtains a node topology as a JSON string.

Parameters:host – The remote node to get the configuration from.
Returns:The topology of the node as a JSON string.
void StopNode(System.Net.IPEndPoint host, System.String reason)

Stops the node designated by its host and port number. This stop is generally effective within a few seconds of being issued, enabling inflight calls to complete successfully.

Parameters:
  • host – The remote node to stop.
  • reason – A string detailing the reason for the stop that will appear in the remote node’s log.