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)
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++).
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.
The quasardb .NET API will collect and throw Exceptions when the Handle.Close() method is called, or the Handle object goes out of scope.
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.
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());
}
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.
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());
}
Prefix based search is a powerful tool that helps you lookup entries efficiently.
For example, if you want to find all entries whose aliases start with “record”:
try
{
System.String[] results = h.PrefixGet("record");
}
catch (qdb.Exception ex)
{
Console.WriteLine("Getting prefixes for 'record' failed: {0}", ex.ToString());
}
Batch operations are used similarly as in C, except a method Handle.RunBatch() is provided for convenience.
All classes and instance methods reside in the ‘qdb’ namespace.
Constructor. Creates a qdb.Handle object by which you can manipulate the cluster.
| Returns: | A qdb.Handle object. |
|---|
Terminates all connections and releases all client-side allocated resources.
Tests if the current handle is properly connected to a quasardb cluster.
| Returns: | true if the handle is properly connected to a cluster. |
|---|
Sets the timeout for connections.
| Parameters: | timeout – The amount of time after which the connection should timeout. |
|---|
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. |
|---|
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. |
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: |
|
|---|
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: |
|
|---|
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: |
|
|---|
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: |
|
|---|
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. |
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. |
Atomically gets and updates (in this order) the entry on the quasardb server. If the entry does not exist, the function will fail.
| Parameters: |
|
|---|---|
| Returns: | The requested entry’s content, before the update. |
Atomically gets and updates (in this order) the entry on the quasardb server. If the entry does not exist, the function will fail.
| Parameters: |
|
|---|---|
| Returns: | The requested entry’s content, before the update. |
Atomically compares the entry with the comparand and updates it to newValue if, and only if, they match.
| Parameters: |
|
|---|---|
| Returns: | The original content, before the update, if any. |
Atomically compares the entry with the comparand and updates it to newValue if, and only if, they match.
| Parameters: |
|
|---|---|
| Returns: | The original content, before the update, if any. |
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. |
|---|
Atomically compares the entry with the comparand and removes it if, and only if, they match.
| Parameters: |
|
|---|---|
| Returns: | True if the entry was successfully removed, false otherwise. |
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.
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. |
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. |
Sets the expiry time of an existing entry from the quasardb cluster. A value of null means the entry never expires.
| Parameters: |
|
|---|
Sets the expiry time of an existing entry from the quasardb cluster, relative to the current time.
| Parameters: |
|
|---|
Retrieves the expiry time of an existing entry. A value of null means the entry never expires.
| Parameters: |
|
|---|---|
| Returns: | True if there is an expiry, false otherwise. |
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. |
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. |
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. |
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: |
|
|---|