001    /*
002    // $Id: //open/mondrian/src/main/mondrian/spi/DataSourceChangeListener.java#4 $
003    // This software is subject to the terms of the Common Public License
004    // Agreement, available at the following URL:
005    // http://www.opensource.org/licenses/cpl.html.
006    // Copyright (C) 2005-2008 Julian Hyde
007    // All Rights Reserved.
008    // You must accept the terms of that agreement to use this software.
009    */
010    package mondrian.spi;
011    
012    
013    import mondrian.rolap.RolapHierarchy;
014    import mondrian.rolap.agg.Aggregation;
015    
016    
017    /**
018     * Definition of a data source change listener.
019     *
020     * A change listener can be specified in the connection string.  It is used
021     * to ask what is changed in the datasource (e.g. database).
022     *
023     * Everytime mondrian has to decide whether it will use data from cache, it
024     * will call the change listener.  When the change listener tells mondrian
025     * the datasource has changed for a dimension, cube, ... then mondrian will
026     * flush the cache and read from database again.
027     *
028     * It is specified in the connection string, like this :
029     *
030     * <blockquote><code>
031     * Jdbc=jdbc:odbc:MondrianFoodMart; JdbcUser=ziggy; JdbcPassword=stardust; DataSourceChangeListener=com.acme.MyChangeListener;
032     * </code></blockquote>
033     *
034     * This class should be called in mondrian before any data is read, so
035     * even before cache is build.  This way, the plugin is able to register
036     * the first timestamp mondrian tries to read the datasource.
037     *
038     * @author Bart Pappyn
039     * @version $Id: //open/mondrian/src/main/mondrian/spi/DataSourceChangeListener.java#4 $
040     * @since Dec 12, 2006
041     */
042    
043    public interface DataSourceChangeListener {
044    
045        /**
046         * Checks if the given hierarchy has changed since the previous
047         * time this function was called.
048         *
049         * The first time, this function will be called when the cache
050         * is still empty.  This is because the plugin is able to register
051         * the first timestamp the function was accessed.
052         *
053         * It is highly recommended to optimize the plugin and minimize
054         * the time needed to evaluate this function, because this plugin
055         * is called many times for each mondrian query.
056         */
057        public boolean isHierarchyChanged(RolapHierarchy hierarchy);
058    
059        /**
060         * Checks if the given aggregation has changed since the previous
061         * time this function was called.
062         *
063         * The first time, this function will be called when the cache
064         * is still empty.  This is because the plugin is able to register
065         * the first timestamp the function was accessed.
066         */
067        public boolean isAggregationChanged(Aggregation aggregation);
068    }
069    
070    // End DataSourceChangeListener.java