4. Mapping

Annotations, also known as "Metadata" are a new, incredibly powerful feature which come with the JDK5 of Java(TM). If you are new to the concept of Annotation, you can think at them as a way to add information to your code, which can be useful for external tools to perform any kind of operations. In this case Ammentos uses metadata information to elaborate how objects can be persisted.

Currently available Ammentos annotations are:

• @PersistentEntity
• @PersistentField.
• @PersistentList.
• @PersistentMap.

For instance, there's a very simple example of Product class.

public class Product
{
  private String m_id; 
  private String m_description;
  
  public String getId()
  {
    return m_id;
  }

  public void setDescription( String description )
  {
    m_description = description;
  }
  
  public String getDescription()
  {
    return m_description;
  }
}

Notice that this class is a completely normal Java class. It does not extend any class nor implement any interface.

@PersistentEntity
  
(
  sourceDomain="products",
  targetDomain="products",
  primaryKey="id"
)
public class Product

This declaration means that the class must be loaded from the products table and saved to the same table, and that the id field is its primary key. As you see source domain and target domain can be declared differently. This means that, for instance, you can load a class from a view and save it to a table. Furthermore, the paramer being a plain string, you can set the source domain to something like "products inner join magazine on[...]": by the way this is not recommended; using a view in this cases is he preferred way.

As a second step you must annotate each class member you want make persistent. Luckily ammentos is able to obtain automatically most annotation values. The most simple mapping declaration is as this one below:

@PersistentEntity
(
  sourceDomain="products",
  primaryKey="id"
)

public classProduct{
  @PersistentField
  private String id;
  
  @PersistentField  
  private String description;
}
                

This code shows the most essential information needed to allow Ammentos persist the Person class. Behind the scenes a lot of information is automatically obtained from the class code itself. Of course, in this example, the fields in the database are supposed to have the same names as the class members. In several cases you will need to provide additional information to make the mapping consistent. Here's an example:

  @PersistentField
  ( 
    fieldName="id", 
    description="Product code", 
    type=STRING, 
    automatic=false 
  )
  private String m_id;
  
  @PersistentField
  ( 
    fieldName="description", 
    description="Product description", 
    type=STRING
  )
  private String m_description;

The first annotation says that the annotated member represents the column "id" in the database and that it has to be traited as a STRING type from Ammentos persistors. It is also specified that is value must not be automatically initialized from the framework. The second annotation marks the class member as persistent into the "description" column.
What about collections?
Currently Ammentos supports the most used ones, List and Map collections. The example below shows a snippet from a class representing a commercial invoice. As you can see, mapping java lists is very simple and intuitive:

@PersistentEntity( sourceDomain="invoices", primaryKey="id" )
public class Invoice {
    @PersistentField( fieldName="id", automatic=true )
    private long m_id;

    // invoice fields ...

    @PersistentList(
        query="invoice_id=?",
        cascadeOnSave=true,
        cascadeOnDelete=false,
        deleteOnRemove=false )
    private List<Item> m_items;

    /** Creates a new instance of Invoice */
    public Invoice() {
        m_items = new ArrayList<Item>();
    }
    
    // invoice methods ...
}

By saving an instance of this class, the framework will recursively save all the items in the m_items list too; while loading it will instead load the list by using the provide query, where the "?" parameter will be replaced from the current Invoice's instance.
The second example shows how to represent the marks of a student through a PersistentMap:

  @PersistentMap(
    query="student_id=?",
    deleteOnRemove=true,
    cascadeOnDelete=true, 
    keyField="course_id")
  private Map<Course,Mark> m_marks;

See Appendix 3 for all details about PersistentList and PersistentMap.

Important: Each class annotated for Ammentos must have a default constructor (a constructor which does not take parameters). If you are worring about your code encapsulation, notice that this constructor can be even declared as private. If you are using PersistentLists too, still remember to do not add items to them from inside the default constructor. Because this would cause inconsistence, Ammentos will throw a PersistenceException if you do so. Obviously, without the default constructor, you can use your lists as you normally do.

Ammentos.save( product );

Product product = Ammentos.load( Product.class, "product_1" );

Ammentos.delete( product );

Query qry = new Query();
QueryFilter filter = query.appendFilter( "description" );
filter.setString( "my product" );
filter.setOperator( QueryFilter.OP_NOTEQUALS );
List<Product> products = Ammentos.load( Product.class, qry );

