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