/*
* 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>AsynchronousCharacteristicContext</code> is declares asynchronous access for characteristics.
* <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>
*
* @author <a href="mailto:andrej.kosmrlj@cosylab.com">Andrej Kosmrlj</a>
*
*/
public interface AsynchronousCharacteristicContext extends AsynchronousContext
{
/**
* Accesses asynchronously the complete map of characteristics as
* name value pairs for this context. This method returns a map of
* currently known characteristics via <code>ResponseListener</code> (map
* could be accessed via <code>ResponseEvent.getResponse()</code>). If it
* is known that a given characteristic exists, it has to be present in
* the map. If the underlying source is remote, this method may optimize
* access to the characteristics, since underlying implementations may
* support grouped data access requests. Primitive types must be wrapped
* in <code>Object</code> wrappers.
*
* @param names names of requested characteristics
*
* @return Request associated with returned response
*
* @exception DataExchangeException because this method communicates with
* the underlying data source, an exception may be thrown if
* the communication fails.
*/
public Request<? extends Object> getCharacteristicsAsynchronously(String[] names)
throws DataExchangeException;
/**
* Accesses asynchronously the complete map of characteristics as
* name value pairs for this context. This method returns a map of
* currently known characteristics via <code>ResponseListener</code> (map
* could be accessed via <code>ResponseEvent.getResponse()</code>). If it
* is known that a given characteristic exists, it has to be present in
* the map. If the underlying source is remote, this method may optimize
* access to the characteristics, since underlying implementations may
* support grouped data access requests. Primitive types must be wrapped
* in <code>Object</code> wrappers.
*
* @param names names of requested characteristics
* @param listener a callback listener receiving responses only for this singe request.
*
* @return Request associated with returned response
*
* @exception DataExchangeException because this method communicates with
* the underlying data source, an exception may be thrown if
* the communication fails.
*/
public Request<? extends Object> getCharacteristicsAsynchronously(String[] names, ResponseListener<? extends Object> listener)
throws DataExchangeException;
/**
* Accesses asynchronously the value of the characteristic. The
* value of the characteristic is returned via
* <code>ResponseListener</code> (characteristic value could be accessed
* via <code>ResponseEvent.getResponse()</code>). If the characteristic
* with such name does not exist this method returns <code>null</code>. If
* the characteristic exists but the value is unknown,
* <code>UNINITIALIZED</code> is returned.
*
* @param name the name of the characteristic, may not be <code>null</code>
* or an empty string
*
* @return Object the value of the characteristic or <code>null</code> if
* unknown
*
* @exception DataExchangeException when the query for the characteristic
* value on the data source fails
*/
public Request<? extends Object> getCharacteristicAsynchronously(String name)
throws DataExchangeException;
/**
* Accesses asynchronously the value of the characteristic. The
* value of the characteristic is returned via
* <code>ResponseListener</code> (characteristic value could be accessed
* via <code>ResponseEvent.getResponse()</code>). If the characteristic
* with such name does not exist this method returns <code>null</code>. If
* the characteristic exists but the value is unknown,
* <code>UNINITIALIZED</code> is returned.
*
* @param name the name of the characteristic, may not be <code>null</code>
* or an empty string
* @param listener a callback listener receiving responses only for this singe request.
*
* @return Object the value of the characteristic or <code>null</code> if
* unknown
*
* @exception DataExchangeException when the query for the characteristic
* value on the data source fails
*/
public Request<?> getCharacteristicAsynchronously(String name, ResponseListener<?> listener)
throws DataExchangeException;
}
/* __oOo__ */