lucene-java-3.5.0/lucene/contrib/facet/src/java/org/apache/lucene/util/encoding/IntEncoder.java

   1 package org.apache.lucene.util.encoding;
   2
   3 import java.io.IOException;
   4 import java.io.OutputStream;
   5
   6 /**
   7  * Licensed to the Apache Software Foundation (ASF) under one or more
   8  * contributor license agreements.  See the NOTICE file distributed with
   9  * this work for additional information regarding copyright ownership.
  10  * The ASF licenses this file to You under the Apache License, Version 2.0
  11  * (the "License"); you may not use this file except in compliance with
  12  * the License.  You may obtain a copy of the License at
  13  *
  14  *     http://www.apache.org/licenses/LICENSE-2.0
  15  *
  16  * Unless required by applicable law or agreed to in writing, software
  17  * distributed under the License is distributed on an "AS IS" BASIS,
  18  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  19  * See the License for the specific language governing permissions and
  20  * limitations under the License.
  21  */
  22
  23 /**
  24  * Encodes integers to a set {@link OutputStream}. Extending classes need to
  25  * override {@link #encode(int)} to encode the value using their encoding
  26  * algorithm. The default implementation of {@link #close()} closes the set
  27  * {@link OutputStream}.
  28  * <p>
  29  * The default {@link #IntEncoder() constructor} is provided for convenience
  30  * only. One must call {@link #reInit(OutputStream)} before calling
  31  * {@link #encode(int)} or {@link #close()}.
  32  * <p>
  33  * For convenience, each encoder implements {@link #createMatchingDecoder()} for
  34  * easy access to the matching decoder.
  35  * <p>
  36  * <b>NOTE:</b> some implementations may buffer the encoded values in memory
  37  * (such as {@link IntEncoderFilter} implementations) and encoding will happen
  38  * only upon calling {@link #close()}. Therefore it is important to always call
  39  * {@link #close()} on the encoder at hand.
  40  * <p>
  41  * <b>NOTE:</b> encoders are usually not thread safe, unless specifically
  42  * documented otherwise by an implementation.
  43  *
  44  * @lucene.experimental
  45  */
  46 public abstract class IntEncoder {
  47
  48   protected OutputStream out = null;
  49
  50   /**
  51    * Default constructor, provided here for robustness: if in the future a
  52    * constructor with parameters will be added, this might break custom
  53    * implementations of this class which call this implicit constructor. So we
  54    * make it explicit to avoid any such issue in the future.
  55    */
  56   public IntEncoder() {
  57   }
  58
  59   /**
  60    * Instructs the encoder to finish the encoding process. This method closes
  61    * the output stream which was specified by {@link #reInit(OutputStream)
  62    * reInit}. An implementation may do here additional cleanup required to
  63    * complete the encoding, such as flushing internal buffers, etc.<br>
  64    * Once this method was called, no further calls to {@link #encode(int)
  65    * encode} should be made before first calling {@link #reInit(OutputStream)
  66    * reInit}.
  67    * <p>
  68    * <b>NOTE:</b> overriding classes should make sure they either call
  69    * <code>super.close()</code> or close the output stream themselves.
  70    */
  71   public void close() throws IOException {
  72     if (out != null) {
  73       out.close();
  74     }
  75   }
  76
  77   /**
  78    * Encodes an integer to the output stream given in
  79    * {@link #reInit(OutputStream) reInit}
  80    */
  81   public abstract void encode(int value) throws IOException;
  82
  83   /**
  84    * Returns an {@link IntDecoder} which matches this encoder. Every encoder
  85    * must return an {@link IntDecoder} and <code>null</code> is not a valid
  86    * value. If an encoder is just a filter, it should at least return its
  87    * wrapped encoder's matching decoder.
  88    * <p>
  89    * <b>NOTE:</b> this method should create a new instance of the matching
  90    * decoder and leave the instance sharing to the caller. Returning the same
  91    * instance over and over is risky because encoders and decoders are not
  92    * thread safe.
  93    */
  94   public abstract IntDecoder createMatchingDecoder();
  95
  96   /**
  97    * Reinitializes the encoder with the give {@link OutputStream}. For
  98    * re-usability it can be changed without the need to reconstruct a new
  99    * object.
 100    * <p>
 101    * <b>NOTE:</b> after calling {@link #close()}, one <u><i>must</i></u> call
 102    * this method even if the output stream itself hasn't changed. An example
 103    * case is that the output stream wraps a byte[], and the output stream itself
 104    * is reset, but its instance hasn't changed. Some implementations of
 105    * {@link IntEncoder} may write some metadata about themselves to the output
 106    * stream, and therefore it is imperative that one calls this method before
 107    * encoding any data.
 108    */
 109   public void reInit(OutputStream out) {
 110     this.out = out;
 111   }
 112
 113 }