Find this tutorial in:
Try the Tutorial
Scenario: Headmaster Dumbledore needs to list all the courses and find the Potions instructor.
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 findAll and findByInstructor methods use 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 nameis 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 findByPrimaryKey, the collection-valued findAll, and the single-argument findByInstructor. 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.
The findAll method returns all the courses in the database as a collection. The client code just iterates through the courses.
findByInstructor returns the course taught by an instructor. Single-valued finder methods expect to return exactly one bean. If there are no matching courses, findByInstructor throws an ObjectNotFoundException. If more than one courses are taught by the instructor, it will throw a FinderException.
The CourseHome interface defines the findAll and findByInstructor methods. As with findByPrimaryKey, the 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 thesection. Although we've specified the SQL mapping using the sql-table and sql-column elements, the queries use the abstract names.