Version 4.10.0

hirondelle.web4j.database
Class SqlId

Object
  extended by hirondelle.web4j.database.SqlId

public final class SqlId
extends Object

Identifier of an SQL statement block in an .sql file. (Such identifiers must be unique.)

This class does not contain the text of the underlying SQL statement. Rather, this class allows a code friendly way of referencing SQL statements. Since .sql files are simple text files, there is a need to build a bridge between these text files and java code. This class is that bridge.

Please see the package summary for important information regarding .sql files.

Typical use case :

public static final SqlId MEMBER_FETCH = new SqlId("MEMBER_FETCH");
This corresponds to an entry in an .sql file :
MEMBER_FETCH {
  SELECT Id, Name, IsActive, DispositionFK 
  FROM Member WHERE Id=?
}

This class is unusual, since there is only one way to use these objects. That is, they must be declared as public static final fields in a public class. They should never appear only as local objects in the body of a method. (This unusual restriction exists to allow the framework to find and examine such fields using reflection.) The text passed to the constructor must correspond to the identifier of some SQL statement block in an .sql file. Such identifiers must match a specific FORMAT.

Startup Checks
To discover simple typographical errors as quickly as possible, the framework will run diagnostics upon startup : there must be an exact, one-to-one correspondence between the SQL statement identifiers defined in the .sql file(s), and the public static final SqlId fields declared by the application. Any mismatch will result in an error. (Running such diagnostics upon startup is highly advantageous, since the only alternative is discovery during actual use, upon the first execution of a particular operation.)

Where To Declare SqlId Fields
Where should SqlId fields be declared? The only real restriction is that they must be declared in a public class. With the most recommended first, one may declare SqlId fields in :

Design Note
The justification for recommending that SqlId fields appear in a Action is as follows :


Field Summary
static String FORMAT
          Format of SQL statement identifiers.
 
Constructor Summary
SqlId(String aStatementName)
          Constructor for statement against the default database.
SqlId(String aDatabaseName, String aStatementName)
          Constructor for statement against a named database.
 
Method Summary
 boolean equals(Object aThat)
           
static SqlId fromStringId(String aSqlId)
          Factory method for building an SqlId from a String which may or may not be qualified by the database name.
 String getDatabaseName()
          Return aDatabaseName passed to the constructor.
 String getStatementName()
          Return aStatementName passed to the constructor.
 int hashCode()
           
 String toString()
          Return the SQL statement identifier as it appears in the .sql file.
 
Methods inherited from class Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
 

Field Detail

FORMAT

public static final String FORMAT
Format of SQL statement identifiers.

Matching examples include :

One or more letters/underscores, with possible trailing digits.

To scope an SQL statement to a particular database, simply prefix the identifier with a second such identifier to represent the database, separated by a period, as in 'TRANSLATION_DB.ADD_BASE_TEXT'.

See Also:
Constant Field Values
Constructor Detail

SqlId

public SqlId(String aStatementName)
Constructor for statement against the default database.

Parameters:
aStatementName - identifier of an SQL statement, satisfies FORMAT, and matches the name attached to an SQL statement appearing in an .sql file.

SqlId

public SqlId(String aDatabaseName,
             String aStatementName)
Constructor for statement against a named database.

Parameters:
aDatabaseName - identifier for the target database, satisfies FORMAT, matches one of the return values of ConnectionSource.getDatabaseNames(), and also matches the prefix for a aStatementName. See package overview for more information.
aStatementName - identifier of an SQL statement, satisfies FORMAT, and matches the name attached to an SQL statement appearing in an .sql file.
Method Detail

fromStringId

public static SqlId fromStringId(String aSqlId)
Factory method for building an SqlId from a String which may or may not be qualified by the database name.

Parameters:
aSqlId - which may or may not be qualified by the database name.

getDatabaseName

public String getDatabaseName()
Return aDatabaseName passed to the constructor.

If no database name was passed to the constructor, then return an empty String (corresponds to the 'default' database).


getStatementName

public String getStatementName()
Return aStatementName passed to the constructor.


toString

public String toString()
Return the SQL statement identifier as it appears in the .sql file.

Example return values :

Overrides:
toString in class Object

equals

public boolean equals(Object aThat)
Overrides:
equals in class Object

hashCode

public int hashCode()
Overrides:
hashCode in class Object

Version 4.10.0

Copyright Hirondelle Systems. Published October 19, 2013 - User Guide - All Docs.