stringarraycolumnspec.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): Alix Jermyn ([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.util.ArrayList;
import java.util.StringTokenizer;


/**
 * Subclass of AbstractColumnSpec that handles arrays of strings.<p/>
 *
 * This Column Spec will take an array of Strings from a Persistent
 * Object and convert it to a comma delimited string back in the database.
 * Similarly, a commma delimited String in a database column will be
 * reconstituted back into an array of Strings.<p/>
 *
 * The default delimiter is a comma, but this can be dynamically reset.<p/>
 *
 * The underlying field in the PersistentObject will be an Array of Strings.
 * If this array is null, the corresponding column in the database will be
 * set to null.  Similarly, a null column in the database will reconstitute
 * itself as a null String[] object.<p/>
 *
 * However, a String[] of zero length will be saved as an empty String,
 * and an empty String will reconstitute itself as an zero length array.
 * Null objects in the String Array, or strings which are empty or contain
 * only spaces, will be ignored when being converted.
 */
public class StringArrayColumnSpec
    extends AbstractColumnSpec
  {


  /* ===============  Static Variables  =============== */

  public    static final String   EMPTY_STRING = "";
  public    static final String[] EMPTY_ARRAY  = new String[0];
  public    static final String   COMMA        = ",";
  protected static       Class    s_class      = String[].class;

  /* ===============  Instance Variables  =============== */

  protected String i_delimiter   = COMMA;


  /* ===============  Constructors  =============== */



  public StringArrayColumnSpec(
      String columnName,
      String getter,
      String setter,
      Object defaultValue)
    {
    super(columnName,
          getter,
          setter,
          (String[]) defaultValue);
    }

  public StringArrayColumnSpec(
      String columnName,
      String getter,
      String setter,
      Object defaultValue,
      int    option1)
    {
    super(columnName,
          getter,
          setter,
          (String[]) defaultValue,
          option1);
    }

  public StringArrayColumnSpec(
      String columnName,
      String getter,
      String setter,
      Object defaultValue,
      int    option1,
      int    option2)
    {
    super(columnName,
          getter,
          setter,
          (String[]) defaultValue,
          option1,
          option2);
    }

  public StringArrayColumnSpec(
      String columnName,
      String getter,
      String setter,
      Object defaultValue,
      int    option1,
      int    option2,
      int    option3)
    {
    super(columnName,
          getter,
          setter,
          (String[]) defaultValue,
          option1,
          option2,
          option3);
    }


  /**
   * Sets the delimiter used to delimit the String stored
   * in the database.<p/>
   *
   * The default delimiter is the comma, ",".
   */
  public void setDelimiter(String delimiter)
    {
    i_delimiter = delimiter;
    }


// ---------------------------------------------------- ArrayToDelimitedString


  /**
   * Takes an array of Strings and converts them into a single
   * delimited String.  If the array is empty, or contains only
   * null or empty objects an empty string is returned "".
   * If the Array is null, then a null String is returned.
   * External spaces are removed from each array item.
   * If an array object is null, empty or  constains only
   * white space, it is ignored.
   *
   * @parameter array the array to convert
   * @returns   a comma delimited (default) string, or null
   * @see ListToFromDelimitedString(List list)
   */
  protected static String arrayToDelimitedString (String[] values,
                                                  String delimiter)
    {

    if (values == null)
        {
        return (String) null;
        }

    int length = values.length;
    if (length == 0)
        {
        return EMPTY_STRING;
        }

    // a typical lookup value is a 3 char string, so allowing for the
    // delimiters, the output string length should be about:
    StringBuffer sb = new StringBuffer(length * 4);
    String token    = null;

    for (int i = 0; i < length; i++)
        {

        if (values[i] == null)
            {
            continue;
            }

        token = values[i].trim();

        if (EMPTY_STRING.equals(token))
            {
            continue;
            }

        if (sb.length() > 0)
            {
            sb.append(delimiter);
            }
        sb.append(token);
        }

    if (sb.length() > 0)
        {
        return sb.toString();
        }
    else
        {
        return EMPTY_STRING;
        }
    } // arrayToDelimitedString


//  ------------------------------------------------- ArrayFromDelimitedString
  /**
   * Takes a delimited string of values and
   * converts it into an array of string values.
   * If the original String is empty or null, a zero length Array is returned
   *
   * @parameter values the String to convert to an Array of Strings
   * @returns   an Array of Strings (never null)
   * @see #arrayToDelimitedString (String[] values)
   */
  protected static String[] arrayFromDelimitedString(String values,
                                                     String delimiter)
    {

    if (values == null)
        {
        return (String[]) null;
        }

    if (EMPTY_STRING.equals(values.trim()))
        {
        return EMPTY_ARRAY;
        }

    ArrayList list     = new ArrayList();
    String token       = null;
    StringTokenizer st = new StringTokenizer(values, String.valueOf(delimiter));

    while (st.hasMoreTokens())
        {
        token = st.nextToken().trim();
        if (EMPTY_STRING.equals(token))
            {
            continue;
            }
        list.add(token);
        }
    return  (String[]) list.toArray(new String[list.size()]);
    }


  /**
   * This method overrides the superclass implementation.  A string of
   * "null" is returned if object is null, otherwise it returns a String
   * with quotes around it.  Internal single quotes are converted to two
   * single quotes and the string is wrapped in single quotes.
   *
   * @param aValueObject a value of type 'ValueObject'
   * @return a value of type 'String'
   */
  public String formatForSql(Object obj, DatabasePolicy dbPolicy)
    {

    String returnValue = "null";
    if (obj != null)
        {
        returnValue =
                JDBCHelper.delimitString(
                    StringArrayColumnSpec.arrayToDelimitedString((String[]) obj,
                                                                 i_delimiter),
                    "'");
        }
    return returnValue;
    } // formatForSql(...)


  /**
   * Decodes an Array of Strings from an encoded String.<p/>
   *
   * Note that null String[] objects are encoded as the string "'null",
   * so this method does not work correctly for an Array of Strings
   * consisting of a single String with a value of "null"
   *
   * @param aString a value of type 'String'
   * @return a value of type 'Object' (This actually will be a String or null)
   */
  public Object decode(String aString)
    {
    if (aString.trim().equals("null"))
        {
        return null;
        }
    return StringArrayColumnSpec.arrayFromDelimitedString(aString, i_delimiter);
    }

  /**
   * Overidden method that matches with decode().<p/>
   *
   * Note that null String[] objects are encoded as the string "'null",
   * so this method does not work correctly for an Array of Strings
   * consisting of a single String with a value of "null".<p/>
   *
   * @param obj the object (String[]) to encode to a String'
   * @return an encoded string)
   */
  public String encode(Object obj)
    {
    return (obj==null ?
            "null" :
            StringArrayColumnSpec.arrayToDelimitedString((String[]) obj,
                                                         i_delimiter));
    }


  public Class getColumnClass()
    {
    return s_class;
    }


  /**
   * Return a String[] from JDBCHelper.  Reconstitute an Array of Strings
   * from a delimited String.  The strange behaviour with SQLServer (and
   * maybe Sybase) that keeps returning empty or whitespace strings as one
   * blank character can be ignored, as any white spaced is trimmed out
   * before creating the array.
   *
   * @param helper a value of type 'JDBCHelper'
   * @return a value of type 'Object'
   * @exception SQLException if an error occurs in JDBCHelper
   */
  public Object getColumnValueFrom(JDBCHelper helper)
          throws SQLException
    {
    String[] returnValue =
            StringArrayColumnSpec.arrayFromDelimitedString(
                        helper.getString(this.getColumnName()),
                        i_delimiter);
    return returnValue;
    }


  /**
   * This is an override of the superclass implementation.  This method adds
   * a check to make sure the string is not empty or blank.
   *
   * @param aPO a value of type 'PersistentObject'
   * @return a value of type 'Object'
   * @exception MissingAttributeException if an error occurs
   */
  public Object validateRequired(PersistentObject aPO)
          throws MissingAttributeException
    {
    String value = (String) super.validateRequired(aPO);
    // a null value tells us it had to be non-required or an error would
    // have been thrown.
    if (value != null &&
        value.trim().length() == 0)
        {
        throw new MissingAttributeException(
            "Required attribute - "
            + this.getColumnName()
            + "- is an empty string value.");
        }
    return value;
    } // validateRequired(aPersistentObject)


  /**
   * Return the ANSI standard SQL column type.  This was written to support
   * the test suites.  If there is no standard that will work across
   * platforms, then we'll add a method to dbPolicy and return its value.
   *
   * @param dbPolicy a value of type 'DatabasePolicy'
   * @return a value of type 'String'
   */
  public String getSQLColumnType(DatabasePolicy dbPolicy)
    {
    return "VARCHAR(255)";
    }


  public JoinColumn buildJoinColumn()
    {
    StringArrayJoinColumn joinColumn =
           new StringArrayJoinColumn(this.getColumnName(),
                                     this.getSetter());
    joinColumn.setDelimiter(i_delimiter);
    return joinColumn;
    }


  } // StringArrayColumnSpec