java.sql
Annotation Type Select

@Documented
@Target(value=METHOD)
@Retention(value=RUNTIME)
public @interface Select

Annotation used to decorate a method in a Query interface with a SQL statement that can return a result set from the underlying data store. The Select annotation must not be used in-conjunction with a SQL statement that returns an update count.

A Query interface may contain zero, one or more methods decorated with an Select annotation.

The following provides an example of using the Select annotation.

 // Define DataSet type
 public class Mammal {
     public String name;
     public String description;
     public int age;
 }
 // Define the interface containing the methods representing SQL statements
 // that can be invoked.
 
 interface MyQueries extends BaseQuery {    
    @Select("select name, description, age from mammal")
    DataSet<Mammal> getAllMammals();
 
    @Update("delete from mammal")
    int deleteAllMammals();
 }
 

 MyQueries mq = con.createQueryObject(MyQueries.class);
 Dataset<Mammal> rows = mq.getAllMammals();
 

Using a Parameterized sql annotation element

• A String value designated by a question mark(?) prefix follwed by an integer.
• The numbering for parameter markers starts at 1. For example ?1.
• The number of distinct parameter marks must not exceed the number of method parameters for the method that was decorated by the Select annotation. If this occurs, a SQLRuntimeException will be thrown.
• A parameter marker may be specfied more than once in a sql annotation element.

 interface MyQueries extends BaseQuery {    
 
    @Select(sql="select name, description from mammal where weight > ?1")
     DataSet<Mammal> getBigMammals(int weight);
 }
 

 MyQueries mq = con.createQueryObject(MyQueries.class);
 DataSet<Mammal> rows = mq.getBigMammals(200);
 

When the getBigMammals() method is invoked, the value specified for the parameter weight will be used as the value for the parameter marker.

connected annotation element

If the connected annotation element is set to false, the returned DataSet instance is considered to be disconnected. The DataSet is then treated similar to a CachedRowSet and any modifications to the DataSet are not propogated to the data source until the DataSet.sync method is called.

allColumsMapped annoation element

Consider the following example:

 public class Mammal {
     public String firstName;
     public String lastName;
     public String address;
     public String description;
 }
 public class MammalFail {
     public String name;
     public String description;
     public int age;
 }

 interface Queries {
     @Select(sql="select * from Mammal", allColumnsMapped=true)
     DataSet<Mammal> getAllMammals();
     @Select(sql="select * from Mammal", allColumnsMapped=true)
     DataSet<MammalFail> getAllMammals2();
 }
 

 -----------------------------------------------------------
 |firstName | lastName  | address           | description    |
 ===========================================================
 | homer    | simpson   | Springfield       | Average Joe    | 
 -----------------------------------------------------------
 | fred     | flintsone | San Francisco, CA | stoneage human |
 -----------------------------------------------------------
 | wombat   | jones     | Aspen, CO         | wombat         |
 ============================================================
 

The call to the getAllMammals2 method will result in a SQLRuntimeException being thrown because the data class MammalFail does not contain a field for every column in the result set that is returned by the query specified in the sql annotation element. The fields firstName, lastName and address would need to be added to the data class MammalFail in order for the call to the getAllMammals2 method to succeed.

Since:

1.6

Optional Element Summary
boolean	allColumnsMapped           Determines whether all of the columns that are returned as part of a result set for the SQL command specified in the sql annotation element, are required to be present in the data class for a DataSet.
boolean	connected           Determines whether the returned DataSet is connected to the underlying data store.
boolean	readOnly           Determines if the returned DataSet is updatable.
boolean	scrollable           Determines whether a connected DataSet is scrollable.
String	sql           The SQL command to execute.
String	tableName           Specifies the name of the table from where this data is to be written back to.
String	value           The SQL command to execute.

 

sql

public abstract String sql

The SQL command to execute. The SQL command that is specified can return a result set. The SQL command must not return an update count.

Note: If the sql and the value annotation element are specified at the same time, a SQLRuntimeException will be thrown.

Returns:

a String representation of the SQL command.

Since:

1.6

Default:

""

readOnly

public abstract boolean readOnly

Determines if the returned DataSet is updatable.

Returns:

true if the returned DataSet cannot be modified; false otherwise

Since:

1.6

See Also:

DataSet.isReadOnly()

Default:

true

connected

public abstract boolean connected

Determines whether the returned DataSet is connected to the underlying data store.

Returns:

true if the returned DataSet is connected to the underlying data store; false otherwise.

Since:

1.6

See Also:

DataSet.isConnected()

Default:

true

allColumnsMapped

public abstract boolean allColumnsMapped

Determines whether all of the columns that are returned as part of a result set for the SQL command specified in the sql annotation element, are required to be present in the data class for a DataSet.

Returns:

false if the data class for a DataSet does not require a field for each column returned in result set; true if there must be a field present in the data class for every column returned in a result set.

Since:

1.6

Default:

false

value

public abstract String value

The SQL command to execute. The SQL command that is specified can return a result set. The SQL command must not return an update count.

Note: If the sql and the value annotation element are specified at the same time, a SQLRuntimeException will be thrown.

Returns:

a String representation of the SQL command.

Since:

1.6

Default:

""

scrollable

public abstract boolean scrollable

Determines whether a connected DataSet is scrollable. If the DataSet is scrollable, it has a ResultSet type of TYPE_SCROLL_INSENSITVE. If the DataSet is not scrollable, the ResultSet type is specified to be TYPE_FORWARD_ONLY.

If the DataSet is disconnected, the scrollable annotation element is ignored.

Returns:

true if the connected DataSet is scrollable; false otherwise.

Since:

1.6

See Also:

DataSet.isScrollable()

Default:

false

tableName

public abstract String tableName

Specifies the name of the table from where this data is to be written back to.

This annotation element is required when the DataSet is in disconnected mode and the contents of the DataSet can be written back to the database.

Note: If the connected annotation element is set to false, the readOnly annotation element is set to false and the tableName annotation element is not specified, a SQLRuntimeException will be thrown.

Returns:

name of the table from which the data in the DataSet can be be written back to.

Since:

1.6

Default:

""