package org.apache.lucene.index;

/**
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You under the Apache License, Version 2.0
 * (the "License"); you may not use this file except in compliance with
 * the License.  You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

import java.io.IOException;

import org.apache.lucene.search.DocIdSetIterator;
import org.apache.lucene.util.AttributeSource;
import org.apache.lucene.util.IntsRef;

/** Iterates through the documents, term freq and positions.
 *  NOTE: you must first call {@link #nextDoc}.
 *
 *  @lucene.experimental */
public abstract class DocsEnum extends DocIdSetIterator {

  private AttributeSource atts = null;

  /** Returns term frequency in the current document.  Do
   *  not call this before {@link #nextDoc} is first called,
   *  nor after {@link #nextDoc} returns NO_MORE_DOCS. */
  public abstract int freq();
  
  /** Returns the related attributes. */
  public AttributeSource attributes() {
    if (atts == null) atts = new AttributeSource();
    return atts;
  }

  // TODO: maybe add bulk read only docIDs (for eventual
  // match-only scoring)

  public static class BulkReadResult {
    public final IntsRef docs = new IntsRef();
    public final IntsRef freqs = new IntsRef();
  }

  protected BulkReadResult bulkResult;

  protected final void initBulkResult() {
    if (bulkResult == null) {
      bulkResult = new BulkReadResult();
      bulkResult.docs.ints = new int[64];
      bulkResult.freqs.ints = new int[64];
    }
  }

  public BulkReadResult getBulkResult() {
    initBulkResult();
    return bulkResult;
  }
  
  /** Bulk read (docs and freqs).  After this is called,
   * {@link #docID()} and {@link #freq} are undefined.  This
   * returns the count read, or 0 if the end is reached.
   * The IntsRef for docs and freqs will not have their
   * length set.
   * 
   *  <p>NOTE: the default impl simply delegates to {@link
   *  #nextDoc}, but subclasses may do this more
   *  efficiently. */
  public int read() throws IOException {
    int count = 0;
    final int[] docs = bulkResult.docs.ints;
    final int[] freqs = bulkResult.freqs.ints;
    while(count < docs.length) {
      final int doc = nextDoc();
      if (doc != NO_MORE_DOCS) {
        docs[count] = doc;
        freqs[count] = freq();
        count++;
      } else {
        break;
      }
    }
    return count;
  }
}

@@ -2072,16 +2072,209 @@
  %7D%0A  %7D%0A%0A
+  /** Call this once, up front, and hold a reference to the%0A   *  returned bulk result.  When you call %7B@link #read%7D, it%0A   *  fills the docs and freqs of this pre-shared bulk%0A   *  result. */%0A
   public
@@ -2420,16 +2420,17 @@
 ed,%0A   *
+ 
  %7B@link 
@@ -2475,19 +2475,19 @@
 ned.
+%0A   *
   This
-%0A   *
  ret
@@ -2525,16 +2525,22 @@
 e end is
+%0A   * 
  reached
@@ -2544,25 +2544,184 @@
 hed.
+  The resulting docs and freqs are placed into%0A   *  the pre-shard %7B@link BulkReadResult%7D instance returned%0A   *  by %7B@link #getBulkResult%7D.  Note that the %7B@link
 %0A   * 
-The
  IntsRef
  for
@@ -2716,16 +2716,17 @@
  IntsRef
+%7D
  for doc
@@ -2760,20 +2760,21 @@
 heir
-%0A   *
  length
+%0A   * 
  set

improve flex javadocs