    001/*
    002 * Copyright (c) 2007-2016 Concurrent, Inc. All Rights Reserved.
    003 *
    004 * Project and contact information: http://www.cascading.org/
    005 *
    006 * This file is part of the Cascading project.
    007 *
    008 * Licensed under the Apache License, Version 2.0 (the "License");
    009 * you may not use this file except in compliance with the License.
    010 * You may obtain a copy of the License at
    011 *
    012 *     http://www.apache.org/licenses/LICENSE-2.0
    013 *
    014 * Unless required by applicable law or agreed to in writing, software
    015 * distributed under the License is distributed on an "AS IS" BASIS,
    016 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    017 * See the License for the specific language governing permissions and
    018 * limitations under the License.
    019 */
    020
    021package cascading.tuple.type;
    022
    023import java.io.Serializable;
    024import java.lang.reflect.Type;
    025
    026/**
    027 * Interface CoercibleType allows {@link cascading.tuple.Fields} instances to be extended with custom
    028 * type information.
    029 * <p/>
    030 * It is the role of implementations of this interface to maintain a canonical representation of a given value
    031 * and to allow for coercions between some type representation to the canonical type and back.
    032 * <p/>
    033 * For example, if a field in a text delimited file is a date, ie. {@code 28/Dec/2012:16:17:12:931 -0800}
    034 * it may be beneficial for the internal representation to be a {@link Long} value for performance reasons.
    035 * <p/>
    036 * Note CoercibleType used in conjunction with the TextDelimited parsers is not a replacement for using
    037 * a pipe assembly to cleanse data. Pushing data cleansing down to a {@link cascading.tap.Tap} and
    038 * {@link cascading.scheme.Scheme} may not provide the flexibility and robustness expected.
    039 * <p/>
    040 * CoercibleTypes are a convenience when the input data is of high quality or was previously written out using
    041 * a CoercibleType instance.
    042 * <p/>
    043 * The CoercibleTypes further allow the Cascading planner to perform type checks during joins. If no
    044 * {@link java.util.Comparator} is in use, and lhs and rhs fields are not the same type, the planner will throw an
    045 * exception.
    046 */
    047public interface CoercibleType<Canonical> extends Type, Serializable
    048  {
    049  /** @return the actual Java type this CoercibleType represents */
    050  Class<Canonical> getCanonicalType();
    051
    052  /**
    053   * @param value of type Object
    054   * @return the value coerced into its canonical type
    055   */
    056  Canonical canonical( Object value );
    057
    058  /**
    059   * @param value of type Object
    060   * @param to    of type Type
    061   * @return the value coerced into the requested type
    062   */
    063  <Coerce> Coerce coerce( Object value, Type to );
    064  }