Author: fdesbois Date: 2009-12-21 23:11:23 +0000 (Mon, 21 Dec 2009) New Revision: 144 Modified: trunk/suiviobsmer-business/src/main/java/fr/ifremer/suiviobsmer/TopiaQuery.java Log: Add javadoc Modified: trunk/suiviobsmer-business/src/main/java/fr/ifremer/suiviobsmer/TopiaQuery.java =================================================================== --- trunk/suiviobsmer-business/src/main/java/fr/ifremer/suiviobsmer/TopiaQuery.java 2009-12-21 22:47:09 UTC (rev 143) +++ trunk/suiviobsmer-business/src/main/java/fr/ifremer/suiviobsmer/TopiaQuery.java 2009-12-21 23:11:23 UTC (rev 144) @@ -25,31 +25,53 @@ private static final Logger log = LoggerFactory.getLogger(TopiaQuery.class); + /** Params for HQL query **/ protected List<Object> params; + /** Select part of the query **/ protected String select; + /** From part of the query **/ protected String from; + /** Where part of the query **/ protected String where; + /** Order By part of the query **/ protected String orderBy; + /** Group By part of the query **/ protected String groupBy; + /** Used to determine if parentheses are needed for Where input **/ protected boolean parentheses; + /** + * Enum to simmplify using operation in query + */ public static enum Op { + /** EQUALS **/ EQ("="), + /** GREATER THAN **/ GT(">"), + /** GREATER OR EQUALS **/ GE(">="), + /** LIKE for String manipulation **/ LIKE("LIKE"), + /** LESS THAN **/ LT("<"), + /** LESS OR EQUALS **/ LE("<="), + /** IS NOT NULL **/ NOT_NULL("IS NOT NULL"); protected String value; + /** + * Constructor of the Op Enum. + * + * @param value corresponding to the String for the query + */ Op(String value) { this.value = value; } @@ -60,10 +82,20 @@ } } + /** + * Constructor of TopiaQuery with entityClass initialization. + * + * @param entityClass Class for an entity Query + */ public TopiaQuery(Class<? extends TopiaEntity> entityClass) { this(entityClass.getName()); } + /** + * Constructor of TopiaQuery with String form initialization. + * + * @param from From part for the Query + */ public TopiaQuery(String from) { this.from = " FROM " + from; parentheses = true; @@ -74,6 +106,11 @@ return fullQuery(); } + /** + * Get the full query. + * + * @return a String corresponding to the full query. + */ public String fullQuery() { String result = ""; if (select != null) { @@ -92,6 +129,13 @@ return result.trim(); } + /** + * Add a HQL parameter to the Query. + * + * @param id identification of the param in the query + * @param e value of the param + * @return the TopiaQuery + */ public TopiaQuery addParam(String id, Object e) { if (params == null) { params = new ArrayList<Object>(); @@ -101,6 +145,13 @@ return this; } + /** + * Add a where element to the Query. Could be anything. + * Parentheses are added automatically (even if there are not needed). + * + * @param where element to add + * @return the TopiaQuery + */ public TopiaQuery add(String where) { if (this.where == null) { this.where = " WHERE "; @@ -118,6 +169,15 @@ return this; } + /** + * Add an element to the query. The parameter will be automatically added. + * The constraint is needed to determine what type of operation it is. + * + * @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 + */ public TopiaQuery add(String paramName, Op constraint, Object paramValue) { int dot = paramName.lastIndexOf("."); String valueName = paramName; @@ -128,19 +188,47 @@ return add(paramName + " " + constraint + " :" + valueName).addParam(valueName, paramValue); } + /** + * Add an element to the query with the constraint Not null. + * + * @param paramName name of the parameter in the query + * @return the TopiaQuery + */ public TopiaQuery addNotNull(String paramName) { return add(paramName + " " + Op.NOT_NULL); } + /** + * Add an element to the query. The parameter will be automatically added. + * The default constrainst operation is Op.EQ for EQUALS. + * Ex : add("boat", boat) means -> boat = :boat. + * + * @param paramName name of the parameter in the query + * @param paramValue value of the parameter + * @return the TopiaQuery + * @see #add(java.lang.String, fr.ifremer.suiviobsmer.TopiaQuery.Op, java.lang.Object) + */ public TopiaQuery add(String paramName, Object paramValue) { return add(paramName, Op.EQ, paramValue); } + /** + * 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 + */ public TopiaQuery addFrom(String str) { from += ", " + str; return this; } + /** + * Add an element to the select in the query. Used to add some parameters for the return of query. + * + * @param select element to add + * @return the TopiaQuery + */ public TopiaQuery addSelect(String select) { if (this.select == null) { this.select = "SELECT "; @@ -151,6 +239,12 @@ return this; } + /** + * 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 + */ public TopiaQuery addOrder(String order) { if (orderBy == null) { orderBy = " ORDER BY "; @@ -161,6 +255,12 @@ return this; } + /** + * 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 + */ public TopiaQuery addGroup(String group) { if (groupBy == null) { groupBy = " GROUP BY "; @@ -171,6 +271,14 @@ return this; } + /** + * 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 + * @throws TopiaException + * @see org.nuiton.topia.TopiaContext#find(java.lang.String, java.lang.Object[]) + */ public List execute(TopiaContext transaction) throws TopiaException { if (log.isTraceEnabled()) { log.trace("# QUERY : " + fullQuery()); @@ -184,6 +292,15 @@ return transaction.find(fullQuery(), params.toArray()); } + /** + * Execute the query and get a List of entity. + * + * @param <T> the type of TopiaEntity to return + * @param transaction the TopiaContext to use for execution + * @param entityClass the class of the TopiaEntity used for return type + * @return a List of TopiaEntity corresponding to the entityClass in argument + * @throws TopiaException + */ public <T extends TopiaEntity> List<T> executeToEntityList(TopiaContext transaction, Class<T> entityClass) throws TopiaException { List res = execute(transaction); List<T> results = new ArrayList<T>(); @@ -194,11 +311,29 @@ return results; } + /** + * Execute the query and get the first result entity. + * + * @param <T> the type of TopiaEntity to return + * @param transaction the TopiaContext to use for execution + * @param entityClass the class of the TopiaEntity used for return type + * @return a TopiaEntity corresponding to the entityClass in argument + * @throws TopiaException + */ public <T extends TopiaEntity> T executeToEntity(TopiaContext transaction, Class<T> entityClass) throws TopiaException { List<T> results = executeToEntityList(transaction, entityClass); return !results.isEmpty() ? results.get(0) : null; } + /** + * Execute the query and get an Integer for result. Used for query with COUNT or MAX, ... + * The select is overriden to get only the right value for return. + * + * @param transaction the TopiaContext to use for execution + * @param select the Select overriden (ex : MAX(myParam)) + * @return an Integer + * @throws TopiaException + */ public int executeToInteger(TopiaContext transaction, String select) throws TopiaException { String oldValue = this.select; this.select = "SELECT " + select; @@ -212,6 +347,13 @@ return result; } + /** + * 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 + * @throws TopiaException + */ public int executeCount(TopiaContext transaction) throws TopiaException { return executeToInteger(transaction, "COUNT(*)"); }