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