Author: bpoussin
Date: 2010-01-21 16:59:40 +0100 (Thu, 21 Jan 2010)
New Revision: 1775
Modified:
trunk/topia-persistence/src/main/java/org/nuiton/topia/framework/TopiaQuery.java
Log:
all comment must stop line at 80 chars
Modified: trunk/topia-persistence/src/main/java/org/nuiton/topia/framework/TopiaQuery.java
===================================================================
--- trunk/topia-persistence/src/main/java/org/nuiton/topia/framework/TopiaQuery.java 2010-01-20 10:50:31 UTC (rev 1774)
+++ trunk/topia-persistence/src/main/java/org/nuiton/topia/framework/TopiaQuery.java 2010-01-21 15:59:40 UTC (rev 1775)
@@ -40,15 +40,20 @@
import org.nuiton.topia.persistence.TopiaEntity;
/**
- * Query HQL managment to simplify usage of {@link TopiaContext#find(java.lang.String, java.lang.Object[]) }.
+ * Query HQL managment to simplify usage of
+ * {@link TopiaContext#find(java.lang.String, java.lang.Object[]) }.
*
* TODO-FD20091224 Complete documentation of this class + JUnit Tests
*
* <pre>
- * This class is used to construct a HQL query and then execute it from a TopiaContext. The TopiaQuery is linked to a TopiaEntity which
- * is the main element manipulated in the query. There is two parts in using this class :
- * - construction of the query, using add, addFrom, addOrder, addSelect, addGroup, ...
- * - execution of the query, using executeToEntityList, executeToEntity, executeToInteger, ...
+ * This class is used to construct a HQL query and then execute it from a
+ * TopiaContext. The TopiaQuery is linked to a TopiaEntity which
+ * is the main element manipulated in the query. There is two parts in using
+ * this class :
+ * - construction of the query, using add, addFrom, addOrder, addSelect,
+ * addGroup, ...
+ * - execution of the query, using executeToEntityList, executeToEntity,
+ * executeToInteger, ...
*
* Construction
* ============
@@ -67,9 +72,11 @@
* "firstName", "M%", year, 1980);
*
* TopiaQuery :
- * TopiaQuery query = TopiaQuery.createQuery(Person.class).add(Person.FIRST_NAME, Op.LIKE, "M%").add(Person.YEAR, Op.GT, 1980);
+ * TopiaQuery query = TopiaQuery.createQuery(Person.class).add(
+ * Person.FIRST_NAME, Op.LIKE, "M%").add(Person.YEAR, Op.GT, 1980);
*
- * But the real advantage is when you have some parameters to test before adding them to the query. With the older method, it was tidious to construct
+ * But the real advantage is when you have some parameters to test before adding
+ * them to the query. With the older method, it was tidious to construct
* and add parameters to finally use the find method from TopiaContext.
*
* Example 2 :
@@ -100,7 +107,8 @@
*
* context.find(query, params.toArray());
*
- * Here we have only two non obligatory params, but imagine if we must have almost 6 or 7 parameters like this !
+ * Here we have only two non obligatory params, but imagine if we must have
+ * almost 6 or 7 parameters like this !
*
* TopiaQuery :
* TopiaQuery query = TopiaQuery.createQuery(Person.class);
@@ -116,17 +124,24 @@
* Many ways to create the same query :
* ------------------------------------
*
- * You can use multiple different manners to create a query, it depends on the complexicity. More complex is the query, more easier is to construct it.
+ * You can use multiple different manners to create a query, it depends on the
+ * complexicity. More complex is the query, more easier is to construct it.
*
* HQL : "FROM PersonImpl AS P WHERE (P.company IS NULL OR P.company = :company) AND P.firstName LIKE :firstName"
*
* Using TopiaQuery and an Alias :
* query = TopiaQuery.createQuery(Person.class, "P");
- * 1- query.add("(P.company IS NULL OR P.company = :company") AND P.firstName LIKE :firstName").addParam("company", company).addParam("firstName",firstName + "%");
- * 2- query.add("P.company IS NULL OR P.company = :company").add("P.firstName LIKE :firstName").addParam("company", company).addParam("firstName",firstName + "%");
- * 3- query.add("P.company IS NULL OR P.company = :company").add("P.firstName", Op.LIKE, firstName + "%").addParam("company", company);
+ * 1- query.add("(P.company IS NULL OR P.company = :company") AND P.firstName LIKE :firstName")
+ * .addParam("company", company).addParam("firstName",firstName + "%");
+ * 2- query.add("P.company IS NULL OR P.company = :company")
+ * .add("P.firstName LIKE :firstName").addParam("company", company)
+ * .addParam("firstName",firstName + "%");
+ * 3- query.add("P.company IS NULL OR P.company = :company")
+ * .add("P.firstName", Op.LIKE, firstName + "%")
+ * .addParam("company", company);
*
- * You can use TopiaQuery to create a subquery in an other TopiaQuery, you have to use the method {@link #fullQuery() } to get the full query in HQL and give
+ * You can use TopiaQuery to create a subquery in an other TopiaQuery, you have
+ * to use the method {@link #fullQuery() } to get the full query in HQL and give
* it as a string in the other TopiaQuery.
*
* Execution
@@ -137,19 +152,22 @@
* Default method :
* ----------------
*
- * - execute : as the same result as {@link org.nuiton.topia.TopiaContext#find(java.lang.String, java.lang.Object[]) }
+ * - execute : as the same result as
+ * {@link org.nuiton.topia.TopiaContext#find(java.lang.String, java.lang.Object[]) }
*
* Depends on entity type ;
* ------------------------
*
* - executeToEntity : only one result, the first one
* - executeToEntityList : all results returned in a List
- * - executeToEntityMap : all results returned in a Map with key defined by user or topiaId by default
+ * - executeToEntityMap : all results returned in a Map with key defined by user
+ * or topiaId by default
*
* For aggregate :
* ---------------
*
- * These methods have in argument the SELECT to execute the query. The previous SELECT (if defined) will not be deleted, but temporarly not used.
+ * These methods have in argument the SELECT to execute the query. The previous
+ * SELECT (if defined) will not be deleted, but temporarly not used.
*
* - executeToInteger : for example for "SUM", "COUNT"
* - executeToString : for example for "MAX"
@@ -159,21 +177,28 @@
* Property loading
* ================
*
- * When using Hibernate, some times, Entities linked to the main one will be lazy initialized, but you want them directly when the
- * query will be executed to avoid problems when closing context. You can use the method {@link #addLoad(java.lang.String[]) } to
- * tell the TopiaQuery to load some properties when executing the query. After that, you don't need to call them for loading them in Hibernate.
+ * When using Hibernate, some times, Entities linked to the main one will be
+ * lazy initialized, but you want them directly when the query will be executed
+ * to avoid problems when closing context. You can use the method
+ * {@link #addLoad(java.lang.String[]) } to tell the TopiaQuery to load some
+ * properties when executing the query. After that, you don't need to call them
+ * for loading them in Hibernate.
*
- * The syntax is the same as a property in HQL query using delegation : "person.company" where person and company are entities.
+ * The syntax is the same as a property in HQL query using delegation :
+ * "person.company" where person and company are entities.
*
- * Note : loading only available on collection or entities but not property on a collection of entities which must be made manually.
+ * Note : loading only available on collection or entities but not property
+ * on a collection of entities which must be made manually.
*
- * For a Contact which is linked to a person (entity) and the person linked to company (entity) you can add to a TopiaQuery<Contact> :
+ * For a Contact which is linked to a person (entity) and the person linked to
+ * company (entity) you can add to a TopiaQuery<Contact> :
* query.addLoad("person.company")
*
* For a list of addresses (entity) in the contact you can do :
* query.addLoad("addresses")
*
- * But it's not possible to do for example with meeting (entity) linked to the contact and responsible (entity) linked to a meeting :
+ * But it's not possible to do for example with meeting (entity) linked to the
+ * contact and responsible (entity) linked to a meeting :
* query.addLoad("meetings.responsible")
*
* </pre>
@@ -397,13 +422,16 @@
/**
* Add a property to load when query is executed.
- * Used to avoid LazyInitializationException for property needed after closing context.
+ * Used to avoid LazyInitializationException for property needed after
+ * closing context.
* The property is a string like those in HQL query.
* <pre>
* Exemples :
- * - "person.company" (Property TopiaEntity person linked to the result entity in query and company linked to person)
+ * - "person.company" (Property TopiaEntity person linked to the result
+ * entity in query and company linked to person)
* --> calling myEntity.getPerson().getCompany();
- * - "partyRoles" (Property Collection partyRoles linked to the result entity in query)
+ * - "partyRoles" (Property Collection partyRoles linked to the result
+ * entity in query)
* --> calling myEntity.getPartyRoles().size();
* </pre>
*
@@ -454,7 +482,8 @@
* The constraint is needed to determine what type of operation it is.
* Ex : add("boat", Op.EQ, boat) means -> boat = :boat.
*
- * @param paramName the name of the parameter in the query (attribute of the entity)
+ * @param paramName the name of the parameter in the query (attribute of
+ * the entity)
* @param constraint the operation concerned
* @param paramValue the value of the parameter (an other entity, a String, ...)
* @return the TopiaQuery
@@ -514,9 +543,11 @@
}
/**
- * Add an element to the query with a list of different values. The IN key word will be used to
- * set the different values. An other constraint on nullity can be set with isNull argument.
- * The element can have one of the value from the collection or can be null if the isNull argument is true.
+ * Add an element to the query with a list of different values. The IN key
+ * word will be used to set the different values. An other constraint on
+ * nullity can be set with isNull argument.
+ * The element can have one of the value from the collection or can be null
+ * if the isNull argument is true.
*
* @param paramName name of the parameter in the query
* @param values different values for this parameter
@@ -548,8 +579,9 @@
}
/**
- * Add a map of properties to the where clause of the query. Each property will be added to the query with
- * Op.EQ operation, the key in the map is the property name, and the value is the value of the parameter in the
+ * Add a map of properties to the where clause of the query. Each property
+ * will be added to the query with Op.EQ operation, the key in the map is
+ * the property name, and the value is the value of the parameter in the
* query.
*
* @param properties
@@ -563,7 +595,8 @@
}
/**
- * Add an element to the from in the query. Used to add some other data in the query or for join.
+ * Add an element to the from in the query. Used to add some other data in
+ * the query or for join.
*
* @param str the element to add
* @return the TopiaQuery
@@ -574,8 +607,10 @@
}
/**
- * Add an element to the select in the query. Depends on the result wanted in execute methods. The main entity will be
- * automatically added only if an alias is initialize from constructor. If you want only this select element, use {@link #setSelect(java.lang.String) }
+ * Add an element to the select in the query. Depends on the result wanted
+ * in execute methods. The main entity will be automatically added only if
+ * an alias is initialize from constructor. If you want only this select
+ * element, use {@link #setSelect(java.lang.String) }
* method instead.
*
* @param select element to add
@@ -600,7 +635,8 @@
}
/**
- * Set the select in the query. Depends on the result wanted in execute methods.
+ * Set the select in the query. Depends on the result wanted in execute
+ * methods.
*
* @param select element to set
* @return the TopiaQuery
@@ -611,7 +647,8 @@
}
/**
- * Add the distinct key word in the query. The result will not have multiple same values.
+ * Add the distinct key word in the query. The result will not have multiple
+ * same values.
*
* @return the TopiaQuery
*/
@@ -621,7 +658,8 @@
}
/**
- * Add an element to the order in the query. Used to add some parameters to order by.
+ * Add an element to the order in the query. Used to add some parameters to
+ * order by.
*
* @param order element to add
* @return the TopiaQuery
@@ -641,7 +679,8 @@
}
/**
- * Add an element to the group of the query. Used to add some paramters to group by.
+ * Add an element to the group of the query. Used to add some paramters to
+ * group by.
*
* @param group element to add
* @return the TopiaQuery
@@ -685,7 +724,8 @@
}
/**
- * Simple execution of the query. This method use directly the find method in TopiaContext interface.
+ * Simple execution of the query. This method use directly the find method
+ * in TopiaContext interface.
*
* @param transaction the TopiaContext to use for execution
* @return a List of results
@@ -716,7 +756,8 @@
}
/**
- * Execute the query and get a List of entity. Some properties will be loaded if they are
+ * Execute the query and get a List of entity. Some properties will be
+ * loaded if they are
* prealably set using ${@link #addLoad(java.lang.String[]) }.
*
* @param transaction the TopiaContext to use for execution
@@ -736,7 +777,8 @@
continue;
}
if (o instanceof Object[]) {
- // If it's an array, we want only the first element wich is the entity wanted
+ // If it's an array, we want only the first element wich is the
+ entity wanted
// We know that the array have at least one element
o = ((Object[])o)[0];
}
@@ -744,7 +786,8 @@
throw new ClassCastException(o.getClass().getName() + " can't be cast to " + mainEntityClass.getName() + " o : " + o);
}
E entity = (E)o;
- // Check distinct constraint for complex query where o is firstly an Object[] (potentially distinct results with existing entity to add)
+ // Check distinct constraint for complex query where o is firstly an
+ // Object[] (potentially distinct results with existing entity to add)
if (! (distinct && results.contains(entity)) ) {
if (!getPropertiesToLoad().isEmpty()) {
loadProperties(entity);
@@ -770,7 +813,8 @@
}
/**
- * Execute the query and get a Map of entity with key type in argument. Some properties will be loaded if they are
+ * Execute the query and get a Map of entity with key type in argument. Some
+ * properties will be loaded if they are
* prealably set using ${@link #addLoad(java.lang.String[]) }.
*
* @param <K> the type of the map key
@@ -814,7 +858,8 @@
}
/**
- * Execute the query and get a Map of entity with topiaId in key. Some properties will be loaded if they are
+ * Execute the query and get a Map of entity with topiaId in key. Some
+ * properties will be loaded if they are
* prealably set using ${@link #addLoad(java.lang.String[]) }.
*
* @param transaction the TopiaContext to use for execution
@@ -842,7 +887,8 @@
}
/**
- * Execute the query and get the first result entity. Some properties will be loaded if they are
+ * Execute the query and get the first result entity. Some properties will
+ * be loaded if they are
* prealably set using ${@link #addLoad(java.lang.String[]) }.
*
* @param transaction the TopiaContext to use for execution
@@ -873,7 +919,8 @@
}
/**
- * Execute the query and get an Integer for result. Used for query with COUNT or SUM, ...
+ * Execute the query and get an Integer for result. Used for query with
+ * COUNT or SUM, ...
* The select is overriden to get only the right value for return.
*
* @param transaction the TopiaContext to use for execution
@@ -965,7 +1012,8 @@
}
/**
- * Execute a simple count on the query, i.e. the number of results get from the query.
+ * Execute a simple count on the query, i.e. the number of results get from
+ * the query.
*
* @param transaction the TopiaContext to use for execution
* @return an int corresponding to the number of result in the query
