com.opengamma.elsql (ElSql 1.3 API)

Package

Class

Use

Tree

Deprecated

Index

Help

PREV PACKAGE NEXT PACKAGE

FRAMES NO FRAMES

Package com.opengamma.elsql

A library to manage SQL external to the application.

See:
Description

Interface Summary
SqlParams	Provides access to SQL parameters.

Class Summary
ElSql	Main entry point, providing access to a bundle of elsql formatted SQL.
ElSqlBundle	Entry point integrated with the Spring framework, providing access to a bundle of elsql formatted SQL.
ElSqlConfig	Configuration that provides support for differences between databases.
MapSqlParams	Provides access to SQL parameters from a map.
SpringSqlParams	Provides access to SQL parameters from Spring.

Package com.opengamma.elsql Description

A library to manage SQL external to the application.

This package contains a standalone library for managing SQL.

There are a number of techniques for creating SQL within an application. The main ones are:

an Object Relational Mapper framework, such as Hibernate
appending Strings, such as sql = "SELECT foo " + "FROM bar " + "WHERE ..."
using a fluent API library, with methods like select("foo").from("bar").where(..)
reading in an external file, such as a properties file

This library focuses on the last of these, using an external file. It is a standalone library with no dependencies.

The key benefit is a simple external file that a DBA can understand, something which is invaluable for later maintenance and debugging.

The file format is a file which typically has the suffix ".elsql". Here is an example highlighting the structure:

  -- an example comment
  @NAME(SelectBlogs)
    SELECT @INCLUDE(CommonFields)
    FROM blogs
    WHERE id = :id
      @AND(:date)
        date > :date
  @NAME(CommonFields)
    title, author, content

two dashes are used for comments
tags start with the @ symbol
the primary blocks are @NAME(name) - the name refers to the block
indentation is used to create blocks - indented lines "belong" to the parent less-indented line
variables start with a colon
the various tags aim to handle over 80% of your needs

These are the tags:

@NAME(name)
The name tag creates a named block which can be referred to from the application or another part of the elsql file. The tag must be on a line by itself.

@INCLUDE(nameOrVariable)
The include tag includes the contents of a named block or a variable (prefixed by colon). The tag may be embedded in the middle of a line.

@WHERE
The where tag works together with the and/or tags to build dynamic searches. The tag will output an SQL WHERE, but only if there is at least some content output from the block. Normally, the where tag is not needed, as there is typically always one active where clause. The where tag must be on a line by itself.

@AND(expression), @OR(expression)
These tags are equivalent and output SQL AND or OR. The block that the tag contains is only output if the expression is true. The output SQL will avoid outputting the AND or OR if it immediately follows a WHERE. The and/or tag must be on a line by itself.

The expression is evaluated as follows. If the variable does not exist, then the result is false. Otherwise, if the expression is (:foo) and foo is a boolean, then the result is the boolean value. Otherwise, if the expression is (:foo) and foo is not a boolean, then the result is true. Otherwise, if the expression is (:foo = bar) then the result is true if the variable equals "bar" ignoring case.

@LIKE sqlWithVariable
@LIKE(variable)
The like tag adds either an SQL = or an SQL LIKE based on the specified variable. If the tag has no variable in brackets, then the text between the like tag and the end of the line is parsed for a variable. This tag can differ by database, so the actual SQL is generated by the configuration class.

@ENDLIKE
The end-like tag is used on rare occasions to scope the end of the like tag. Normally, the SQL should be written such that the end of the like tag is the end of the line.

@EQUALS sqlWithVariable
@EQUALS(variable)
The equals tag adds either an SQL = or an SQL IS NULL based on the specified variable. If the tag has no variable in brackets, then the text between the equals tag and the end of the line is parsed for a variable.

@ENDEQUALS
The end-equals tag is used on rare occasions to scope the end of the equals tag. Normally, the SQL should be written such that the end of the equals tag is the end of the line.

@PAGING(offsetVariable,fetchVariable)
The paging tag adds the SQL code to page the results of a search. These can differ by database, so the actual SQL is generated by the configuration class. The tag bases its actions on the specified integer variables which should begin with a colon. This replaces the OFFSETFETCH/FETCH tags in most situations as it enables window functions to be used where necessary.

@OFFSETFETCH
@OFFSETFETCH(offsetVariable,fetchVariable)
The offset-fetch tag adds the SQL OFFSET and FETCH clauses for paging results. These can differ by database, so the actual SQL is generated by the configuration class. The tag bases its actions on the specified integer variables which should begin with a colon. The names "paging_offset" and "paging_fetch" are used if the variables are not specified.

@FETCH(fetchVariable)
The fetch tag adds the SQL FETCH clause. It works as per the offset-fetch tag.

To use the library, simply obtain an instance of ElSql and call getSql().