001/**
002 * Licensed to the Apache Software Foundation (ASF) under one
003 * or more contributor license agreements.  See the NOTICE file
004 * distributed with this work for additional information
005 * regarding copyright ownership.  The ASF licenses this file
006 * to you under the Apache License, Version 2.0 (the
007 * "License"); you may not use this file except in compliance
008 * with the License.  You may obtain a copy of the License at
009 *
010 *     http://www.apache.org/licenses/LICENSE-2.0
011 *
012 * Unless required by applicable law or agreed to in writing, software
013 * distributed under the License is distributed on an "AS IS" BASIS,
014 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
015 * See the License for the specific language governing permissions and
016 * limitations under the License.
017 */
018
019package org.apache.hadoop.io;
020
021
022import java.io.IOException;
023
024import org.apache.hadoop.classification.InterfaceAudience;
025import org.apache.hadoop.classification.InterfaceStability;
026import org.apache.hadoop.conf.Configuration;
027import org.apache.hadoop.fs.FileSystem;
028import org.apache.hadoop.fs.Path;
029
030/** A file-based set of keys. */
031@InterfaceAudience.Public
032@InterfaceStability.Stable
033public class SetFile extends MapFile {
034
035  protected SetFile() {}                            // no public ctor
036
037  /** 
038   * Write a new set file.
039   */
040  public static class Writer extends MapFile.Writer {
041
042    /** Create the named set for keys of the named class. 
043     *  @deprecated pass a Configuration too
044     */
045    public Writer(FileSystem fs, String dirName,
046        Class<? extends WritableComparable> keyClass) throws IOException {
047      super(new Configuration(), fs, dirName, keyClass, NullWritable.class);
048    }
049
050    /** Create a set naming the element class and compression type. */
051    public Writer(Configuration conf, FileSystem fs, String dirName,
052                  Class<? extends WritableComparable> keyClass,
053                  SequenceFile.CompressionType compress)
054      throws IOException {
055      this(conf, fs, dirName, WritableComparator.get(keyClass, conf), compress);
056    }
057
058    /** Create a set naming the element comparator and compression type. */
059    public Writer(Configuration conf, FileSystem fs, String dirName,
060                  WritableComparator comparator,
061                  SequenceFile.CompressionType compress) throws IOException {
062      super(conf, new Path(dirName), 
063            comparator(comparator), 
064            valueClass(NullWritable.class), 
065            compression(compress));
066    }
067
068    /** Append a key to a set.  The key must be strictly greater than the
069     * previous key added to the set. */
070    public void append(WritableComparable key) throws IOException{
071      append(key, NullWritable.get());
072    }
073  }
074
075  /** Provide access to an existing set file. */
076  public static class Reader extends MapFile.Reader {
077
078    /** Construct a set reader for the named set.*/
079    public Reader(FileSystem fs, String dirName, Configuration conf) throws IOException {
080      super(fs, dirName, conf);
081    }
082
083    /** Construct a set reader for the named set using the named comparator.*/
084    public Reader(FileSystem fs, String dirName, WritableComparator comparator, Configuration conf)
085      throws IOException {
086      super(new Path(dirName), conf, comparator(comparator));
087    }
088
089    // javadoc inherited
090    @Override
091    public boolean seek(WritableComparable key)
092      throws IOException {
093      return super.seek(key);
094    }
095
096    /** Read the next key in a set into <code>key</code>.  Returns
097     * true if such a key exists and false when at the end of the set. */
098    public boolean next(WritableComparable key)
099      throws IOException {
100      return next(key, NullWritable.get());
101    }
102
103    /** Read the matching key from a set into <code>key</code>.
104     * Returns <code>key</code>, or null if no match exists. */
105    public WritableComparable get(WritableComparable key)
106      throws IOException {
107      if (seek(key)) {
108        next(key);
109        return key;
110      } else
111        return null;
112    }
113  }
114
115}