Amber
Amber
Amber
Lifecycle
Tutorials
Basic Amber
Create/Destroy
Find/Query
Many-To-One
One-To-Many
Tutorials
Tutorials
Create/Destroy
Find this tutorial in: /usr/local/resin/resin-3.0.12/webapps/resin-doc/amber/tutorial/basic
Try the Tutorial

Introduces Amber with a single-table bean, describing everything needed to configure and start Amber.

This example focuses on:

  • Introduces Amber fundamental concepts
  • Configuring Amber as a Resin resource in JNDI
  • Developing the Bean classes
  • Developing a Servlet to lookup and use the bean

  1. Files in this tutorial
  2. Database Schema
  3. Implementation Class
  4. Configuration
  5. Resin Configuration
  6. Client Servlet
  7. Conclusion

Amber manages tables in a relational database using a Java bean interface.

Files in this tutorial

WEB-INF/web.xml Configures the Amber resource and Database
WEB-INF/classes/example/Course.java The Course bean.
WEB-INF/classes/example/Course.hbm.xml The Course configuration file.
WEB-INF/classes/example/CourseServlet.java The Course servlet.
WEB-INF/classes/example/InitResource.java A resource to initialize the database for the demo

Database Schema

course.sql 
CREATE TABLE amber_basic_courses (
  id INTEGER PRIMARY KEY,

  name VARCHAR(250),
  teacher VARCHAR(250)
);

INSERT INTO amber_basic_courses VALUES(1, 'Potions', 'Severus Snape');
INSERT INTO amber_basic_courses VALUES(2, 'Transfiguration', 'Minerva McGonagall');

Implementation Class

Course.java 
package example;

public class Course {
  private int _id;
  private String _name;
  private String _teacher;

  public int getId()
  {
    return _id;
  }

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

  public String getName()
  {
    return _name;
  }

  public void setName(String name)
  {
    _name = name;
  }

  public String getTeacher()
  {
    return _teacher;
  }

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

With Amber, all Java source or the Java classes can be dropped in WEB-INF/classes. Resin will automatically compile the Java class if necessary. Amber will enhance the class.

Configuration

Amber currently uses Hibernate's syntax to configure the beans. The configuration has the same name and directory as the class file, with a ".hbm.xml" extension instead of ".class".

example/Course.hbm.xml 
<hibernate-mapping>
  <class name="example.Course" table="amber_basic_courses">
    <id name="id"/>

    <property name="name"/>
    <property name="teacher"/>
  </class>
</hibernate-mapping>

Hibernate configurationmeaningdefault
hibernate-mappingtop-level xml node for the Hibernate syntaxrequired
classConfigures a Java class as an entityrequired
namename of the class or propertyrequired
tablename of the database table for the classthe class name
idconfigures a field as the table's primary key
propertyconfigures a field as a property

Resin Configuration

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

WEB-INF/web.xml 
<web-app>
  <database jndi-name="jdbc/resin">
    <driver type="com.caucho.db.jca.ConnectionFactory">
      <path>WEB-INF/db</path>
    </driver>
  </database>

  <resource jndi-name="amber/factory">
    <type>com.caucho.amber.jca.AmberConnectionFactory</type>
    <init>
      <data-source>java:comp/env/jdbc/resin</data-source>
    </init>
  </resource>
</web-app>

Amber configurationmeaning
databaseconfigures a database
jndi-nameThe JNDI name where the resource will be stored
driverThe database driver
typeThe class name of the database driver
resourceConfigures a resource, in this case Amber
data-sourceSets the database for Amber

Client Servlet

Now that we've defined the entity, we should go ahead and use it.

CourseServlet.java 
package example;

import java.io.*;
import javax.servlet.*;
import javax.servlet.http.*;
import javax.naming.*;

import com.caucho.amber.AmberFactory;
import com.caucho.amber.AmberConnection;

public class CourseServlet extends HttpServlet {
  // Cache the amber factory so the JNDI lookup only happens once
  private AmberFactory _factory = null;

  public void init()
    throws ServletException
  {
    try {
      Context ic = new InitialContext();

      _factory = (AmberFactory) ic.lookup("java:comp/env/amber/factory");
    } catch (NamingException e) {
      throw new ServletException(e);
    }
  }

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

    res.setContentType("text/html");

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

    AmberConnection aConn = null;

    try {
      aConn  = _factory.getConnection();
      for (int i = 1; i <= 2; i++) {
        // Find the course using the home interface

        Course course = (Course) aConn.load(Course.class, new Integer(i));

        out.println("course: " + course.getName() + "<br>");
        out.println("teacher: " + course.getTeacher() + "<br>");
        out.println("<br>");
      }
    } finally {
      if (aConn != null)
        aConn.close();
    }
  }
}


Course Details

course: Potions
teacher: Severus Snape

course: Transfiguration
teacher: Minerva McGonagall

Conclusion

The core of Amber's database management is its management of a single table. Much of the work underlying the database management is hidden from the application.

Try the Tutorial

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