    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.tap.partition;
    022
    023    import java.io.Serializable;
    024
    025    import cascading.tuple.Fields;
    026    import cascading.tuple.TupleEntry;
    027
    028    /**
    029     * The Partition interface allows for custom partitioning mechanisms to be created with the {@link BasePartitionTap}
    030     * sub-classes.
    031     * <p/>
    032     * A partition is a directory on a filesystem, where the directory contains data related to the files underneath
    033     * the partition directory.
    034     * <p/>
    035     * For example, a partition could be {@code "2012/09/01"}, which would contain log files for that day.
    036     */
    037    public interface Partition extends Serializable
    038      {
    039      /**
    040       * Returns the directory search depth of the partition.
    041       * <p/>
    042       * For example, a Partition implementation that returns values like {@code "2012/09/01"} would have a depth of 3.
    043       *
    044       * @return an int
    045       */
    046      int getPathDepth();
    047
    048      /**
    049       * The {@link Fields} used to populate the partition.
    050       *
    051       * @return a Fields instance
    052       */
    053      Fields getPartitionFields();
    054
    055      /**
    056       * Converts the given partition String to a {@link TupleEntry} using the given TupleEntry instance for re-use.
    057       *
    058       * @param partition  a String
    059       * @param tupleEntry a TupleEntry
    060       */
    061      void toTuple( String partition, TupleEntry tupleEntry );
    062
    063      /**
    064       * Converts the given tupleEntry into a partition string.
    065       *
    066       * @param tupleEntry a TupleEntry
    067       * @return a String
    068       */
    069      String toPartition( TupleEntry tupleEntry );
    070      }