12.6.2. EJB-QL Declaration

Every select or finder method (except findByPrimaryKey) must have an EJB-QL query defined in the ejb-jar.xml file. The EJB-QL query is declared in a query element, which is contained in the entity element. The following are the declarations for findBadDudes_ejbql and ejbSelectBoss_ejbql queries:

<ejb-jar>
    <enterprise-beans>
        <entity>
            <ejb-name>GangsterEJB</ejb-name> 
            <!-- ... -->
            <query>
                <query-method>
                    <method-name>
               findBadDudes_ejbql
            </method-name>
                    <method-params>
                        <method-param>int</method-param>
                    </method-params>
                </query-method>
                <ejb-ql><![CDATA[
                 
               SELECT OBJECT(g) FROM gangster g WHERE g.badness > ?1
            
                 ]]></ejb-ql>
            </query>
            <query>
                <query-method>
                    <method-name>
               ejbSelectBoss_ejbql
            </method-name>
                    <method-params>
                        <method-param>java.lang.String</method-param>
                    </method-params>
                </query-method>
                <ejb-ql><![CDATA[
                 
               SELECT DISTINCT underling.organization.theBoss FROM gangster underling WHERE underling.name = ?1 OR underling.nickName = ?1
            
                 ]]></ejb-ql>
            </query>
        </entity>
    </enterprise-beans>
</ejb-jar>

EJB-QL is similar to SQL but has some surprising differences. The following are some important things to note about EJB-QL:

EJB-QL is a typed language, meaning that it only allows comparison of like types (i.e., strings can only be compared with strings).
In an equals comparison a variable (single valued path) must be on the left hand side. Some examples follow:

g.hangout.state = 'CA' Legal
'CA' = g.shippingAddress.state 
               NOT Legal
            
'CA' = 'CA' 
               NOT Legal
            
(r.amountPaid * .01) > 300 
               NOT Legal
            
r.amountPaid > (300 / .01) 
               Legal

Parameters use a base 1 index like java.sql.PreparedStatement.
Parameters are only allowed on the right hand side of a comparison. For example:

gangster.hangout.state = ?1 
               Legal
            
?1 = gangster.hangout.state 
               NOT Legal