com.aquenos.epics.jackie.client

Class DefaultChannelAccessClient

java.lang.Object

com.aquenos.epics.jackie.client.DefaultChannelAccessClient

All Implemented Interfaces:

ChannelAccessClient

public class DefaultChannelAccessClient
extends java.lang.Object
implements ChannelAccessClient

Default implementation of a ChannelAccessClient. This implementation is configurable and should thus be usable for virtually any application.

This implementation chooses to keep weak references to its channels, the monitors, and even the client itself. This means that if all references are lost, a monitor, a channel, or the whole client will eventually get garbage collected and destroyed. However, as the garbage collector is non-deterministic, you should still use explicit resource management where feasible. However, if your resource management does not correctly cover all cases, the garbage collector should eventually take care of freeing resources, unless you keep strong references to unused objects.

This implementation notifies listeners within the thread that triggers the event. Therefore, listeners should only perform quick operations and they must not block. Care must be taken when listeners acquire a mutex because typically, the code calling the listener will hold a mutex that protects its list of listeners and possibly other attributes. If the listener acquires a mutex, care must be taken that this mutex is never acquired when calling any method of the object that notifies the listener. All exceptions thrown by listeners are caught and forwarded to the configured ErrorHandler.

This client is configurable through its ChannelAccessClientConfiguration and its ClientThreadingStrategy. By default, it uses a default ChannelAccessClientConfiguration and an instance of DefaultClientThreadingStrategy.

Typically, each ClientThreadingStrategy can only be used with a single client, so a new instance should be created for each client that is created.

This client implementation creates instances of DefaultBeaconDetector and DefaultChannelNameResolver for detecting beacon anomalies and resolving channel names.

Author:

Sebastian Marsching

Constructor Summary

Constructors

Constructor and Description
DefaultChannelAccessClient() Creates a Channel Access client using default options.
DefaultChannelAccessClient(ChannelAccessClientConfiguration configuration) Creates a Channel Access client using the specified configuration.
DefaultChannelAccessClient(ChannelAccessClientConfiguration configuration, ClientThreadingStrategy threadingStrategy) Creates a Channel Access client using the specified configuration and threading strategy.
DefaultChannelAccessClient(ChannelAccessClientConfiguration configuration, ListenerLockPolicy listenerLockPolicy) Creates a Channel Access client using the specified configuration.
DefaultChannelAccessClient(ChannelAccessClientConfiguration configuration, ListenerLockPolicy listenerLockPolicy, ClientThreadingStrategy threadingStrategy) Creates a Channel Access client using the specified configuration, listener lock-policy, and threading strategy.
DefaultChannelAccessClient(ClientThreadingStrategy threadingStrategy) Creates a Channel Access client using the specified threading strategy.
DefaultChannelAccessClient(ListenerLockPolicy listenerLockPolicy) Creates a Channel Access client using the specified listener lock-policy.
DefaultChannelAccessClient(ListenerLockPolicy listenerLockPolicy, ClientThreadingStrategy threadingStrategy) Creates a Channel Access client using the specified threading strategy.

Method Summary

Modifier and Type	Method and Description
void	destroy() Destroys this client.
protected void	finalize() Finalizes this object, destroying the client.
ChannelAccessChannel	getChannel(java.lang.String channelName) Returns a reference to the channel with the given name.
ChannelAccessClientConfiguration	getConfiguration() Returns the configuration for this Channel Access client.

Methods inherited from class java.lang.Object

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

Constructor Detail

DefaultChannelAccessClient

public DefaultChannelAccessClient()

Creates a Channel Access client using default options. Uses the ChannelAccessClientConfiguration.ChannelAccessClientConfiguration() constructor to create a configuration and the DefaultClientThreadingStrategy.DefaultClientThreadingStrategy(ErrorHandler) constructor (passing the ErrorHandler from the configuration) to create its configuration and threading strategy. The listener lock-policy is set to BLOCK.

DefaultChannelAccessClient

