dhis2-devs team mailing list archive

[noreply@xxxxxxxxxxxxx]

------------------------------------------------------------
revno: 11224
committer: Lars Helge Øverland <larshelge@xxxxxxxxx>
branch nick: dhis2
timestamp: Tue 2013-06-18 13:33:56 +0200
message:
  Analytics, added convenience methods to DataQueryParams and improved javadoc on AnalyticsService interface in order to make it easier to use analytics from Java
modified:
  dhis-2/dhis-services/dhis-service-analytics/src/main/java/org/hisp/dhis/analytics/AnalyticsService.java
  dhis-2/dhis-services/dhis-service-analytics/src/main/java/org/hisp/dhis/analytics/DataQueryParams.java
  dhis-2/dhis-services/dhis-service-reporting/src/main/java/org/hisp/dhis/datasetreport/jdbc/AnalyticsDataSetReportStore.java


--
lp:dhis2
https://code.launchpad.net/~dhis2-devs-core/dhis2/trunk

Your team DHIS 2 developers is subscribed to branch lp:dhis2.
To unsubscribe from this branch go to https://code.launchpad.net/~dhis2-devs-core/dhis2/trunk/+edit-subscription

=== modified file 'dhis-2/dhis-services/dhis-service-analytics/src/main/java/org/hisp/dhis/analytics/AnalyticsService.java'
--- dhis-2/dhis-services/dhis-service-analytics/src/main/java/org/hisp/dhis/analytics/AnalyticsService.java	2013-05-29 18:35:32 +0000
+++ dhis-2/dhis-services/dhis-service-analytics/src/main/java/org/hisp/dhis/analytics/AnalyticsService.java	2013-06-18 11:33:56 +0000
@@ -36,6 +36,54 @@
 import org.hisp.dhis.i18n.I18nFormat;
 
 /**
+ * This interface is responsible for retrieving aggregated data. Data will be
+ * returned in a grid object or as a dimensional key-value mapping. 
+ * 
+ * Most objects accept a DataQueryParams object which encapsulates the query 
+ * parameters. The dimensions in the response will appear in the same order as
+ * they are set on the DataQueryParams object. You can use various methods for
+ * setting indicators, data elements, data sets, periods, organisation units,
+ * categories, data element group sets and organisation unit group sets on the
+ * the DataQueryParams object. Objects can be defined as dimensions or filters.
+ * 
+ * Example usage for setting multiple indicators and a period as dimensions
+ * and an organisation unit as filter. In the grid response the first column
+ * will contain indicator identifiers, the second column will contain period
+ * identifiers and the third column will contain aggregated values. Note that
+ * the organisation unit is excluded since it is defined as a filter:
+ * 
+ * <pre>
+ * <code>
+ * DataQueryParams params = new DataQueryParams();
+ * 
+ * params.setIndicators( indicators );
+ * params.setPeriod( period );
+ * params.setFilterOrganisationUnit( organisationUnit );
+ * 
+ * Grid grid = analyticsService.getAggregatedDataValues( params );
+ * </code>
+ * </pre>
+ * 
+ * Example usage for including category option combos in the response. Note that 
+ * the index position of category option combos will follow the order of when the
+ * enableCategoryOptionCombos method was called. In the map response, the keys
+ * will represent the dimensions defined in the DataQueryParams object and will
+ * contain dimension identifiers separated by the "-" character. The key will
+ * be of type String and contain a data element identifier, a category option 
+ * combo identifier and an organisation unit identifier in that order. The map 
+ * values will be the aggregated values of type Double:
+ * 
+ * <pre>
+ * <code>
+ * DataQueryParams params = new DataQueryParams();
+ * 
+ * params.setDataElement( dataElement );
+ * params.enableCategoryOptionCombos();
+ * params.setOrganisationUnits( organisationUnits );
+ * params.setFilterPeriod( period );
+ * 
+ * Map<String, Double> map = analyticsService.getAggregatedDataValueMapping( params );
+ * 
  * @author Lars Helge Overland
  */
 public interface AnalyticsService
