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.util.Calendar;
013import java.util.Date;
014
015/**
016 * Interface used to control stored procedure query execution.
017 *
018 * @see Query
019 * @see Parameter
020 * @since Java Persistence 2.1
021 */
022public interface StoredProcedureQuery extends Query {
023  /**
024   * Set a query property or hint. The hints elements may be used to specify query properties and hints.
025   * Properties defined by this specification must be observed by the provider. Vendor-specific hints that
026   * are not recognized by a provider must be silently ignored. Portable applications should not rely on the
027   * standard timeout hint. Depending on the database in use, this hint may or may not be observed.
028   *
029   * @param hintName name of the property or hint
030   * @param value    value for the property or hint
031   * @return the same query instance
032   * @throws IllegalArgumentException if the second argument is not valid for the implementation
033   */
034  StoredProcedureQuery setHint(String hintName, Object value);
035
036  /**
037   * Bind the value of a Parameter object.
038   *
039   * @param param parameter object
040   * @param value parameter value
041   * @return the same query instance
042   * @throws IllegalArgumentException if the parameter does not correspond to a parameter of the query
043   */
044  <T> StoredProcedureQuery setParameter(Parameter<T> param, T value);
045
046  /**
047   * Bind an instance of java.util.Calendar to a Parameter object.
048   *
049   * @param param        parameter object
050   * @param value        parameter value
051   * @param temporalType temporal type
052   * @return the same query instance
053   * @throws IllegalArgumentException if the parameter does not correspond to a parameter of the query
054   */
055  StoredProcedureQuery setParameter(Parameter<Calendar> param, Calendar value, TemporalType temporalType);
056
057  /**
058   * Bind an instance of java.util.Date to a Parameter object.
059   *
060   * @param param        parameter object
061   * @param value        parameter value
062   * @param temporalType temporal type
063   * @return the same query instance
064   * @throws IllegalArgumentException if the parameter does not correspond to a parameter of the query
065   */
066  StoredProcedureQuery setParameter(Parameter<Date> param, Date value, TemporalType temporalType);
067
068  /**
069   * Bind an argument to a named parameter.
070   *
071   * @param name  parameter name
072   * @param value parameter value
073   * @return the same query instance
074   * @throws IllegalArgumentException if the parameter name does not correspond to a parameter of the query
075   *                                  or if the argument is of incorrect type
076   */
077  StoredProcedureQuery setParameter(String name, Object value);
078
079  /**
080   * Bind an instance of java.util.Calendar to a named parameter.
081   *
082   * @param name         parameter name
083   * @param value        parameter value
084   * @param temporalType temporal type
085   * @return the same query instance
086   * @throws IllegalArgumentException if the parameter name does not correspond to a parameter of the query
087   *                                  or if the value argument is of incorrect type
088   */
089  StoredProcedureQuery setParameter(String name, Calendar value, TemporalType temporalType);
090
091  /**
092   * Bind an instance of java.util.Date to a named parameter.
093   *
094   * @param name         parameter name
095   * @param value        parameter value
096   * @param temporalType temporal type
097   * @return the same query instance
098   * @throws IllegalArgumentException if the parameter name does not correspond to a parameter of the query
099   *                                  or if the value argument is of incorrect type
100   */
101  StoredProcedureQuery setParameter(String name, Date value, TemporalType temporalType);
102
103  /**
104   * Bind an argument to a positional parameter.
105   *
106   * @param position position
107   * @param value    parameter value
108   * @return the same query instance
109   * @throws IllegalArgumentException if position does not correspond to a positional parameter of the query
110   *                                  or if the argument is of incorrect type
111   */
112  StoredProcedureQuery setParameter(int position, Object value);
113
114  /**
115   * Bind an instance of java.util.Calendar to a positional parameter.
116   *
117   * @param position     position
118   * @param value        parameter value
119   * @param temporalType temporal type
120   * @return the same query instance
121   * @throws IllegalArgumentException if position does not correspond to a positional parameter of the query
122   *                                  or if the value argument is of incorrect type
123   */
124  StoredProcedureQuery setParameter(int position, Calendar value, TemporalType temporalType);
125
126  /**
127   * Bind an instance of java.util.Date to a positional parameter.
128   *
129   * @param position     position
130   * @param value        parameter value
131   * @param temporalType temporal type
132   * @return the same query instance
133   * @throws IllegalArgumentException if position does not correspond to a positional parameter of the query
134   *                                  or if the value argument is of incorrect type
135   */
136  StoredProcedureQuery setParameter(int position, Date value, TemporalType temporalType);
137
138  /**
139   * Set the flush mode type to be used for the query execution. The flush mode type applies to the query
140   * regardless of the flush mode type in use for the entity manager.
141   *
142   * @param flushMode flush mode
143   * @return the same query instance
144   */
145  StoredProcedureQuery setFlushMode(FlushModeType flushMode);
146
147  /**
148   * Register a positional parameter. All positional parameters must be registered.
149   *
150   * @param position parameter position
151   * @param type     type of the parameter
152   * @param mode     parameter mode
153   * @return the same query instance
154   */
155  StoredProcedureQuery registerStoredProcedureParameter(int position, Class type, ParameterMode mode);
156
157  /**
158   * Register a named parameter. When using parameter names, all parameters must be registered in the order
159   * in which they occur in the parameter list of the stored procedure.
160   *
161   * @param parameterName name of the parameter as registered or specified in metadata
162   * @param type          type of the parameter
163   * @param mode          parameter mode
164   * @return the same query instance
165   */
166  StoredProcedureQuery registerStoredProcedureParameter(String parameterName, Class type, ParameterMode mode);
167
168  /**
169   * Retrieve a value passed back from the procedure through an INOUT or OUT parameter. For portability, all
170   * results corresponding to result sets and update counts must be retrieved before the values of output
171   * parameters.
172   *
173   * @param position parameter position
174   * @return the result that is passed back through the parameter
175   * @throws IllegalArgumentException if the position does not correspond to a parameter of the query or is
176   *                                  not an INOUT or OUT parameter
177   */
178  Object getOutputParameterValue(int position);
179
180  /**
181   * Retrieve a value passed back from the procedure through an INOUT or OUT parameter. For portability, all
182   * results corresponding to result sets and update counts must be retrieved before the values of output
183   * parameters.
184   *
185   * @param parameterName name of the parameter as registered or specified in metadata
186   * @return the result that is passed back through the parameter
187   * @throws IllegalArgumentException if the parameter name does not correspond to a parameter of the query
188   *                                  or is not an INOUT or OUT parameter
189   */
190  Object getOutputParameterValue(String parameterName);
191
192  /**
193   * Return true if the first result corresponds to a result set, and false if it is an update count or if
194   * there are no results other than through INOUT and OUT parameters, if any.
195   *
196   * @return true if first result corresponds to result set
197   * @throws QueryTimeoutException if the query execution exceeds the query timeout value set and only the
198   *                               statement is rolled back
199   * @throws PersistenceException  if the query execution exceeds the query timeout value set and the
200   *                               transaction is rolled back
201   */
202  boolean execute();
203
204  /**
205   * Return true if the next result corresponds to a result set, and false if it is an update count or if
206   * there are no results other than through INOUT and OUT parameters, if any.
207   *
208   * @return true if next result corresponds to result set
209   * @throws QueryTimeoutException if the query execution exceeds the query timeout value set and only the
210   *                               statement is rolled back
211   * @throws PersistenceException  if the query execution exceeds the query timeout value set and the
212   *                               transaction is rolled back
213   */
214  boolean hasMoreResults();
215
216  /**
217   * Return the update count or -1 if there is no pending result or if the next result is not an update
218   * count.
219   *
220   * @return update count or -1 if there is no pending result or if the next result is not an update count
221   * @throws QueryTimeoutException if the query execution exceeds the query timeout value set and only the
222   *                               statement is rolled back
223   * @throws PersistenceException  if the query execution exceeds the query timeout value set and the
224   *                               transaction is rolled back
225   */
226  int getUpdateCount();
227
228}