    001    /*
    002     * Copyright (c) 2007-2014 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
    021    package cascading.tuple.type;
    022
    023    import java.io.Serializable;
    024    import 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     */
    047    public 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      }