// Copyright 2009 Google Inc. All Rights Reserved.
//
// Licensed 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.

package com.google.enterprise.connector.traversal;

import com.google.common.base.Preconditions;

/**
 * Holder for the desired batch size.
 */
/* Historically this held more data.  It is now a single value. */
public class BatchSize {
  private final int hint;

  /**
   * Constructs a new {@link BatchSize} with a hint of 0.
   */
  public BatchSize() {
    this(0);
  }

  /**
   * Constructs a new {@link BatchSize}, containing an optimal batch size
   * ({@code batchHint}) number of items to return in a
   * {@link com.google.enterprise.connector.spi.DocumentList DocumentList}.
   *<p>
   * Connectors should try to return an optimal size batch to stay within
   * the host load limit.  The hint acts as a suggestion; the connector
   * may choose to return a {@code DocumentList} that contains fewer documents
   * or more documents than the hint.  The {@link Traverser} will iterate over
   * the {@code DocumentList} until it is exhausted or the
   * {@code traversalTimeLimit} expires.
   *
   * @param batchHint optimal number of documents to return in this batch.
   */
  public BatchSize(int batchHint) {
    Preconditions.checkArgument(batchHint >= 0,
                                "Batch Size cannot be negative.");
    this.hint = batchHint;
  }

  /**
   * Returns the optimal traversal batch size.
   * Connectors should try to return an optimal size batch to stay within
   * the host load limit.  The hint acts as a suggestion; the connector
   * may choose to return a {@code DocumentList} that contains fewer documents
   * or more documents than the hint.
   *
   * @return the optimal number of documents to return in this batch.
   */
  public int getHint() {
    return hint;
  }

  @Override
  public String toString() {
    return "BatchSize: hint = " + hint;
  }
}