| The Casbah Project: APIs and Reference Manual: Developer's Release 1 | ||
|---|---|---|
| Prev | The Casbah Project: Oriel API | Next |
These methods are invoked by a Cairo Application Object Server only. An end-user script should not need to use these methods.
Table 1. __cb_init__()
Return Type | Method Name | Method Arguments |
|---|---|---|
void | __cb_init__() | (CaDict options) |
The __cb_init__() method asks an Oriel driver instance to configure itself based on the options being handed to it. __cb_init__() is the constructor, so it is only invoked when the system administrator is setting up a server. __cb_init__() must not be invoked at server startup by Cairo. __cb_init__() must not actually create any network sockets or attach to any shared memory segments. __cb_init__() must only fill in the instance variables of this object in preparation for a call to __cb_setup__()
There are no defined options for the Oriel API. Drivers may define whatever options they choose.
Table 2. __cb_compile__()
Return Type | Method Name | Method Arguments |
|---|---|---|
CaObject | __cb_compile__() | (CaObject source, CaString method_name, CaString target, CaObject object_instance, CaList args) |
__cb_compile__() converts the object stored in source into a new type. This new type is called p-code, but it can take many forms. method_name is the name of the method that must be converted if source contains more than one method. args is the array of arguments that are being passed to method_name. __cb_compile__() must not actually execute the method. __cb_compile__() must not alter the argument list (stored in args). __cb_compile__() must not alter the object in object_instance.
__cb_compile__() must convert to the type named in target. If target has the value of CaNull then the Oriel driver may chose whichever p-code target is appropiate.
Table 3. __cb_invoke__()
Return Type | Method Name | Method Arguments |
|---|---|---|
CaObject | __cb_invoke__() | (CaObject pcode, CaString method_name, CaObject object_instance, CaList args) |
__cb_invoke__() executes method_name, which should be stored in p-code. __cb_invoke__() must return the result of the execution of the method. Should an error arise while executing the method‐for example, __cb_invoke__() cannot execute the method or the method itself throws an exception---__cb_invoke__() must throw the exception to its caller so that the caller of __cb_invoke__() may handle the error.
method_name may have the value CaNull, which must be interpreted as meaning the "default" value. For a language such as C or Java, this might be the method/function "main()". For Perl or TCL, this might mean to execute the code in the order it is given, as would be expected for that language normally.
object_instance must have the value CaNull when the invoke is being done on a script rather than on the method of an object.
__cb_invoke__() may throw an exception if the type of pcode is not in the list returned by __cb_get_pcode_list__(). Cairo must not pass __cb_invoke__() a type of p-code that was not in the list returned by __cb_get_pcode_list__().
Example 2. __cb_invoke__() in Perl
sub invoke
{
my ($pcode, $method_name, $object_instance, $args) = @_;
my ($sub);
$sub = eval join('', "sub {", $pcode, "; goto &$method_name(@_);}");
&{$sub}($object_instance, @$args);
}
Example 3. __cb_invoke__() in Java
public Object invoke (Object pcode, String method_name, Object instanceOfObject, Vector args)
throws Exception
{
Object method_args;
Class c;
Class method_proto;
Method m;
method_args = new Object[args.size()];
args.copyInto(method_args);
method_proto = new Object[args.size()];
for (int i = 0; i < method_proto.length; i++)
{
method_proto[i] = args.elementAt(0).getClass();
}
c = instanceOfObject.getClass();
m = c.getDeclaredMethod(method_name, method_proto);
try
{
return m.invoke(instanceOfObject, method_args);
} catch (InvocationTargetException ite)
{
throw(ite.getTargetException());
}
}
The __cb_info__() method must be implemented by all Oriel driver. __cb_info__() returns a dictionary of driver metadata.
Table 4. __cb_info__()
Method | Prototype | Returns |
|---|---|---|
__cb_info__() | () | CaDict |
The following key/value pairs must be returned in __cb_info__()'s dictionary.
Table 5. __cb_info__() key/value pairs
Key Name (type) | Example Value (type) | Description |
|---|---|---|
name (CaString) | JPython (CaString) | A short, descriptive filename-like name for the driver. |
description (CaString) | Provides Oriel scripting support for JPython. (CaString) | A sentence or two that describes the functions the driver performs. |
author (CaString) | Bijan Parsia (CaString) | The full name of the primary developer of the driver. |
contact (CaString) | <bparsia@casbah.org> (CaString) | Contact information for the driver author; typically an email address. |
api (CaString) | oriel (CaString) | Specifies which API the driver implements. For Oriel drivers, this is always the string "oriel". |
revision (CaString) | 1.15 (CaString) | The CVS driver revision. Used for quality control and support. This is not the API version number. |
source_list (CaString) | {'foo':'bar'} (CaDict) | source_list maps to a CaDict that contains source types the driver can compile as keys, mapped to the resulting p-code types. |
p-code_list (CaString) | ['foo', 'bar', 'baz'] (CaList) | p-code_list maps to a list of invokable p-code types. |