/*
 * Copyright (c) 2006 Stiftung Deutsches Elektronen-Synchroton,
 * Member of the Helmholtz Association, (DESY), HAMBURG, GERMANY.
 *
 * THIS SOFTWARE IS PROVIDED UNDER THIS LICENSE ON AN "../AS IS" BASIS.
 * WITHOUT WARRANTY OF ANY KIND, EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED
 * TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR PARTICULAR PURPOSE AND
 * NON-INFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE
 * FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
 * TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR
 * THE USE OR OTHER DEALINGS IN THE SOFTWARE. SHOULD THE SOFTWARE PROVE DEFECTIVE
 * IN ANY RESPECT, THE USER ASSUMES THE COST OF ANY NECESSARY SERVICING, REPAIR OR
 * CORRECTION. THIS DISCLAIMER OF WARRANTY CONSTITUTES AN ESSENTIAL PART OF THIS LICENSE.
 * NO USE OF ANY SOFTWARE IS AUTHORIZED HEREUNDER EXCEPT UNDER THIS DISCLAIMER.
 * DESY HAS NO OBLIGATION TO PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS,
 * OR MODIFICATIONS.
 * THE FULL LICENSE SPECIFYING FOR THE SOFTWARE THE REDISTRIBUTION, MODIFICATION,
 * USAGE AND OTHER RIGHTS AND OBLIGATIONS IS INCLUDED WITH THE DISTRIBUTION OF THIS
 * PROJECT IN THE FILE LICENSE.HTML. IF THE LICENSE IS NOT INCLUDED YOU MAY FIND A COPY
 * AT HTTP://WWW.DESY.DE/LEGAL/LICENSE.HTM
 */

package org.csstudio.dal;



/**
 * This interface contains methods that access the set of transient objects generated
 * by the underlying implementation when the dynamic value is queried. What these
 * transient objects contain depends on the implementation. The implementation - in
 * case the query does not require any transient objects, such as completion codes,
 * requests, responses, error codes etc - may return <code>null</code>. The access
 * to these objects <b>must be thread local</b>. For details, see the documentation
 * of <code>java.lang.ThreadLocal</code>. In short, this requirement means that the
 * returned values are different for different threads that invoke these methods. The
 * "last request" is defined as being the last that has been invoked from the caller's
 * thread.
 * <p>
 * A dynamic value can be accessed in different ways, either by subscriptions (observer
 * pattern) or by direct invocation of <code>get</code> methods. An instance of
 * <code>ValueUpdateable</code> must store the value, when accessed by any means, with the
 * latest timestamp as provided by the underlying implementation (or, if the underlying
 * implementation does not provide timestamped data, with the latest local timestamp), in
 * the <code>latestReceivedValueAsObject</code>. The <code>latestValueChangeTimestamp</code>
 * and <code>latestValueUpdateTimestamp</code> reflect the times, when the value last
 * changed and when the underlying implementation last confirmed that the value is still the
 * same, respectivelly.
 * </p>
 * <p>
 * This interface is implemented by all objects that allow access to the dynamic value.
 * </p>
 */
public interface ValueUpdateable<T>
{

	/**
	 * Returns the latest value change timestamp. The change is defined
	 * by the implementation, but should normally follow the criterion that
	 * <code>!newvalue.equals(oldvalue)</code>.
	 *
	 * @return the timestamp in Java <code>System.currentTimeMillis</code>
	 *         format of the latest change in dynamic value
	 */
	public Timestamp getLatestValueChangeTimestamp();

	/**
	 * This is a convenience method implemented in the underlying layer
	 * that examines the latest response and determines if all data quality
	 * parameters in the response indicate that the dynamic value update is
	 * error-free, alarm-free and in general without any warning condition.
	 * The users of Datatypes may conclude that, if this method returns
	 * <code>true</code>, no further examination of
	 * <code>latestValueResponse</code> or <code>latestValueRequest</code> is
	 * necessary.<p>Note: this method returns <code>true</code> if no
	 * request has been submitted or no response has arrived.</p>
	 *
	 * @return boolean <code>true</code> iff the latetst dynamic value update
	 *         is error-free
	 */
	public boolean getLatestValueSuccess();

	/**
	 * Returns the time of the latest dynamic value update. An update
	 * is either a change in dynamic value or the confirmation from the
	 * primary data source that the value and its quality are still the same.
	 * The timestamp must be that provided by the underlying implementation
	 * or, if that is unavailable, it must be the local timestamp. This
	 * definition also implies that the
	 * <code>latestValueUpdateTimestamp</code> must be necessarily equal to or
	 * later than the <code>latestValueChangeTimestamp</code>, since the value
	 * may be updated without being changed, but not vice versa.
	 *
	 * @return a Java <code>System.currentTimeMillis</code> style
	 *         timestamp of the latest update
	 */
	public Timestamp getLatestValueUpdateTimestamp();

	/**
	 * Returns common monitor which controls all dynamic value
	 * listeners, which has been registered at property with
	 * <code>addDynamicValueListener</code> method.
	 *
	 * @return common monitor for all listeners without special monitor
	 */
	public DynamicValueMonitor getDefaultMonitor();

	/**
	 * Returns all by this property created monitors.
	 *
	 * @return common all created or active monitors
	 */
	public DynamicValueMonitor[] getMonitors();

	/**
	 * Creates new monitor which controls updates for single value
	 * listener independantly from default monitor.
	 *
	 * @param listener
	 *
	 * @return particular monitor with single listener
	 *
	 * @throws RemoteException DOCUMENT ME!
	 */
	public <E extends SimpleProperty<T>> DynamicValueMonitor createNewMonitor(DynamicValueListener<T, E> listener)
		throws RemoteException;
}

/* __oOo__ */