org.epics.pvmanager

Class MultiplexedChannelHandler<ConnectionPayload,MessagePayload>

java.lang.Object

org.epics.pvmanager.ChannelHandler

org.epics.pvmanager.MultiplexedChannelHandler<ConnectionPayload,MessagePayload>

Type Parameters:

ConnectionPayload - type of the payload for the connection

MessagePayload - type of the payload for each message

Direct Known Subclasses:

PVAChannelHandler

public abstract class MultiplexedChannelHandler<ConnectionPayload,MessagePayload>
extends ChannelHandler

Implements a ChannelHandler on top of a single subscription and multiplexes all reads on top of it.

This abstract handler takes care of forwarding the connection and message events of a single connection to multiple readers and writers. One needs to:

• implement the connect() and disconnect() function to add the protocol specific connection and disconnection logic; the resources shared across multiple channels should be left in the datasource
• every time the connection state changes, call processConnection(java.lang.Object), which will trigger the proper connection notification mechanism; the type chosen as connection payload should be one that stores all the information about the channel of communications
• every time an event is sent, call processMessage(java.lang.Object), which will trigger the proper value notification mechanism
• implement isConnected(java.lang.Object) and isWriteConnected(java.lang.Object) with the logic to extract the connection information from the connection payload
• use reportExceptionToAllReadersAndWriters(java.lang.Exception) to report errors
• implement a set of DataSourceTypeAdapter that can convert the payload to types for pvmanager consumption; the connection payload and message payload never leave this handler, only value types created by the type adapters

Author:

carcassi

Constructor Summary

Constructors

Constructor and Description
MultiplexedChannelHandler(String channelName) Creates a new channel handler.

Method Summary

Methods

Modifier and Type	Method and Description
protected void	addReader(ChannelHandlerReadSubscription subscription) Used by the data source to add a read request on the channel managed by this handler.
protected void	addWriter(ChannelHandlerWriteSubscription subscription) Used by the data source to prepare the channel managed by this handler for write.
protected abstract void	connect() Used by the handler to open the connection.
protected abstract void	disconnect() Used by the handler to close the connection.
protected DataSourceTypeAdapter<ConnectionPayload,MessagePayload>	findTypeAdapter(ValueCache<?> cache, ConnectionPayload connection) Finds the right adapter to use for the particular cache given the information of the channels in the connection payload.
protected ConnectionPayload	getConnectionPayload() The last processes connection payload.
protected MessagePayload	getLastMessagePayload() The last processed message payload.
int	getReadUsageCounter() Returns how many readers are open on this channel.
int	getUsageCounter() Returns how many readers or writers are open on this channel.
int	getWriteUsageCounter() Returns how many writers are open on this channel.
boolean	isConnected() Returns true if it is connected.
protected boolean	isConnected(ConnectionPayload payload) Determines from the payload whether the channel is connected or not.
boolean	isWriteConnected() Returns true if it is channel can be written to.
protected boolean	isWriteConnected(ConnectionPayload payload) Determines from the payload whether the channel can be written to.
protected void	processConnection(ConnectionPayload connectionPayload) Process the next connection payload.
protected void	processMessage(MessagePayload payload) Process the payload for this channel.
protected void	removeReader(ChannelHandlerReadSubscription subscription) Used by the data source to remove a read request.
protected void	removeWrite(ChannelHandlerWriteSubscription subscription) Used by the data source to conclude writes to the channel managed by this handler.
protected void	reportExceptionToAllReadersAndWriters(Exception ex) Notifies all readers and writers of an error condition.
protected void	reportExceptionToAllWriters(Exception ex) Notifies all writers of an error condition.
protected void	resetMessage() Resets the last message to null.
protected boolean	saveMessageAfterDisconnect() Signals whether the last message received after the disconnect should be kept so that it is available at reconnect.
protected void	setProcessMessageOnDisconnect(boolean processMessageOnDisconnect) Determines whether processConnection(java.lang.Object) should trigger processMessage(java.lang.Object) with the same (non-null) payload in case the channel has been disconnected.
protected void	setProcessMessageOnReconnect(boolean processMessageOnReconnect) Determines whether processConnection(java.lang.Object) should trigger processMessage(java.lang.Object) with the same (non-null) payload in case the channel has reconnected.
protected abstract void	write(Object newValue, ChannelWriteCallback callback) Implements a write operation.

Methods inherited from class org.epics.pvmanager.ChannelHandler

getChannelName, getProperties

Methods inherited from class java.lang.Object

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

Constructor Detail

MultiplexedChannelHandler

public MultiplexedChannelHandler(String channelName)

Creates a new channel handler.

Parameters:

channelName - the name of the channel this handler will be responsible of

Method Detail

reportExceptionToAllReadersAndWriters

protected final void reportExceptionToAllReadersAndWriters(Exception ex)

Notifies all readers and writers of an error condition.

Parameters:

ex - the exception to notify

reportExceptionToAllWriters

protected final void reportExceptionToAllWriters(Exception ex)

Notifies all writers of an error condition.

Parameters:

ex - the exception to notify

getConnectionPayload

protected final ConnectionPayload getConnectionPayload()

The last processes connection payload.

Returns:

the connection payload or null

getLastMessagePayload

protected final MessagePayload getLastMessagePayload()