@@ -53,7 +101,7 @@
     /**
      * Generates an aggregated value grid for the given query. The grid will
      * represent a table with dimensions used as columns and rows as specified
-     * in columnDimensions and rowDimensions arguments.
+     * in columns and rows dimension arguments.
      * 
      * @param params the data query parameters.
      * @param tableLayout whether to render the grid as a table with columns and rows,

=== modified file 'dhis-2/dhis-services/dhis-service-analytics/src/main/java/org/hisp/dhis/analytics/DataQueryParams.java'
--- dhis-2/dhis-services/dhis-service-analytics/src/main/java/org/hisp/dhis/analytics/DataQueryParams.java	2013-06-05 15:59:40 +0000
+++ dhis-2/dhis-services/dhis-service-analytics/src/main/java/org/hisp/dhis/analytics/DataQueryParams.java	2013-06-18 11:33:56 +0000
@@ -36,10 +36,10 @@
 import static org.hisp.dhis.common.DimensionalObject.DATAELEMENT_OPERAND_ID;
 import static org.hisp.dhis.common.DimensionalObject.DATASET_DIM_ID;
 import static org.hisp.dhis.common.DimensionalObject.DATA_X_DIM_ID;
+import static org.hisp.dhis.common.DimensionalObject.DIMENSION_SEP;
 import static org.hisp.dhis.common.DimensionalObject.INDICATOR_DIM_ID;
 import static org.hisp.dhis.common.DimensionalObject.ORGUNIT_DIM_ID;
 import static org.hisp.dhis.common.DimensionalObject.PERIOD_DIM_ID;
-import static org.hisp.dhis.common.DimensionalObject.DIMENSION_SEP;
 import static org.hisp.dhis.common.NameableObjectUtils.asList;
 import static org.hisp.dhis.common.NameableObjectUtils.getList;
 import static org.hisp.dhis.system.util.CollectionUtils.emptyIfNull;
@@ -1190,6 +1190,11 @@
         setDimensionOptions( INDICATOR_DIM_ID, DimensionType.INDICATOR, null, asList( indicators ) );
     }
     
+    public void setIndicator( NameableObject indicator )
+    {
+        setIndicators( getList( indicator ) );
+    }
+    
     public List<NameableObject> getDataElements()
     {
         return getDimensionOptions( DATAELEMENT_DIM_ID );
@@ -1200,6 +1205,11 @@
         setDimensionOptions( DATAELEMENT_DIM_ID, DimensionType.DATAELEMENT, null, asList( dataElements ) );
     }
     
+    public void setDataElement( NameableObject dataElement )
+    {
+        setDataElements( getList( dataElement ) );
+    }
+    
     public List<NameableObject> getDataSets()
     {
         return getDimensionOptions( DATASET_DIM_ID );
@@ -1210,6 +1220,11 @@
         setDimensionOptions( DATASET_DIM_ID, DimensionType.DATASET, null, asList( dataSets ) );
     }
     
+    public void setDataSet( NameableObject dataSet )
+    {
+        setDataSets( getList( dataSet ) );
+    }
+    
     public List<NameableObject> getPeriods()
     {
         return getDimensionOptions( PERIOD_DIM_ID );
@@ -1219,6 +1234,11 @@
     {
         setDimensionOptions( PERIOD_DIM_ID, DimensionType.PERIOD, null, asList( periods ) );
     }
+    
+    public void setPeriod( NameableObject period )
+    {
+        setPeriods( getList( period ) );
+    }
 
     public List<NameableObject> getOrganisationUnits()
     {
@@ -1230,6 +1250,11 @@
         setDimensionOptions( ORGUNIT_DIM_ID, DimensionType.ORGANISATIONUNIT, null, asList( organisationUnits ) );
     }
     
+    public void setOrganisationUnit( NameableObject organisationUnit )
+    {
+        setOrganisationUnits( getList( organisationUnit ) );
+    }
+    
     public List<DimensionalObject> getDataElementGroupSets()
     {
         List<DimensionalObject> list = new ArrayList<DimensionalObject>();
@@ -1287,6 +1312,11 @@
         setFilterOptions( PERIOD_DIM_ID, DimensionType.PERIOD, null, periods );
     }
     
+    public void setFilterPeriod( Period period )
+    {
+        setFilterPeriods( getList( period ) );
+    }
+    
     public List<NameableObject> getFilterOrganisationUnits()
     {
         return getFilterOptions( ORGUNIT_DIM_ID );
@@ -1297,6 +1327,11 @@
         setFilterOptions( ORGUNIT_DIM_ID, DimensionType.ORGANISATIONUNIT, null, organisationUnits );
     }
     
+    public void setFilterOrganisationUnit( NameableObject organisationUnit )
+    {
+        setFilterOrganisationUnits( getList( organisationUnit ) );
+    }
+    
     public void setFilter( String filter, DimensionType type, NameableObject item )
     {
         setFilterOptions( filter, type, null, getList( item ) );

=== modified file 'dhis-2/dhis-services/dhis-service-reporting/src/main/java/org/hisp/dhis/datasetreport/jdbc/AnalyticsDataSetReportStore.java'
--- dhis-2/dhis-services/dhis-service-reporting/src/main/java/org/hisp/dhis/datasetreport/jdbc/AnalyticsDataSetReportStore.java	2013-05-23 13:38:20 +0000
+++ dhis-2/dhis-services/dhis-service-reporting/src/main/java/org/hisp/dhis/datasetreport/jdbc/AnalyticsDataSetReportStore.java	2013-06-18 11:33:56 +0000
@@ -27,8 +27,6 @@
  * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  */
 
-import static org.hisp.dhis.common.NameableObjectUtils.getList;
-
 import java.util.ArrayList;
 import java.util.HashMap;
 import java.util.List;
@@ -84,8 +82,8 @@
         DataQueryParams params = new DataQueryParams();
         
         params.setDataElements( dataElements );
-        params.setPeriods( getList( period ) );
-        params.setOrganisationUnits( getList( unit ) );
+        params.setPeriod( period );
+        params.setOrganisationUnit( unit );
         params.enableCategoryOptionCombos();
         
         if ( groups != null && !groups.isEmpty() )
@@ -131,8 +129,8 @@
                 DataQueryParams params = new DataQueryParams();
                 
                 params.setDataElements( dataElements );
-                params.setPeriods( getList( period ) );
-                params.setOrganisationUnits( getList( unit ) );
+                params.setPeriod( period );
+                params.setOrganisationUnit( unit );
                 params.setCategory( category );            
 
                 if ( groups != null && !groups.isEmpty() )
@@ -171,8 +169,8 @@
         DataQueryParams params = new DataQueryParams();
         
         params.setDataElements( dataElements );
-        params.setPeriods( getList( period ) );
-        params.setOrganisationUnits( getList( unit ) );
+        params.setPeriod( period );
+        params.setOrganisationUnit( unit );
 
         if ( groups != null && !groups.isEmpty() )
         {
@@ -208,8 +206,8 @@
         DataQueryParams params = new DataQueryParams();
         
         params.setIndicators( indicators );
-        params.setPeriods( getList( period ) );
-        params.setOrganisationUnits( getList( unit ) );
+        params.setPeriod( period );
+        params.setOrganisationUnit( unit );
 
         if ( groups != null && !groups.isEmpty() )
         {