Working with mapped statements - iBATIS in Action - page 85

4.1.2 The SqlMap API

Now that you have an understanding of what JavaBeans are, we can start to look at
the API that i BATIS gives you for working with them. The SqlMapClient interface
has over 30 methods on it, and we will get to all of them in the coming chapters.
But for now, let's look only at the parts of it that we will be using in this chapter.

The queryForObject() methods
The queryForObject() methods are used to get a single row from the database
into a Java object, and come with two signatures:
■ Object queryForObject(String id, Object parameter) throws SQLExcep-
tion;
■ Object queryForObject(String id, Object parameter, Object result)
throws SQLException;

The first version is the more commonly used one, and creates the returned object
for you if it has a default constructor (and throws a runtime exception if it does not).
The second form accepts an object that will be used as the return value—after
running the mapped statement the properties will be set on it instead of creating
a new object. The second form is useful if you have an object that cannot be easily
created because of a protected constructor or the lack of a default constructor.
Something to remember when using queryForObject() is that if the query
returns more than one row, this method will throw an exception, because it
checks to make sure that only one row is returned.

The queryForList() methods
The queryForList() methods are used to get one or more rows from the database
into a List of Java objects, and like queryForObject() , they also come in two versions:
■ List queryForList(String id, Object parameter) throws SQLException;
■ List queryForList(String id, Object parameter, int skip, int max)
throws SQLException;

The first method returns all of the objects that are returned by the mapped state-
ment. The second returns only a subset of them—it skips ahead up to the number
indicated by the skip parameter, and returns only max rows from the query. So, if
you have a mapped statement that returns 100 rows but you only want the first set
of 10 rows, you can pass in 0 for skip and 10 for max to get them. If you want the
second set of 10 records, you can repeat the call with a value of 10 for skip to get
the next 10 rows.