Add experimental API for client to ask server to notify when the cell…

… set

changes. XMLA driver does not currently support the API.


git-svn-id: https://olap4j.svn.sourceforge.net/svnroot/olap4j/trunk@319 c6a108a4-781c-0410-a6c6-c2d559e19af0

src/org/olap4j/CellSetListener.java

@@ -0,0 +1,200 @@
+/*
+// $Id: CellSet.java 310 2010-04-23 19:57:41Z jhyde $
+// This software is subject to the terms of the Eclipse Public License v1.0
+// Agreement, available at the following URL:
+// http://www.eclipse.org/legal/epl-v10.html.
+// Copyright (C) 2010-2010 Julian Hyde
+// All Rights Reserved.
+// You must accept the terms of that agreement to use this software.
+*/
+package org.olap4j;
+
+import java.util.List;
+
+/**
+ * Listener interface for receiving events when the contents of a
+ * {@link CellSet} have changed.
+ *
+ * <p>NOTE: This functionality is experimental and is subject to change or
+ * removal without notice.
+ *
+ * <p>The client can ask the server to provide the listener with a specific
+ * {@link Granularity granularity} of events, but the server can decline to
+ * provide that granularity.
+ *
+ * <p>Fine granularity deals with changes such as cell values changing (and
+ * reports the before and after value, before and after formatted value),
+ * positions being deleted, positions being changed.
+ *
+ * <p>When an atomic change happens on the server (say a cache flush, if the
+ * server is mondrian) then an event will arrive on the client containing all of
+ * those changes. Although {@link CellSetChange#getCellChanges} and
+ * {@link CellSetChange#getAxisChanges} return lists, the client should assume
+ * that all of the events in these lists simultaneously.
+ *
+ * <p>At any point, the server is free to throw up its hands and say 'there are
+ * too many changes' by sending null values for {@code getCellChanges} or
+ * {@code getAxisChanges}. This prevents situations where there are huge numbers
+ * of changes that might overwhelm the server, the network link, or the client,
+ * such as might happen if a large axis is re-sorted.
+ *
+ * <p>The client should always be ready for that to happen (even for providers
+ * that claim to provide fine granularity events), and should re-execute the
+ * query to get the cell set. In fact, we recommend that clients re-execute the
+ * query to get a new cellset whenever they get an event. Then the client can
+ * use the details in the event to highlight cells that have changed.
+ *
+ * <h3>Notes for implementors</h3>
+ *
+ * <p>The purpose of registering a listener before creating a cell set is to
+ * ensure that no events "leak out" between creating a cell set and registering
+ * a listener, or while a statement is being re-executed to produce a new cell
+ * set.
+ *
+ * <p>The {@link #cellSetOpened(CellSet)} and {@link #cellSetClosed(CellSet)}
+ * methods are provided so that the listener knows what is going on when a
+ * statement is re-executed. In particular, suppose a statement receives an
+ * change event decides to re-execute. The listener is attached to the
+ * statement, so receives notifications about both old and new cell sets. The
+ * driver implicitls closes the previous cell set and calls
+ * {@code cellSetClosed}, then calls {@code cellSetOpened} with the new cell
+ * set.
+ *
+ * <p>If changes are occurring regularly on the server, there will soon be a
+ * call to {@link #cellSetChanged}. It is important to note that this event
+ * contains only changes that have occurred since the new cell set was opened.
+ *
+ * <p>The granularity parameter is provided to {@link OlapStatement#addListener}
+ * for the server's benefit. If granularity is only {@link Granularity#COARSE},
+ * the server may be able to store less information in order to track the cell
+ * set.
+ *
+ * @version $Id: $
+ */
+public interface CellSetListener {
+
+    /**
+     * Invoked when a cell set is opened.
+     *
+     * @param cellSet Cell set
+     */
+    void cellSetOpened(CellSet cellSet);
+
+    /**
+     * Invoked when a cell set is closed.
+     *
+     * @param cellSet Cell set
+     */
+    void cellSetClosed(CellSet cellSet);
+
+    /**
+     * Invoked when a cell set has changed.
+     *
+     * @param cellSetChange Change descriptor
+     */
+    void cellSetChanged(CellSetChange cellSetChange);
+
+    /**
+     * Granularity of notifications that should be sent to a cellset listener.
+     */
+    enum Granularity {
+        FINE,
+        COARSE
+    }
+
+    /**
+     * Description of changes that have occurred to the cell set.
+     */
+    interface CellSetChange {
+        /**
+         * Returns the cell set affected by this change.
+         *
+         * @return Cell set affected by this change.
+         */
+        CellSet getCellSet();
+
+        /**
+         * Returns a list of cells that have changed, or null if the server
+         * cannot provide detailed changes.
+         *
+         * <p>The server is always at liberty to provide a {@code CellSetChange}
+         * without a detailed list of changes, even if
+         * {@link Granularity#COARSE} was specified when the listener was
+         * attached. Here are some typical reasons:<ul>
+         *
+         * <li>If there are very many changes. (Transmitting these changes over
+         * the network would be costly, and the user interface also might
+         * struggle to redisplay so many cells.)
+         *
+         * <li>If the axes have changed significantly. (If an axis position has
+         * changed, all of the cells at that position will necssarily have
+         * changed.)
+         *
+         * <li>If the client did not ask for detailed changes
+         *
+         * <li>If the the provider is not capable of giving detailed changes.
+         * </ul>
+         */
+        List<CellChange> getCellChanges();
+
+        /**
+         * Returns a list of axis changes, or null if server cannot provide
+         * detailed changes.
+         *
+         * <p>The reasons why this method returns null are similar to the
+         * reasons why {@link #getCellChanges()} returns null.
+         *
+         * @return List of changes to positions on axes, or null if the server
+         * cannot provide detailed changes.
+         */
+        List<AxisChange> getAxisChanges();
+    }
+
+    /**
+     * Description of a change to a particular {@link Cell}; part of a
+     * {@link CellSetChange}.
+     */
+    interface CellChange {
+        /**
+         * Returns the cell before the change.
+         */
+        Cell getBeforeCell();
+
+        /**
+         * Returns the cell after the change.
+         */
+        Cell getAfterCell();
+    }
+
+    /**
+     * Description of a change to a particular {@link CellSetAxis}; part of a
+     * {@link CellSetChange}.
+     */
+    interface AxisChange {
+        /**
+         * Returns the axis affected by this change.
+         *
+         * @return Axis affected by this change
+         */
+        CellSetAxis getAxis();
+
+        /**
+         * Returns the position before the change. Null if the change created a
+         * new position.
+         *
+         * @return Position before the change, or null if the position is newly
+         * created
+         */
+        Position getBeforePosition();
+
+        /**
+         * Returns the position after the change. Null if the change deleted
+         * this position.
+         *
+         * @return Position after the change, or null if the position is deleted
+         */
+        Position getAfterPosition();
+    }
+}
+
+// End CellSetListener.java

