View.java

/**************************************************************************************
 * Copyright (C) 2008 EsperTech, Inc. All rights reserved.                            *
 * http://esper.codehaus.org                                                          *
 * http://www.espertech.com                                                           *
 * ---------------------------------------------------------------------------------- *
 * The software in this package is published under the terms of the GPL license       *
 * a copy of which has been included with this distribution in the license.txt file.  *
 **************************************************************************************/
package com.espertech.esper.view;

import com.espertech.esper.client.EventBean;

/**
 * The View interface provides a way for a stream, data provider, or another view,
 * to notify an object of additions and deletions to its data set.
 * Views are themselves Viewable by other Views, and can implement their own set of cached data internally.
 * The contract is that a View is wholly derived from the object (its parent) to which it is attached.
 * That is, it must be able to reconstitute its cached state from a playback of source data passed to it
 * through the update() method.
 *
 * A view's job is to derive some data from the data in the Viewable object to which it is attached.
 * This can happen by a 'push' mechanism whereby new data in the underlying collection is pushed to the view
 * through the update method. A view that operates in this mode incrementally updates its derived data and
 * then provides this data to any queries or requesters through its Data interface and potentially through
 * other customized methods it exposes. When these methods are called, the view in push mode does not contact
 * its parent: it just supplies the requester with the data it already derived. The push mode is efficient
 * when data in a view is slow-changing with respect to how much its data is requested. For example, a view
 * calculating the mean of an intermittent signal over time may be queried very frequently. It incrementally
 * updates its statistic and then provides that quantity to callers whenever they want it, which may be much
 * more frequently than the incoming signal occurs.
 *
 * The 'pull' mechanism is driven by requests to the view's Data interface or other customized data access methods.
 * A view operating in 'pull' mode may know whether it is "clean" or "dirty" by listening to its update method, or
 * it may not get any calls to its update method, and have to consult its parent to re-derive data when it is called.
 * This mode is efficient when requests to a view for its data are infrequent compared to the update frequency of its
 * parent's data. For example, a temperature sensor may be changing on a near-continuous basis, and a view which
 * derives some quantity from that sensor may be queried irregularly. It is most efficient for that view to operate
 * in pull mode, and only update itself when it is asked by some consumer for its derived quantity. It then asks the
 * temperature sensor for the current temperature, does its derivation, and returns to the requester.
 *
 * To feed views that are registered with it, a view should only call the update method on its child views when its own
 * data has changed. If it receives an update which results in no change to its data, it should not update any children
 * views.
 */
public interface View extends EventCollection, Viewable
{
    /**
     * Returns the View's parent Viewable.
     * @return viewable
     */
    public Viewable getParent();

    /**
     * Called when the View is added to a Viewable object.
     * @param parent is the parent that this view is a child of
     */
    public void setParent(Viewable parent);

    /**
     * Notify that data has been added or removed from the Viewable parent.
     * The last object in the newData array of objects would be the newest object added to the parent view.
     * The first object of the oldData array of objects would be the oldest object removed from the parent view.
     *
     * If the call to update contains new (inserted) data, then the first argument will be a non-empty list and the
     * second will be empty. Similarly, if the call is a notification of deleted data, then the first argument will be
     * empty and the second will be non-empty. Either the newData or oldData will be non-null.
     * This method won't be called with both arguments being null, but either one could be null.
     * The same is true for zero-length arrays. Either newData or oldData will be non-empty.
     * If both are non-empty, then the update is a modification notification.
     *
     * When update() is called on a view by the parent object, the data in newData will be in the collection of the
     * parent, and its data structures will be arranged to reflect that.
     * The data in oldData will not be in the parent's data structures, and any access to the parent will indicate that
     * that data is no longer there.
     *
     * @param newData is the new data that has been added to the parent view
     * @param oldData is the old data that has been removed from the parent view
     */
    void update(EventBean[] newData, EventBean[] oldData);
}