The Casbah Project: APIs and Reference Manual: Developer's Release 1
PrevThe Casbah Project: Qibla APINext

The QiblaConnection Class

Required Methods

__cb_handle_connection__()

Table 11. __cb_handle_connection__() method

return type

method name

method arguments

void

__cb_handle_connection__()

()

Handles the connection that this object represents. This object was created by a QiblaDriver instance during an __cb_accept_one_client__() call.

The __cb_handle_connection__() method must block, returning only when the client connection is considered "complete" by the QiblaDriver. When it returns, all communication channels used by this connection must be closed and released; any other resources must be cleaned up as well.[1]

__cb_handle_connection__() must deal with authenticating the client. __cb_accept_one_client__() must not do authentication. If any authentication information is obtained during __cb_accept_one_client__() it must be cached in client until __cb_handle_connection__() is called. This requirement allows Cairo to schedule resource usage as well as for sound security.

__cb_handle_connection__() has limited access model to the QiblaDriver instance that created the current connection object. Specifically, __cb_handle_connection__() must only invoke methods on its "parent" Qibla instance. __cb_handle_connection__() must not attempt to access instance variables directly. [2]

__cb_handle_connection__() reads and processes requests from the connection. Requests are classified as a set of operations that the server should perform. [3] __cb_handle_connection__() must parse the request and order it to be carried out using the Cairo Public Interface methods. Results from the methods in the Cairo Public Interface may be sent back to the other side of the connection as the protocol specifies. __cb_handle_connection__() must handle all exceptions thrown by any method of the Cairo Public Interface, even if this means closing down the connection and aborting processing.

__cb_handle_connection__() must not throw any exceptions, it should gracefully return to its caller.

__cb_kill_connection__()

Table 12. __cb_kill_connection__() method

return type

method name

method arguments

void

__cb_kill_connection__()

()

Orders the current connection to be shutdown as soon as possible. A conforming QiblaDriver must support this method. __cb_kill_connection__() should set a state variable in the connection instance which will cause __cb_handle_connection__() to abort the connection the next time it can safely shutdown and return to its caller.

__cb_kill_connection__() must be callable from a different thread than __cb_handle_connection__(). A conforming Cairo implementation must give __cb_kill_connection__() access to the instance variables of the connection such that it can modify an instance variable for __cb_handle_connection__() to pick up in the future.

Example 1. __cb_kill_connection__() in Java

        public class MyProtoQiblaConnection implements QiblaConnection
        {
                private boolean keep_running;
                
                public MyProtoQiblaConnection()
                {
                        keep_running = TRUE;
                }

                public void handle_connection()
                {
                        boolean run_it = TRUE;
                        while(run_it)
                        {
                                // Parse request
                                // Process request
                                // Send result

                                run_it = run_state(TRUE);
                        }
                        
                        // Close connection
                }

                public void kill_connection()
                {
                        run_state(FALSE);
                }

                private synchronized boolean run_state(boolean new_state)
                {
                        keep_running = new_state;
                        return keep_running;
                }
        }

Here is another example written in C using Posix threads. [4]

Example 2. __cb_kill_connection__() in C

        #include <pthread.h>

        struct MyProtoQiblaConnection_tag;
        typedef struct MyProtoQiblaConnection_tag MyProtoQiblaConnection;
        struct MyProtoQiblaConnection_tag
        {
                pthread_mutex_t LOCK;
                int             keep_running;
        };

        MyProtoQiblaConnection* MyProtoQiblaConnection___init(MyProtoQiblaConnection *this)
        {
                this->keep_running = 1;
                pthread_mutex_init(&this->LOCK, NULL);
                return this;
        }

        void MyProtoQiblaConnection___destroy(MyProtoQiblaConnection *this)
        {
                pthread_mutex_destroy(&this->LOCK);
        }

        void MyProtoQiblaConnection_handle_connection(MyProtoQiblaConnection *this)
        {
                int     run_it;

                run_it = 1;
                while(run_it)
                {
                        /* Read request */
                        /* Process request */
                        /* Send result */
                        
                        pthread_mutex_lock(&this->LOCK);
                        run_it = this->keep_running;
                        pthread_mutex_unlock(&this->LOCK);
                }

                /* Close connection */
        }

        void MyProtoQiblaConnection_kill_connection(MyProtoQiblaConnection *this)
        {
                pthread_mutex_lock(&this->LOCK);
                this->keep_running = 0;
                pthread_mutex_unlock(&this->LOCK);
        }

__cb_info__()

The __cb_info__() method must be implemented in QiblaDriver. __cb_info__() returns a dictionary of driver metadata. The following key/value pairs must be returned in __cb_info__()'s dictionary.

Table 13. __cb_info__() method

return type

method name

method arguments

CaDict

__cb_info__

()

Table 14. __cb_info__() key/value pairs

Key Name (type)

Example Value (type)

Description

name (CaString)

QiblaHTTPConnect (CaString)

A short, descriptive filename-like name for the driver.

description (CaString) (CaString)

Provides HTTP protocol access to Cairo Application Object Server (CaString)

A sentence or two that describes the functions the driver performs.

author (CaString)

Scott Miller (CaString)

The full name of the primary developer of the driver.

contact (CaString)

(CaString)

Contact information for the driver author; typically an email address.

api (CaString)

qibla driver (CaString)

Specifies which API the driver implements. For QiblaDriver objects, this is always the string "qibla driver".

revision (CaString)

1.15 (CaString)

The CVS driver revision. Used for quality control and support. This is not the API version number.

remote (CaString)

tcpip/204.181.96.94

Contains IP address of the remotely connected host.

remote-host (CaString)

tcpip-hostname/microsoft.die.die.com

Contains hostname of the remotely connected host.

Notes

[1]

Other resources includes temporary files, memory segments, threads, and processes which cannot be garabage collected by the implemenetation langauge or the default Casbah runtime environment.

[2]

This restriction exists because of memory boundaries and thread synchronization limits.

[3]

For example: return the object /about/index.html.

[4]

In this example all functions are prefixed with the "class" name, followed by an underscore. The special methods __init and __destroy are used to intially construct an object, and to release its internal resources when it is being destroyed.

PrevHomeNext
QiblaDriverUpSecurity Considerations