Annotations in beans

You can use annotations in beans to override the default mapping to columns. Annotations can also indicate whether a property corresponds to a generated column in the corresponding database table or view.

Property-level annotations

pureQuery recognizes property-level annotations only on public properties and public get() or set() methods. It does not recognize these annotations on private or protected properties.

To understand the conventions that are used in the syntax diagram, see How to read syntax diagrams.

@Column
Read syntax diagramSkip visual syntax diagram
>>-@Column--(--name--=--name_of_column--+-------------------------+-><
                                        '-table--=--name_of_table-'   

Specifies the SQL column in a database object that a property maps to. You can use this annotation only on public properties and public methods. If you use it anywhere else, pureQuery ignores it.

You can use the @Column annotation for either of two reasons:

  • The name of an SQL column and the name of a property in a bean will not match in a case-insensitive search. In this situation, you would use only the name attribute of the annotation.
    @Column(name="DEPTNO") 
    public String deptNum;
    @Column(name="EMPNO") 
    public String getEmpNum() { 		
        return empNum; 	
    }
  • A query result from a join of tables contains two or more columns that have the same name. In this situation, you use both the name and table attributes of the annotation. If the combination of the table name and column name are also duplicated, you cannot use the @Column annotation. Instead, you must use an AS clause in your query.

    Example

    For example, suppose that your application runs the following simple query:
    	select a.col1, b.col1 from a, b where a.id=b.id;
    The set() methods for the corresponding properties in the beans that hold the query results need @Column annotations that give the name of the table in which the two id columns appear:
    public class JoinExample{
    
      private int a_id;
      private int b_id;
    
      @Column (name="id", table="a")
      public void setA_id (int a_id)
      {
        this.a_id = a_id;
      }
      public int getA_id ()
      {
        return a_id;
      }
    
      @Column (name="id", table="b")
      public void setB_id (int b_id)
      {
        this.b_id = b_id;
      }
      public int getB_id ()
      {
        return b_id;
      }
    }
@GeneratedKey
Indicates that the SQL column is an auto-generated column. That is, the value is automatically assigned by the database during INSERT or UPDATE operations.
If a bean that contains this annotation is provided as the only parameter for an INSERT or UPDATE operation with an annotated method, or the Data interface method defined int update(String sql, Object... parameters), then annotated properties are updated before control is returned to your application.
Attention: If you pass two or more beans as input parameters to an update operation, and at least one @GeneratedKey annotation exists in each bean, the update operation does not succeed. This restriction applies to the update() method (for the inline programming style) and to methods in @Update annotations (for the annotated-method programming style).

Bean-level annotations

Bean-level annotations apply to the entire bean. When you use a bean-level annotation, you specify it before you start the definition of the bean, as in this example:
@ColumnOverride(propertyName="extension", column="PHONE") 
 
public class EmployeeNewCo extends Employee {...

To understand the conventions that are used in the syntax diagrams, see How to read syntax diagrams.

@ColumnOverride
Read syntax diagramSkip visual syntax diagram
>>-@ColumnOverride--(--propertyName--=--"--property--",--column--=--"--name--")-><

Specifies an association between an SQL column and a property of the bean. This annotation contains the name of a column in the table or view that is implicitly or explicitly associated with the containing class, and the name of the property to which this annotation maps. The mapping that is indicated by this annotation overrides other column mappings for this property, including mappings that are defined elsewhere in this class or in a superclass.
@ColumnOverrides
Read syntax diagramSkip visual syntax diagram
>>-@ColumnOverrides--(------------------------------------------>

      .-,----------------------------------------------------------------------------.      
      V                                                                              |      
>--{----@ColumnOverride--(--propertyName--=--"--property--",--column--=--"--name--")-+--}-->

>--)-----------------------------------------------------------><

Specifies an array of @ColumnOverride annotations. Use this annotation when you need to specify more than one @ColumnOverride annotation.

Note that the array of @ColumnOverride annotations appears within curly braces within the parentheses for the @ColumnOverrides annotation.

Example

Suppose that you want to define a bean to hold records that are returned by queries against the HRDEPT.EMPLOYEE table.
CREATE TABLE HRDEPT.EMPLOYEE(
  EMPNO CHAR(6) NOT NULL,
  FIRSTNME VARCHAR(12) NOT NULL,
  MIDINIT CHAR(1),
  LASTNAME VARCHAR(15), 
  WORKDEPT CHAR(2), 
  PHONENO CHAR(4),
  HIREDATE DATE,
  PRIMARY KEY(EMPNO))
Some of the column names are abbreviated or do not follow Java™ naming conventions.

The following definition for an Employee bean uses @Column annotations to provide more meaningful names to the users of objects of the com.company.Employee class.

public class Employee
{
  private String employeeId;
  private String firstName;
  private String middleInitial;
  private String lastName;
  private String departmentId;
  private String extension;
  private Date hireDate;

  @Column(name = "EMPNO")
  public String getEmployeeId ()
  {
    return employeeId;
  }

  public void setEmployeeId (String employeeId)
  {
    this.employeeId = employeeId;
  }

  @Column(name = "FIRSTNME")
  public String getFirstName ()
  {
    return firstName;
  }

  public void setFirstName (String firstName)
  {
    this.firstName = firstName;
  }

  @Column(name = "MIDINIT")
  public String getMiddleInitial ()
  {
    return middleInitial;
  }

  public void setMiddleInitial (String middleInitial)
  {
    this.middleInitial = middleInitial;
  }

  public String getLastName ()
  {
    return lastName;
  }

  public void setLastName (String lastName)
  {
    this.lastName = lastName;
  }

  @Column(name = "WORKDEPT")
  public String getDepartmentId ()
  {
    return departmentId;
  }

  public void setDepartmentId (String departmentId)
  {
    this.departmentId = departmentId;
  }

  @Column(name = "PHONENO")
  public String getExtension ()
  {
    return extension;
  }

  public void setExtension (String extension)
  {
    this.extension = extension;
  }

  public Date getHireDate ()
  {
    return hireDate;
  }

  public void setHireDate (Date hireDate)
  {
    this.hireDate = hireDate;
  }

}

Now, suppose an application runs against a database with a slightly different schema. The table is defined as follows:

CREATE TABLE HRDEPTNEWCO.EMPLOYEE(
  EMPNO CHAR(6) NOT NULL,
  FIRSTNME VARCHAR(12) NOT NULL,
  MIDINIT CHAR(1),
  LASTNAME VARCHAR(15), 
  WORKDEPT CHAR(2), 
  PHONE CHAR(4),
  HIREDATE DATE,
  PRIMARY KEY(EMPNO))

You can subclass the Employee bean to override the previous annotation so that you can work with the new table definition. The beginning of the subclass might look like this:

@ColumnOverride(propertyName="extension", column="PHONE") 
 
public class EmployeeNewCo extends Employee {...

Feedback