Author: ppoddar
Date: Tue Apr 30 00:18:13 2013
New Revision: 1477417
URL: http://svn.apache.org/r1477417
Log:
Add comments
Modified:
openjpa/sandboxes/21/openjpa-persistence/src/main/java/org/apache/openjpa/persistence/AbstractQuery.java
Modified:
openjpa/sandboxes/21/openjpa-persistence/src/main/java/org/apache/openjpa/persistence/AbstractQuery.java
URL:
http://svn.apache.org/viewvc/openjpa/sandboxes/21/openjpa-persistence/src/main/java/org/apache/openjpa/persistence/AbstractQuery.java?rev=1477417&r1=1477416&r2=1477417&view=diff
==============================================================================
---
openjpa/sandboxes/21/openjpa-persistence/src/main/java/org/apache/openjpa/persistence/AbstractQuery.java
(original)
+++
openjpa/sandboxes/21/openjpa-persistence/src/main/java/org/apache/openjpa/persistence/AbstractQuery.java
Tue Apr 30 00:18:13 2013
@@ -30,8 +30,10 @@ import java.util.Map.Entry;
import java.util.Set;
import javax.persistence.Parameter;
+import javax.persistence.Query;
import javax.persistence.TemporalType;
import javax.persistence.TypedQuery;
+import javax.persistence.criteria.CriteriaBuilder;
import javax.persistence.criteria.ParameterExpression;
import org.apache.openjpa.kernel.Filters;
@@ -41,7 +43,33 @@ import org.apache.openjpa.lib.util.Order
import org.apache.openjpa.meta.QueryMetaData;
/**
- * An abstract implementation of the Query interface.
+ * An abstract implementation of the JPA Query interface.
+ * <br>
+ * The major functions implemented in this abstraction is to handle the
+ * query parameters. All query parameters are internally represented
+ * as {@link Parameter} instances where a {@link Parameter} is an interface
+ * defined in JPA specification.
+ * <br>
+ * The application user can identify a query parameter with a positional index
+ * or a logical name or, in case of Criteria query, as a {@link Parameter}
instance
+ * directly. In each case, this receiver converts the user view of a parameter
+ * to an internal concrete instance of {@link Parameter}.
+ * <br>
+ * Declaring a paremeter and binding it to a query are two distinct operations.
+ * A parameter is declared by parsing a string representaion of a query e.g.
+ * a JPQL string or via e.g. {@link CriteriaBuilder#parameter(Class) explicit
creation}
+ * of a parameter. Whereas, a parameter is bound to a query before executing
+ * a query via {@link Query#setParameter(int, Object)} method or one of its
+ * many variants. A parameter can only be bound if this receiver determines
+ * that the parameter has been declared.
+ * <br>
+ * It is important to note that the bound value of parameter is <em>not</em>
contained
+ * in the parameter instance, but in this receiver itself. This not only
allows the
+ * same parameter instance be used in multiple query objects having bound
+ * to separate values, but also to efficiently determine if all declared
parameters
+ * are bound before query execution.
+ *
+ * @author Pinaki Poddar
*/
public abstract class AbstractQuery<X> implements OpenJPAQuerySPI<X> {
private static final Localizer _loc =
Localizer.forPackage(AbstractQuery.class);
@@ -64,24 +92,6 @@ public abstract class AbstractQuery<X> i
_boundParams = new HashMap<Parameter<?>, Object>();
}
- /**
- * Gets a map of values of each bound parameter indexed by their
<em>original</em> key.
- *
- * @return empty map if no parameter is declared or no parameter is bound
to this query.
- */
- Map<Object, Object> getParameterValues() {
- Map<Object, Object> result = new HashMap<Object, Object>();
- if (_boundParams == null || _boundParams.isEmpty())
- return result;
- for (Map.Entry<Object, Parameter<?>> entry :
getDeclaredParameters().entrySet()) {
- Object paramKey = entry.getKey();
- Parameter<?> param = entry.getValue();
- if (_boundParams.containsKey(param))
- result.put(paramKey, _boundParams.get(param));
- }
- return result;
- }
-
public boolean isNative() {
return QueryLanguages.LANG_SQL.equals(getLanguage());
}
@@ -102,6 +112,24 @@ public abstract class AbstractQuery<X> i
//
=================================================================================
/**
+ * Gets a map of values of each bound parameter indexed by their
<em>original</em> key.
+ *
+ * @return empty map if no parameter is declared or no parameter is bound
to this query.
+ */
+ Map<Object, Object> getParameterValues() {
+ Map<Object, Object> result = new HashMap<Object, Object>();
+ if (_boundParams == null || _boundParams.isEmpty())
+ return result;
+ for (Map.Entry<Object, Parameter<?>> entry :
getDeclaredParameters().entrySet()) {
+ Object paramKey = entry.getKey();
+ Parameter<?> param = entry.getValue();
+ if (_boundParams.containsKey(param))
+ result.put(paramKey, _boundParams.get(param));
+ }
+ return result;
+ }
+
+ /**
* Binds the parameter identified by the given position to the given
value. The parameter are bound to a value in
* the context of this query. The same parameter may be bound to a
different value in the context of another
* query. <br>
@@ -109,17 +137,16 @@ public abstract class AbstractQuery<X> i
* As native queries may not be parsed and hence their declared parameters
may not be known, setting an positional
* parameter has the side-effect of a positional parameter being declared.
*
- * @param position
- * positive, integer position of the parameter
- * @param value
- * an assignment compatible value
+ * @param position positive, integer position of the parameter. The
position is {@code 1}-based
+ * i.e. any value less than {@code 1} is not allowed.
+ * @param value an assignment compatible value
* @return the same query instance
* @throws IllegalArgumentException
* if position does not correspond to a positional parameter
of the query or if the argument is of
* incorrect type
*/
public OpenJPAQuery<X> setParameter(int pos, Object value) {
- if (_convertPositionalParams == true) {
+ if (_convertPositionalParams) {
return setParameter("_" + String.valueOf(pos), value);
}
@@ -267,6 +294,8 @@ public abstract class AbstractQuery<X> i
/**
* Sets the values of the parameters from the given Map. The keys of the
given map designate the name of the
* declared parameter.
+ * <br>
+ * Any parameter that are bound earlier gets cleared as a side-effect.
*/
public OpenJPAQuery<X> setParameters(Map params) {
assertOpen();
@@ -307,7 +336,7 @@ public abstract class AbstractQuery<X> i
* if invoked on a native query unless the same parameter
position is bound already.
*/
public <T> Parameter<T> getParameter(int pos, Class<T> type) {
- if (_convertPositionalParams == true) {
+ if (_convertPositionalParams) {
return getParameter("_" + String.valueOf(pos), type);
}
Parameter<?> param = getParameter(pos);
