The Enterprise JavaBeans query language, EJB QL, was introduced in the EJB 2.0 specification. It is used to define queries for entity beans that operate with container-managed persistence (CMP). EJB QL enables you to specify the semantics of query methods in a portable way.

For an Enterprise application, EJB QL can express queries for two different styles of operations:

• To express the semantics and exact operation of the finder methods defined in the home interface. Finder methods allow the results of an EJB QL query to be used by the clients of the entity bean. Previously, all but the simplest finder methods required the use of vendor-specific functionality to express rich queries.
• To select entity objects or other values derived from an entity bean’s abstract schema type through select methods defined on the entity bean class. Select methods allow you to use EJB QL to find objects or values related to the state of an entity bean without exposing the results to the client. These are queries that you make use of yourself inside of your bean's implementation methods.

This tutorial demonstrates the simple use of EJB QL for finder methods. It does not demonstrate the use of the select methods nor the traversal of entity relationships to form joins between objects.

To use EJB QL, you provide a string that contains a SELECT clause and a FROM clause, and optionally a WHERE clause. EJB QL is very similar to a subset of SQL, with a marginally different syntax. The query must be defined in an application's ejb-jar.xml file.

The following XML code maps a query to a findByEmail method in a bean's Home interface. The FBS sample application uses this query and method to find the user account that corresponds to a given email address. (For more information, see the Implementation section.)

<entity>
...
  <ejb-class>oracle.otnsamples.ibfbs.usermanagement.ejb.UserAccountBean</ejb-class>
...

  <abstract-schema-name>UserAccount</abstract-schema-name>
...
  <query>

    <query-method>
      <method-name>findByEmail</method-name> 
        <method-params> 
          <method-param>java.lang.String</method-param> 
        </method-params> 
    </query-method> 

    <ejb-ql>
      [!CDATA[
        SELECT DISTINCT object(ua) 
        FROM UserAccount ua 
        WHERE ua.email = ?1]]
    </ejb-ql> 

  </query>
...

In EJB QL the <abstract-schema-name> tag defines a value analogous to a table name in standard SQL. In the code above, the abstract schema name is UserAccount, and it maps to the bean named UserAccountBean.

EJB QL queries are implemented by the EJB container, which translates EJB QL statements to the appropriate database SQL statements when the application is deployed. Thus, the container is responsible for converting elements of the bean description to the appropriate database tables, primary keys, foreign keys, and column names. An EJB QL query is portable to any database supported by the container.

EJB QL uses the abstract persistence schemas of entity beans, including their relationships, for its data model. It defines operators and expressions based on this data model. EJB QL depends on navigation and selection based on the CMP-fields and CMR-fields of the related entity beans. You can navigate from an entity bean to other entity beans by using the names of CMR-fields in EJB QL queries.

Also, with a bean that uses CMP, the Home interface can include findAll and findByPrimaryKey methods. Each method performs a query under the hood, but the semantics and operation are managed entirely by the container. In fact, the EJB specification explicitly prevents you from trying to subvert its behavior by specifying the queries yourself.