Find this tutorial in:
Try the Tutorial
Scenario: Headmaster Dumbledore needs a database of Courses.
This example focuses on:
Note: The EJB 3.0 Basic tutorial describes the same example for EJB 3.0. You can compare the two tutorials to help evaluate which technology best suits your application.
Resin-CMP manages tables in a relational database using a Java bean interface. Each database table corresponds to a single "entity bean". (Since Resin-CMP uses the EJB specification, most of its jargon comes from EJB.) By creating an entity bean with container managed persistence, you let Resin-CMP generate the SQL to load, store, and cache entity beans from the database. Avoiding SQL is an advantage in itself, but the primary advantage is the increased flexiblity of your application code. Maintenance and code-refactoring can focus on the beans instead of changing lots of SQL statements in the program.
In this example, Hogwarts School of Witchcraft and Wizardry uses Resin-CMP to manage its list of courses offered for the term. Each course has a name and a teacher for the course. The example has been simplified as much as possible; following examples show how to query the database and create and remove database entries.
The database table uses the course name as the primary key. Each bean in Resin-CMP needs its own primary key. It is possible to let the database generate primary keys, e.g. automatically generated integers. Since this example only reads data from the table, we'll prepopulate it with the courses.
Each table maps to a single object, using the abstract-schema-name and sql-table in the ejb.xml. If you look at the distribution's database schema (in cmp/WEB-INF/sql/default.sql), you'll notice that each example has its own table, e.g. basic_courses and find_courses, even though the examples often share the same table. Generally a Resin-CMP bean has complete control over a database table. Because it controls the table, the bean can cache data without worrying that the database will change without its knowledge.
Database columns map to accessor methods in the bean, using standard rules. The id field maps to getId. The instructor column maps to getInstructor and setInstructor.
Each database table corresponds to a single "entity bean". Since Resin-CMP uses the EJB specification, most of its the jargon comes from EJB. The developer needs to write three classes for each entity bean:
Why three classes? The interfaces add code clarity for the developer and flexibility for Resin-CMP. It's conceptually cleaner to separate the interfaces of the bean from its implementation. It's also cleaner to separate the factory pattern interface from the object interface. Separating the classes gives Resin-CMP the flexibility to add its caching and transaction code without requiring any client changes.
Resin-CMP focuses on, as opposed to the of traditional EJB. Local interfaces are used in a single servlet web-application and avoid the complexities of distributed computing. In addition, local interfaces are faster since they can use normal pass-by-reference Java calls. In this way, Resin-CMP turns EJB on its head. EJB is a distributed computing interface with support for object-managed databases. Resin-CMP provides an object view to relational database, and has support for distributed calls for those rare applications which really need it.
The home interface is reponsible for factory pattern methods: finding existing objects and creating new objects. At minimum, each home interface lets you find an object using its primary key. The findByPrimaryKey method exists for any entity bean. Like all the find methods, Resin-CMP will generate the implementation code and SQL for findByPrimaryKey. We just need to add the method to the interface.
Find methods always return the local interface for the bean or a collection of local interfaces and always throw the FinderException.
Each home interface must extend the EJBLocalHome interface. Local home interfaces can only be used same web-application as the server. This makes it a perfect solution for servlet-based database applications.
The local interface, Course, is where all the action is. We expose three methods to clients, getCourseId, getInstructor and setInstructor. Local interfaces always extend EJBLocalObject.
Clients always use the home interface to get the local interface. The Resin-CMP generated stub (the class implementing the interface) will call the underlying implementation bean and SQL, adding transaction management as necessary.
Since Resin-CMP provides most of the implementation code, the Bean implementation just has a bunch of abstract methods. More complicated beans will add business methods to the entity bean's implementation class. Because business methods run in a single transaction context, you can use them to ensure database consistency without having to write any transaction code yourself.
The field accessors are abstract since Resin-CMP will generate the code to call JDBC and execute the SQL queries. Like all entity beans, clients never use a CourseBean directly, but always work through a stub generated by Resin-CMP.
The AbstractEntityBean class is a convenience class in Resin-CMP. Each entity bean must implement the EntityBean interface which has several methods. Since most applications don't need to customize the methods, AbstractEntityBean simplifies the implementation code.
With Resin-EJB, all the Java source can be dropped in WEB-INF/classes. Resin will automatically compile any changes and regenerate the persistence classes, stubs and skeletons.
The deployment descriptor configures the entity bean. It specifies the home, local, and implementation classes.
The *.ejb file is generally defined by the bean provider, i.e. whoever creates the bean. Later, we'll also need to attach the bean to the webserver as described in the following section. Deploying the bean is as easy as dropping the *.ejb in WEB-INF. When the web-app reloads, EJBServer will automatically pick up the *.ejb. (You may need to force a reload by touching a class file.)
names the abstract table for the entity bean. If no other mapping is specified, it will be used for the SQL table. In the example, it's set to "basic_courses". If the abstract-schema-name is missing, Resin-CMP will use the ejb-name for the database table. You can add a sql-table to specify a different SQL table. sql-table is a Resin-CMP extension.
Database fields are converted from the get and set accessor names using a beans-like mapping. "get" is removed and the uppercased character is lower cased. Resin-EJB will convert any xY pattern to "x_y". So getId maps to the SQL column "id". You can specify a sql-column to specify the SQL column:
Now that we've built the bean, we need to attach it to Resin. The entity bean is deployed using the EJBServer resource.
The database needs to be configured using XADataSource instead of the usual DataSource. The reason is that XADataSource enables transactions in the database. DataSource is not transaction aware. So if there's a conflict or some other need to roll back the transaction, you need XADataSource and the database's transaction ability to protect the database consistency.
Now that we've defined the EJB, we should go ahead and use it. Because we haven't defined any method to find all the courses, we need to know them beforehand.
Because everything is defined in the web.xml, we just need to know that the CourseHome is at java:comp/env/cmp/house. So servlet code can be completely independent of the server deployment. Because the JNDI lookup is relatively slow, applications generally lookup the Home interface in the init() interface and store it as a servlet variable.
The core of Resin-CMP's database management is its management of a single table. Much of the work underlying the database management is hidden from the applicaton. Transaction management and caching happen automatically. For example, once the course has been loaded from the database, Resin-CMP does not need to query the database again until the course changes. So read-only requests, the most common, can avoid all database traffic.
More complicated applications build on the single table management. The following examples add more realistic features to this example: using queries to find all courses and creating new database rows.