org.epics.pvmanager

Class DataSource

java.lang.Object

org.epics.pvmanager.DataSource

Direct Known Subclasses:

CompositeDataSource, FileDataSource, JCADataSource, LocalDataSource, MockDataSource, PVADataSource, SimulationDataSource, SystemDataSource, TestDataSource

public abstract class DataSource
extends Object

A source for data that is going to be processed by the PVManager. PVManager can work with more than one source at a time. Support for each different source can be added by external libraries.

To implement a datasource, one has to implement the createChannel(java.lang.String) method, and the requested will be forwarded to the channel accordingly. The channels are automatically cached and reused. The name under which the channels are looked up in the cache or registered in the cache is configurable.

Channel handlers can be implemented from scratch, or one can use the MultiplexedChannelHandler for handlers that want to open a single connection which is going to be shared by all readers and writers.

Author:

carcassi

Constructor Summary

Constructors

Constructor and Description
DataSource(boolean writeable) Creates a new data source.

Method Summary

Methods

Modifier and Type	Method and Description
protected String	channelHandlerLookupName(String channelName) Returns the lookup name to use to find the channel handler in the cache.
protected String	channelHandlerRegisterName(String channelName, ChannelHandler handler) Returns the name the given handler should be registered as.
void	close() Closes the DataSource and the resources associated with it.
void	connectRead(ReadRecipe readRecipe) Connects to a set of channels based on the given recipe.
void	connectWrite(WriteRecipe writeRecipe) Prepares the channels defined in the write recipe for writes.
protected abstract ChannelHandler	createChannel(String channelName) Creates a channel handler for the given name.
void	disconnectRead(ReadRecipe readRecipe) Disconnects the set of channels given by the recipe.
void	disconnectWrite(WriteRecipe writeRecipe) Releases the resources associated with the given write recipe.
Map<String,ChannelHandler>	getChannels() Returns the channel handlers for this data source.
boolean	isWriteable() Returns true whether the channels of this data source can be written to.
void	write(WriteRecipe writeRecipe, Runnable callback, ExceptionHandler exceptionHandler) Writes the contents in the given write recipe to the channels of this data sources.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

DataSource

public DataSource(boolean writeable)

Creates a new data source.

Parameters:

writeable - whether the data source implements write operations

Method Detail

isWriteable

public boolean isWriteable()

Returns true whether the channels of this data source can be written to.

Returns:

true if data source accept write operations

channelHandlerLookupName

protected String channelHandlerLookupName(String channelName)

Returns the lookup name to use to find the channel handler in the cache. By default, it returns the channel name itself. If a datasource needs multiple different channel names to be the same channel handler (e.g. parts of the channel name are initialization parameters) then it can override this method to change the lookup.

Parameters:

channelName - the channel name

Returns:

the channel handler to look up in the cache

channelHandlerRegisterName

protected String channelHandlerRegisterName(String channelName,
                                ChannelHandler handler)

Returns the name the given handler should be registered as. By default, it returns the lookup name, so that lookup and registration in the cache are consistent. If a datasource needs multiple different channel names to be the same channel handler (e.g. parts of the channel name are read/write parameters) then it can override this method to change the registration.

Parameters:

channelName - the name under which the ChannelHandler was created

handler - the handler to register

Returns:

the name under which to register in the cache

createChannel

protected abstract ChannelHandler createChannel(String channelName)

Creates a channel handler for the given name. In the simplest case, this is the only method a data source needs to implement.

Parameters:

channelName - the name for a new channel

Returns:

a new handler

connectRead

public void connectRead(ReadRecipe readRecipe)

Connects to a set of channels based on the given recipe.

The data source must update the value caches relative to each channel. Before updating any cache, it must lock the collector relative to that cache and after any update it must notify the collector.

Parameters:

readRecipe - the instructions for the data connection

disconnectRead

public void disconnectRead(ReadRecipe readRecipe)

Disconnects the set of channels given by the recipe.

The disconnect call is guaranteed to be given the same object, so that the recipe itself can be used as a key in a map to retrieve the list of resources needed to be closed.

Parameters:

readRecipe - the instructions for the data connection

connectWrite

public void connectWrite(WriteRecipe writeRecipe)

Prepares the channels defined in the write recipe for writes.

If these are channels over the network, it will create the network connections with the underlying libraries.

Parameters:

writeRecipe - the recipe that will contain the write data

disconnectWrite

public void disconnectWrite(WriteRecipe writeRecipe)

Releases the resources associated with the given write recipe.

Will close network channels and deallocate memory needed.

Parameters:

writeRecipe - the recipe that will no longer be used

write

public void write(WriteRecipe writeRecipe,
         Runnable callback,
         ExceptionHandler exceptionHandler)

Writes the contents in the given write recipe to the channels of this data sources.

The write recipe needs to be first prepared with connectWrite(org.epics.pvmanager.WriteRecipe) and then cleaned up with disconnectWrite(org.epics.pvmanager.WriteRecipe).

Parameters:

writeRecipe - the recipe containing the data to write

callback - function to call when the write is concluded

exceptionHandler - where to report the exceptions

getChannels

public Map<String,ChannelHandler> getChannels()

Returns the channel handlers for this data source.

Returns:

an unmodifiable collection

close

public void close()

Closes the DataSource and the resources associated with it.