/*
    * $Source: /usr/cvsroot/melati/poem/src/main/java/org/melati/poem/BasePoemType.java,v $
    * $Revision: 1.48 $
    *
    * Copyright (C) 2000 William Chesters
    *
    * Part of Melati (http://melati.org), a framework for the rapid
    * development of clean, maintainable web applications.
    *
   * Melati is free software; Permission is granted to copy, distribute
   * and/or modify this software under the terms either:
   *
   * a) the GNU General Public License as published by the Free Software
   *    Foundation; either version 2 of the License, or (at your option)
   *    any later version,
   *
   *    or
   *
   * b) any version of the Melati Software License, as published
   *    at http://melati.org
   *
   * You should have received a copy of the GNU General Public License and
   * the Melati Software License along with this program;
   * if not, write to the Free Software Foundation, Inc.,
   * 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA to obtain the
   * GNU General Public License and visit http://melati.org to obtain the
   * Melati Software License.
   *
   * Feel free to contact the Developers of Melati (http://melati.org),
   * if you would like to work out a different arrangement than the options
   * outlined here.  It is our intention to allow Melati to be used by as
   * wide an audience as possible.
   *
   * This program is distributed in the hope that it will be useful,
   * but WITHOUT ANY WARRANTY; without even the implied warranty of
   * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
   * GNU General Public License for more details.
   *
   * Contact details for copyright holder:
   *
   *     William Chesters <williamc At paneris.org>
   *     http://paneris.org/~williamc
   *     Obrechtstraat 114, 2517VX Den Haag, The Netherlands
   */
  
  package org.melati.poem;
  
  import java.sql.PreparedStatement;
  import java.sql.ResultSet;
  import java.sql.SQLException;
  import java.util.Enumeration;
  
  import org.melati.poem.dbms.Dbms;
  import org.melati.poem.util.ConsEnumeration;
  
  /**
   * Base class of all fundamental types.
   */
  public abstract class BasePoemType implements SQLPoemType, Cloneable {
    private int sqlTypeCode;
    protected boolean nullable;
  
    private Comparable low = null, limit = null;
  
    BasePoemType(int sqlTypeCode, boolean nullable) {
      this.sqlTypeCode = sqlTypeCode;
      this.nullable = nullable;
    }
  
    /**
     * Set the limits, if applicable.
     * @param low included lower limit
     * @param limit excluded upper limit
     */
    public void setRawRange(Comparable low, Comparable limit) {
      this.low = low;
      this.limit = limit;
    }
  
    protected Comparable getLowRaw() {
      return low;
    }
  
    protected Comparable getLimitRaw() {
      return limit;
    }
  
    protected abstract void _assertValidRaw(Object raw)
        throws ValidationPoemException;
  
    private void assertRawInRange(Object raw) {
      // Range check.  Since we can't do this with multiple inheritance, we
      // provide it as a facility even in types for which it is meaningless.
  
      Comparable asComparable;
      try {
        asComparable = (Comparable)raw;
      }
      catch (ClassCastException e) {
       throw new NotComparablePoemException(raw, this);
     }
 
     if ((low != null && low.compareTo(asComparable) > 0) ||
         (limit != null && limit.compareTo(asComparable) <= 0))
       throw new ValidationPoemException(
           this, raw, new OutsideRangePoemException(low, limit, raw));
   }
 
   /**
    * {@inheritDoc}
    * @see org.melati.poem.PoemType#assertValidRaw(java.lang.Object)
    */
   public final void assertValidRaw(Object raw)
       throws ValidationPoemException {
     if (raw == null) {
       if (!nullable)
         throw new NullTypeMismatchPoemException(this);
     }
     else {
       if (low != null || limit != null)
         assertRawInRange(raw);
       _assertValidRaw(raw);
     }
   }
 
   /**
    * Check if the raw value is valid, as expected.
    * @param raw an Object which should be of correct type
    */
   private void doubleCheckValidRaw(Object raw) {
     try {
       assertValidRaw(raw);
     }
     catch (ValidationPoemException e) {
       throw new UnexpectedValidationPoemException(e);
     }
   }
 
   protected abstract Object _getRaw(ResultSet rs, int col)
       throws SQLException;
 
   /**
    * {@inheritDoc}
    * @see org.melati.poem.SQLType#getRaw(java.sql.ResultSet, int)
    */
   public final Object getRaw(ResultSet rs, int col)
       throws ValidationPoemException {
     Object o;
     try {
       o = _getRaw(rs, col);
     }
     catch (SQLException e) {
       throw new SQLSeriousPoemException(e);
     }
 
     assertValidRaw(o);
     return o;
   }
 
   protected abstract void _setRaw(PreparedStatement ps, int col,
                                   Object raw)
       throws SQLException;
 
   /**
    * {@inheritDoc}
    * @see org.melati.poem.SQLType#setRaw(java.sql.PreparedStatement, int, java.lang.Object)
    */
   public final void setRaw(PreparedStatement ps, int col, Object raw) {
     doubleCheckValidRaw(raw);
     try {
       if (raw == null)
         ps.setNull(col, sqlTypeCode());
       else
         _setRaw(ps, col, raw);
     }
     catch (SQLException e) {
       throw new SQLSeriousPoemException(e);
     }
   }
 
   protected Enumeration _possibleRaws() {
     return null;
   }
   
   /**
    * {@inheritDoc}
    * @see org.melati.poem.PoemType#possibleRaws()
    */
   public Enumeration possibleRaws() {
     Enumeration them = _possibleRaws();
     return them == null ? null :
                    getNullable() ? new ConsEnumeration(null, them) :
                    them;
   }
 
   protected abstract String _stringOfRaw(Object raw);
 
   /**
    * This <B>doesn't</B> do an explicit <TT>assertValidRaw</TT>.
       * {@inheritDoc}
    * @see org.melati.poem.PoemType#stringOfRaw(java.lang.Object)
    */
   public final String stringOfRaw(Object raw)
       throws ValidationPoemException {
     return raw == null ? null : _stringOfRaw(raw);
   }
 
   /**
    * Converts a non-null string to an appropriate value 
    * for insertion into the underlying DBMS.
    */
   protected abstract Object _rawOfString(String string)
       throws ParsingPoemException;
 
   /**
    * Converts a possibly null <code>String</code> to a low level
    * representation of a valid database column value.
    * <p>
    * Null values are not changed.
    * <p>
    * This result is validated with {@link #assertValidRaw(Object)}
    * whereas {@link #stringOfRaw(Object)} assumes this is not
    * required.
    * {@inheritDoc}
    * @see org.melati.poem.PoemType#rawOfString(java.lang.String)
    */
   public final Object rawOfString(String string)
       throws ParsingPoemException, ValidationPoemException {
     Object raw = string == null ? null : _rawOfString(string);
     assertValidRaw(raw);
     return raw;
   }
 
   protected abstract void _assertValidCooked(Object cooked)
       throws ValidationPoemException;
 
   /**
    * {@inheritDoc}
    * @see org.melati.poem.PoemType#assertValidCooked(java.lang.Object)
    */
   public final void assertValidCooked(Object cooked)
       throws ValidationPoemException {
     if (cooked == null) {
       if (!nullable)
         throw new NullTypeMismatchPoemException(this);
     }
     else {
       _assertValidCooked(cooked);
       if (low != null || limit != null)
         assertRawInRange(_rawOfCooked(cooked));
     }
   }
 
   /**
    * Check that object is valid, as expected.
    * NOTE If it isn't valid then it isn't cooked.
    * @param cooked the cooked object
    */
   final void doubleCheckValidCooked(Object cooked) {
     try {
       assertValidCooked(cooked);
     }
     catch (ValidationPoemException e) {
       throw new UnexpectedValidationPoemException(e);
     }
   }
 
   /**
    * Converts a non-null low-level representation of a database
    * column value to the appropriate object.
    * <p>
    * For the base object types, (String, Integer etc) this involves no change. 
    * <p>
    * For types with an integer id, such as Poem internal types and user defined types, 
    * then the appropriate instantiated type is returned from its Integer id.
    * @param raw the base object or Integer object id
    * @return the unchanged base object or an instantiated type
    */
   protected abstract Object _cookedOfRaw(Object raw) throws PoemException;
 
   /**
    * Converts a possibly null low-level representation of a database
    * column value to its canonical form. 
    * Types represented as integers in the database are converted to 
    * corresponding objects .
    * <p>
    * The raw value is checked to ensure it is valid.
    * {@inheritDoc}
    * @see org.melati.poem.PoemType#cookedOfRaw(java.lang.Object)
    */
   public final Object cookedOfRaw(Object raw) throws PoemException {
     doubleCheckValidRaw(raw);
     return raw == null ? null : _cookedOfRaw(raw);
   }
 
   protected abstract Object _rawOfCooked(Object raw) throws PoemException;
 
   /**
    * {@inheritDoc}
    * @see org.melati.poem.PoemType#rawOfCooked(java.lang.Object)
    */
   public final Object rawOfCooked(Object cooked) {
     doubleCheckValidCooked(cooked);
     return cooked == null ? null : _rawOfCooked(cooked);
   }
 
   protected abstract String _stringOfCooked(Object cooked,
                                            PoemLocale locale, int style)
       throws PoemException;
 
   /**
    * {@inheritDoc}
    * @see org.melati.poem.PoemType#stringOfCooked(java.lang.Object, 
    *          org.melati.poem.PoemLocale, int)
    */
   public final String stringOfCooked(Object cooked,
                                     PoemLocale locale, int style)
       throws PoemException {
     doubleCheckValidCooked(cooked);
     return cooked == null ? "" : _stringOfCooked(cooked, locale, style);
   }
 
   /**
    * {@inheritDoc}
    * @see org.melati.poem.PoemType#getNullable()
    */
   public final boolean getNullable() {
     return nullable;
   }
 
   /**
    * {@inheritDoc}
    * @see org.melati.poem.SQLType#sqlTypeCode()
    */
   public final int sqlTypeCode() {
     return sqlTypeCode;
   }
 
   protected abstract String _sqlDefinition(Dbms dbms);
 
   /**
    * {@inheritDoc}
    * @see org.melati.poem.SQLType#sqlDefinition(org.melati.poem.dbms.Dbms)
    */
   public String sqlDefinition(Dbms dbms) {
     return sqlTypeDefinition(dbms) + (nullable ? "" : " NOT NULL");
   }
   /**
    * {@inheritDoc}
    * @see org.melati.poem.SQLType#sqlTypeDefinition(org.melati.poem.dbms.Dbms)
    */
   public String sqlTypeDefinition(Dbms dbms) {
     return _sqlDefinition(dbms);
   }
   protected abstract boolean _canRepresent(SQLPoemType other);
 
   /**
    * {@inheritDoc}
    * @see org.melati.poem.PoemType#canRepresent(org.melati.poem.PoemType)
    */
   public PoemType canRepresent(PoemType other) {
     // FIXME takes no account of range---need to decide on semantics for this,
     // is it subset (inclusion) or some other notion of storability?
     if (!(other instanceof SQLPoemType)) 
       // NOTE Never happens as currently all PoemTypes are SQLPoemTypes
       return null;
     else {
       SQLPoemType q = (SQLPoemType)other;
       return
           !(!nullable && q.getNullable()) && // Nullable may represent not nullable
           _canRepresent(q) ?
               q : null;
     }
   }
 
   /**
    * {@inheritDoc}
    * @see org.melati.poem.PoemType#withNullable(boolean)
    */
   public final PoemType withNullable(boolean nullableP) {
     if (this.nullable == nullableP)
       return this;
     else {
       BasePoemType it = (BasePoemType)clone();
       it.nullable = nullableP;
       return it;
     }
   }
 
   protected abstract void _saveColumnInfo(ColumnInfo info)
       throws AccessPoemException;
 
   /**
    * {@inheritDoc}
    * @see org.melati.poem.PoemType#saveColumnInfo(org.melati.poem.ColumnInfo)
    */
   public void saveColumnInfo(ColumnInfo info) throws AccessPoemException {
     info.setNullable(nullable);
     info.setSize(0);
     info.setRangelow_string(
         getLowRaw() == null ? null : stringOfRaw(getLowRaw()));
     // this _won't_ throw an OutsideRangePoemException since it doesn't check
     info.setRangelimit_string(
         getLimitRaw() == null ? null : stringOfRaw(getLimitRaw()));
     _saveColumnInfo(info);
   }
 
   protected abstract String _quotedRaw(Object raw);
 
   /**
    * {@inheritDoc}
    * @see org.melati.poem.SQLType#quotedRaw(java.lang.Object)
    */
   public String quotedRaw(Object raw) throws ValidationPoemException {
     assertValidRaw(raw);
     return raw == null ? "NULL" : _quotedRaw(raw);
   }
 
   protected abstract String _toString();
 
   // 
   // --------
   //  Object
   // --------
   // 
 
   /**
    * {@inheritDoc}
    * @see java.lang.Object#toString()
    */
   public String toString() {
     return (nullable ? "nullable " : "") + _toString() + 
     " (" + this.getClass().getName() + ")";
   }
 
   /**
    * {@inheritDoc}
    * @see java.lang.Object#clone()
    */
   protected Object clone() {
     try {
       return super.clone();
     }
     catch (CloneNotSupportedException e) {
       throw new PoemBugPoemException();
     }
   }
 }