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 }