1 Amos II Java Interfaces Daniel Elin and Tore Risch Uppsala Database Laboratory Department of Information Technology Uppsala University Sweden [email protected] 2000-08-25 Latest modification 2014-02-06 This report describes the external interfaces between Amos II and the programming lan- guage Java. There are also interfaces between Amos II and the programming languages C and Lisp, documented separately. There are mainly two ways to interface Amos II with Java programs: Either a Java program calls Amos II through the callin interface, or for- eign AmosQL functions are defined by Java methods through the callout interface. The combination is also possible whereforeign functions in Java call Amos II back through the callin interface. 2 1. Introduction There are external interfaces between Amos II and the programming languages ANSII C, Lisp, and Java. This docu- ment describes Java interfaces, while the the C and Lisp interfaces are documented separately in [3]. The Java interface is the most convenient way to write Amos II applications and to do simple extensions. The C and Lisp interfaces must be used for more advanced system extensions and time critical applications. Some advantages with the Java interfaces compared to the C interfaces are: 1. Programming errors in Java code cannot cause Amos II to crash. By contrast, programming errors in C can cause very nasty system errors. The Lisp interfaces are much safer than C, but not as protected (and limited) as the Java interfaces. 2. Memory is deallocated automatically in Java through its automatic garbage collector. In C/C++ memory dealloca- tion is manual and very error prone, while Lisp also has automatic garbage collection. 3. Java has extensive libraries for user interfaces, web accesses, etc. which can easily be interfaced from Amos II through its Java interfaces. The disadvantages with the Java interfaces are that they are slower and more limited than the other ones. There are two main kinds of external interfaces, the callin and the callout interfaces: • With the callin interface a program in Java calls Amos II. The callin interface is similar to the call level interfaces for relational databases, such as ODBC or JDBC. • With the callout interface Amos II functions call methods written in Java. Each such foreign AMOS function is implemented by one or several Java methods. The foreign functions in Amos II are multi-directional which allow them to have separately definined inverses and to be indexed [2]. The system furthermore allows the callin interface to be used also in foreign functions, which gives great flexibility and allows Java methods to be used as a form of procedural functions [1]. With the callin interface there are two ways to call Amos II from Java: • In the embedded query interface a Java method is provided that passes strings containing AMOSQL statements to Amos II for dynamic evaluation. Methods are also provided to access the results of the dynamically evaluated AMOSQL statement. The embedded query interface is relatively slow since the AMOSQL statements have to be parsed and compiled at run time. • In the fast-path interface predefined Amos II functions are called as Java methods, without the overhead of dynam- ically parsing and executing AMOSQL statements. The fast-path is significantly faster than the embedded query interface. It is therefore recommended to always make Amos II derived functions and procedural functions for the various Amos II operations performed by the application and then use the fast-path interface to invoke them direct- ly [1]. There are also two choices of how the connection between application programs and Amos II is handled: 1. Amos II can be linked directly with a Java application program. This is called the tight connection where Amos II is an embedded database in the application. It provides for the fastest possible interface between an application and Amos II since both the application and Amos II run in the same address space. The disadvantages with the tight connection is that Amos II and the application must run on the same computer. Another disadvantage is that only a single Java application can be linked to Amos II. 2. The Java application can be run as a client to an Amos II server. This is called the client-server connection. With the client-server connection several applications can access the same Amos II concurrently. The Java applications and the Amos II server run as different programs. However, the overhead of calling Amos II from another program can be several hundred times slower than the tight connection. Currently the client-server connection also requires Amos II kernel code (in C) to be called from Java in the client, and Amos II Java clients are thus not applets. The callout interface is implemented through a mechanism called the multi-directional foreign function interface [1]. 3 For example, external databases can be accessed through Java and made fully available in Amos II. Programs called through the callout interface always run in the same address space as the Amos II server. With the Java callout interface it is easy to extend Amos II with simple foreign Amos II functions written in Java. This document is organized as follows: • Sec. 2. documents the callin interface to Amos II from Java using either the embedded query or the fast-path inter- face. • Sec. 3.describes the callout interface where Amos II functions can be defined in Java. • Sec. 4. describes how to customize the query optimizer with cost hints for the callout functions. 2. The Callin Interface The following things should be observed when calling Amos II from Java: • There exists both an embedded query interface (Sec. 2.3) and a fast-path interface (Sec. 2.6). The fast-path interface is up two orders of magnitude faster. • There is a tight connection between an application and Amos II where the Amos II is linked to a Java application program. Two DLLs (amos.dll and JavaAMOS.dll) and a JAR file (javaamos.jar) are provided for this. • Data is passed between the application and Amos II using some special Java classes defined in javaamos.jar. The system is delivered with sample Java programs that demonstrates the callin (AmosDemo.java), and the callout (Foreign.java) interfaces, respectively. 2.1 Connections The class Connection represents connections to Amos II databases. The constructor is: Connection(String dbName) throws AmosException; If dbName is the empty string it represents a tight connection to the embedded database; otherwise dbName must be the name of an Amos II mediator peer known to the Amos II nameserver [1] running on the same computer as the appli- cation. If you with to connect to an Amos II peer managed by a nameserver running on the computer with IP address nameServerHost use this constructor instead: Connection(String dbName, String nameServerHost) throws AmosException; A connection can be terminated when no longer used with the Connection method: void disconnect() throws AmosException; Connections are automatically terminated when deallocated by Java’s garbage collector. 2.2 Java client programs A Java client program connects to Amos II using its client-server callin API. The client program must first initialize the API by calling the method Connection.initializeClient() throws AmosException After initializing the client API you need to establish a connection to the Amos II peer name nm by calling constructing 4 a new Connection object: Connection conn = new Connection("A"); After that you can place the client code sending requests to client conn. When the work is done the connection is freed using the method conn.Disconnect() For example, assuming your client class is named clientDemo the program code in the file JavaClient.java would have this structure: /* Import API code: */ import callin.AmosException; import callin.Connection; import callin.Scan; import callin.Tuple; public class JavaClient { public static void main(String args[]) throws AmosException {try { /* Initialize client interface */ Connection.initializeClient(); /* Connect to server named A: */ Connection conn = new Connection("A"); /* Do the work here */ conn.disconnect(); } catch (AmosException e) { System.out.println(e.errstr); e.printStackTrace(); /* Print backtrace on error */ } } 2.3 The Embedded Query Interface In the embedded query interface, strings with AMOSQL statements can be sent to the Amos II kernel for execution by calling the Connection method: Scan execute(String query) throws AmosException; For example theScan = theConnection.execute("select name(t) from type t;"); The query is a C string with an AMOSQL statement ended with’;’. The result of the query is a Scan object associated with the connection. A scan is a stream of tuples (rows) which can be iterated through with special interface functions as explaned below. If the number of tuples returned in the scan is large it is sometimes desired to limit the number of tuples to return (i.e. limiting the size of the scan). A second variant of execute is used for this where the parameter stopAfter specifies how many tuples are maximally returned in the scan: Scan execute(String query, int stopAfter) throws AmosException; 5 2.3.1 Scans In the embedded query interface, and also when Amos II functions are called through the fast-path interface, the results are returned as scans. Use the following method to iterate through all tuples in a scan s: ... theScan = theConnection.execute("select name(t) from type t;"); while (!theScan.eos()) // While there are more rows in the scan { Tuple row; // Will hold each result tuple in scan String str; // Will hold each type name in each result tuple row = theScan.getRow(); // Get current row in the scan str = row.getStringElem(0); // Get 1st element (enumerated 0 and up) in row as a string // Here you have access to each type name theScan.nextRow(); // Advance the scan forward } The Scan method eos tests if there are any more rows in a scan: boolean eos(); The Scan method getRow picks up the current tuple (initially 1st in the scan) from the scan: void getRow(Tuple preAlloc) throws AmosException; The Scan method nextRow advances the scan forward, i.e. sets the current tuple to the next tuple: void nextRow() throws AmosException; The scan is automatically closed by the system when all tuples have been iterated through or it is deallocated by the garbage collector. In case you for some reason need to close the scan prematurely you can close it explicitly by calling the Scan method closeScan: void closeScan() throws AmosException; 2.3.2 Single tuple results Often the result of a query is a single tuple. In those cases there is no need to iterate through the scan (or close it) and the value can be accessed by this method: String str; ... str = theConnection.execute("concat(’a’,’b’);",1).getRow.getStringElem(0); In this case the result string is the first element (position 0) of the first row returned from the AMOSQL statement. Notice that the error ’Empty scan’ is raised if there is no result from the query. 2.4 Object Proxies Object Proxies are Java objects representing a corresponding referenced Amos II database objects. An object proxy represents a reference to an Amos II database object. Object proxies can reference any kind of data stored in Amos II databases, including number, strings, surrogate objects, arrays, and other internal Amos II data structures. Object prox- ies are represented using the class Oid. The name of the Amos II datatype of an object proxy can be retrieved with the method: String getTypename() throws AmosException; 6 The Amos II datatype object of an object proxy can be retrieved with the method: Oid getType() throws AmosException; The connection to the Amos II system owning an object proxy can be retrieved with: Connection getConnection() throws AmosExcetion; 2.5 Tuples Tuple is a commonly used datatype in the Amos II Java interface. Tuple objects are represented as object of class Tuple. A tuple represents an ordered collection of Amos II database objects. Tuples are used for many purposes in the inter- faces: • Tuples are used for representing tuples retrieved from the database when iterating through scans from results of Amos II commands and function calls, as illustrated in Sec. 2.3.1. • Tuples are used for representing argument lists in Amos II function calls (Sec. 2.6). • Tuples represent sequences (Sec. 2.5.5) of data values. • Tuples are used in the callout interface for interfacing argument lists of foreign AMOS functions defined in Java. There are a number of system functions for moving data between tuples and other types of Java objects. The Tuple method getArity returns the number of elements in the tuple, its arity. int getArity() throws AmosException; To allocate a new tuple with the a given arity and use the Tuple constructor: Tuple(int arity); The elements of the argument list should then be assigned with some tuple update function as explained below. The elements of a tuple are enumerated starting at 0 and can be accessed through a number of tuple access functions specific for each element class, as described next. 2.5.1 String elements To copy data from an element in a tuple into a Java string use the Tuple method getStringElem: String getStringElem(int pos) throws AmosException; It copies element number pos of the tuple into a Java string. An error occurs if the element is not a string. To store a string str in element pos of a tuple use the overloaded Tuple method: void setElem(int pos, String str) throws AmosException; For example, the following code creates a tuple containing a single string: Tuple tp = new Tuple(1); tp.setElem(0,"HELLO WORLD"); 2.5.2 Integer elements To get an integer stored in position pos of a tuple use the Tuple method getIntElem: int getIntElem(int pos) throws AmosException; An error is generated if there is no integer in the specified position of the tuple. 7 To store an integer in element pos of the tuple use the overloaded Tuple method: void setElem(int pos, int integer) throws AmosException; 2.5.3 Floating point elements To get a double precision floating point number stored in position pos of a tuple use the Tuple method getDoubleElem: double getDoubleElem(int pos) throws AmosException; An error is generated if there is no a real number in the specified position of the tuple. To store a floating point number in element pos of a tuple use the overloaded Tuple method setElem: void setElem(int pos, double dbl) throws AmosException; 2.5.4 Object elements To get a proxy for the object stored in position pos of a tuple use the Tuple method getOidElem: Oid getOidElem(int pos) throws AmosException; It returns an Amos II object proxy which represents in Java any kind of data structure supported by the Amos II storage manager, as explained in Sec. 2.4. To store an object handle in element pos of a tuple use the overloaded Tuple method setElem: void setElem(int pos, Oid obj) throws AmosException; 2.5.5 Sequences Sequences are special Amos II objects containing several other objects with significant order represented as objects of type vector in Amos II databases. Sequences are also represented as as objects of Tuple in Java. To get a sequence stored in position pos of a tuple use the Tuple method getSeqElem: Tuple getSeqElem(int pos) throws AmosException; An error is generated if there is no sequence in the specified position of the tuple. The usual tuple access methods can then be used for accessing the elements of the sequence. To store a copy of the tuple tpl as a sequence in element pos of a tuple use the overloaded Tuple method setElem: void setElem(int pos, Tuple tpl) throws AmosException; 2.5.6 Element data type tests The data type of an element in position pos of a tuple can be tested with these Tuple methods: boolean isString(int pos) throws AmosException; boolean isInteger(int pos) throws AmosException; boolean isDouble(int pos) throws AmosException; boolean isObject(int pos) throws AmosException; boolean isTuple(int pos) throws AmosException; 8 2.6 The Fast-Path Interface The fast-path interface permits Amos II functions to be called from Java. Primitives are provided for building argument lists of Java data to be passed as parameters to a Amos II function call. The result of a fast-path function call is always as scan which is treated in the same way as the result of an embedded query call (Sec. 2.3). The following example shows how to call the Amos II function charstring.lower->charstring (which lower cases a string) from Java: Tuple argl; // The actual argument list String res; // The result string argl = new Tuple(1); // There is one argument argl.setElem(0, "HELLO WORLD"); // the string argument is inserterd into the argument list res = theConnection.callFunction("charstring.lower->charstring",argl).getRow().getStringElem(0); // res will now contain the string ’hello world’ Argument lists represent arguments to be passed to fast-path AMOS function calls. They are represented as Java ob- jects of type Tuple. Before an Amos II function is called an argument list must be allocated with the correct arity of the function to call by using the Tuple constructor: Tuple(int arity) The elements of the argument list should then be assigned with some tuple update function (Sec. 2.5). The first element in the tuple (position 0) is the first argument, etc. When all arguments in the argument list are assigned the function named fnName can be applied on the argument list fnArgs with the fnName method callFunction: Scan callFunction(String fnName, Tuple fnArgs) throws AmosException; Scan callFunction(String fnName, Tuple fnArgs, int stopAfter) throws AmosException; The second variant is to limit the scan size as for fnName. The result of the function call is a scan. Notice here that the Java interface caches the association between the name of an Amos II function, fnName, and the corresponding function proxy representing the database function with that name. This has two consequences: 1. The first call to callFunction accesses the database to get the function proxy and the subsequent calls will then be very fast. 2. callFunction will not notice if the name of the function has been changed between two calls, and thus the function proxy used by the first call will be returned even if the name of the function has changed in the meantime. If required, the function proxy cache can be cleared by calling the Connection method clearFunctionCache: void clearFunctionCache(); To explicitly get the function proxy, given a function name, use the Connection method getFunction: Oid getFunction(String fnName) throws AmosException; callFunction is overloaded to also accept function proxies instead of function names: Scan callFunction(Oid fnObject, Tuple fnArgs) throws AmosException; Scan callFunction(Oid fnObject, Tuple fnArgs, int stopAfter) throws AmosException; 2.7 Creating and Deleting Objects This subsection describes how to create new Amos II database objects from Java. A new such database object of an Amos II type named TypeName is created with the Connection method createObject: Oid createObject(String TypeName) throws AmosException; 9 As for function proxies the system internally maintains object proxies for types too, called type proxies. When create- Object is passed the name of a type it first looks up the database to find the database object representing that type and then create the corresponding type proxy in Java. As for function proxies the type proxies are cached in the Java mem- ory. In the very unlikely situation that some cached type proxy has become invalid1 the type cache can be cleared with the Connection method clearTypeCache: void clearTypeCache(); You can also explicitly obtain the type proxy with the Connection method getType: Oid getType(String typeName) throws AmosException; It returns the type proxy for the type named typeName. createObject is overloaded to also accept type proxies: Oid createObject(Oid type) throws AmosException; where type is the type proxy for the new object. createObject creates a new database object and returns its object proxy. To delete a database object theObject use the Connection method deleteObject: void deleteObject(Oid theObject) throws AmosException; 2.8 Updating Amos II functions Stored Amos II functions and some derived functions can be updated, i.e. assigned a new value for a given argument combination. The following is an example of how to create an object of type person and then update the function name for the new object: Connection theConnection; Oid nw; ... nw = theConnection.createObject("person"); Tuple argl = new Tuple(1); Tuple resl = new Tuple(1); argl.setElem(0,nw); resl.setElem(0,"Tore"); theConnection.addFunction("name",argl,resl); The Connection method setFunction updates an Amos II function: void setFunction(String fnName, Tuple argList, Tuple resList) throws AmosException; void setFunction(Oid fn, Tuple argList, Tuple resList) throws AmosException; The first variant uses the function proxy cache. The second variant requires that a function proxy has been previously retrieved, e.g. with getFunction. The Connection method addFunction adds a new value to a bag valued Amos II function: void addFunction(String fnName, Tuple argList, Tuple resList) throws AmosException; void addFunction(Oid fn, Tuple argList, Tuple resList) throws AmosException; Notice that addFunction and setFunction have the same effect when no previous function value exists. However, since addFunction is faster than setFunction, it is recommended to use addFunction when setting new object properties, as in the example above. The Connection method remFunction removes a value from a bag valued Amos II function: void remFunction(String fnName, Tuple argList, Tuple resList) throws AmosException; void remFunction(Oid fn, Tuple argList, Tuple resList) throws AmosException; 1.This can only happen if the type is first deleted and then another type with the same name is created. In that very unlikely case the system will report that the type is not found when using the type proxy. 10 2.9 Transaction Control The transaction control primitives only make sense in the embedded database. For client/server calls Amos II every Amos II call is a separate transaction (autocommit), so the transaction primitives will then be treated as dummy oper- ations. Local transactions are committed with the Connection method: void commit() throws AmosException; Local transactions are rolled back (aborted) with the Connection method: void rollback() throws AmosException; 2.10 The driver program In order to call Amos II from a Java client in the tight connection where Amos II runs as an databasde in the same main process as the Java applications, a driver program (Sec. 2.2) is needed. It is a Java main program that sets up the Amos II environment and then calls the Amos II kernel. The driver program JavaAMOS (in javaamos.jar) is a very simple driver program that simply calls the AmosQL top loop [1]. This is an example of a driver program; it shows the complete code of the system driver JavaAMOS: import callin.*; // The Amos II callin interface /** The standard JavaAMOS driver program. This is the typical format of all JavaAMOS drivers started from the command line. */ public class JavaAMOS { public static void main(String argv[]) throws AmosException { Connection.initializeAmos(argv); // Can only be called once to initialize the Amos II kernel Connection theConnection = new Connection(""); theConnection.amosTopLoop("JavaAMOS"); // Enters the AMOSQL top-loop } } Amos II must first be initialized with the method Connection.initializeAmos(String imageName) throws AmosException; The parameters specified on the command line are passed to the Amos II kernel through argv for interpretation. initial- izeAmos knows how to handle a user specified name of a database image from the command line parameters. If the initialization failed the system will throw the exception AmosException; it can be caught using Java’s exception handling mechanisms. In order to access an Amos II database an object of class Connection must be allocated first. The constructor takes the name of the Amos II database server to which the connection is to be established as parameter. If the empty string in specified, as in the example, it indicates a tight connection to an embedded local Amos II database. If a client-server connection is to be established this constructor takes the name of the Amos II server to connect to as parameter. To enter the interactive AmosQL top loop from C, call the method void amosTopLoop(String prompt); amosTopLoop returns if the AmosQL command ’exit;’ is executed. By contrast, the AMOSQL command ’quit;’ termi- nates the program.