MONDRIAN: Added more documentation on the data source change listener…

… plugin and set some members to public in order for the plugin to be able to access the necessary data.

[git-p4: depot-paths = "//open/mondrian/": change = 8592]

doc/schema.html

@@ -1959,12 +1959,29 @@ <h1>6.8 Data source change listener<a name="DataSource_change_listener">&nbsp;</
 even before cache is build.  This way, the plugin is able to register
 the first timestamp mondrian tries to read the datasource.</p>
 
-<p>For now, only flushing of the hierarchy cache is implemented.</p>
+<p>Each time a query is started, aggregate cache is checked to see if
+it has changed.  If so, cache will be flushed and aggregates will be
+reloaded from the data source.</p>
 
 <p>Here is an example of a data source change listener plugin class :
 <blockquote>
   <code>&nbsp;package com.acme;<br>
   <br>
+&nbsp;//...<br>
+&nbsp;import javax.sql.DataSource;<br>
+&nbsp;import java.sql.Connection;<br>
+&nbsp;import java.sql.ResultSet;<br>
+&nbsp;import java.sql.SQLException;<br>
+&nbsp;import java.sql.Timestamp;<br>
+&nbsp;//...<br>
+&nbsp;import mondrian.olap.MondrianDef;<br>
+&nbsp;import mondrian.rolap.RolapHierarchy;<br>
+&nbsp;import mondrian.rolap.RolapUtil;<br>
+&nbsp;import mondrian.rolap.agg.Aggregation;<br>
+&nbsp;import mondrian.rolap.RolapStar;<br>
+&nbsp;import mondrian.spi.impl.DataSourceChangeListenerImpl;<br>
+&nbsp;//...<br>
+<br>
 &nbsp;public class MyChangeListener extends DataSourceChangeListenerImpl {<br>
 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;public MyChangeListener() {<br>
 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;}<br>
@@ -1986,6 +2003,20 @@ <h1>6.8 Data source change listener<a name="DataSource_change_listener">&nbsp;</
 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;}<br>
 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;}<br>
 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;}<br>
+&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<br>
+&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;public synchronized boolean isAggregationChanged(Aggregation aggregation) {<br><br>
+&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;// The first time, register star and bitKey and remember first time of access...<br>
+&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;RolapStar star = aggregation.getStar();<br>
+&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;BitKey bitKey = aggregation.getConstrainedColumnsBitKey();<br>
+&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<br>
+&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;// The first time this function is called, only the bitKey is set,<br>
+&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;// the columns are not filled up yet.<br>
+&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;RolapStar.Column[] columns = aggregation.getColumns();<br>
+&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;if (columns != null) {<br>
+&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;// Check database...<br>
+&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;}<br>
+&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;}<br>
+
 &nbsp;}<br>
 </blockquote>
 

src/main/mondrian/rolap/agg/Aggregation.java

@@ -356,16 +356,24 @@ public synchronized Object get(RolapStar.Measure measure,
     /**
      * This is called during Sql generation.
      */
-    RolapStar.Column[] getColumns() {
+    public RolapStar.Column[] getColumns() {
         return columns;
     }
 
     /**
      * This is called during Sql generation.
      */
-    RolapStar getStar() {
+    public RolapStar getStar() {
         return star;
     }
+
+    /**
+     * Returns the BitKey for ALL columns (Measures and Levels) involved in the
+     * query.
+     */
+    public BitKey getConstrainedColumnsBitKey() {
+        return constrainedColumnsBitKey;
+    }    
 
     // -- classes -------------------------------------------------------------
 
@@ -444,6 +452,8 @@ boolean contains(Object key) {
             return valueSet.contains(key);
         }
     }
+
+
 }
 
 // End Aggregation.java

src/main/mondrian/spi/impl/DataSourceChangeListenerImpl.java

@@ -57,7 +57,7 @@ public synchronized boolean isAggregationChanged(Aggregation aggregation) {
         return false;
     }
 
-    String getTableName(RolapHierarchy hierarchy) {
+    public String getTableName(RolapHierarchy hierarchy) {
         MondrianDef.Relation relation = hierarchy.getRelation();
         if (relation instanceof MondrianDef.Table) {
             MondrianDef.Table tableRelation = (MondrianDef.Table)relation;

src/main/mondrian/spi/impl/DataSourceChangeListenerImpl2.java

@@ -57,7 +57,7 @@ public synchronized boolean isAggregationChanged(Aggregation aggregation) {
         return false;
     }
 
-    String getTableName(RolapHierarchy hierarchy) {
+    public String getTableName(RolapHierarchy hierarchy) {
         MondrianDef.Relation relation = hierarchy.getRelation();
         if (relation instanceof MondrianDef.Table) {
             MondrianDef.Table tableRelation = (MondrianDef.Table)relation;

src/main/mondrian/spi/impl/DataSourceChangeListenerImpl3.java

@@ -57,7 +57,7 @@ public synchronized boolean isAggregationChanged(Aggregation aggregation) {
         return true;
     }
 
-    String getTableName(RolapHierarchy hierarchy) {
+    public String getTableName(RolapHierarchy hierarchy) {
         MondrianDef.Relation relation = hierarchy.getRelation();
         if (relation instanceof MondrianDef.Table) {
             MondrianDef.Table tableRelation = (MondrianDef.Table)relation;

src/main/mondrian/spi/impl/DataSourceChangeListenerImpl4.java

@@ -85,7 +85,7 @@ public synchronized boolean isAggregationChanged(Aggregation aggregation) {
         }
     }
 
-    String getTableName(RolapHierarchy hierarchy) {
+    public String getTableName(RolapHierarchy hierarchy) {
         MondrianDef.Relation relation = hierarchy.getRelation();
         if (relation instanceof MondrianDef.Table) {
             MondrianDef.Table tableRelation = (MondrianDef.Table)relation;