public DefaultChannelAccessClient(ChannelAccessClientConfiguration configuration)

Creates a Channel Access client using the specified configuration. The client's threading strategy is created using @link DefaultClientThreadingStrategy #DefaultClientThreadingStrategy(ErrorHandler)} constructor (passing the ErrorHandler from the configuration). The listener lock-policy is set to BLOCK.

Parameters:

configuration - client configuration. If null, a default-constructed ChannelAccessClientConfiguration is used.

DefaultChannelAccessClient

public DefaultChannelAccessClient(ListenerLockPolicy listenerLockPolicy)

Creates a Channel Access client using the specified listener lock-policy. Uses the ChannelAccessClientConfiguration.ChannelAccessClientConfiguration() constructor to create a configuration and the DefaultClientThreadingStrategy.DefaultClientThreadingStrategy(ErrorHandler) constructor (passing the ErrorHandler from the configuration) to create its configuration and threading strategy.

Parameters:

listenerLockPolicy - listener lock-policy used by this client. The lock policy defines the behavior when removing listeners. This affects all channels and subscription monitors created by this client and all futures returned by the channels or monitors. If null, the ListenerLockPolicy.BLOCK policy is used.

Since:

EPICS Jackie 2.0.0.

DefaultChannelAccessClient

public DefaultChannelAccessClient(ClientThreadingStrategy threadingStrategy)

Creates a Channel Access client using the specified threading strategy. The configuration is created using the ChannelAccessClientConfiguration.ChannelAccessClientConfiguration() constructor. The listener lock-policy is set to BLOCK.

Parameters:

threadingStrategy - threading strategy to be used by this client. Typically, threading strategies are not reusable, meaning that a separate instance must be created for each client. If null, a DefaultClientThreadingStrategy is created.

DefaultChannelAccessClient

public DefaultChannelAccessClient(ChannelAccessClientConfiguration configuration,
                                  ListenerLockPolicy listenerLockPolicy)

Creates a Channel Access client using the specified configuration. The client's threading strategy is created using @link DefaultClientThreadingStrategy #DefaultClientThreadingStrategy(ErrorHandler)} constructor (passing the ErrorHandler from the configuration).

Parameters:

configuration - client configuration. If null, a default-constructed ChannelAccessClientConfiguration is used.

listenerLockPolicy - listener lock-policy used by this client. The lock policy defines the behavior when removing listeners. This affects all channels and subscription monitors created by this client and all futures returned by the channels or monitors. If null, the ListenerLockPolicy.BLOCK policy is used.

Since:

EPICS Jackie 2.0.0.

DefaultChannelAccessClient

public DefaultChannelAccessClient(ChannelAccessClientConfiguration configuration,
                                  ClientThreadingStrategy threadingStrategy)

Creates a Channel Access client using the specified configuration and threading strategy. The listener lock-policy is set to BLOCK.

Parameters:

configuration - client configuration. If null, a default-constructed ChannelAccessClientConfiguration is used.

threadingStrategy - threading strategy to be used by this client. Typically, threading strategies are not reusable, meaning that a separate instance must be created for each client. If null, a DefaultClientThreadingStrategy is created.

DefaultChannelAccessClient

public DefaultChannelAccessClient(ListenerLockPolicy listenerLockPolicy,
                                  ClientThreadingStrategy threadingStrategy)

Creates a Channel Access client using the specified threading strategy. The configuration is created using the ChannelAccessClientConfiguration.ChannelAccessClientConfiguration() constructor.

Parameters:

listenerLockPolicy - listener lock-policy used by this client. The lock policy defines the behavior when removing listeners. This affects all channels and subscription monitors created by this client and all futures returned by the channels or monitors. If null, the ListenerLockPolicy.BLOCK policy is used.

threadingStrategy - threading strategy to be used by this client. Typically, threading strategies are not reusable, meaning that a separate instance must be created for each client. If null, a DefaultClientThreadingStrategy is created.

Since:

EPICS Jackie 2.0.0.

DefaultChannelAccessClient

