|
Version 4.10.0 | ||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
Object hirondelle.web4j.database.SqlId
public final class SqlId
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 :
Action
Design Note
The justification for recommending that SqlId fields appear in a
Action
is as follows :
Action
is always public anyway, so adding a SqlId will
not change its scope.
Action
is intended as the public face of each feature. Therefore,
all important items related to the feature should be documented there - what it does, when is it called, and
how it shows a response. One can argue with some force that the single most important thing about a
feature is "What does it do?". In a typical database application, the answer to that
question is usually "these SQL operations".
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 |
---|
public static final String FORMAT
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'.
Constructor Detail |
---|
public SqlId(String aStatementName)
aStatementName
- identifier of an SQL statement, satisfies FORMAT
,
and matches the name attached to an SQL statement appearing in an .sql file.public SqlId(String aDatabaseName, String aStatementName)
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 |
---|
public static SqlId fromStringId(String aSqlId)
aSqlId
- which may or may not be qualified by the database name.public String getDatabaseName()
If no database name was passed to the constructor, then return an empty String
(corresponds to the 'default' database).
public String getStatementName()
public String toString()
Example return values :
toString
in class Object
public boolean equals(Object aThat)
equals
in class Object
public int hashCode()
hashCode
in class Object
|
Version 4.10.0 | ||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |