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 }