Author: adamw Date: 2008-09-03 02:04:11 -0400 (Wed, 03 Sep 2008) New Revision: 138 Modified: trunk/src/main/org/jboss/envers/query/RevisionProperty.java trunk/src/main/org/jboss/envers/query/RevisionTypeProperty.java trunk/src/main/org/jboss/envers/query/criteria/AggregatedFieldVersionsExpression.java trunk/src/main/org/jboss/envers/query/criteria/VersionsConjunction.java trunk/src/main/org/jboss/envers/query/criteria/VersionsDisjunction.java trunk/src/main/org/jboss/envers/query/impl/AbstractVersionsQuery.java trunk/src/main/org/jboss/envers/query/impl/EntitiesAtRevisionQuery.java trunk/src/main/org/jboss/envers/query/impl/Parameters.java trunk/src/main/org/jboss/envers/query/impl/QueryBuilder.java trunk/src/main/org/jboss/envers/query/impl/RevisionsOfEntityQuery.java trunk/src/main/org/jboss/envers/query/order/RevisionVersionsOrder.java trunk/src/main/org/jboss/envers/query/order/VersionsOrder.java trunk/src/main/org/jboss/envers/query/projection/RevisionVersionsProjection.java trunk/src/main/org/jboss/envers/query/projection/VersionsProjection.java Log: ENVERS-47: some comments Modified: trunk/src/main/org/jboss/envers/query/RevisionProperty.java =================================================================== --- trunk/src/main/org/jboss/envers/query/RevisionProperty.java 2008-09-02 11:42:56 UTC (rev 137) +++ trunk/src/main/org/jboss/envers/query/RevisionProperty.java 2008-09-03 06:04:11 UTC (rev 138) @@ -115,13 +115,13 @@ } /** - * Select the revision number + * Projection the revision number */ public static VersionsProjection revisionNumber() { return new RevisionProperty(); } - public Triple<String, String, Boolean> getProjectionData(VersionsConfiguration verCfg) { + public Triple<String, String, Boolean> getData(VersionsConfiguration verCfg) { return Triple.make(null, verCfg.getVerEntCfg().getRevisionPropPath(), false); } } Modified: trunk/src/main/org/jboss/envers/query/RevisionTypeProperty.java =================================================================== --- trunk/src/main/org/jboss/envers/query/RevisionTypeProperty.java 2008-09-02 11:42:56 UTC (rev 137) +++ trunk/src/main/org/jboss/envers/query/RevisionTypeProperty.java 2008-09-03 06:04:11 UTC (rev 138) @@ -33,13 +33,13 @@ private RevisionTypeProperty() { } /** - * Select the revision type + * Projection on the revision type */ public static VersionsProjection revisionType() { return new RevisionTypeProperty(); } - public Triple<String, String, Boolean> getProjectionData(VersionsConfiguration verCfg) { + public Triple<String, String, Boolean> getData(VersionsConfiguration verCfg) { return Triple.make(null, verCfg.getVerEntCfg().getRevisionTypePropName(), false); } } \ No newline at end of file Modified: trunk/src/main/org/jboss/envers/query/criteria/AggregatedFieldVersionsExpression.java =================================================================== --- trunk/src/main/org/jboss/envers/query/criteria/AggregatedFieldVersionsExpression.java 2008-09-02 11:42:56 UTC (rev 137) +++ trunk/src/main/org/jboss/envers/query/criteria/AggregatedFieldVersionsExpression.java 2008-09-03 06:04:11 UTC (rev 138) @@ -68,10 +68,10 @@ // Setting the desired projection of the aggregated query switch (mode) { case MIN: - subQb.addProjection("min", propertyName); + subQb.addProjection("min", propertyName, false); break; case MAX: - subQb.addProjection("max", propertyName); + subQb.addProjection("max", propertyName, false); } // Adding the constrain on the result of the aggregated criteria Modified: trunk/src/main/org/jboss/envers/query/criteria/VersionsConjunction.java =================================================================== --- trunk/src/main/org/jboss/envers/query/criteria/VersionsConjunction.java 2008-09-02 11:42:56 UTC (rev 137) +++ trunk/src/main/org/jboss/envers/query/criteria/VersionsConjunction.java 2008-09-03 06:04:11 UTC (rev 138) @@ -44,7 +44,7 @@ } public void addToQuery(VersionsConfiguration verCfg, String entityName, QueryBuilder qb, Parameters parameters) { - Parameters andParameters = parameters.addSubParameters("and"); + Parameters andParameters = parameters.addSubParameters(Parameters.AND); for (VersionsCriterion criterion : criterions) { criterion.addToQuery(verCfg, entityName, qb, andParameters); Modified: trunk/src/main/org/jboss/envers/query/criteria/VersionsDisjunction.java =================================================================== --- trunk/src/main/org/jboss/envers/query/criteria/VersionsDisjunction.java 2008-09-02 11:42:56 UTC (rev 137) +++ trunk/src/main/org/jboss/envers/query/criteria/VersionsDisjunction.java 2008-09-03 06:04:11 UTC (rev 138) @@ -44,7 +44,7 @@ } public void addToQuery(VersionsConfiguration verCfg, String entityName, QueryBuilder qb, Parameters parameters) { - Parameters orParameters = parameters.addSubParameters("or"); + Parameters orParameters = parameters.addSubParameters(Parameters.OR); for (VersionsCriterion criterion : criterions) { criterion.addToQuery(verCfg, entityName, qb, orParameters); Modified: trunk/src/main/org/jboss/envers/query/impl/AbstractVersionsQuery.java =================================================================== --- trunk/src/main/org/jboss/envers/query/impl/AbstractVersionsQuery.java 2008-09-02 11:42:56 UTC (rev 137) +++ trunk/src/main/org/jboss/envers/query/impl/AbstractVersionsQuery.java 2008-09-03 06:04:11 UTC (rev 138) @@ -29,7 +29,6 @@ import org.jboss.envers.query.projection.VersionsProjection; import org.jboss.envers.exception.VersionsException; import org.jboss.envers.configuration.VersionsConfiguration; -import org.jboss.envers.tools.MutableInteger; import org.jboss.envers.tools.Pair; import org.jboss.envers.tools.Triple; import org.hibernate.*; @@ -69,24 +68,24 @@ entityName = cls.getName(); versionsEntityName = verCfg.getVerEntCfg().getVersionsEntityName(entityName); - qb = new QueryBuilder(versionsEntityName, "e", new MutableInteger(), new MutableInteger()); + qb = new QueryBuilder(versionsEntityName, "e"); } - protected List listQuery() { + protected List buildAndExecuteQuery() { StringBuilder querySb = new StringBuilder(); - Map<String, Object> paramValues = new HashMap<String, Object>(); + Map<String, Object> queryParamValues = new HashMap<String, Object>(); - qb.build(querySb, paramValues); + qb.build(querySb, queryParamValues); Query query = versionsReader.getSession().createQuery(querySb.toString()); - for (Map.Entry<String, Object> paramValue : paramValues.entrySet()) { + for (Map.Entry<String, Object> paramValue : queryParamValues.entrySet()) { query.setParameter(paramValue.getKey(), paramValue.getValue()); } setQueryProperties(query); System.out.println("QUERY: " + querySb); - System.out.println("PARAMS: " + paramValues); + System.out.println("PARAMS: " + queryParamValues); return query.list(); } @@ -125,7 +124,7 @@ } public VersionsQuery addProjection(VersionsProjection projection) { - Triple<String, String, Boolean> projectionData = projection.getProjectionData(verCfg); + Triple<String, String, Boolean> projectionData = projection.getData(verCfg); hasProjection = true; qb.addProjection(projectionData.getFirst(), projectionData.getSecond(), projectionData.getThird()); return this; @@ -138,7 +137,7 @@ } public VersionsQuery addOrder(VersionsOrder order) { - Pair<String, Boolean> orderData = order.getOrderData(verCfg); + Pair<String, Boolean> orderData = order.getData(verCfg); return addOrder(orderData.getFirst(), orderData.getSecond()); } Modified: trunk/src/main/org/jboss/envers/query/impl/EntitiesAtRevisionQuery.java =================================================================== --- trunk/src/main/org/jboss/envers/query/impl/EntitiesAtRevisionQuery.java 2008-09-02 11:42:56 UTC (rev 137) +++ trunk/src/main/org/jboss/envers/query/impl/EntitiesAtRevisionQuery.java 2008-09-03 06:04:11 UTC (rev 138) @@ -62,7 +62,7 @@ String originalIdPropertyName = verEntCfg.getOriginalIdPropName(); // SELECT max(e2.revision) - maxRevQb.addProjection("max", revisionPropertyPath); + maxRevQb.addProjection("max", revisionPropertyPath, false); // e2.revision <= :revision maxRevQb.getRootParameters().addWhereWithParam(revisionPropertyPath, "<=", revision); // e2.id = e.id @@ -78,7 +78,7 @@ criterion.addToQuery(verCfg, entityName, qb, qb.getRootParameters()); } - List queryResult = listQuery(); + List queryResult = buildAndExecuteQuery(); if (hasProjection) { return queryResult; Modified: trunk/src/main/org/jboss/envers/query/impl/Parameters.java =================================================================== --- trunk/src/main/org/jboss/envers/query/impl/Parameters.java 2008-09-02 11:42:56 UTC (rev 137) +++ trunk/src/main/org/jboss/envers/query/impl/Parameters.java 2008-09-03 06:04:11 UTC (rev 138) @@ -9,10 +9,13 @@ import java.util.HashMap; /** - * Parameters of a query. + * Parameters of a query, built using {@link org.jboss.envers.query.impl.QueryBuilder}. * @author Adam Warski (adam at warski dot org) */ public class Parameters { + public final static String AND = "and"; + public final static String OR = "or"; + /** * Main alias of the entity. */ @@ -22,17 +25,26 @@ */ private final String connective; /** - * For use by the parameter generator. + * For use by the parameter generator. Must be the same in all "child" (and parent) parameters. */ private final MutableInteger queryParamCounter; + /** + * A list of sub-parameters (parameters with a different connective). + */ private final List<Parameters> subParameters; + /** + * A list of negated parameters. + */ private final List<Parameters> negatedParameters; + /** + * A list of complete where-expressions. + */ private final List<String> expressions; /** * Values of parameters used in expressions. */ - private final Map<String, Object> queryParamValues; + private final Map<String, Object> localQueryParamValues; Parameters(String alias, String connective, MutableInteger queryParamCounter) { this.alias = alias; @@ -42,13 +54,20 @@ subParameters = new ArrayList<Parameters>(); negatedParameters = new ArrayList<Parameters>(); expressions = new ArrayList<String>(); - queryParamValues = new HashMap<String, Object>(); + localQueryParamValues = new HashMap<String, Object>(); } private String generateQueryParam() { return "_p" + queryParamCounter.getAndIncrease(); } + /** + * Adds sub-parameters with a new connective. That is, the parameters will be grouped in parentheses in the + * generated query, e.g.: ... and (exp1 or exp2) and ..., assuming the old connective is "and", and the + * new connective is "or". + * @param newConnective New connective of the parameters. + * @return Sub-parameters with the given connective. + */ public Parameters addSubParameters(String newConnective) { if (connective.equals(newConnective)) { return this; @@ -59,8 +78,13 @@ } } + /** + * Adds negated parameters, by default with the "and" connective. These paremeters will be grouped in parentheses + * in the generated query and negated, e.g. ... not (exp1 and exp2) ... + * @return Negated sub paremters. + */ public Parameters addNegatedParameters() { - Parameters newParams = new Parameters(alias, "and", queryParamCounter); + Parameters newParams = new Parameters(alias, AND, queryParamCounter); negatedParameters.add(newParams); return newParams; } @@ -96,7 +120,7 @@ expression.append(" ").append(op).append(" "); String paramName = generateQueryParam(); - queryParamValues.put(paramName, paramValue); + localQueryParamValues.put(paramName, paramValue); expression.append(":").append(paramName); expressions.add(expression.toString()); @@ -110,7 +134,7 @@ for (int i=0; i<paramValues.length; i++) { Object paramValue = paramValues[i]; String paramName = generateQueryParam(); - queryParamValues.put(paramName, paramValue); + localQueryParamValues.put(paramName, paramValue); expression.append(":").append(paramName); if (i != paramValues.length-1) { @@ -131,7 +155,7 @@ expression.append(" ").append(op).append(" "); expression.append("("); - right.build(expression, queryParamValues); + right.build(expression, localQueryParamValues); expression.append(")"); expressions.add(expression.toString()); @@ -147,11 +171,11 @@ isFirst.unset(); } - public boolean isEmpty() { + boolean isEmpty() { return expressions.size() == 0 && subParameters.size() == 0 && negatedParameters.size() == 0; } - public void build(StringBuilder sb, Map<String, Object> paramValues) { + void build(StringBuilder sb, Map<String, Object> queryParamValues) { MutableBoolean isFirst = new MutableBoolean(true); for (String expression : expressions) { @@ -159,17 +183,22 @@ } for (Parameters sub : subParameters) { - append(sb, "(", isFirst); - sub.build(sb, paramValues); - sb.append(")"); + if (!subParameters.isEmpty()) { + append(sb, "(", isFirst); + sub.build(sb, queryParamValues); + sb.append(")"); + } } for (Parameters negated : negatedParameters) { - append(sb, "not (", isFirst); - negated.build(sb, paramValues); - sb.append(")"); + if (!negatedParameters.isEmpty()) { + append(sb, "not (", isFirst); + negated.build(sb, queryParamValues); + sb.append(")"); + } } - paramValues.putAll(queryParamValues); + queryParamValues.putAll(localQueryParamValues); } } + Modified: trunk/src/main/org/jboss/envers/query/impl/QueryBuilder.java =================================================================== --- trunk/src/main/org/jboss/envers/query/impl/QueryBuilder.java 2008-09-02 11:42:56 UTC (rev 137) +++ trunk/src/main/org/jboss/envers/query/impl/QueryBuilder.java 2008-09-03 06:04:11 UTC (rev 138) @@ -9,6 +9,7 @@ import java.util.ArrayList; /** + * A class for incrementaly building a HQL query. * @author Adam Warski (adam at warski dot org) */ public class QueryBuilder { @@ -19,20 +20,46 @@ * For use by alias generator (in case an alias is not provided by the user). */ private final MutableInteger aliasCounter; + /** + * For use by parameter generator, in {@link org.jboss.envers.query.impl.Parameters}. This counter must be + * the same in all parameters and sub-queries of this query. + */ private final MutableInteger paramCounter; - private final Parameters parameters; + /** + * Main "where" parameters for this query. + */ + private final Parameters rootParameters; + /** + * A list of pairs (from entity name, alias name). + */ private final List<Pair<String, String>> froms; + /** + * A list of pairs (property name, order ascending?). + */ private final List<Pair<String, Boolean>> orders; + /** + * A list of complete projection definitions: either a sole property name, or a function(property name). + */ private final List<String> projections; - public QueryBuilder(String entityName, String alias, MutableInteger aliasCounter, MutableInteger paramCounter) { + /** + * + * @param entityName Main entity which should be selected. Its properties don't have to be referred to + * using the alias. + * @param alias Alias of the entity + */ + public QueryBuilder(String entityName, String alias) { + this(entityName, alias, new MutableInteger(), new MutableInteger()); + } + + private QueryBuilder(String entityName, String alias, MutableInteger aliasCounter, MutableInteger paramCounter) { this.entityName = entityName; this.alias = alias; this.aliasCounter = aliasCounter; this.paramCounter = paramCounter; - parameters = new Parameters(alias, "and", paramCounter); + rootParameters = new Parameters(alias, "and", paramCounter); froms = new ArrayList<Pair<String, String>>(); orders = new ArrayList<Pair<String, Boolean>>(); @@ -41,6 +68,12 @@ addFrom(entityName, alias); } + /** + * Add an entity from which to select. + * @param entityName Name of the entity from which to select. Its properties always have to be referred to + * using the alias. + * @param alias Alias of the entity. Should be different than all other aliases. + */ public void addFrom(String entityName, String alias) { froms.add(Pair.make(entityName, alias)); } @@ -50,7 +83,8 @@ } /** - * @return A sub-query builder for the same entity (with an auto-generated alias). + * @return A sub-query builder for the same entity (with an auto-generated alias). The sub-query can + * be later used as a value of a parameter. */ public QueryBuilder newSubQueryBuilder() { return newSubQueryBuilder(entityName, generateAlias()); @@ -59,24 +93,21 @@ /** * @param entityName Entity name, which will be the main entity for the sub-query. * @param alias Alias of the entity, which can later be used in parameters. - * @return A sub-query builder for the given entity, with the given alias. + * @return A sub-query builder for the given entity, with the given alias. The sub-query can + * be later used as a value of a parameter. */ public QueryBuilder newSubQueryBuilder(String entityName, String alias) { return new QueryBuilder(entityName, alias, aliasCounter, paramCounter); } public Parameters getRootParameters() { - return parameters; + return rootParameters; } public void addOrder(String propertyName, boolean ascending) { orders.add(Pair.make(propertyName, ascending)); } - public void addProjection(String function, String propertyName) { - addProjection(function, propertyName, false); - } - public void addProjection(String function, String propertyName, boolean distinct) { if (function == null) { projections.add((distinct ? "distinct " : "") + alias + "." + propertyName); @@ -85,7 +116,13 @@ } } - public void build(StringBuilder sb, Map<String, Object> paramValues) { + /** + * Builds the given query, appending results to the given string buffer, and adding all query parameter values + * that are used to the map provided. + * @param sb String builder to which the query will be appended. + * @param queryParamValues Values of parameters used in the query. + */ + public void build(StringBuilder sb, Map<String, Object> queryParamValues) { sb.append("select "); if (projections.size() > 0) { // all projections separated with commas @@ -97,10 +134,10 @@ sb.append(" from "); // all from entities with aliases, separated with commas StringTools.append(sb, getFromList().iterator(), ", "); - // where part - parameters - if (!parameters.isEmpty()) { + // where part - rootParameters + if (!rootParameters.isEmpty()) { sb.append(" where "); - parameters.build(sb, paramValues); + rootParameters.build(sb, queryParamValues); } // orders if (orders.size() > 0) { Modified: trunk/src/main/org/jboss/envers/query/impl/RevisionsOfEntityQuery.java =================================================================== --- trunk/src/main/org/jboss/envers/query/impl/RevisionsOfEntityQuery.java 2008-09-02 11:42:56 UTC (rev 137) +++ trunk/src/main/org/jboss/envers/query/impl/RevisionsOfEntityQuery.java 2008-09-03 06:04:11 UTC (rev 138) @@ -98,7 +98,7 @@ //versionsCriteria.createCriteria("e.originalId._revision").add(Property.forName("id").eq(1)); } - List<Map> queryResult = listQuery(); + List<Map> queryResult = buildAndExecuteQuery(); if (hasProjection) { return queryResult; } else { Modified: trunk/src/main/org/jboss/envers/query/order/RevisionVersionsOrder.java =================================================================== --- trunk/src/main/org/jboss/envers/query/order/RevisionVersionsOrder.java 2008-09-02 11:42:56 UTC (rev 137) +++ trunk/src/main/org/jboss/envers/query/order/RevisionVersionsOrder.java 2008-09-03 06:04:11 UTC (rev 138) @@ -34,7 +34,7 @@ this.asc = asc; } - public Pair<String, Boolean> getOrderData(VersionsConfiguration verCfg) { + public Pair<String, Boolean> getData(VersionsConfiguration verCfg) { String revisionPropPath = verCfg.getVerEntCfg().getRevisionPropPath(); return Pair.make(revisionPropPath, asc); } Modified: trunk/src/main/org/jboss/envers/query/order/VersionsOrder.java =================================================================== --- trunk/src/main/org/jboss/envers/query/order/VersionsOrder.java 2008-09-02 11:42:56 UTC (rev 137) +++ trunk/src/main/org/jboss/envers/query/order/VersionsOrder.java 2008-09-03 06:04:11 UTC (rev 138) @@ -28,5 +28,9 @@ * @author Adam Warski (adam at warski dot org) */ public interface VersionsOrder { - Pair<String, Boolean> getOrderData(VersionsConfiguration verCfg); + /** + * @param verCfg Configuration. + * @return A pair: (property name, ascending?). + */ + Pair<String, Boolean> getData(VersionsConfiguration verCfg); } Modified: trunk/src/main/org/jboss/envers/query/projection/RevisionVersionsProjection.java =================================================================== --- trunk/src/main/org/jboss/envers/query/projection/RevisionVersionsProjection.java 2008-09-02 11:42:56 UTC (rev 137) +++ trunk/src/main/org/jboss/envers/query/projection/RevisionVersionsProjection.java 2008-09-03 06:04:11 UTC (rev 138) @@ -42,7 +42,7 @@ this.type = type; } - public Triple<String, String, Boolean> getProjectionData(VersionsConfiguration verCfg) { + public Triple<String, String, Boolean> getData(VersionsConfiguration verCfg) { String revisionPropPath = verCfg.getVerEntCfg().getRevisionPropPath(); switch (type) { Modified: trunk/src/main/org/jboss/envers/query/projection/VersionsProjection.java =================================================================== --- trunk/src/main/org/jboss/envers/query/projection/VersionsProjection.java 2008-09-02 11:42:56 UTC (rev 137) +++ trunk/src/main/org/jboss/envers/query/projection/VersionsProjection.java 2008-09-03 06:04:11 UTC (rev 138) @@ -29,5 +29,10 @@ * @author Adam Warski (adam at warski dot org) */ public interface VersionsProjection { - Triple<String, String, Boolean> getProjectionData(VersionsConfiguration verCfg); + /** + * + * @param verCfg Configuration. + * @return A triple: (function name - possibly null, property name, add distinct?). + */ + Triple<String, String, Boolean> getData(VersionsConfiguration verCfg); }