Property-based Persistent Object
Resin 3.0

Features
Installation
Configuration
Web Applications
IOC/AOP
Resources
JSP
Quercus
Servlets and Filters
Databases
Admin (JMX)
CMP
EJB
Amber
EJB 3.0
Security
XML and XSLT
XTP
JMS
Performance
Protocols
Third-party
Troubleshooting/FAQ

Amber
Lifecycle
@Table
Tutorials

CMP Field
CMP Basic
CMP Create
Transactions
CMP Query
CMP Many-to-One
CMP One-to-Many
CMP Many-to-Many
CMP Inherit
Sessions
CMP Field
Tutorials
CMP Create

Find this tutorial in: /usr/local/resin/webapps/resin-doc/amber/tutorial/cmp-basic
Try the Tutorial

Basic persistence example showing configuration, classes, and client code for a single-table bean.

This example focuses on:

  • Introduces persistence fundamental concepts
  • Setting up the database
  • Developing the Entity classes
  • Developing a Servlet to lookup and use the entity bean
  • Configuring Resin to deploy the bean and use JNDI

  1. Files in this tutorial
  2. Database Schema
  3. Overview
  4. Bean Implementation
  5. Resin Configuration
  6. persistence.xml
  7. Client Servlet
  8. Conclusion

Amber's persistence manages tables in a relational database using a Java bean interface. Each database table corresponds to a single "entity bean". By creating an entity bean with container managed persistence, you let Amber 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.

Files in this tutorial

WEB-INF/resin-web.xml resin-web.xml configuration
WEB-INF/classes/META-INF/persistence.xml persistence.xml configuration
WEB-INF/classes/example/CourseBean.java The course bean
WEB-INF/classes/example/CourseServlet.java The course servlet

Database Schema

course.sql
CREATE TABLE basic_courses (
  id INTEGER PRIMARY KEY auto_increment,

  course VARCHAR(250),
  teacher VARCHAR(250)
);

INSERT INTO basic_courses VALUES('Potions', 'Severus Snape');
INSERT INTO basic_courses VALUES('Transfiguration', 'Minerva McGonagall');

Overview

To find and enhance a persistent Java bean, Amber follows the following procedure.

  1. <ejb-server> in the resin-web.xml configures Amber to start looking for persistence.xml in the classpath.
  2. The persistence.xml in WEB-INF/classes/META-INF tells Amber to create a persistence-unit named "example".
  3. The "example" persistence-unit contains a class example.CourseBean
  4. Amber enhances example.CourseBean as a persistent object.

By the end of initialization time, Amber has enhanced CourseBean and made it available to the application in the persistence-unit "example".

A servlet will then lookup the CourseBean with the following procedure:

  1. Obtain an EntityManager for the persistence unit from JNDI either directly as java:comp/env/persistence/PersistenceContext/example, or using the @PersistenceUnit injection annotation.
  2. Use the EntityManager to find the instance of the bean.

Bean Implementation

CourseBean.java
package example;

import javax.persistence.*;

@Entity 
@Table (name="amber_basic_course")
public class CourseBean {
  private int _id;
  private String _course;
  private String _teacher;

  @Id 
  @Column (name="id")
  @GeneratedValue 
  public int getId()
  {
    return _id;
  }

  public void setId(int id)
  {
    _id = id;
  }

  @Basic 
  public String getCourse()
  {
    return _course;
  }

  public void setCourse(String course)
  {
    _course = course;
  }

  @Basic 
  public String getTeacher()
  {
    return _teacher;
  }

  public void setTeacher(String teacher)
  {
    _teacher = teacher;
  }
}

With Resin, 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.

Resin Configuration

Now that we've built the bean, we need to attach it to Resin. The entity bean is deployed using the ejb-server resource.

WEB-INF/resin-web.xml
<web-app>
  <!-- server configuration -->
  <ejb-server data-source="jdbc/resin"/>

  <servlet servlet-name="basic" servlet-class="example.CourseServlet"/>

  <servlet-mapping url-pattern="/basic" servlet-name="basic"/>
</web-app>

persistence.xml

The persistence.xml lives in META-INF/persistence.xml. Since we're developing in WEB-INF/classes, the file will be in WEB-INF/classes/persistence.xml.

WEB-INF/classes/META-INF/persistence.xml
<persistence xmlns="http://java.sun.com/xml/ns/persistence" version="1.0">
  <persistence-unit name="example">
    <class>example.CourseBean</class>

    <exclude-unlisted-classes/>
  </persistence-unit>
</persistence>

Client Servlet

CourseServlet.java
import javax.persistence.*;

public class CourseServlet extends HttpServlet {
  @PersistenceUnit(name="example")
  private EntityManager _manager;

  public void service(HttpServletRequest req, HttpServletResponse res)
    throws java.io.IOException, ServletException
  {
    PrintWriter out = res.getWriter();

    res.setContentType("text/html");

    CourseBean []course = new CourseBean[2];

    course[0] = _manager.find(CourseBean.class, new Integer(1));
    course[1] = _manager.find(CourseBean.class, new Integer(2));

    out.println("<h3>Course Details</h3>");

    for (int i = 0; i < course.length; i++) {
      out.println("course: " + course[i].getCourse() + "<br>");
      out.println("teacher: " + course[i].getTeacher() + "<br>");
      out.println("<br>");
    }
  }
}

Course Details

course: Potions instructor: Severus Snape course: Transfiguration instructor: Minerva McGonagall

Conclusion

The core of Amber's persistence 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, Amber 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.

Try the Tutorial


CMP Field
Tutorials
CMP Create
Copyright © 1998-2006 Caucho Technology, Inc. All rights reserved.
Resin® is a registered trademark, and HardCoretm and Quercustm are trademarks of Caucho Technology, Inc.