001    /*
002     * Copyright (c) 2007-2015 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      }