Building a K2 Client

Socket connections

If you simply want to connect to the server and run some queries interactively, the easiest way is to use the built-in socket client. The K2 jar file contains a class called TestClient, whose main method provides a command-line interface to K2. To run it, you must first have the K2 jar file in your CLASSPATH. Then execute the following command:

java K2.system.clients.TestClient hostname portnum

where hostname is the name of the machine on which the K2 server is running, and portnum is the port number on which it's listening for connections. TestClient can be used to execute any OQL query. This includes function definitions, which will exist only in that client's namespace. You can also read in OQL, ODL, or K2MDL scripts using the readscript command.

Socket connections also support so-called "metadata queries". These provide information about the environment in which OQL queries are run. Specifically, you can get the names and types of all of the functions and data source connections available. Through TestClient, you perform a metadata query by prepending it with 'mdq: '. For example, 'mdq: functions' lists the names of all functions in the environment, along with the number and types of their arguments, and their return types. Similarly, 'mdq: connections' lists the names of all data sources to which the server is connected. To get a list of the entry points (with types) for a particular data source, use the data source name as the metadata query.

TestClient uses K2's ClientSocketConnection class to connect to the server. This class encapsulates the socket protocol, easing the process of communicating with the server. If you're building your own socket client, you should use this class to handle the communication for you. Of course, this assumes that your client is written in Java™. If you'd rather use Perl, a Perl implementation of ClientSocketConnection is available. If you want to use some other language, you'll need to implement the socket protocol yourself.

If you're going to use ClientSocketConnection, regardless of which language you're using, you should call the getConnected method to create a new connection. Also, be sure to call either the getResponseString, echoResponseToWriter, or getResponseStringBuffer method after each call to an execute... method, even if you're not interested in the server's response. This clears the result holder to get ready for the next query. Finally, when you're done, call the close method to close the socket before exiting your program.

The other kind of user connection is the RMI user connection.

[Tech Docs Index]