ATerm Database Interface
XT -- A Bundle of Program Transformation Tools
Description
The
SATerm Database Interface? (aterm-dbi) offers an
ATermServices look on a relational database.
aterm-dbi uses Java Stratego.ATerm Servlets.
Interface
Currently there is just a query service. It is accessible on the URL
aterm-dbi/query
. The query service
is an
ATermService . It accepts a
Query
term in the body of a HTTP POST request and returns the result of
the query in the body of the reponse.
For example this query:
Query("SELECT ID, Name FROM Customer")
Might result in this
ResultSet
:
ResultSet(
MetaData(
Columns(
[ Column(Name("id"), Type(Std("INTEGER"), Db("int4")))
, Column(Name("name"), Type(Std("CHAR"), Db("bpchar")))
]
)
)
, Data(
[ Row([160, "Meindert Kroese"])
, Row([159, "Steven van Dijk"])
, Row([158, "Martijn Schrage"])
, Row([157, "Sandor Spruit" ])
]
)
)
The Stratego.ATerm Database Interface rewrites values of SQL types to an Stratego.ATerm representation.
The current implementation can just handle integer types (INTEGER, SMALLINT, and BIGINT) and string types (CHAR, VARCHAR, and LONGVARCHAR). This will be extended in the future to handle all SQL data types.
Invocation
From Stratego you can invoke the services of aterm-dbi with the
http-transform
strategy of
StrategoNetworking.
There is one problem: the Java implementation of the
ATermLibrary doesn't provide a reader for BAF, the
Binary Stratego.ATerm Format?. Because of this format is very efficient, it is used by
XTC by default. You should thus invoke the services of aterm-dbi in TAF, the
Textual Stratego.ATerm Format?. You could do this with this strategy:
http-text-transform(service-url) =
xtc-temp-files(
write-to-text
; xtc-http-transform(service-url)
; read-from
)
Invocation of the query service of aterm-dbi:
<http-text-transform(!URL("http://127.0.0.1:8080/aterm-dbi/query"))>
Query("SELECT ID, Name FROM Customer")
Download
You can download the latest release at:
The
war
file is a Java Web Archive, a binary distribution. You can immediately put this file in your servlet container. The .tar.gz files are source distributions. You need
Ant to build the sources.
You can also get the latest sources from the Subversion repository:
svn checkout %SVNSTRATEGOXT%/trunk/experimental/aterm-dbi
See
latest sources? for more information on how to checkout packages from the
StrategoXT subversion repository.
In the samples package of
Stratego Networking? you can find some samples in the
xmpl/aterm-dbi
directory (unreleased, use the Subversion repository).
Implementation
aterm-dbi is a J2EE application. It uses a JDBC
DataSource
that is made available by the application server it is hosted in via the JNDI.
Advantages of this approach:
- by using techniques developed for database servers that should be able
to handle a lot of requests, the Stratego.ATerm Database Interface scales very well.
- You don't need to modify any Java code to use a different database
managament system, or one at a different location.
Installation
You should be able to run the Stratego.ATerm database interface on any J2EE Application
Server and using any database system implementation (as long as there is a
JDBC 3 driver available).
I will provide instructions for a configuration where I'm using
Tomcat 5 and PostgreSQL. Please consult the documentation of the application
and database server if you choose other software.
Basic applications
First of all you need a
PostgreSQL database. You need version 7.2 or 7.3.
Please refer to the documentation of PostgreSQL if you need to install
the database system by yourself.
You need a
Java 2 SDK to run Tomcat. It is wise to use
a recent release (version 1.4.x). Make sure the environment variable
JAVA_HOME points to the location where you installed your J2SDK.
Next, you need
Tomcat 5. Tomcat 4 will not do the job! Installation of
Tomcat 5 is very straightforward nowadays.
Configuration and extension
Now the basic components of Java based database application
are available, now comes the Stratego.ATerm database interface specific part.
You need a
JDBC3 driver for your DBMS, in this case the
JDBC3 driver for PostgreSQL.
Put it in the
common/lib
directory of your Tomcat installation.
Now it's finally time to install the web archive (.war) of aterm-dbi. You should
put this war in the
webapps
directory of Tomcat.
We still have to configure Tomcat with the database you want to use.
This is application server and database specific, so you will probably
need to consult some other documentation.
In Tomcat you should add this to the
Host
element with the
name
attribute
localhost
:
<Context path="/aterm-dbi" docBase="aterm-dbi.war" debug="5" reloadable="true">
<Logger className="org.apache.catalina.logger.FileLogger"
prefix="aterm-dbi-log."
suffix=".txt"
timestamp="true"/>
<Resource name="jdbc/aterm-dbi"
auth="Container"
type="org.postgresql.jdbc3.Jdbc3PoolingDataSource"/>
<ResourceParams name="jdbc/aterm-dbi">
<parameter>
<name>factory</name>
<value>org.postgresql.jdbc3.Jdbc3ObjectFactory</value>
</parameter>
<parameter>
<name>databaseName</name><value>.....</value>
</parameter>
<parameter>
<name>serverName</name><value>127.0.0.1</value>
</parameter>
<parameter>
<name>user</name><value>....</value>
</parameter>
<parameter>
<name>password</name><value>.....</value>
</parameter>
</ResourceParams>
</Context>
Of course you should fill in your database-, server-, and username and your password.
We've chosen the
PoolingDataSource
implementation of the PostgreSQL JDBC driver,
but if your application server offers a connection pooling implementation
which interfaces with a
ConnectionPoolDataSource
, you should choose that option.
Todo or might do
- Implement services for inserts, updates and deletes. Maybe use terms instead of concrete syntax in some cases.
- Convert more SQL data types like bit, boolean, dates etc.
- Conceptually it is much more attractive to send an AST representation of the SQL statements to the ATermService instead of concrete syntax for SQL in an Stratego.ATerm wrapper. This would be an excellent combination with the use of ConcreteSyntax for SQL in Stratego. This would at compile-time ensure syntactical correctness of the SQL statements. There are some problems:
- Many SQL statements use database specific constructs. The practical use of the Stratego.ATerm Database Interface? would decrease if we would enforce standard SQL.
- We need a PrettyPrinter on the server-side, because the database system (well, JDBC) just accepts concrete syntax for SQL.
- We need a SQL syntax definition (but a starting-point is already available)
--
MartinBravenboer - 10 Mar 2003