1 // $Id: Query.java 11282 2007-03-14 22:05:59Z epbernard $
2 package javax.persistence;
3
4 import java.util.Calendar;
5 import java.util.Date;
6 import java.util.List;
7
8
9 /**
10 * Interface used to control query execution.
11 */
12 public interface Query
13 {
14 /**
15 * Execute the query and return the query results as a List.
16 *
17 * @return a list of the results
18 * @throws IllegalStateException f called for a Java Persistence query language UPDATE or DELETE statement
19 */
20 public List getResultList();
21
22 /**
23 * Execute a SELECT query that returns a single result.
24 *
25 * @return the result
26 * @throws NoResultException if there is no result
27 * @throws NonUniqueResultException if more than one result
28 * @throws IllegalStateException if called for a Java
29 * Persistence query language UPDATE or DELETE statement
30 */
31 public Object getSingleResult();
32
33 /**
34 * Execute an update or delete statement.
35 *
36 * @return the number of entities updated or deleted
37 * @throws IllegalStateException if called for a Java Persistence query language SELECT statement
38 * @throws TransactionRequiredException if there is no transaction
39 */
40 public int executeUpdate();
41
42 /**
43 * Set the maximum number of results to retrieve.
44 *
45 * @param maxResult
46 * @return the same query instance
47 * @throws IllegalArgumentException if argument is negative
48 */
49 public Query setMaxResults(int maxResult);
50
51 /**
52 * Set the position of the first result to retrieve.
53 *
54 * @param startPosition position of the first result, numbered from 0
55 * @return the same query instance
56 * @throws IllegalArgumentException if argument is negative
57 */
58 public Query setFirstResult(int startPosition);
59
60 /**
61 * Set an implementation-specific hint. If the hint name is not recognized, it is silently
62 * ignored.
63 *
64 * @param hintName
65 * @param value
66 * @return the same query instance
67 * @throws IllegalArgumentException if the second argument is not valid for the implementation
68 */
69 public Query setHint(String hintName, Object value);
70
71 /**
72 * Bind an argument to a named parameter.
73 *
74 * @param name the parameter name
75 * @param value
76 * @return the same query instance
77 * @throws IllegalArgumentException if parameter name does not correspond to parameter in query
78 * string or argument is of incorrect type
79 */
80 public Query setParameter(String name, Object value);
81
82 /**
83 * Bind an instance of java.util.Date to a named parameter.
84 *
85 * @param name
86 * @param value
87 * @param temporalType
88 * @return the same query instance
89 * @throws IllegalArgumentException if parameter name does not correspond to parameter in query
90 * string
91 */
92 public Query setParameter(String name, Date value, TemporalType temporalType);
93
94 /**
95 * Bind an instance of java.util.Calendar to a named parameter.
96 *
97 * @param name
98 * @param value
99 * @param temporalType
100 * @return the same query instance
101 * @throws IllegalArgumentException if parameter name does not correspond to parameter in query
102 * string
103 */
104 public Query setParameter(String name, Calendar value, TemporalType temporalType);
105
106 /**
107 * Bind an argument to a positional parameter.
108 *
109 * @param position
110 * @param value
111 * @return the same query instance
112 * @throws IllegalArgumentException if position does not correspond to positional parameter of
113 * query or argument is of incorrect type
114 */
115 public Query setParameter(int position, Object value);
116
117 /**
118 * Bind an instance of java.util.Date to a positional parameter.
119 *
120 * @param position
121 * @param value
122 * @param temporalType
123 * @return the same query instance
124 * @throws IllegalArgumentException if position does not correspond to positional parameter of
125 * query
126 */
127 public Query setParameter(int position, Date value, TemporalType temporalType);
128
129 /**
130 * Bind an instance of java.util.Calendar to a positional parameter.
131 *
132 * @param position
133 * @param value
134 * @param temporalType
135 * @return the same query instance } correspond to positional parameter of query
136 */
137 public Query setParameter(int position, Calendar value, TemporalType temporalType);
138
139 /**
140 * Set the flush mode type to be used for the query execution.
141 * The flush mode type applies to the query regardless of the
142 * flush mode type in use for the entity manager.
143 *
144 * @param flushMode
145 */
146 public Query setFlushMode(FlushModeType flushMode);
147
148 }
Save This Page