SqlQueryFilter sqlqf = new SqlQueryFilter( "name=? and surname=?" );
sqlqf.setString( "Alan" );
sqlqf.setString( "Ford" );
List<Person> lp = Ammentos.load( Person.class, new Query( sqlqf ) );

qry.setDomain( "(select * from people where name='Alan') 
                as Alan_named" );

try
{
  Ammentos.openTransaction();
  //[...]
  Ammentos.save( obj1 );
  //[...]
  Ammentos.save( obj2 );  
  Ammentos.commitTransaction();
}
catch( SomeKindOfException e)
{
  try { Ammentos.rollbackTransaction(); } 
  catch( PersistenceException ex );
}

Ammentos.openTransaction( java.sql.Connection.TRANSACTION_SERIALIZABLE );

  public void objectSaved( PersistenceEvent e );
  
  public void objectDeleted( PersistenceEvent e );

  public abstract void performValidation( E obj );

package it.biobytes.ammentos.test;

import it.biobytes.ammentos.*;
import it.biobytes.ammentos.validation.*;

public class PersonValidator extends Validator<Person>
{
  public void performValidation( Person obj )
  {
    checkTrue( ( obj.getName() != null ) 
    && ( !Character.isDigit( obj.getName().charAt( 0 ) ) ),
    "The name cannot be null and cannot start whit a digit" );

    checkTrue( ( obj.getSurname() != null ) 
      && ( !Character.isDigit( obj.getSurname().charAt( 0 ) ) ),
      "The surname cannot be null and cannot start whit a digit" );
  }
}

@PersistentEntity
(
  sourceDomain="people",
  targetDomain="people",
  primaryKey="id",
  validator="it.biobytes.ammentos.test.PersonValidator"
)
public class Person
{[..]

@PersistentEntity
(
  sourceDomain="teachers",
  targetDomain="teachers",
  primaryKey="id"
)
public class Teacher extends Person
{
  @PersistentField( fieldName="id", description="code", type=STRING )  
  private String m_id;
  [...]

@PersistentEntity
(
  sourceDomain="students",
  targetDomain="students",
  primaryKey="code",
  superKey="person_id"
)
public class Student extends Person
{
  @PersistentField
  ( 
    fieldName="code", 
    description="student code", 
    type=STRING 
  )  
  private String m_code;
  
  @PersistentField
  ( 
    fieldName="media", 
    description="student media", 
    type=INTEGER 
  )  
  private int m_media;
  
  @PersistentField
  ( 
    fieldName="person_id", 
    description="person_id", 
    type=STRING 
  )  
  private String m_personId;
  
  /** Creates a new instance of Student */
  public Student( String code, String personId )
  {
    super( personId );
    m_personId = personId;
    m_code = code;
  }

@PersistentEntity(sourceDomain="superclasses", primaryKey="id",
typeTable="classtypes", typeField="classtype", typeTableAutoCreate=true,
  typeTableAutoInsert=true)
public class Superclass {
  @PersistentField(automatic=true)
  private String id;
}

@PersistentEntity(sourceDomain="subclasses1", primaryKey="id",
superKey="superclass_id",
typeId=1, syncKeys=true)
public class Subclass1 extends Superclass{
  @PersistentField(automatic=true)
  private String id;
  @PersistentField(fieldName="superclass_id")
  private String superclassId;
}

  PersistenceContext context = Ammentos.createContext(myDataSource);
  ...
  
  context.openTransaction();
  ...
  context.save(myObject);
  ...
  context.commitTransaction();

    int count = 0;
    for (Student s : Ammentos.iterate(Student.class, new Query())){
      count++;
    }
    System.out.println(count);
    
    ...
    
    Ammentos.closeIteration();

  @PersistentEntity(
    sourceDomain = "lessons", 
    primaryKey = "teacher_id, course_id"
  )
  public class Lesson {
    @PersistentField(fieldName="teacher_id")
    private String teacher;

    @PersistentField(fieldName="course_id")
    private String course;

    @PersistentField
    private String topic;  

    // ...
  }

  ...
  @PersistentField
  private Date m_timeStamp;
  
  @OnSave(When.BEFORE)
  private void updateTStamp(){
    m_timeStamp = new Date();
  }

  ...
  QueryFilter filter = new SqlQueryFilter("name=? and surname=?");
  Person person = Ammentos.loadUnique(Person.class, filter);