11d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert/*
21d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * Copyright (C) 2011 The Guava Authors
31d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert *
41d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
51d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * in compliance with the License. You may obtain a copy of the License at
61d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert *
71d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * http://www.apache.org/licenses/LICENSE-2.0
81d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert *
91d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * Unless required by applicable law or agreed to in writing, software distributed under the License
101d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
111d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * or implied. See the License for the specific language governing permissions and limitations under
121d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * the License.
131d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert */
141d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert
151d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringertpackage com.google.common.hash;
161d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert
171d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringertimport com.google.common.annotations.Beta;
181d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert
197dd252788645e940eada959bdde927426e2531c9Paul Duffinimport java.io.Serializable;
207dd252788645e940eada959bdde927426e2531c9Paul Duffin
211d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert/**
227dd252788645e940eada959bdde927426e2531c9Paul Duffin * An object which can send data from an object of type {@code T} into a {@code PrimitiveSink}.
230888a09821a98ac0680fad765217302858e70fa4Paul Duffin * Implementations for common types can be found in {@link Funnels}.
247dd252788645e940eada959bdde927426e2531c9Paul Duffin *
257dd252788645e940eada959bdde927426e2531c9Paul Duffin * <p>Note that serialization of {@linkplain BloomFilter bloom filters} requires the proper
267dd252788645e940eada959bdde927426e2531c9Paul Duffin * serialization of funnels. When possible, it is recommended that funnels be implemented as a
277dd252788645e940eada959bdde927426e2531c9Paul Duffin * single-element enum to maintain serialization guarantees. See Effective Java (2nd Edition),
287dd252788645e940eada959bdde927426e2531c9Paul Duffin * Item 3: "Enforce the singleton property with a private constructor or an enum type". For example:
297dd252788645e940eada959bdde927426e2531c9Paul Duffin * <pre>   {@code
307dd252788645e940eada959bdde927426e2531c9Paul Duffin *   public enum PersonFunnel implements Funnel<Person> {
317dd252788645e940eada959bdde927426e2531c9Paul Duffin *     INSTANCE;
327dd252788645e940eada959bdde927426e2531c9Paul Duffin *     public void funnel(Person person, PrimitiveSink into) {
330888a09821a98ac0680fad765217302858e70fa4Paul Duffin *       into.putUnencodedChars(person.getFirstName())
340888a09821a98ac0680fad765217302858e70fa4Paul Duffin *           .putUnencodedChars(person.getLastName())
357dd252788645e940eada959bdde927426e2531c9Paul Duffin *           .putInt(person.getAge());
367dd252788645e940eada959bdde927426e2531c9Paul Duffin *     }
377dd252788645e940eada959bdde927426e2531c9Paul Duffin *   }}</pre>
380888a09821a98ac0680fad765217302858e70fa4Paul Duffin *
391d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * @author Dimitris Andreou
401d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert * @since 11.0
411d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert */
421d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert@Beta
437dd252788645e940eada959bdde927426e2531c9Paul Duffinpublic interface Funnel<T> extends Serializable {
447dd252788645e940eada959bdde927426e2531c9Paul Duffin
451d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert  /**
461d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert   * Sends a stream of data from the {@code from} object into the sink {@code into}. There
471d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert   * is no requirement that this data be complete enough to fully reconstitute the object
481d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert   * later.
497dd252788645e940eada959bdde927426e2531c9Paul Duffin   *
507dd252788645e940eada959bdde927426e2531c9Paul Duffin   * @since 12.0 (in Guava 11.0, {@code PrimitiveSink} was named {@code Sink})
511d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert   */
527dd252788645e940eada959bdde927426e2531c9Paul Duffin  void funnel(T from, PrimitiveSink into);
531d580d0f6ee4f21eb309ba7b509d2c6d671c4044Bjorn Bringert}
54