/*
 * 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;


/**
 * <code>AsynchronousAccess</code> defines data access interface with asychronous
 * commands. Data channel inplementing this interface must implement as well
 * <code>AsyncrhonousContext</code> interface.
 * <p>
 * This interface is implemented by types that contain asynchronous methods.
 * An asynchronous method is a method that, when invoked, returns immediately,
 * but the processing still continues in the underlying data source layer.
 * When the processing finishes there, an asynchronous notification, called
 * a response, is sent back to the original caller. Because the dispatching of
 * responses follows the standard multicast JavaBeans event scheme, we must
 * identify which JavaBeans notification was generated by which asynchronous
 * invocation.</p>
 */
public interface AsynchronousAccess<T> extends AsynchronousContext
{
	/**
	 * Gets the dynamic value in an asynchronous way. When the value is
	 * read, the <code>ResponseListeners</code> will be delivered a
	 * <code>ResponseEvent</code>. Use the return value of this method to
	 * identify the correct event for this request.
	 *
	 * @return the request that uniquely identifies this asynchronous call
	 *
	 * @throws DataExchangeException if the call fails
	 */
	public Request<T> getAsynchronous() throws DataExchangeException;

	/**
	 * Gets the dynamic value in an asynchronous way. When the value is
	 * read, the <code>ResponseListeners</code> will be delivered a
	 * <code>ResponseEvent</code>. Use the return value of this method to
	 * identify the correct event for this request and the
	 * <code>RequestUtilities</code> to  extract the value.
	 *
	 * @param listener a listener that will receive response only for this
	 *        asynchronous operation and then will be released. This is
	 *        callback style of listener.
	 *
	 * @return the request that uniquely identifies this asynchronous call
	 *
	 * @throws DataExchangeException if the call fails
	 */
	public Request<T> getAsynchronous(ResponseListener<T> listener)
		throws DataExchangeException;

	/**
	 * Sets the dynamic value in an asynchronous way. When the value is
	 * set, the <code>ResponseListeners</code> will be delivered a
	 * <code>ResponseEvent</code>. Use the return value of this method to
	 * identify the correct event for this request and the
	 * <code>RequestUtilities</code> to  extract the completion code,
	 * timestamp and type.
	 *
	 * @param value the value to set
	 *
	 * @return the request that uniquely identifies this asynchronous call
	 *
	 * @throws DataExchangeException if the call fails
	 */
	public Request<T> setAsynchronous(T value) throws DataExchangeException;

	/**
	 * Sets the dynamic value in an asynchronous way. When the value is
	 * set, the <code>ResponseListeners</code> will be delivered a
	 * <code>ResponseEvent</code>. Use the return value of this method to
	 * identify the correct event for this request and the
	 * <code>RequestUtilities</code> to  extract the completion code,
	 * timestamp and type.
	 *
	 * @param value the value to set
	 * @param listener a listener that will receive response only for this
	 *        asynchronous operation and then will be released. This is
	 *        callback style of listener.
	 *
	 * @return the request that uniquely identifies this asynchronous call
	 *
	 * @throws DataExchangeException if the call fails
	 */
	public Request<T> setAsynchronous(T value, ResponseListener<T> listener)
		throws DataExchangeException;
}

/* __oOo__ */