You are viewing a plain text version of this content. The canonical link for it is here.
Posted to jdo-commits@db.apache.org by an...@apache.org on 2015/06/26 19:25:27 UTC
svn commit: r1687819 - in /db/jdo/trunk/api/src/java/javax/jdo:
JDOQLTypedQuery.java JDOQLTypedSubquery.java Query.java
Author: andyj
Date: Fri Jun 26 17:25:26 2015
New Revision: 1687819
URL: http://svn.apache.org/r1687819
Log:
JDO-736 Add some more detail to javadocs. Set parameters via setParameters(...) before calling new execute methods, throw exception if wrong execute method called with/without result etc.
Modified:
db/jdo/trunk/api/src/java/javax/jdo/JDOQLTypedQuery.java
db/jdo/trunk/api/src/java/javax/jdo/JDOQLTypedSubquery.java
db/jdo/trunk/api/src/java/javax/jdo/Query.java
Modified: db/jdo/trunk/api/src/java/javax/jdo/JDOQLTypedQuery.java
URL: http://svn.apache.org/viewvc/db/jdo/trunk/api/src/java/javax/jdo/JDOQLTypedQuery.java?rev=1687819&r1=1687818&r2=1687819&view=diff
==============================================================================
--- db/jdo/trunk/api/src/java/javax/jdo/JDOQLTypedQuery.java (original)
+++ db/jdo/trunk/api/src/java/javax/jdo/JDOQLTypedQuery.java Fri Jun 26 17:25:26 2015
@@ -41,10 +41,10 @@ import javax.jdo.query.TimeExpression;
/**
* Interface for a type-safe query, using a fluent API.
* Designed to handle JDO query requirements as a whole.
+ *
* @param <T> candidate type for this query
*/
-public interface JDOQLTypedQuery<T> extends Serializable, Closeable
-{
+public interface JDOQLTypedQuery<T> extends Serializable, Closeable {
public static final String QUERY_CLASS_PREFIX = "Q";
/**
@@ -246,13 +246,6 @@ public interface JDOQLTypedQuery<T> exte
JDOQLTypedQuery<T> setParameters(Map namedParamMap);
/**
- * Method to set the values of the numbered parameters on this query prior to execution.
- * @param paramValues Values of the numbered parameters, in order.
- * @return This query
- */
- JDOQLTypedQuery<T> setParameters(Object... paramValues);
-
- /**
* Method to set a parameter value for use when executing the query.
* @param paramExpr Parameter expression
* @param value The value
@@ -270,28 +263,25 @@ public interface JDOQLTypedQuery<T> exte
JDOQLTypedQuery<T> setParameter(String paramName, Object value);
/**
- * Method to clear all parameter values.
- * TODO Drop this
- * @return The query
- */
- JDOQLTypedQuery<T> clearParameters();
-
- /**
- * Method to execute the query where there are (potentially) multiple rows and we are returning
- * the candidate type.
+ * Method to execute the query where there are (potentially) multiple rows and we are returning the candidate type.
+ * Any parameters required should be set prior to calling this method, using one of the <cite>setParameters</cite> methods.
+ * <P>Calling this method with a result being specified will result in JDOUserException being thrown.
* @return The results
*/
List<T> executeList();
/**
* Method to execute the query where there is a single row and we are returning the candidate type.
+ * Any parameters required should be set prior to calling this method, using one of the <cite>setParameters</cite> methods.
+ * <P>Calling this method with a result being specified will result in JDOUserException being thrown.
* @return The result
*/
T executeUnique();
/**
- * Method to execute the query where there are (potentially) multiple rows and we are returning either a
- * result type or the candidate type.
+ * Method to execute the query where there are (potentially) multiple rows and we are returning either the result type.
+ * Any parameters required should be set prior to calling this method, using one of the <cite>setParameters</cite> methods.
+ * <P>Calling this method with no result being specified will result in JDOUserException being thrown.
* @param resultCls Result class
* @return The results
* @param <R> result type
@@ -299,8 +289,9 @@ public interface JDOQLTypedQuery<T> exte
<R> List<R> executeResultList(Class<R> resultCls);
/**
- * Method to execute the query where there is a single row and we are returning either a result type
- * or the candidate type.
+ * Method to execute the query where there is a single row and we are returning either the result type.
+ * Any parameters required should be set prior to calling this method, using one of the <cite>setParameters</cite> methods.
+ * <P>Calling this method with no result being specified will result in JDOUserException being thrown.
* @param resultCls Result class
* @return The result
* @param <R> result type
@@ -308,21 +299,24 @@ public interface JDOQLTypedQuery<T> exte
<R> R executeResultUnique(Class<R> resultCls);
/**
- * Method to execute the query where there are (potentially) multiple rows and we have a result defined
- * but no result class.
+ * Method to execute the query where there are (potentially) multiple rows and we have a result defined but no result class.
+ * Any parameters required should be set prior to calling this method, using one of the <cite>setParameters</cite> methods.
+ * <P>Calling this method with no result being specified will result in JDOUserException being thrown.
* @return The results
*/
List<Object> executeResultList();
/**
- * Method to execute the query where there is a single row and we have a result defined
- * but no result class.
+ * Method to execute the query where there is a single row and we have a result defined but no result class.
+ * Any parameters required should be set prior to calling this method, using one of the <cite>setParameters</cite> methods.
+ * <P>Calling this method with no result being specified will result in JDOUserException being thrown.
* @return The results
*/
Object executeResultUnique();
/**
* Method to execute the query deleting the affected instances.
+ * Any parameters required should be set prior to calling this method, using one of the <cite>setParameters</cite> methods.
* @return The number of objects deleted
*/
long deletePersistentAll();
Modified: db/jdo/trunk/api/src/java/javax/jdo/JDOQLTypedSubquery.java
URL: http://svn.apache.org/viewvc/db/jdo/trunk/api/src/java/javax/jdo/JDOQLTypedSubquery.java?rev=1687819&r1=1687818&r2=1687819&view=diff
==============================================================================
--- db/jdo/trunk/api/src/java/javax/jdo/JDOQLTypedSubquery.java (original)
+++ db/jdo/trunk/api/src/java/javax/jdo/JDOQLTypedSubquery.java Fri Jun 26 17:25:26 2015
@@ -36,8 +36,7 @@ import javax.jdo.query.TimeExpression;
*
* @param <T> (Candidate) type being represented
*/
-public interface JDOQLTypedSubquery<T> extends Serializable
-{
+public interface JDOQLTypedSubquery<T> extends Serializable {
/**
* Method to return an expression for the candidate of the subquery.
* Cast the returned expression to the candidate "Q" type to be able to call methods on it.
Modified: db/jdo/trunk/api/src/java/javax/jdo/Query.java
URL: http://svn.apache.org/viewvc/db/jdo/trunk/api/src/java/javax/jdo/Query.java?rev=1687819&r1=1687818&r2=1687819&view=diff
==============================================================================
--- db/jdo/trunk/api/src/java/javax/jdo/Query.java (original)
+++ db/jdo/trunk/api/src/java/javax/jdo/Query.java Fri Jun 26 17:25:26 2015
@@ -994,18 +994,24 @@ public interface Query<T> extends AutoCl
/**
* Method to execute the query where there are (potentially) multiple rows and we are returning the candidate type.
+ * Any parameters required should be set prior to calling this method, using one of the <cite>setParameters</cite> methods.
+ * <P>Calling this method with a result being specified will result in JDOUserException being thrown.
* @return The List of candidate objects
*/
List<T> executeList();
/**
* Method to execute the query where there is a single row and we are returning the candidate type.
+ * Any parameters required should be set prior to calling this method, using one of the <cite>setParameters</cite> methods.
+ * <P>Calling this method with a result being specified will result in JDOUserException being thrown.
* @return The candidate object returned by the query (or null)
*/
T executeUnique();
/**
* Method to execute the query where there are (potentially) multiple rows and we are returning a result type for the specified result.
+ * Any parameters required should be set prior to calling this method, using one of the <cite>setParameters</cite> methods.
+ * <P>Calling this method with no result being specified will result in JDOUserException being thrown.
* @param resultCls The result class
* @return List of result objects
* @param <R> The result type
@@ -1014,6 +1020,8 @@ public interface Query<T> extends AutoCl
/**
* Method to execute the query where there is a single row and we are returning a result type for the specified result.
+ * Any parameters required should be set prior to calling this method, using one of the <cite>setParameters</cite> methods.
+ * <P>Calling this method with no result being specified will result in JDOUserException being thrown.
* @param resultCls The result class
* @return The result object (or null)
* @param <R> The result type
@@ -1022,12 +1030,16 @@ public interface Query<T> extends AutoCl
/**
* Method to execute the query where there are (potentially) multiple rows and we have a result defined but no result class.
+ * Any parameters required should be set prior to calling this method, using one of the <cite>setParameters</cite> methods.
+ * <P>Calling this method with no result being specified will result in JDOUserException being thrown.
* @return The list of query results
*/
List<Object> executeResultList();
/**
* Method to execute the query where there is a single row and we have a result defined but no result class.
+ * Any parameters required should be set prior to calling this method, using one of the <cite>setParameters</cite> methods.
+ * <P>Calling this method with no result being specified will result in JDOUserException being thrown.
* @return The query result (or null)
*/
Object executeResultUnique();