columnspec.java

把java对象映射成数据库表中的一条记录

/*
 *
 * The contents of this file are subject to the Mozilla Public License
 * Version 1.1 (the "License"); you may not use this file except in
 * compliance with the License. You may obtain a copy of the License at
 *
 * http://www.mozilla.org/MPL/
 *
 * Software distributed under the License is distributed on an "AS IS"
 * basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See the
 * License for the specific language governing rights and limitations under
 * the License.
 *
 * The Original Code is jRelationalFramework.
 *
 * The Initial Developer of the Original Code is is.com.
 * Portions created by is.com are Copyright (C) 2000 is.com.
 * All Rights Reserved.
 *
 * Contributor(s): Jonathan Carlson ([e-mail])
 * Contributor(s): ____________________________________
 *
 * Alternatively, the contents of this file may be used under the terms of
 * the GNU General Public License (the "GPL") or the GNU Lesser General
 * Public license (the "LGPL"), in which case the provisions of the GPL or
 * LGPL are applicable instead of those above.  If you wish to allow use of
 * your version of this file only under the terms of either the GPL or LGPL
 * and not to allow others to use your version of this file under the MPL,
 * indicate your decision by deleting the provisions above and replace them
 * with the notice and other provisions required by either the GPL or LGPL
 * License.  If you do not delete the provisions above, a recipient may use
 * your version of this file under either the MPL or GPL or LGPL License.
 *
 */
package com.is.jrf;


import com.is.util.sql.JDBCHelper;

import java.sql.SQLException;
import java.sql.Timestamp;


/**
 *  Implementors of this interface represent columns in the table
 *  represented by the domain subclass.
 */
public interface ColumnSpec
    extends JRFConstants
  {

  /* ===============  Abstract Method Definitions  =============== */

  /**
   * Returns a string representing the given attribute value. The string
   * will be used in an SQL expression.
   *
   * @param obj a value of type 'Object'
   * @return a value of type 'String'
   */
  public String formatForSql(Object obj, DatabasePolicy dbPolicy);


  /**
   * See IntegerColumnSpec for how to implement.
   */
  public abstract Class getColumnClass();


  /**
   * See IntegerColumnSpec for how to implement:
   */
  public abstract Object getColumnValueFrom(JDBCHelper helper)
          throws SQLException;



  /**
   * Copy the value of my column to the appropriate attribute for this
   * persistent object.
   *
   * @param helper a value of type 'JDBCHelper'
   * @param aPO a value of type 'PersistentObject'
   * @exception SQLException if an error occurs
   */
  public void copyColumnValueToPersistentObject(JDBCHelper helper,
                                                PersistentObject aPO)
          throws SQLException;


  /**
   * Copy the attribute I represent from one persistent object to another.
   *
   * @param aPO1 a value of type 'PersistentObject'
   * @param aPO2 a value of type 'PersistentObject'
   */
  public void copyAttribute(PersistentObject aPO1,
                            PersistentObject aPO2);


  /**
   * Note: This method is overridden by CompoundPrimaryKeyColumnSpec to
   * include " AND " between each name-value pair.
   *
   * @param aPO a value of type 'PersistentObject'
   * @param separator a value of type 'String'
   * @param tableName a value of type 'String'
   * @param dbPolicy a value of type 'DatabasePolicy'
   * @return a value of type 'String'
   */
  public String buildWhereClause(Object pkOrPersistentObject,
                                 String separator,
                                 String tableName,
                                 DatabasePolicy dbPolicy);


  /**
   * This method is used to build an equals (or not-equals) String for WHERE
   * clauses and UPDATE statements.  This method should not be used for
   * CompoundPrimaryKeyColumnSpec instances.  Use #buildWhereClause() instead.
   *
   * @param pkOrPersistentObject a value of type 'Object'
   * @param separator a value of type 'String' - use EQUALS or NOT_EQUALS
   *        static final variables.
   * @param tableName a value of type 'String'
   * @param dbPolicy a value of type 'DatabasePolicy'
   * @return a value of type 'String'
   */
  public String buildNameValuePair(Object pkOrPersistentObject,
                                   String separator,
                                   String tableName,
                                   DatabasePolicy dbPolicy);


  /**
   * Make sure the PersistentObject object has this attribute (if required).
   *
   * @param aPO a value of type 'PersistentObject'
   * @return a value of type 'Object' - This is the value of the attribute.
   *         This is so subclasses can call super.validateRequired().
   * @exception MissingAttributeException if attribute should be populated
   *            and it is not.
   */
  public Object validateRequired(PersistentObject aPO)
          throws MissingAttributeException;


  /**
   * If Column is declared UNIQUE, make sure it doesn't already exist in the
   * table.
   *
   * @param aPO a value of type 'PersistentObject'
   * @param helper a value of type 'JDBCHelper'
   * @param pkColumnSpec a value of type 'ColumnSpec'
   * @exception DuplicateRowException if a row with this value already exists.
   */
  public void validateUnique(PersistentObject aPO,
                             JDBCHelper helper,
                             ColumnSpec pkColumnSpec,
                             DatabasePolicy dbPolicy,
                             String tableName)
          throws DuplicateRowException;


  /**
   * Get a string representation of the value of this attribute from
   * aPO.  This string can be inserted into a SQL statement.
   *
   * @param aPO a value of type 'PersistentObject'
   * @return a value of type 'String'
   */
  public String getSqlValueFrom(PersistentObject aPO,
                                DatabasePolicy dbPolicy);

  /**
   * Get the value of this attribute from aPO.  If the value is
   * null, the default value will be returned.
   *
   * @param aPO a value of type 'PersistentObject'
   * @return a value of type 'Object'
   */
  public Object getValueFrom(PersistentObject aPO);


  /**
   * This is a pass-through method that passes along my setter and column
   * class.
   *
   * @param aValue a value of type 'Object'
   * @param aPO a value of type 'PersistentObject'
   */
  public void setValueTo(Object aValue,
                         PersistentObject aPO);


  /**
   * Convert the attribute(s) in the given PersistentObject to a String that
   * can be decoded later.  The result of this method is not for use in SQL.
   *
   * @param aPO a value of type 'PersistentObject'
   * @return a value of type 'String'
   */
  public String encodeFromPersistentObject(PersistentObject aPO);


  /**
   * This method does the reverse of encodeFromPersistentObject(aPO)
   *
   * @param aString a value of type 'String'
   * @param aPO a value of type 'PersistentObject'
   */
  public void decodeToPersistentObject(String aString,
                                       PersistentObject aPO);



  /* ===============  Getters =============== */

  public String getFullyQualifiedColumnName(String tableAlias);

  public String getColumnName();

  public String getGetter();

  public String getSetter();

  public boolean isRequired();

  public boolean isSequencedPrimaryKey();

  public boolean isNaturalPrimaryKey();

  public boolean isPrimaryKey();

  public boolean isUnique();

  public boolean isSubtypeIdentifier();

  public Object getDefault();

  public boolean isOptimisticLock();

  /**
   * CompoundPrimaryKeyColumnSpec uses this to force it's children to
   * "REQUIRED".
   */
  public void setRequired(boolean b);

  public String columnDefinitionString(DatabasePolicy dbPolicy);


  } // ColumnSpec