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;
018import static javax.persistence.LockModeType.NONE;
019
020/**
021 * Specifies a static, named query in the Java Persistence query language. Query names are scoped to the
022 * persistence unit. The <code>NamedQuery</code> annotation can be applied to an entity or mapped superclass.
023 * <p>
024 * The following is an example of the definition of a named query in the Java Persistence query language:
025 * <p>
026 * <pre>
027 *    &#064;NamedQuery(
028 *            name="findAllCustomersWithName",
029 *            query="SELECT c FROM Customer c WHERE c.name LIKE :custName"
030 *    )
031 * </pre>
032 * <p>
033 * The following is an example of the use of a named query:
034 * <p>
035 * <pre>
036 *    &#064;PersistenceContext
037 *    public EntityManager em;
038 *    ...
039 *    customers = em.createNamedQuery("findAllCustomersWithName")
040 *            .setParameter("custName", "Smith")
041 *            .getResultList();
042 * </pre>
043 *
044 * @since Java Persistence 1.0
045 */
046@Target({TYPE})
047@Retention(RUNTIME)
048@Repeatable(NamedQueries.class)
049public @interface NamedQuery {
050  /**
051   * (Required) The name used to refer to the query with the {@link EntityManager} methods that create query
052   * objects.
053   *
054   * @return The name
055   */
056  String name();
057
058  /**
059   * (Required) The query string in the Java Persistence query language.
060   *
061   * @return The query
062   */
063  String query();
064
065  /**
066   * (Optional) The lock mode type to use in query execution. If a <code>lockMode</code> other than
067   * <code>LockModeType.NONE</code> is specified, the query must be executed in a transaction.
068   *
069   * @return The lock mode
070   * @since Java Persistence 2.0
071   */
072  LockModeType lockMode() default NONE;
073
074  /**
075   * (Optional) Query properties and hints. May include vendor-specific query hints.
076   *
077   * @return The hints
078   */
079  QueryHint[] hints() default {};
080}