All enterprise applications need to perform operations on the underlying datasource, and EJB 3 supports this with EJB Query Language or native query support.
Most of what you are going to read here is very similar to the Hibernate cartridge support for queries. There are a few differences which will be further discussed.
UML allows you to specify queries, be it in a more generic language. For this purpose OCL can be used, which supports body constructs since OCL 2.0. Although you can choose to override any generated query using a tagged value specifying your custom query, it is strongly recommended to use OCL since this will guarantee your code to remain portable over different technologies. If you don't want to get to know OCL and have no problem sticking to EJBQL then you might consider using tagged values instead.
Finder methods require the query flag to be set, usually operations with this flag have the commercial at symbol '@' in front of their name when displayed in diagrams. Make sure you model the operation in classifier scope, in diagrams this will show them as underlined and check the Query checkbox for the operation to indicate this is a finder method. By enabling this checkbox, the '@' symbol will appear in front of the operation in your model.
Remember that classifier scoped operations go into the DAO while instance scoped operations go into the entity's implementation class (they are considered to be business operations).
The documentation discussing the modeling of queries in OCL is found on the AndroMDA main project in Translation Libraries and Query Translation Library Modeling. The tagged value overriding queries using EJB QL directly is found here: andromda_ejb_query.
If you look at the Car and Person Java entities, you will notice that a set of @NamedQuery annotations define the named queries for each entity. By default the entityGenericFinders namespace property is enabled, therefore a findAll named query will always exist for every entity. Other named queries are either defined using AndroMDA's default creation or OCL.
It is important to note that until the ORM xml descriptor is available, named queries are defined in the class with the @Entity annotation. This has a drawback for entities with instance scoped operations where a mapped superclass contains most of the persistence mapping annotations, but the implementation class contains the @Entity and named query(ies) annotations. In this example, the Car entity is an example of this case. Because the isRented() operation is an instance scoped method, the named queries are defined in the Car.java implementation which extends the CarEmbeddable.java class. As a result, adding new finder methods to the Car entity will not generate these named query definitions since the implementation class is not overridden. This is not the case for the Person entity since it is always regenerated.
The DAO base classes provide the ability to use the named queries declared in the entities or by specifying the query manually. By default, unless you manually specify the query string, the DAO finder methods will use named queries, so keep this in mind when performing dynamic queries. The loadAll DAO operation also used the generic finder method named query definition.
Currently, named queries are defined in two ways. Either you let AndroMDA auto create your basic EJB QL for you, or use OCL to configure your query. Named queries will NOT be defined if you use the andromda_ejb_query tagged value. It would be suggested that a new tagged value i.e andromda_ejb_query_named be added to manually set the named query, but OCL is still the preferred solution.
In some circumstance it is convenient to have the option of using Hibernate criteria queries. This is particularly useful for search queries which are really on-the-fly queries. If you are using JBoss AS, then most likely you are using Hibernate as the persistence engine (unless you have changed this default behavior). Criteria queries are a Hibernate feature, so this is a strict requirement.
Before you can use criteria queries with the EJB3 cartridge, you must enable the persistenceProviderExtensions namespace property in the ejb3 namespace section of your andromda.xml application descriptor, like so:
<namespace name="ejb3">
<properties>
...
<property name="persistenceProviderExtensions">hibernate</property>
...
</properties>
</namespace>
You should also add the hibernate artifact dependency to your root project pom.xml as:
<dependencyManagement>
<dependencies>
...
<dependency>
<groupId>org.hibernate</groupId>
<artifactId>hibernate</artifactId>
<version>3.2.0.ga</version>
<scope>provided</scope>
</dependency>
...
<dependencies>
<dependencyManagement>
Then in the core sub-project, add the above dependency to avoid build errors when the org.hibernate.Session object is injected in the DAO base class.
By setting the persistenceProviderExtensions property value to hibernate, you are telling the EJB3 cartridge to use Hibernate add-on features and annotations. Specifically, this will inject the org.hibernate.Session into the auto-generated DAO base classes of your project like so:
@javax.persistence.PersistenceContext(unitName = "timetracker")
protected org.hibernate.Session hibernateSession;
You can then model a Classifier scoped operation in your Entity such that you can over-write the implementation in the DAOImpl (DAO implementation) and use the session object to create the criteria and perform the query.
To further understand this usage, you can take are look at the timetracker-ejb3 Timetracker EJB3 - JSF sample. The following segment of code is taken from this sample project showing you how similar it can be to the standard usage under the Hibernate/Spring cartridges; only difference being that the hibernate session is already injected into the DAO base class for you.
protected java.util.List handleFindByCriteria(org.andromda.timetracker.vo.TimecardSearchCriteriaVO criteria)
{
// Create the timecard criteria
Criteria timecardCriteria = hibernateSession.createCriteria(Timecard.class);
timecardCriteria.setFetchMode("submitter", FetchMode.JOIN);
timecardCriteria.setFetchMode("approver", FetchMode.JOIN);
// Add sumitter criteria
if (criteria.getSubmitterId() != null)
{
timecardCriteria.createCriteria("submitter").add(Restrictions.idEq(criteria.getSubmitterId()));
}
// Add approver criteria
if (criteria.getApproverId() != null)
{
timecardCriteria.createCriteria("approver").add(Restrictions.idEq(criteria.getApproverId()));
}
// Add status criteria
if (criteria.getStatus() != null)
{
timecardCriteria.add(Restrictions.eq("status", criteria.getStatus()));
}
// Add startDateMin criteria
if (criteria.getStartDateMin() != null)
{
timecardCriteria.add(Restrictions.ge("startDate", criteria.getStartDateMin()));
}
// Add startDateMax criteria
if (criteria.getStartDateMax() != null)
{
timecardCriteria.add(Restrictions.le("startDate", criteria.getStartDateMax()));
}
List timecards = timecardCriteria.list();
if (logger.isDebugEnabled())
{
logger.debug(timecards.size() + " timecards found");
}
return timecards;
}
It's allowed to override queries such as finders in the DAO, just override the appropriate method in an entity's DAO implementation class. What follows is an example of a code snippet overriding a generated EJBQL query (example taken from a fictitious UserDAOImpl class):
public List findActiveUsers(int transform)
{
// the next query is user-specified and overrides the one generated in super.findActiveUsers(int transform)
return super.findActiveUsers(transform, "from Users as user where user.exitDate is null");
}
You might consider doing this when you think the generated query is not performant enough, or when you need to do something which is so complex the OCL translation can't properly handle it.
The next section will cover the modeling of exceptions, click here to go to that section.