1 /* 2 * Copyright (C) 2011 The Guava Authors 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except 5 * in compliance with the License. You may obtain a copy of the License at 6 * 7 * http://www.apache.org/licenses/LICENSE-2.0 8 * 9 * Unless required by applicable law or agreed to in writing, software distributed under the License 10 * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express 11 * or implied. See the License for the specific language governing permissions and limitations under 12 * the License. 13 */ 14 15 package com.google.common.hash; 16 17 import com.google.common.annotations.Beta; 18 19 import java.io.Serializable; 20 21 /** 22 * An object which can send data from an object of type {@code T} into a {@code PrimitiveSink}. 23 * Implementations for common types can be found in {@link Funnels}. 24 * 25 * <p>Note that serialization of {@linkplain BloomFilter bloom filters} requires the proper 26 * serialization of funnels. When possible, it is recommended that funnels be implemented as a 27 * single-element enum to maintain serialization guarantees. See Effective Java (2nd Edition), 28 * Item 3: "Enforce the singleton property with a private constructor or an enum type". For example: 29 * <pre> {@code 30 * public enum PersonFunnel implements Funnel<Person> { 31 * INSTANCE; 32 * public void funnel(Person person, PrimitiveSink into) { 33 * into.putUnencodedChars(person.getFirstName()) 34 * .putUnencodedChars(person.getLastName()) 35 * .putInt(person.getAge()); 36 * } 37 * }}</pre> 38 * 39 * @author Dimitris Andreou 40 * @since 11.0 41 */ 42 @Beta 43 public interface Funnel<T> extends Serializable { 44 45 /** 46 * Sends a stream of data from the {@code from} object into the sink {@code into}. There 47 * is no requirement that this data be complete enough to fully reconstitute the object 48 * later. 49 * 50 * @since 12.0 (in Guava 11.0, {@code PrimitiveSink} was named {@code Sink}) 51 */ funnel(T from, PrimitiveSink into)52 void funnel(T from, PrimitiveSink into); 53 } 54