    001    /*
    002     * Copyright (c) 2007-2014 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
    021    package cascading.pipe.joiner;
    022
    023    import java.io.Serializable;
    024    import java.util.Iterator;
    025
    026    import cascading.tuple.Tuple;
    027
    028    /**
    029     * Interface Joiner allows for custom join strategies against a {@link cascading.pipe.CoGroup}.
    030     * <p/>
    031     * Joins perform based on the equality of the join keys. In the case of null values, Java treats two
    032     * null values as equivalent. SQL does not treat null values as equal. To produce SQL like results in a given
    033     * join, a new {@link java.util.Comparator} will need to be used on the joined values to prevent null from
    034     * equaling null. As a convenience, see the {@link cascading.util.NullNotEquivalentComparator} class.
    035     */
    036    public interface Joiner extends Serializable
    037      {
    038      /**
    039       * Returns an iterator that joins the given CoGroupClosure co-groups.
    040       *
    041       * @param closure of type GroupClosure
    042       * @return an iterator
    043       */
    044      Iterator<Tuple> getIterator( JoinerClosure closure );
    045
    046      /**
    047       * Returns the number of joins this instance can handle. A value of -1 denotes there is no limit.
    048       *
    049       * @return an int
    050       */
    051      int numJoins();
    052      }