The last processed message payload.

Returns:

the message payload or null

processConnection

protected final void processConnection(ConnectionPayload connectionPayload)

Process the next connection payload. This should be called whenever the connection state has changed.

Parameters:

connectionPayload -

findTypeAdapter

protected DataSourceTypeAdapter<ConnectionPayload,MessagePayload> findTypeAdapter(ValueCache<?> cache,
                                                                      ConnectionPayload connection)

Finds the right adapter to use for the particular cache given the information of the channels in the connection payload. By overriding this method a datasource can implement their own matching logic. One can use the logic provided in DataSourceTypeSupport as a good first implementation.

Parameters:

cache - the cache that will store the data

connection - the connection payload

Returns:

the matched type adapter

getUsageCounter

public int getUsageCounter()

Description copied from class: ChannelHandler

Returns how many readers or writers are open on this channel.

Specified by:

getUsageCounter in class ChannelHandler

Returns:

the number of open readers and writers

getReadUsageCounter

public int getReadUsageCounter()

Description copied from class: ChannelHandler

Returns how many readers are open on this channel.

Specified by:

getReadUsageCounter in class ChannelHandler

Returns:

the number of open readers

getWriteUsageCounter

public int getWriteUsageCounter()

Description copied from class: ChannelHandler

Returns how many writers are open on this channel.

Specified by:

getWriteUsageCounter in class ChannelHandler

Returns:

the number of open writers

addReader

protected void addReader(ChannelHandlerReadSubscription subscription)

Description copied from class: ChannelHandler

Used by the data source to add a read request on the channel managed by this handler.

Specified by:

addReader in class ChannelHandler

Parameters:

subscription - the data required for a subscription

removeReader

protected void removeReader(ChannelHandlerReadSubscription subscription)

Description copied from class: ChannelHandler

Used by the data source to remove a read request.

Specified by:

removeReader in class ChannelHandler

Parameters:

subscription - the subscription to remove

addWriter

protected void addWriter(ChannelHandlerWriteSubscription subscription)

Description copied from class: ChannelHandler

Used by the data source to prepare the channel managed by this handler for write.

Specified by:

addWriter in class ChannelHandler

Parameters:

subscription - the data required for the subscription

removeWrite

protected void removeWrite(ChannelHandlerWriteSubscription subscription)

Description copied from class: ChannelHandler

Used by the data source to conclude writes to the channel managed by this handler.

Specified by:

removeWrite in class ChannelHandler

Parameters:

subscription - the subscription to remove

resetMessage

protected final void resetMessage()

Resets the last message to null. This can be used to invalidate the last message without triggering a notification. It is useful when a reconnect should behave as the first connection.

processMessage

protected final void processMessage(MessagePayload payload)

Process the payload for this channel. This should be called whenever a new value needs to be processed. The handler will take care of using the correct DataSourceTypeAdapter for each read monitor that was setup.

Parameters:

payload - the payload of for this type of channel

saveMessageAfterDisconnect

protected boolean saveMessageAfterDisconnect()

Signals whether the last message received after the disconnect should be kept so that it is available at reconnect.

By default, the message is discarded so that no memory is kept allocated.

Returns:

true if the message should be kept

connect

protected abstract void connect()

Used by the handler to open the connection. This is called whenever the first read or write request is made.

disconnect

protected abstract void disconnect()

Used by the handler to close the connection. This is called whenever the last reader or writer is de-registered.

write

protected abstract void write(Object newValue,
         ChannelWriteCallback callback)

Description copied from class: ChannelHandler

Implements a write operation. Writes the newValues to the channel and call the callback when done.

Specified by:

write in class ChannelHandler

Parameters:

newValue - new value to be written

callback - called when done or on error

isConnected

protected boolean isConnected(ConnectionPayload payload)

Determines from the payload whether the channel is connected or not.

By default, this uses the usage counter to determine whether it's connected or not. One should override this to use the actual connection payload to check whether the actual protocol connection has been established.

Parameters:

payload - the connection payload

Returns:

true if connected

isWriteConnected

protected boolean isWriteConnected(ConnectionPayload payload)

Determines from the payload whether the channel can be written to.

By default, this always return false. One should override this if it's implementing a write-able data source.

Parameters:

payload -

Returns:

true if ready for writes

isConnected

public final boolean isConnected()

Description copied from class: ChannelHandler

Returns true if it is connected.

Specified by:

isConnected in class ChannelHandler

Returns:

true if underlying channel is connected

isWriteConnected

public final boolean isWriteConnected()

Returns true if it is channel can be written to.

Returns:

true if underlying channel is write ready

setProcessMessageOnDisconnect

protected final void setProcessMessageOnDisconnect(boolean processMessageOnDisconnect)

Determines whether processConnection(java.lang.Object) should trigger processMessage(java.lang.Object) with the same (non-null) payload in case the channel has been disconnected. Default is true.

Parameters:

processMessageOnDisconnect - whether to process the message on disconnect

setProcessMessageOnReconnect

protected final void setProcessMessageOnReconnect(boolean processMessageOnReconnect)

Determines whether processConnection(java.lang.Object) should trigger processMessage(java.lang.Object) with the same (non-null) payload in case the channel has reconnected. Default is true.

Parameters:

processMessageOnReconnect - whether to process the message on disconnect