Most applications need to query the database to find entities with special properties. With the query language EJB-QL, entity beans can define find methods in the home interface to look up beans with arbitrary properties.
The container managed fields in the previous example is great if you already know which entity bean to use, but in most applications the database entries are not hardcoded. Finding the right bean in the first place requires a query language.
Adding a find method has two steps:
Resin-CMP uses the EJB-QL query language from the EJB 2.0 specification. EJB-QL resembles SQL with a few restrictions and extensions appropriate to handling entity beans. For example, EJB-QL extends SQL with direct support for relations and for method arguments.
In the following example, the school's headmaster needs to know which courses are being taught and needs to find the course taught by a named teacher.
The example uses the same database table as the previous basic example.
the EJB Query Language (EJB-QL) to select a teacher from the
database. EJB-QL resembles a restricted SQL, but adds direct support
for relations and function arguments.
The findAll method finds all the courses in the database. The schema name is from the abstract-schema-name. The field is the cmp-field name. These names are not necessarily the same as the SQL table and columns. If the deployment changes the SQL table and columns, the EJB-QL still refers to the same abstract names.
findByInstructor uses the method's argument to select the course by the instructor. Since the instructor is an argument, it needs to be specified in the query. The EJB-QL syntax for a function argument is , where is the argument number, starting at 1.
The example servlet uses three finders: the usual
, and the
. Find methods always return the
local interface, either as a single value or a collection. The pairing of
the local object and its home interface matches the home interfaces's role
as a factory pattern. (Remote home
finders always return the remote interface or a collection of the
remote interface.) If applications need to return other values,
including other local beans, they need to use ejbSelect methods.
method returns all the courses in the database as a
collection. The client code just iterates through the courses.
returns the course taught by an
instructor. Single-valued finder methods expect to return exactly
one bean. If there are no matching courses,
. If more than one courses are taught
by the instructor, it will throw a
interface defines the
methods. As with
implementation bean does not implement the method. Resin-CMP will
generate that code automatically.
The other classes are included for completeness, but follow the same idea as in the persistent field tutorial.
The main new feature of the deployment descriptor is the /> section. Although we've specified the SQL mapping using the sql-table and sql-column elements, the queries use the abstract names.