Karoo project Cave setup

Basic service setup

The cave application is a database interface. It provides a access to a database very conveniently, maintaining a connection pool, and making it extremely simple to specify services and their SQL. E.g. following is a simple cave configuration file:

 <?xml version="1.0" encoding="utf-8"?>
 <cave xmlns="http://www.zwartberg.com/fab/1.0" poll-delay="15">
   <database name="KarooDB" username="bmodra" password="" connect_timeout="1" connection-pool-size="3"/>
   <service name="user" id="login">
    <sql transaction="commit">
       select permission,username,sessionid from login(
        <parameter name="username"/>,
        <parameter name="password"/>);
     </sql>
   </service>
 ... etc
 </cave>

The only service displayed in this example is the "login" service. The rest of the file was snipped out to avoid over-complicating this example.

This example specifies first that the cave application must re-read this configuration file every 15 seconds, to check for changes. If so, it will re-configure itself automatically. This is very useful in a large online system that can't be shut down and restarted.

Next it specifies the database name, username, password, and connection parameters. The connection parameters include the timeout for a connection, and the size of the connection pool. The connection pool generally does not need to be large, because The Karoo System is based on multiplexed connections. It can be servicing hundreds of clients on just one database connection, if the database services are all short lived. But if some services become longer in transactional time, then it will be wise to create another cave rock which services just the slower transactions. (You don't want to mix slow transactions and fast transactions in the same queue, otherwise the slow transactions will cause a large latency for the fast transactions.)

Then the service is specified. t present, the service name is not actually used, though it is required. This will be used in future. The service ID is used to specify the service in all the APIs.

A service contains 1 or more SQLs. A default SQL is a non-transaction type of SQL. This will only be useful if the SQL only gets information from the database without making any modifications. Otherwise, the SQL can be specified as a transaction, by using the

 transaction="commit"
attribute.

Then the text in the SQL is written as plain text, with the addition that you can specify parameters, which are replaced at runtime with the parameter value.

A parameter can be specified by name only - which means it will be assumed to have a textual value, or you can also specify the type. The type can be one of:

E.g.
 <service name="set image" id="set-image">
   <sql transaction="commit">
     select setthumb as success2 from setThumb(
       <parameter name="id" type="integer"/>,
       <parameter name="image" type="image" width="212" height="160"/>,
       <parameter name="sessionid" type="integer"/>);
     select setimage as success from setImage(
       <parameter name="id" type="integer"/>,
       <parameter name="image" type="image" width="752" height="500"/>,
       <parameter name="sessionid" type="integer"/>);
   </sql>
 </service>

The above example runs two SQLs in a single transaction, calling two PLPGSQL functions, and returning two rows: The first with a column "success2" and the second with a column "success". In this case, it could be more efficient to call just one SQL, except that the size of the SQL with two escaped strings becomes quite huge and causes problems in the SQL parser of PostgreSQL.

Web service setup

The Cave application is primarily a database access service, but it also is a basic web server. For a full web server, and dynamic web pages, see the surf application: Karoo project Surf setup

Plain Vanilla Web Server setup

To do this, create an XML file (using the "fab" syntax) which describes the location of the HTML documents, e.g.

 <?xml version="1.0" encoding="utf-8"?>
 <cave xmlns="http://www.zwartberg.com/fab/1.0" poll-delay="15">
   <mime-type ext='html' type='text/html'/>
   <mime-type ext='gif' type='image/gif'/>
   <mime-type ext='png' type='image/png'/>
   <mime-type ext='jpg' type='image/jpeg'/>
   <mime-type ext='js' type='text/javascript'/>
   <mime-type ext='css' type='text/css'/>
   <mime-type ext='xsl' type='text/xsl'/>
   <database name="KarooDB" username="bmodra" password="" connect_timeout="1" connection-pool-size="3"/>
   <service name="user" id="login">
 ... etc
   <service name="get-image" id="properties_images">
     <sql>
       select image from property where id=<parameter name="id" type="integer"/>;
     </sql>
   </service>
 ... etc
 </cave>

Then to start the web server, you would start up the cave application and tell it the URL of this XML file. E.g.

 /usr/local/bin/cave --url file:///usr/local/etc/cave.xml

Then the following URL will be available:

 http://localhost:8080/properties_images/by_id/2.jpg

... where "2" in this case corresponds to the id column. It will call the "properties_images" service, sending id=2 and returning as raw data, the contents of the image column (which is assumed to be of type BYTEA.)

See also


Generated on Tue Feb 16 15:04:29 2010 for Karoo by  doxygen 1.5.8