    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;
    022
    023import java.io.InputStream;
    024
    025/**
    026 * The StreamComparator interface allows for two {@link InputStream} instances to be compared, typically bit-wise.
    027 * This is most useful when defining custom types to be stored in {@link Tuple} instances and the values will need
    028 * to be grouped on and/or secondary sorted (via {@link cascading.pipe.GroupBy} and/or {@link cascading.pipe.CoGroup})
    029 * and the underlying serialization implementation enables a useful bit-wise comparison without deserializing the custom
    030 * type into memory.
    031 * <p/>
    032 * Typically this interface is used to mark a {@link java.util.Comparator} as additionally
    033 * supporting the ability to compare raw streams in tandem with comparing Object instances.
    034 * Thus concrete implementations should implement this interface and the Comparator interface when being used
    035 * as a "grouping" or "sorting" field Comparator
    036 * <p/>
    037 * When used with Hadoop, a {@link cascading.tuple.hadoop.io.BufferedInputStream} is passed into the
    038 * {@link #compare(java.io.InputStream, java.io.InputStream)}
    039 * method. This class gives access to the underlying byte[] array so each individual byte need to be
    040 * {@link java.io.InputStream#read()}.
    041 * So it is useful to declare an implementation as
    042 * {@code public class YourCustomComparator implements StreamComparator&lt;BufferedInputStream>, Comparator&lt;YourCustomType>, Serializable}
    043 * <p/>
    044 * Note the method {@link cascading.tuple.hadoop.io.BufferedInputStream#skip(long)} will need to be called with the number
    045 * of bytes read from the underlying byte buffer before the compare() method returns.
    046 *
    047 * @param <T>
    048 */
    049public interface StreamComparator<T extends InputStream>
    050  {
    051  int compare( T lhsStream, T rhsStream );
    052  }