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    
019    package org.apache.hadoop.io;
020    
021    
022    import java.io.IOException;
023    
024    import org.apache.hadoop.classification.InterfaceAudience;
025    import org.apache.hadoop.classification.InterfaceStability;
026    import org.apache.hadoop.conf.Configuration;
027    import org.apache.hadoop.fs.FileSystem;
028    import org.apache.hadoop.fs.Path;
029    
030    /** A file-based set of keys. */
031    @InterfaceAudience.Public
032    @InterfaceStability.Stable
033    public 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    }