001/**
002 * Copyright 2005-2016 The Kuali Foundation
003 *
004 * Licensed under the Educational Community License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 * http://www.opensource.org/licenses/ecl2.php
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016package org.kuali.rice.krad.data.jpa;
017
018import java.lang.annotation.Retention;
019import java.lang.annotation.Target;
020
021import static java.lang.annotation.ElementType.*;
022import static java.lang.annotation.RetentionPolicy.RUNTIME;
023
024/**
025 * Defines a primary key generator that may be referenced by name when a generator element is specified for the
026 * {@link javax.persistence.GeneratedValue} annotation.
027 *
028 * <p>
029 * A portable sequence generator may be specified on the entity class or on the primary key field or property. The scope
030 * of the generator name is global to the persistence unit (across all generator types).
031 * </p>
032 *
033 * <p>
034 * The term "portable" in this case indicates that native sequences will be used if the target database platform
035 * supports them. However, if it does not have native sequence support, then sequence-like behavior will be emulated
036 * using an appropriate strategy for the target platform.
037 * </p>
038 *
039 * <pre>
040 *   Examples:
041 *
042 *   &#064;PortableSequenceGenerator(name="EMP_SEQ")
043 *
044 *   &#064;PortableSequenceGenerator(name="EMP_SEQ", sequenceName="EMP_SEQ", initialValue = 1)
045 * </pre>
046 *
047 * <p>
048 * Current, in order for this annotation to work properly, the
049 * {@link org.kuali.rice.krad.data.jpa.eclipselink.KradEclipseLinkCustomizer} must be configured for the EclipseLink
050 * persistence unit. This can be done manually using
051 * {@link org.eclipse.persistence.config.PersistenceUnitProperties#SESSION_CUSTOMIZER}, or it will be done automatically
052 * when using {@link org.kuali.rice.krad.data.jpa.eclipselink.KradEclipseLinkEntityManagerFactoryBean}.</p>
053 *
054 * @author Kuali Rice Team (rice.collab@kuali.org)
055 */
056@Target({TYPE, METHOD, FIELD})
057@Retention(RUNTIME)
058public @interface PortableSequenceGenerator {
059
060    /**
061     * (Required) A unique generator name that can be referenced by one or more classes to be the generator for primary
062     * key values.
063     *
064     * @return the name of the sequence generator.
065     */
066    String name();
067
068    /**
069     * (Optional) The name of the database sequence object from which to obtain primary key values. If not specified,
070     * will default to the name of this generator.
071     *
072     * @return the sequence name associated with the sequence generator.
073     */
074    String sequenceName() default "";
075
076    /**
077     * (Optional) The value from which the sequence object is to start generating. Only used for generation of the
078     * sequence in the schema.
079     *
080     * <p>
081     * If the sequence construct already exists in the database or schema generation is not enabled, then this value is
082     * effectively ignored.
083     * </p>
084     *
085     * @return the initial value of the sequence.
086     */
087    int initialValue() default 1000;
088
089}