001/*
002 * Copyright (c) 2007-2017 Xplenty, 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.tap.partition;
022
023import java.io.Serializable;
024
025import cascading.tuple.Fields;
026import 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 */
037public 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  }