public DefaultChannelAccessClient(ChannelAccessClientConfiguration configuration,
                                  ListenerLockPolicy listenerLockPolicy,
                                  ClientThreadingStrategy threadingStrategy)

Creates a Channel Access client using the specified configuration, listener lock-policy, and threading strategy.

Parameters:

configuration - client configuration. If null, a default-constructed ChannelAccessClientConfiguration is used.

listenerLockPolicy - listener lock-policy used by this client. The lock policy defines the behavior when removing listeners. This affects all channels and subscription monitors created by this client and all futures returned by the channels or monitors. If null, the ListenerLockPolicy.BLOCK policy is used.

threadingStrategy - threading strategy to be used by this client. Typically, threading strategies are not reusable, meaning that a separate instance must be created for each client. If null, a DefaultClientThreadingStrategy is created.

Since:

EPICS Jackie 2.0.0.

Method Detail

destroy

public void destroy()

Description copied from interface: ChannelAccessClient

Destroys this client. This method should be called if the client is not needed any longer, so that its resources can be released (e.g. background threads can be terminated). Destroying a client also destroys all its channels and subsequently all monitors.

Specified by:

destroy in interface ChannelAccessClient

getChannel

public ChannelAccessChannel getChannel(java.lang.String channelName)

Description copied from interface: ChannelAccessClient

Returns a reference to the channel with the given name. Calling this method multiple times for the same channel name will result in separate instances being returned each time. In the background however, all these channels will share the same implementation, so that the resource overhead for the separate instances is negligible. This way, you can get a channel instance (and destroy it when you do not need it any longer) without having to worry whether other parts of your application still need this channel.

Specified by:

getChannel in interface ChannelAccessClient

Parameters:

channelName - network name of the channel. The name is serialized using the configured charset (see ChannelAccessClientConfiguration.getCharset()).

Returns:

new instance of the Channel Access channel with the specified name.

getConfiguration

public ChannelAccessClientConfiguration getConfiguration()

Description copied from interface: ChannelAccessClient

Returns the configuration for this Channel Access client.

Specified by:

getConfiguration in interface ChannelAccessClient

Returns:

configuration used by this client.

finalize

protected void finalize()
                 throws java.lang.Throwable

Finalizes this object, destroying the client. This method calls destroy() followed by super.finalize(). This ensures that a client is destroyed when it is not used any longer. However, the point in time at which finalize() is called is non-deterministic. For this reason, the destroy() method should be called explicitly whenever this is feasible.

From the documentation of Object.finalize():

Called by the garbage collector on an object when garbage collection determines that there are no more references to the object. A subclass overrides the finalize method to dispose of system resources or to perform other cleanup.

The general contract of finalize is that it is invoked if and when the Java™ virtual machine has determined that there is no longer any means by which this object can be accessed by any thread that has not yet died, except as a result of an action taken by the finalization of some other object or class which is ready to be finalized. The finalize method may take any action, including making this object available again to other threads; the usual purpose of finalize, however, is to perform cleanup actions before the object is irrevocably discarded. For example, the finalize method for an object that represents an input/output connection might perform explicit I/O transactions to break the connection before the object is permanently discarded.

The Java programming language does not guarantee which thread will invoke the finalize method for any given object. It is guaranteed, however, that the thread that invokes finalize will not be holding any user-visible synchronization locks when finalize is invoked. If an uncaught exception is thrown by the finalize method, the exception is ignored and finalization of that object terminates.

After the finalize method has been invoked for an object, no further action is taken until the Java virtual machine has again determined that there is no longer any means by which this object can be accessed by any thread that has not yet died, including possible actions by other objects or classes which are ready to be finalized, at which point the object may be discarded.

The finalize method is never invoked more than once by a Java virtual machine for any given object.

Any exception thrown by the finalize method causes the finalization of this object to be halted, but is otherwise ignored.

Overrides:

finalize in class java.lang.Object

Throws:

java.lang.Throwable - the Exception raised by this method