src/org/olap4j/OlapDatabaseMetaData.java

@@ -38,6 +38,21 @@ public interface OlapDatabaseMetaData extends DatabaseMetaData, OlapWrapper {
      */
     OlapConnection getConnection() throws SQLException;
 
+    /**
+     * Returns the granularity of changes to cell sets that the database is
+     * capable of providing.
+     *
+     * <p>It's optional whether an olap4j provider supports cellset listeners,
+     * and also optional which granularities it supports. If the provider does
+     * not support the cell set listener API, returns an empty set. Never
+     * returns null.
+     *
+     * @return set of the granularities that are supported when listening for
+     * changes to a cell set, never null
+     */
+    Set<CellSetListener.Granularity> getSupportedCellSetListenerGranularities()
+        throws OlapException;
+
     /**
      * Retrieves a result set describing the Actions in this database.
      *

src/org/olap4j/OlapStatement.java

@@ -57,6 +57,34 @@ public interface OlapStatement extends Statement, OlapWrapper {
      * or another thread cancels the statement (see {@link #cancel()})
      */
     CellSet executeOlapQuery(SelectNode selectNode) throws OlapException;
+
+    /**
+     * Adds a listener to be notified of events to {@link CellSet}s created by
+     * this statement.
+     *
+     * <p>NOTE: You may wonder why this method belongs to the
+     * {@link OlapStatement} class and not {@code CellSet}. If the method
+     * belonged to {@code CellSet} there would be a window between creation and
+     * registering a listener during which events might be lost, whereas
+     * registering the listener with the statement ensures that the listener is
+     * attached immediately that the cell set is opened. It follows that
+     * registering a listener does not affect the cell set <em>currently
+     * open</em> (if any), and that no events will be received if the statement
+     * has no open cell sets.
+     *
+     * @param granularity Granularity of cell set events to listen for
+     *
+     * @param listener Listener to be notified of changes
+     *
+     * @throws OlapException if granularity is not one supported by this server,
+     *   per the
+     *   {@link OlapDatabaseMetaData#getSupportedCellSetListenerGranularities()}
+     *   method
+     */
+    void addListener(
+        CellSetListener.Granularity granularity,
+        CellSetListener listener)
+        throws OlapException;
 }
 
 // End OlapStatement.java

src/org/olap4j/driver/xmla/XmlaOlap4jDatabaseMetaData.java

@@ -957,7 +957,7 @@ public <T> T unwrap(Class<T> iface) throws SQLException {
      *
      * @return Error handler
      */
-    private final XmlaHelper getHelper() {
+    private XmlaHelper getHelper() {
         return olap4jConnection.helper;
     }
 
@@ -967,6 +967,13 @@ public boolean isWrapperFor(Class<?> iface) throws SQLException {
 
     // implement OlapDatabaseMetaData
 
+    public Set<CellSetListener.Granularity>
+        getSupportedCellSetListenerGranularities()
+        throws OlapException
+    {
+        return Collections.emptySet();
+    }
+
     public ResultSet getActions(
         String catalog,
         String schemaPattern,
@@ -1176,7 +1183,6 @@ public ResultSet getSets(
             "SET_NAME", wildcard(setNamePattern));
     }
 
-
     /**
      * Wrapper which indicates that a restriction is to be treated as a
      * SQL-style wildcard match.

src/org/olap4j/driver/xmla/XmlaOlap4jStatement.java

@@ -343,6 +343,15 @@ public CellSet executeOlapQuery(
         return executeOlapQuery(mdx);
     }
 
+    public void addListener(
+        CellSetListener.Granularity granularity,
+        CellSetListener listener)
+        throws OlapException
+    {
+        throw getHelper().createException(
+            "This driver does not support the cell listener API.");
+    }
+
     /**
      * Waits for an XMLA request to complete.
      *