001/*
002 * Copyright (c) 2008, 2009, 2011 Oracle, Inc. All rights reserved.
003 *
004 * This program and the accompanying materials are made available under the
005 * terms of the Eclipse Public License v1.0 and Eclipse Distribution License v. 1.0
006 * which accompanies this distribution.  The Eclipse Public License is available
007 * at http://www.eclipse.org/legal/epl-v10.html and the Eclipse Distribution License
008 * is available at http://www.eclipse.org/org/documents/edl-v10.php.
009 */
010package javax.persistence;
011
012import java.lang.annotation.Repeatable;
013import java.lang.annotation.Retention;
014import java.lang.annotation.Target;
015
016import static java.lang.annotation.ElementType.TYPE;
017import static java.lang.annotation.RetentionPolicy.RUNTIME;
018
019/**
020 * Specifies and names a stored procedure, its parameters, and its result type.
021 * <p>
022 * The NamedStoredProcedureQuery annotation can be applied to an entity or mapped superclass.
023 * <p>
024 * The name element is the name that is passed as an argument to the
025 * {@link EntityManager#createNamedStoredProcedureQuery(String)} method to create an executable
026 * StoredProcedureQuery object. Names are scoped to the persistence unit.
027 * <p>
028 * The procedureName element is the name of the stored procedure in the database.
029 * <p>
030 * The parameters of the stored procedure are specified by the parameters element. All
031 * parameters must be specified in the order in which they occur in the parameter list of the
032 * stored procedure.
033 * <p>
034 * The resultClasses element refers to the class (or classes) that are used to map the results. The
035 * resultSetMappings element names one or more result set mappings, as defined by the
036 * {@link SqlResultSetMapping} annotation.
037 * <p>
038 * If there are multiple result sets, it is assumed that they will be mapped using the same
039 * mechanism — e.g., either all via a set of result class mappings or all via a set of result
040 * set mappings. The order of the specification of these mappings must be the same as the order in
041 * which the result sets will be returned by the stored procedure invocation. If the stored procedure
042 * returns one or more result sets and no resultClasses or resultSetMappings element is specified,
043 * any result set will be returned as a list of type Object[]. The combining of different strategies
044 * for the mapping of stored procedure result sets is undefined.
045 * <p>
046 * The hints element may be used to specify query properties and hints. Properties defined by this
047 * specification must be observed by the provider. Vendor-specific hints that are not recognized
048 * by a provider must be ignored.
049 * <p>
050 * All parameters of a named stored procedure query must be specified using the StoredProcedureParameter
051 * annotation.
052 *
053 * @see StoredProcedureQuery
054 * @see StoredProcedureParameter
055 * @since Java Persistence 2.1
056 */
057@Target(TYPE)
058@Retention(RUNTIME)
059@Repeatable(NamedStoredProcedureQueries.class)
060public @interface NamedStoredProcedureQuery {
061  /**
062   * The name used to refer to the query with the {@link EntityManager} methods that create stored
063   * procedure query objects.
064   *
065   * @return name
066   */
067  String name();
068
069  /**
070   * The name of the stored procedure in the database.
071   *
072   * @return proc name
073   */
074  String procedureName();
075
076  /**
077   * Information about all parameters of the stored procedure.
078   *
079   * @return params
080   */
081  StoredProcedureParameter[] parameters() default {};
082
083  /**
084   * The class or classes that are used to map the results.
085   *
086   * @return result classes
087   */
088  Class[] resultClasses() default {};
089
090  /**
091   * The names of one or more result set mappings, as defined in metadata.
092   *
093   * @return resultset mappings
094   */
095  String[] resultSetMappings() default {};
096
097  /**
098   * Query properties and hints.
099   *
100   * @return any hints
101   */
102  QueryHint[] hints() default {};
103}
104