Author: gmonroe
Date: Fri Dec 3 15:53:48 2010
New Revision: 1041888
URL: http://svn.apache.org/viewvc?rev=1041888&view=rev
Log:
Updated javadocs / replaced OrderedMap with specific class to encourage case
insensitive use.
Modified:
db/torque/runtime/trunk/src/java/org/apache/torque/util/SummaryHelper.java
Modified:
db/torque/runtime/trunk/src/java/org/apache/torque/util/SummaryHelper.java
URL:
http://svn.apache.org/viewvc/db/torque/runtime/trunk/src/java/org/apache/torque/util/SummaryHelper.java?rev=1041888&r1=1041887&r2=1041888&view=diff
==============================================================================
--- db/torque/runtime/trunk/src/java/org/apache/torque/util/SummaryHelper.java
(original)
+++ db/torque/runtime/trunk/src/java/org/apache/torque/util/SummaryHelper.java
Fri Dec 3 15:53:48 2010
@@ -26,9 +26,7 @@ import java.util.Iterator;
import java.util.List;
import java.util.Vector;
-import org.apache.commons.collections.OrderedMap;
import org.apache.commons.collections.OrderedMapIterator;
-// import org.apache.commons.collections.map.ListOrderedMap;
import org.apache.commons.logging.Log;
import org.apache.commons.logging.LogFactory;
import org.apache.torque.TorqueException;
@@ -42,13 +40,13 @@ import com.workingdogs.village.Value;
* <p>A utility to help produce aggregate summary information about a table.
* The default assumes that the underlying DB supports the SQL 99 Standard
* Aggregate functions, e.g. COUNT, SUM, AVG, MAX, & MIN. However, some
- * non-standard functions (like MySQL's older LEAST instead of MIN can be
+ * non-standard functions (like MySQL's older LEAST instead of MIN can be
* handled programatically if needed (@see Aggregate class)</p>
- *
+ *
* <P>Here is a simple example to generate the results of a query like:</P>
- *
+ *
* <pre>
- * SELECT EMPLOYEE, SUM(HOURS), MIN(HOURS), MAX(HOURS)
+ * SELECT EMPLOYEE, SUM(HOURS), MIN(HOURS), MAX(HOURS)
* FROM TIMESHEET WHERE TYPE = 1 GROUP BY EMPLOYEE ORDER BY EMPLOYEE ASC
* </pre>
* <p>Use the following code</p>
@@ -63,10 +61,11 @@ import com.workingdogs.village.Value;
* sHelper.addAggregate(FunctionFactory.Max(TimeSheetPeer.HOURS),"Max_Hrs");
* List results = sHelper.summarize( c );
* </pre>
- * <p>The results list will be an OrderedMap with a key of either the group by
- * column name or the name specified for the aggregate function (e.g. EMPLOYEE
- * or Hours). The value will be a Village Value Class. Below is a simple
- * way to do this. See the dumpResults* method code for a more complex
example.
+ * <p>The results list will be an ListOrderedMapCI with a key of either the
+ * group by column name or the name specified for the aggregate function (e.g.
+ * EMPLOYEE or Hours). The value will be a Village Value Class. Below is
+ * a simple way to do this. See the dumpResults* method code for a more
+ * complex example.
* </p>
* <pre>
* String emp = results.get("EMPLOYEE").asString();
@@ -80,7 +79,7 @@ import com.workingdogs.village.Value;
* method or by the first table prefix in an aggregate function.</p>
* <p>
* This will also work with joined tables if the criteria is creates as
- * to create valid SQL.</p>
+ * to create valid SQL.</p>
*
* @see org.apache.torque.util.functions.FunctionFactory
* @author <a href="mailto:[email protected]";>Greg Monroe</a>
@@ -89,56 +88,58 @@ import com.workingdogs.village.Value;
public class SummaryHelper
{
static Log logger = LogFactory.getLog(SummaryHelper.class);
-
+
/** A list of the group by columns names (e.g. TABLE.COLUMN) */
private List groupByColumns;
- /** A OrderMap<String,Aggregate.Function> with the aggregate functions
- * to use in generating results. */
- private OrderedMap aggregates;
+ /**
+ * A ListOrderMapCI<String,Aggregate.Function> with the aggregate
+ * functions to use in generating results.
+ */
+ private ListOrderedMapCI aggregates;
/** Flag for excluding unnamed columns. */
private boolean excludeExprColumns = false;
-
+
/**
* Simple constructor
*/
- public SummaryHelper()
+ public SummaryHelper()
{
super();
}
-
+
/**
- * Return a list of OrderedMap objects with the results of the summary
- * query. The OrderedMap objects have a key of the column name or
+ * Return a list of ListOrderedMapCI objects with the results of the
summary
+ * query. The ListOrderedMapCI objects have a key of the column name or
* function alias and are in the order generated by the query.
- *
+ *
* @param crit The base criteria to build on.
- * @return Results as a OrderMap<String,Values> object.
+ * @return Results as a ListOrderMapCI<String,Values> object.
* @throws TorqueException
* @throws DataSetException
*/
- public List summarize( Criteria crit )
- throws TorqueException, DataSetException
+ public List summarize( Criteria crit )
+ throws TorqueException, DataSetException
{
return summarize( crit, null );
}
-
+
/**
- * Return a list of ListOrderedMapCI objects with the results of the
- * summary query. The ListOrderedMapCI objects have a key of the column
+ * Return a list of ListOrderedMapCI objects with the results of the
+ * summary query. The ListOrderedMapCI objects have a key of the column
* name or function alias and are in the order generated by the query.
*
* @param crit The base criteria to build on.
* @param conn The DB Connection to use.
- * @return Results as a OrderMap<String,Values> object.
+ * @return Results as a ListOrderMapCI<String,Values> object.
* @throws TorqueException
* @throws DataSetException
* @see ListOrderedMapCI
*/
- public List summarize( Criteria crit, Connection conn )
- throws TorqueException, DataSetException
+ public List summarize( Criteria crit, Connection conn )
+ throws TorqueException, DataSetException
{
Criteria c = buildCriteria( crit );
-
+
List results;
if (conn == null)
{
@@ -150,19 +151,19 @@ public class SummaryHelper
}
Iterator r = results.iterator();
-
+
Vector resultsList = new Vector(results.size());
- while ( r.hasNext() )
+ while ( r.hasNext() )
{
ListOrderedMapCI recordMap = new ListOrderedMapCI();
Record rec = (Record) r.next();
String cName = null;
Value value = null;
- for ( int i = 1; i <= rec.size(); i++ )
+ for ( int i = 1; i <= rec.size(); i++ )
{
value = rec.getValue(i);
cName = rec.schema().column(i).name();
- if ( cName == null || cName.equals("") )
+ if ( cName == null || cName.equals("") )
{
if ( excludeExprColumns() ) {
continue;
@@ -173,22 +174,22 @@ public class SummaryHelper
}
resultsList.add(recordMap);
}
- return resultsList;
+ return resultsList;
}
-
+
/**
* Builds the criteria to use in summarizing the information. Note that
* the criteria passed in will be modified.
- *
+ *
* @param c The base criteria to build the summary criteria from.
* @return A criteria to use in summarizing the information.
* @throws TorqueException
*/
public Criteria buildCriteria( Criteria c ) throws TorqueException {
-
+
c.getSelectColumns().clear();
c.getGroupByColumns().clear();
-
+
UniqueList criteriaSelectModifiers;
criteriaSelectModifiers = c.getSelectModifiers();
@@ -202,29 +203,29 @@ public class SummaryHelper
List cols = null;
Iterator i = null;
-
+
cols = getGroupByColumns();
i = cols.iterator();
boolean haveFromTable = i.hasNext(); // Group By cols define src table.
- while ( i.hasNext() )
+ while ( i.hasNext() )
{
String col = (String) i.next();
c.addGroupByColumn( col );
c.addSelectColumn(col);
}
- if ( haveFromTable )
+ if ( haveFromTable )
logger.debug("From table defined by Group By Cols");
-
+
// Check if the from table is set via a where clause.
- if ( ! haveFromTable && c.keys().hasMoreElements() )
+ if ( ! haveFromTable && c.keys().hasMoreElements() )
{
haveFromTable = true;
logger.debug("From table defined by a where clause");
}
-
- OrderedMap cMap = getAggregates();
+
+ ListOrderedMapCI cMap = getAggregates();
OrderedMapIterator iMap = cMap.orderedMapIterator();
- while ( iMap.hasNext() )
+ while ( iMap.hasNext() )
{
String key = (String) iMap.next();
SQLFunction f = (SQLFunction) iMap.getValue();
@@ -232,20 +233,20 @@ public class SummaryHelper
if ( ! haveFromTable ) // Last chance. Get it from the func.
{
String col = f.getArgument(0).toString();
- if ( col.contains(".") )
+ if ( col.contains(".") )
{
// Kludgy Where table.col = table.col clause to force
// from table identification.
- c.add( col,(Object)(col + "=" + col), SqlEnum.CUSTOM );
+ c.add( col,(Object)(col + "=" + col), SqlEnum.CUSTOM );
haveFromTable = true;
String table = col.substring(0,col.indexOf('.'));
- logger.debug("From table, '" + table +
+ logger.debug("From table, '" + table +
"', defined from aggregate column");
}
}
}
- if ( ! haveFromTable )
+ if ( ! haveFromTable )
{
throw new TorqueException(
"No FROM table defined by the GroupBy set, " +
@@ -256,49 +257,49 @@ public class SummaryHelper
/**
* <p>
- * Add a column that will be used to group the aggregate results by.
+ * Add a column that will be used to group the aggregate results by.
* This is a first added / first listed on SQL method. E.g.,
* </p>
- * <pre>
- * add(TablePeer.COL1);
+ * <pre>
+ * add(TablePeer.COL1);
* add(TablePeer.COL2);
* </pre>
- *
+ *
* <p>Generates SQL like: SELECT .... GROUP BY Table.COL1, TABLE.COL2</p>
- *
+ *
* @param column
*/
- public void addGroupBy( String column )
+ public void addGroupBy( String column )
{
getGroupByColumns().add(column);
}
-
+
/**
- * Add in an Aggregate function to the summary information.
- *
- * @param alias A valid SQL99 column identifier ([_A-Z0-9] no spaces and
+ * Add in an Aggregate function to the summary information.
+ *
+ * @param alias A valid SQL99 column identifier ([_A-Z0-9] no spaces and
* no key words, e.g. function names.
- * @param function One of the inner classes from the Aggregate class.
+ * @param function One of the inner classes from the Aggregate class.
*/
- public void addAggregate( String alias, SQLFunction function )
+ public void addAggregate( String alias, SQLFunction function )
{
getAggregates().put( alias, function );
}
-
+
/**
* Resets the class internal variables to their initial states so
- * the class can be re-used like a new class.
+ * the class can be re-used like a new class.
*/
- public void clear()
+ public void clear()
{
getGroupByColumns().clear();
getAggregates().clear();
setExcludeExprColumns(false);
}
- public List getGroupByColumns()
+ public List getGroupByColumns()
{
- if ( groupByColumns == null )
+ if ( groupByColumns == null )
{
groupByColumns = new Vector();
}
@@ -309,53 +310,53 @@ public class SummaryHelper
* Get the order map list of aggregate functions to use in
* summarizing this table's informations. The key is used
* as the result column alias.
- *
+ *
* @return the avgColumns. Will always return a ListOrderedMap object.
*/
- public OrderedMap getAggregates()
+ public ListOrderedMapCI getAggregates()
{
- if ( aggregates == null )
+ if ( aggregates == null )
{
aggregates = new ListOrderedMapCI();
}
return aggregates;
}
-
+
/**
- * Convenience method to dump a summary results list to an output writer
- * in a semi-CSV format. E.g., there is no handling of embedded
+ * Convenience method to dump a summary results list to an output writer
+ * in a semi-CSV format. E.g., there is no handling of embedded
* quotes/special characters.
- *
+ *
* @param out
* @param results
* @param includeHeader
* @throws IOException
*/
- public void dumpResults(Writer out, List results, boolean includeHeader )
- throws IOException
+ public void dumpResults(Writer out, List results, boolean includeHeader )
+ throws IOException
{
Iterator i = results.iterator();
boolean first = includeHeader;
-
- while ( i.hasNext() )
+
+ while ( i.hasNext() )
{
- OrderedMap rec = (OrderedMap ) i.next();
+ ListOrderedMapCI rec = (ListOrderedMapCI) i.next();
OrderedMapIterator rI = rec.orderedMapIterator();
String heading = "";
String recString = "";
- while ( rI.hasNext() )
+ while ( rI.hasNext() )
{
String colId = (String) rI.next();
- if ( first )
+ if ( first )
{
heading += "\"" + colId + "\"";
- if ( rI.hasNext() )
+ if ( rI.hasNext() )
{
heading += ", ";
}
}
Value v = (Value) rI.getValue();
- if ( v.isString() )
+ if ( v.isString() )
{
recString += "\"" + v.toString() + "\"";
}
@@ -363,12 +364,12 @@ public class SummaryHelper
{
recString += v.toString();
}
- if ( rI.hasNext() )
+ if ( rI.hasNext() )
{
recString += ", ";
}
}
- if ( first )
+ if ( first )
{
first = false;
out.write(heading);
@@ -380,8 +381,8 @@ public class SummaryHelper
}
/**
- * Should the results include unnamed columns, e.g. EXPR{index#}.
- *
+ * Should the results include unnamed columns, e.g. EXPR{index#}.
+ *
* @return the excludeExprColumns
*/
public boolean excludeExprColumns()
@@ -390,18 +391,17 @@ public class SummaryHelper
}
/**
- * <p>Define if unnamed output columns which get labeled as EXPR{index#})
+ * <p>Define if unnamed output columns which get labeled as EXPR{index#})
* should be included in the the output set.</p>
- * <p>
- * Note these are generally added by the criteria
+ * <p>
+ * Note these are generally added by the criteria
* processing to handle special cases such as case insensitive ordering.
- * </p>
- *
+ * </p>
+ *
* @param excludeExprColumns if True, these columns won't be included.
*/
public void setExcludeExprColumns(boolean excludeExprColumns)
{
this.excludeExprColumns = excludeExprColumns;
}
-
}
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
