lucene-java-3.4.0/lucene/contrib/facet/src/java/org/apache/lucene/DocumentBuilder.java

   1 package org.apache.lucene;
   2
   3 import org.apache.lucene.document.Document;
   4 import org.apache.lucene.document.Field;
   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  * An interface which standardizes the process of building an indexable
  25  * {@link Document}.
  26  * <p>
  27  * The idea is that implementations implement {@link #build(Document doc)},
  28  * which adds to the given Document whatever {@link Field}s it wants to add. A
  29  * DocumentBuilder is also allowed to inspect or change existing Fields in the
  30  * Document, if it wishes to.
  31  * <p>
  32  * Implementations should normally have a constructor with parameters which
  33  * determine what {@link #build(Document)} will add to doc.<br>
  34  * To allow reuse of the DocumentBuilder object, implementations are also
  35  * encouraged to have a setter method, which remembers its parameters just like
  36  * the constructor. This setter method cannot be described in this interface,
  37  * because it will take different parameters in each implementation.
  38  * <p>
  39  * The interface defines a builder pattern, which allows applications to invoke
  40  * several document builders in the following way:
  41  *
  42  * <pre>
  43  * builder1.build(builder2.build(builder3.build(new Document())));
  44  * </pre>
  45  *
  46  * @lucene.experimental
  47  */
  48 public interface DocumentBuilder {
  49
  50   /** An exception thrown from {@link DocumentBuilder}'s build(). */
  51   public static class DocumentBuilderException extends Exception {
  52
  53     public DocumentBuilderException() {
  54       super();
  55     }
  56
  57     public DocumentBuilderException(String message) {
  58       super(message);
  59     }
  60
  61     public DocumentBuilderException(String message, Throwable cause) {
  62       super(message, cause);
  63     }
  64
  65     public DocumentBuilderException(Throwable cause) {
  66       super(cause);
  67     }
  68
  69   }
  70
  71   /**
  72    * Adds to the given document whatever {@link Field}s the implementation needs
  73    * to add. Return the docunment instance to allow for chaining calls.
  74    */
  75   public Document build(Document doc) throws DocumentBuilderException;
  76
  77 }