// Copyright 2008 Google Inc.
//
// 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.gwtorm.server;

import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

/**
 * Annotation marking a method in {@link Schema} interface as number generator.
 *
 * <p>Sequence methods must return a primitive <code>int</code> or <code>long</code> type.
 *
 * <pre>
 * public interface BarSchema extends Schema {
 *   &#064;Sequence
 *   int nextId();
 * }
 * </pre>
 *
 * <p>The sequence name will be taken from the method name, after removing the optional prefix
 * "next".
 */
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.METHOD)
public @interface Sequence {
  /** @return the name of the sequence. Defaults to the method name. */
  String name() default "";

  /**
   * @return the initial value of the sequence. Defaults to 1, or whatever the database dialect
   *     defaults to if the sequence starting value is not supplied in the sequence declaration.
   */
  long startWith() default 0;

  /**
   * @return maximum number of values to cache in memory from the sequence. Defaults to -1,
   *     indicating a default caching level should be determined by the database. Cached values may
   *     be lost (never returned by the sequence, creating gaps) if the application or the database
   *     is shutdown and restarted.
   */
  int cache() default -1;
}