/*
 * 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 extends the <code>ValueUpdateable</code> to provide access to additional
 * (non-dynamic-value) requests and responses that may be generated by the declaring object.
 * For example, access to characteristics, setting actions etc. should be stored in
 * "latest" references defined herein. The buffers are thread-local, i.e. for each
 * thread of execution concurrently invoking methods on the same <code>Updateable</code>
 * instance, different "latest" requests and responses are stored, where "latest" is
 * defined with respect to the execution flow within a given thread.
 */
public interface Updateable<T> extends ValueUpdateable<T>
{
	/**
	 * Returns the latest request (that is not the request to obtain
	 * dynamic value) invoked within the calling thread. The possible requests
	 * are set requests, requests for chatacteristics or setting triggers in
	 * the monitors issued by this <code>Updateable</code> and so on.
	 *
	 * @return Object the latest request
	 */
	public Request<?> getLatestRequest();

	/**
	 * Returns the latest response (that is not a response to the
	 * request to obtain a dynamic value).
	 *
	 * @return Object the latest response
	 *
	 * @see #getLatestRequest
	 */
	public Response<?> getLatestResponse();

	/**
	 * Returns <code>true</code> if the latest response is error-free.
	 * The error-free condition is defined by the underlying implementation.
	 * If the condition is  error-free, there should be no need for the
	 * Datatype users to query the latest response explicitly. Please note
	 * that the return value of this method applies to the latest response
	 * received (not the latest request completed). These two may differ
	 * because the request can generate multiple responses in general. This
	 * also  corresponds to natural interpretation of a request-response
	 * mechanism: what the user must check is the correctness of the
	 * responses, where the correctness of  requests is implied if any
	 * response can be produced in the first place.<p>Note: this method
	 * returns <code>true</code> if no response has arrived yet or if no
	 * request has been submitted.</p>
	 *
	 * @return boolean true iff the latest response is error free.
	 *
	 * @see ValueUpdateable#getLatestValueSuccess
	 */
	public boolean getLatestSuccess();

	/**
	 * Returns the thread local request for the dynamic value that
	 * produced the latest received dynamic value. Since several requests can
	 * be running concurrently, this method returns the one that has produced
	 * the last change, in the context of the object that declares this
	 * interface. For example, an <code>DynamicValueMonitor</code> will
	 * usually run a single request to the primary data source, so this method
	 * will return that request. On the other hand, an
	 * <code>AbstractProperty</code> may be running simultaneously several
	 * monitors, and this value should reflect the monitor request that has
	 * generated the latest value change or update. If the underlying
	 * implementation does not create transient connection objects such as
	 * requests, this method may return <code>null</code>.<p>The
	 * meaning of request is defined by the underlying implementation of
	 * Datatypes.</p>
	 *
	 * @return Object the request object that has generated the last value
	 *         change or update
	 */
	public Request<T> getLatestValueRequest();

	/**
	 * Returns the thread local response to a given request that has
	 * caused either the  modification in the
	 * <code>latestReceivedValue</code>, or, if the value did not change, in
	 * the <code>latestValueUpdateTimestamp</code>.<p>The meaning of
	 * response is defined by the underlying implementation of Datatypes.</p>
	 *
	 * @return Object the response object that contains the value update
	 */
	public Response<T> getLatestValueResponse();
}

/* __oOo__ */