The API is contained in a single source file on GitHub.
Inclusion in a development project is, therefore, a straightforward matter
of including the file with other source code under the package
ensuring it is properly imported and referenced by other classes. If
preferred, it can be compiled separately into a class or JAR file to be
included in the classpath for use as an external library or uploaded to
a local repository for build integration.
As the API is provided as source, it is perfectly possible to customize code to meet specific requirements.
However, without prior knowledge of how the interactions work, this is not advised unless the solution to these requirements or issues are known.
It is also possible, and in some contexts encouraged, to wrap the
functionality of this class within a model suitable for your framework.
An example might be the open-source qJava library.
Although it is not compatible with the most recent kdb+ version at the time of writing, it shows how to use
c.java as a core over which an object-oriented framework of q types and functionality has been applied.
The source file is structured as a single outer class,
Within it, a number of constants and inner classes together model an
environment for sending and receiving data from a kdb+ process.
This section explores the fundamentals of the class to provide context and understanding of practical use-cases for the API.
Connection and interface logic¶
The highly-recommended means of connecting to a kdb+ process using the API is through instantiation of the
c object itself.
Three constructors provide for this purpose:
public c(String host,int port,String usernamepassword) public c(String host,int port,String usernamepassword,boolean useTLS) public c(String host,int port)
These constructors are straightforward to use.
The host and port specify a socket-object connection, with the username/password string serialized and passed to the remote instance for authorization.
The core logic is the same for all; the host/port-only constructor attempts to retrieve the user string from the Java properties, and the constructor with the
useTLS boolean will, when flagged true, attempt to use an SSL socket instead of an ordinary socket.
It is also possible to set up the object to accept incoming connections
from kdb+ processes rather than just making them. There are two
constructors which, when passed a server socket reference, will allow a
q session to establish a handle against the
public c(ServerSocket s) public c(ServerSocket s,IAuthenticate a)
IAuthenticate is an interface within the
c class that can be
implemented to emulate kdb+ server-side authentication, allowing the
establishment of authentication rules similar to that which might be
done through the kdb+ function .z.pw.
Both of these constructor families represent two ‘modes’ in which
c object can be instantiated. The first, and ultimately most
widely used, is for making connections to kdb+ processes, which
naturally would be used for queries, subscriptions and any task that
requires the reception of or sending of data to said processes. The
second, which sees Java act as the server, would see utility in
management and aggregation of kdb+ clients, perhaps as a data sink or
an intermediary interface for another technology.
Interactions between Java and kdb+ through these connections are
largely handled by what might be called the ‘k’ family of methods in
c class. There are thirteen combined methods and overloads that
fall under this group. They can be divided roughly into four groups:
Synchronous query methods¶
public Object k(String expr) public Object k(String s,Object x) public Object k(String s,Object x,Object y) public void k(String s,Object x,Object y,Object z) public synchronized Object k(Object x)
These methods are responsible for handling synchronous queries to a kdb+
process. The String parameter will represent either the entire q
expression or the function name; in the case of the latter, the Object
parameters may be used to pass values into that function. In all
instances, the String/Object combinations are merged into a single
object to be passed to the synchronized
Asynchronous query methods¶
public void ks(String expr) public void ks(String s,Object x) public void ks(String s,Object x,Object y) public void ks(String s,Object x,Object y,Object z) public void ks(Object obj)
These methods are responsible for handling asynchronous queries to a kdb+ process. They operate logically in a similar manner to the synchronous query method, with the exception that they are, of course, void methods in that they neither wait for nor return any response from the process.
Incoming message method¶
public Object k()
This method waits on the class input stream and will deserialize the
next incoming kdb+ message. It is used by the
c synchronous methods in
order to capture and return response objects, and is also used in
server-oriented applications in order to capture incoming messages from
Response message methods¶
public void kr(Object obj) public void ke(String text)
These methods are typically used in server-oriented applications to
serialize and write response messages to the class output stream.
kr(Object) will act much like any synchronous response, while
will format and output an error message.
The use of these constructors and methods will be treated in more practical detail through the use-case examples below.