In order to attain the goal of providing a library that can be used easily and conveniently, the API has been designed as a first-grade Java API instead of trying to reuse the concepts of the API of the Channel Access library for the C programming language. This means that the Channel Access client, channels, and channel monitors are all represented by objects. These objects are safe for concurrent use by multiple threads, lifting the user from the burden of having to synchronize access to the API by using a mutex.

The API uses generics to enable the user to deal with the various types of Channel Access values in a type-safe way, benefiting from automatic type checks at compile time. This is combined with a class-hierarchy that actually reflects the hierarchy of Channel Access types. This means that (unlike the API of the C library) there are common base-types for all values that provide alarm information and all values that provide display information (the second being derived from the first because display information always includes alarm information).

The asynchronous nature of network communication in general and the Channel Access protocol in particular is reflected in the API by having asynchronous operations return futures that allow the calling code to wait for the operation to finish or to be notified asynchronously when it finishes.

In order to make using this library convenient, dependencies are kept to a minimum and the library itself is split into modules so that each application can choose to only bundle the parts it actually needs. At the moment, there is a module providing common components and a module providing the client. In the future, there might also be a module providing a server. Please refer to Section 4, “Requirements” to learn more about the (minimal) requirements for using EPICS Jackie.

The goal of being flexible and extensible has lead to a design of the API that focuses on the use of interfaces instead of concrete classes. This way, a user can choose to swap certain components with her own implementation if the built-in configuration options are not sufficient for a certain use case. In addition to that, components for different sub-tasks have been split into separate interfaces and classes, so that they can be used independently.

For example, the encoding and decoding of Channel Access messages is handled by a separate component, so that a user wanting to implement a special application (for example a diagnostics tool for analyzing Channel Access traffic) can use this building block.

Another example is the Channel Access name resolution (finding the server that hosts a certain channel), which is handled by the ChannelAccessNameResolver. This component can also be used on its own (for example for collecting information about channels on the network) or it can be replaced by a custom implementation (for example an implementation that uses a central directory service instead of using the regular name resolution protocol built into Channel Access).

The concept of flexibility even extends to the threading model of the Chanel Access client, which can be changed by providing a different ClientThreadingStrategy.

EPICS Jackie implements the Channel Access protocol in the same way that the C library provided with EPICS Base 3.16.1 implements it. This includes implementation details like the timing scheme used when sending UDP packets and how the broadcast addresses for name resolution are determined when not configured explicitly.

Just like the C library since EPICS Base 3.16.1, EPICS Jackie is only compatible with Channel Access version 4.4 and newer. The current version of the Channel Access protocol (as of EPICS Base 3.16.1) is 4.13. This limitation should not have any practical impact. The oldest EPICS release publicly available (version 3.12.2 released on April 19^th, 1996) already supports Channel Access version 4.6.

The EPICS Jackie client also differs slightly in how it handles connections when TCP is used for name resolution (the Channel Access protocol usually uses UDP, but TCP can be enabled explicitly): While the C implementation uses only one TCP connection when a server is both a name server and a channel server, the EPICS Jackie Client always uses separate connections for name resolution and for accessing channels. This allows for a much simpler and cleaner design of the network logic, separating tasks that are not directly related into separate components. Compared to these benefits, the overhead for maintaining an extra TCP connection is negligible. Most environments use UDP for name resolution and even if TCP is used, the number of name servers is typically low (single digit), so this not have any practical effects.

EPICS Jackie can be run on Java 6 and newer. Java 6 was chosen because it provides all the convenient language features introduced with Java 5, even adding a few improvements. As of today (May 2016), there should be virtually no platforms supporting Java 5, but not supporting Java 6. On the other hand, there are still a few supported Linux distributions that provide Java 6, but do not provide Java 7. For this reason, EPICS Jackie does not require Java 7. This might change in the future as Java 6 is being phased out in favor of more recent versions.

Please note that in order to compile EPICS Jackie from the sources, JDK 1.7 or newer is needed. The compiler from JDK 1.6 has a bug regarding multiple inheritance in interfaces. The original bug report is not available in the bug database any longer, but there are duplicates in both the Oracle JDK and OpenJDK databases. This bug has only been fixed in JDK 1.7, so the compiler from JDK 1.7 has to be used. However, the compiler’s source compatibility level is set to 1.6, so the compiled classes run inside the JVM from JDK 1.6 without any problems.

This compiler bug supposedly does not exist in some alternative compilers so that it might be possible to compile the code with the compiler from a different implementation of the Java 6 platform. However, as most users are going to use OpenJDK or Oracle JDK anyway, it was decided that it was acceptable to have other dependencies on Java 7 in the build process. In particular, this concerns the use of some Maven plugins that can only run with Java 7. This means that the Maven build process always has to run with Java 7 (or newer), but it is acceptable to specify a Java 6 only compiler in the configuration of the Apache Maven Compiler Plugin. There is no particular reason for using such a setup though. Simply running Maven with JDK 1.7 or JDK 1.8 will result in successfully compiled code that will work in the Java Virtual Machine of Java 6.

The Java archives in which the EPICS Jackie library is distributed are ready-to-use OSGi bundles, containing the required manifest. The same applies to all dependencies of EPICS Jackie, so that it can easily be deployed inside an OSGi container (for example Apache Felix or Eclipse Equinox). However, EPICS Jackie does not have any dependencies on OSGi and can thus be used outside an OSGi container without any modifications.

EPICS Jackie is a pure Java-library and is designed to run on all operating systems and architectures supporting the Java Standard Edition. There are a few places where the library makes use of platform-specific features, but neither of these are critical. In these places, the code has typically been designed to support most UNIX-like operating systems (including Linux and OS X) and Microsoft Windows.

When using the Apache Maven (or a compatible) build tool, using the EPICS Jackie Client in a project is as simple as adding the following dependency to the project configuration:

    <dependency>
      <groupId>com.aquenos.epics.jackie</groupId>
      <artifactId>epics-jackie-client</artifactId>
      <version>2.0.0</version>
    </dependency>

When managing dependencies manually, please make sure that the commons-lang3-3.4.jar, epics-jackie-client-2.0.0.jar, and epics-jackie-client-2.0.0.jar are included in the classpath of your project.

In order to get started, here is a very simple example that creates a client using the default configuration, reads a value, increments it by one, writes it back to the channel, and finally reads the updated value again:

import com.aquenos.epics.jackie.client.ChannelAccessChannel;
import com.aquenos.epics.jackie.client.ChannelAccessClient;
import com.aquenos.epics.jackie.client.DefaultChannelAccessClient;
import com.aquenos.epics.jackie.common.value.ChannelAccessDouble;

public class SimpleClient {

    public static void main(String[] args) throws Exception {
        ChannelAccessClient client = new DefaultChannelAccessClient();
        String channelName = "testChannel";
        ChannelAccessChannel channel = client.getChannel(channelName);
        channel.waitForConnectionState(true).get();
        ChannelAccessDouble value = channel.getDouble().get();
        double doubleValue = value.getValue().get(0);
        System.out.println("The current value is " + doubleValue + ".");
        channel.putDouble(doubleValue + 1.0).get();
        value = channel.getDouble().get();
        doubleValue = value.getValue().get(0);
        System.out.println("The new value is " + doubleValue + ".");
        channel.destroy();
        client.destroy();
    }

}

Running this simple example program twice should result in an output similar to the following one (assuming that there is a server hosting “testChannel” on the network and that the channel is writable):

The current value is 0.0.
The new value is 1.0.
The current value is 1.0.
The new value is 2.0.

The individual steps involved in this example are explained in greater detail in the next section.

The client is represented by an object implementing the ChannelAccessClient interface. The EPICS Jackie client library provides an implementation of this interface that is called DefaultChannelAccessClient. This implementation should be suitable for most applications.

ChannelAccessClient client = new DefaultChannelAccessClient();

When using the default constructor, the Channel Access client uses a default-constructed ChannelAccessClientConfiguration and a DefaultClientThreadingStrategy that uses the ErrorHandler from the ChannelAccessClientConfiguration.

By default, the ChannelAccessClientConfiguration initializes itself using environment variables with the EPICS_CA_* prefix These are the same environment variables that are also used by the Channel Access C library. These defaults can be overridden by passing an explicitly constructed ChannelAccessClientConfiguration. There also are a few configuration options that cannot be specified through environment variables but can only be specified by passing them to the ChannelAccessClientConfiguration constructor. Please refer to Section 3, “Configuration options” for details concerning the client configuration.

The DefaultClientThreadingStrategy in its default configuration should be suitable for most use-cases. However, it is possible to modify some behavior by constructing it explicitly and specifying certain options. In the rare case that these customization options are not sufficient, it is even possible to use a custom implementation of the ClientThreadingStrategy. Please refer to Section 6, “Threading strategy” for details concerning the threading strategy.

The ChannelAccessClient is thread-safe. This means that a single instance is typically sufficient for the whole application. In fact, sharing a single instance actually help to save system resources. The only reason for using more than one instance in the same application is when it is necessary to have clients that use different configurations.

After the client has been constructed, channels can be created. For example, we can create a reference to a channel named “testChannel” like this:

ChannelAccessChannel channel = client.getChannel("testChannel");

Each time a channel is requested from the client, a new instance of ChannelAccessChannel is returned. However, all instances referring to the same channel name internally use the same implementation so that the overhead for maintaining several instances is negligible. This concept facilitates the use of a single client for a whole application because a component can request a channel without having to worry whether another component has requested the same channel. This resource sharing is implicitly handled by the library and completely transparent to the user.

Like the ChannelAccessClient, instances of ChannelAccessChannel are thread-safe.

When a channel is created, the new channel object is returned immediately without blocking for network I/O. However, the client starts a name-lookup process for the specified channel name in the background. When the server hosting the channel is found, the client automatically connects to this server and subsequently to the channel. When the client is already connected to a channel hosted by the same server, the existing connection is reused instead of establishing a new one. In any case, once the channel has been successfully connected, the respective channel object changes to the connected state. When, at some later point, the connection is interrupted (for example because of a general network interruption or because the server is stopped), the channel object changes to the disconnected state and the client starts the lookup process again. Once the (new) server for the channel is found, the connection to the server is established again and the channel changes to the connected state once again.

This whole process is transparent to the user of the client. The ChannelAccessChannel object remains valid over the whole life-cycle until it is explicitly destroyed by the user. However, read or write operations fail while a channel is not connected and monitor subscriptions do not receive updates. For this reason, the user might be interested in knowing the channel’s connection state.

if (channel.isConnected()) {
    System.out.println("The channel is connected.");
} else {
    System.out.println("The channel is not connected.");
}

try {
    channel.waitForConnectionState(true).get();
    System.out.println("The channel is now connected.");
} catch (ExecutionException e) {
    e.printStackTrace();
} catch (InterruptedException e) {
    Thread.currentThread().interrupt();
}

ListenableFuture<Boolean> waitForConnectionStateFuture = channel
        .waitForConnectionState(true);
waitForConnectionStateFuture
        .addCompletionListener(new FutureCompletionListener<Boolean>() {
            @Override
            public void completed(ListenableFuture<? extends Boolean> future) {
                try {
                    future.get();
                    System.out.println("The channel is connected now.");
                } catch (ExecutionException e) {
                    e.printStackTrace();
                } catch (InterruptedException e) {
                    throw new RuntimeException(
                            "Unexpected InterruptedException.");
                }
            }
        });

Waiting using a connection listener

The alternative way of being notified when the channel is connected (or disconnected) is through a ChannelAccessConnectionListener that is notified every time when the channel changes its connection state:

channel.addConnectionListener(new ChannelAccessConnectionListener() {
    @Override
    public void connectionStateChanged(ChannelAccessChannel channel,
            boolean nowConnected) {
        if (nowConnected) {
            System.out.println("Channel " + channel.getName() + " connected.");
        } else {
            System.out.println("Channel " + channel.getName()
                    + " disconnected.");
        }
    }
});

Directly after being registered, the listener is called once with the current connection state and after that once for every change of the connection state.

Like future listeners, connection listeners must not block unless specific precautions have been taken. Please refer to Section 5, “Listener lock-policy” and Section 6, “Threading strategy” for details.

Note

In the default implementation of the Channel Access client, the client does not keep a strong reference to a channel. This means that a channel will eventually be marked for garbage collection and destroyed if the application does not retain a strong reference to it. This happens even if there are active connection listeners attached to the channel. However, if possible, an application should not rely solely on garbage collection for resource management because garbage collection is inherently unpredictable. The application should call the channel’s destroy method as soon as it does not need the channel any longer. This will ensure that network resources associated with the channel are released immediately (for example, the connection to the server can be closed if there are no remaining channels hosted by the same server). The automatic destruction during garbage collection is only intended as a last resort in case a bug in the application would otherwise cause a resource leak, very similarly to how the Java platform manages I/O resources. Please refer to Section 2.8, “Resource management” for more information about resource management in the EPICS Jackie Client.

The Channel Access protocol provides a “get” operation that can be used to read the current value of a channel just once. This operation should not be used if continuous updates of a channel’s value are desired. For this use-case, Channel Access provides much more efficient “monitor subscription” (see Section 2.6, “Using monitor subscriptions”).

It is an inherent feature of the Channel Access protocol that the type of a channel cannot be known a priori. For this reason, there are two options for getting a channel’s value: The request can be made using the native type of the channel, that can only be determined at run-time. Alternatively, the request can be made using a specific type. In this case, the server will convert the channel’s value to the requested type before sending it to the client.

First, we look at an example where we specify a specific data-type:

try {
    ChannelAccessDouble value = channel.getDouble().get();
    System.out.println("The channel has the value " + value.getValue().get(0)
            + ".");
} catch (ExecutionException e) {
    e.printStackTrace();
} catch (InterruptedException e) {
    Thread.currentThread().interrupt();
}

As we specified that we want to get a value of type DBR_DOUBLE (by using the getDouble method), we know at compile time that we will get a value of type ChannelAccessDouble. Actually, the type of the return value is ChannelAccessSimpleOnlyDouble, but that interface does not offer any additional methods, so we can simply treat it like a ChannelAccessDouble for now.

The getDouble method does not return the value directly. Reading a channel's value requires network I/O, so the operation can not complete right away. Instead of blocking, the getDouble method returns a listenable future that completes when the value has been read (or the operation has failed). Like we have already seen in the section called “Waiting using a future”, we can block, waiting for the future to complete, or we can register a listener that is notified when the future has completed.

The get… methods of ChannelAccessChannel return sub-types of ChannelAccessValue instead of returning a primitive (or an array thereof) directly. There are two reasons for this: First, these values fit in the same type hierarchy that is also used when the actual type is determined at run-time. This makes the code more generic. Second, depending on the type, the values may carry additional information like the channel’s alarm state or a time stamp.

The value’s getValue method returns a DoubleBuffer instead of a double[] array. This way, the same value may be shared by different components of an application without having to worry that one component might accidentally modify the value, leading to undesired or even undefined behavior. As an alternative, values could be copied whenever they are passed to more than one component, but this would be very inefficient, in particular when large arrays are involved.

Each of the channel’s get… methods has to variants: The first one takes an integer parameter. This parameter specifies the maximum number of array elements that are read from the server. If the channel’s value is represented by an array with more elements, the remaining elements are simply skipped. The second variant does not take any parameters. It always returns all the elements, regardless of the array’s size.

There are two get… methods for each of the data types defined in ChannelAccessValueType, the only exception being the DBR_PUT_ACKT and DBR_PUT_ACKS types which can only be used in put operations. For each of the seven basic types (DBR_STRING, DBR_SHORT, DBR_FLOAT, DBR_ENUM, DBR_CHAR, DBR_LONG, and DBR_DOUBLE), there are sub-types that provide the alarm status (DBR_STS_…), the time stamp and alarm status (DBR_TIME_…), the alarm status and display information (DBR_GR_…), and the alarm status, display information and control limits (DBR_CTRL_…). In addition to that, there are two special types, DBR_STSACK_STRING and DBR_CLASS_NAME. The DBR_STSACK_STRING type (method getAlarmAcknowledgementStatus) is used to get information about acknowledged and unacknowledged alarms and the configuration regarding the acknowledgement of transient alarms. The DBR_CLASS_NAME type (method getClassName) is used to get the name of the implementation backing the channel. For a regular EPICS IOC, this is the name of the record type (for example ai, ao, bi, bo, calc, longin, or longout).

If we do not want to get a value of a specific type, but rather want to use the type that is native to the server, we can use the channel’s getNative method. There also is a get method taking a parameter of type ChannelAccessValueType. It can be used when a specific type shall be requested but this type is not known at compile-time. For example, an application might be interested in getting a value with the type native to the server, but also wants a time stamp. In this case, the application can use the channel's getNativeDataType to determine the native type and than use the corresponding type that also includes a time stamp:

ChannelAccessValueType nativeType = channel.getNativeDataType();
ChannelAccessValueType timeType;
try {
   timeType = nativeType.toTimeType();
} catch (IllegalArgumentException e) {
    timeType = ChannelAccessValueType.DBR_TIME_STRING;
}
try {
    ChannelAccessGettableValue<?> value = channel.get(timeType).get();
    ChannelAccessTimeValue<?> timeValue = (ChannelAccessTimeValue<?>) value;
    System.out.println("Time stamp is " + timeValue.getTimeStamp().toString());
} catch (ExecutionException e) {
    e.printStackTrace();
} catch (InterruptedException e) {
    Thread.currentThread().interrupt();
}

As the exact type cannot be known at compile time, the get method returns a future that in turn returns a value of type ChannelAccessGettableValue. This is the base type implemented by all values that can be returned by read operations. In this example, we can safely cast the value to ChannelAccessTimeValue because we requested a DBR_TIME_… type, so the returned value must implement ChannelAccessTimeValue. The ChannelAccessValue interface provides a method getType that can be used to determine the actual type of a value at run-time. There also is a getGenericValueElement method that can be used to retrieve an element of the value array (specifying the element’s index) without having to know its actual type. Combined with the getValueSize method, this can be used to get all the value elements without knowing their concrete type. However, this involves boxing of primitive values to turn them into objects, making this much less efficient than casting to the correct type and then using the getValue method to get a buffer providing primitives.

Please note that the getNativeDataType method (like the get… methods) can only be used when the channel is connected. Using it when the channel is not connected results in an IllegalStateException being thrown. The get… methods do not throw an IllegalStateException. Instead, the returned future’s get method throws a ChannelAccessException with a status of ECA_DISCONN.

For writing to a channel, the Channel Access protocol provides a “put” operation. Writing a value is very similar to reading one. For example, in order to write a double value, we could use the following code:

try {
    // The get() call on the future is only necessary if we want to wait for the
    // operation to complete or if we want to be notified if it fails.
    channel.putDouble(42.0).get();
} catch (ExecutionException e) {
    e.printStackTrace();
} catch (InterruptedException e) {
    Thread.currentThread().interrupt();
}

Like a read operation, a write operation completes asynchronously. The ListenableFuture returned by the put… method can be used to wait for the operation to be completed or to register a listener that is notified when the operation has completed. If we are not interested in waiting for the operation to complete, we can simply ignore the returned future. In this case, however, we will not be notified either when the operation fails. If we are interested in knowing whether the operation has been successful, we have to call the future’s get method (which will block when the future has not completed yet). This method returns null on success and throws an exception on failure.

The ChannelAccessChannel has two put… methods for each of the seven basic data-types described by ChannelAccessValueType (DBR_STRING, DBR_SHORT, DBR_FLOAT, DBR_ENUM, DBR_CHAR, DBR_LONG, and DBR_DOUBLE). For each data type, there is one method taking a single element and one taking an array of elements (for example double and double[]). The DBR_STRING type is an exception because there is an additional method taking a Collection of Strings.

Writing values of a “complex” type (for example a DBR_GR_STRING) is not supported by the Channel Access protocol. However, there are two special types, that can only be used in write, but not in read operations: DBR_PUT_ACKT and DBR_PUT_ACKS. The first one is used for configuring whether transient alarms need to be acknowledged and can be written by using the channel’s putConfigureAcknowledgeTransientAlarms method. The second one is used for acknowledging alarms and can be written by using the channel’s putAcknowledgeAlarm method.

It is also possible to write a value of a type that is only determined at run-time. The channel’s put method takes a parameter of type ChannelAccessPuttableValue. This is a marker interface that is only implemented by types that may be used in write operations. An application must never attempt to supply its own implementation of any of the interfaces in the ChannelAccessValue type hierarchy. Instead, one of the methods provided by ChannelAccessValueFactory should be used to construct an instance. Please refer to Chapter IV, EPICS Jackie Common Components, Section 2, “Channel Access value objects” for more information about the Channel Access value type system.

Please note that the the put… methods can only be used when the channel is connected. When it is used while the channel is not connected (or when the channel disconnects before the operation has finished) the future returned by the put… method throws a ChannelAccessException with a status of ECA_DISCONN.

The Channel Access protocol has a very useful feature called “monitors”. These monitors can be used to be notified by a server whenever a channel’s state or value changes (significantly). This works asynchronously so that it is much more efficient than polling the channel. This helps to reduce latency and to preserve processing power, I/O operations, and bandwidth.

Creating a monitor subscription is very similar to reading from a channel. Monitor subscriptions support exactly the same data types that are also supported for read operations. For example, the following code shows how we can create a monitor subscription for double values that include a time stamp:

ChannelAccessMonitor<ChannelAccessSimpleOnlyDouble> monitor = channel
        .monitorDouble();
monitor.addMonitorListener(
        new ChannelAccessMonitorListener<ChannelAccessDouble>() {
            @Override
            public void monitorError(
                    ChannelAccessMonitor<? extends ChannelAccessDouble> monitor,
                    ChannelAccessStatus status, String message) {
                System.out.println("Error: " + status.toString()
                        + (message == null ? "" : ", " + message));
            }

            @Override
            public void monitorEvent(
                    ChannelAccessMonitor<? extends ChannelAccessDouble> monitor,
                    ChannelAccessDouble value) {
                System.out.println("Value is " + value.getValue().get(0));
            }
        });

Monitor subscriptions differ from read operations in three ways: First, they can always be created, even when the channel is disconnected. Of course, events are only received as long as the channel is actually connected. Second, the monitor… methods return a ChannelAccessMonitor instead of a ListenableFuture. Third, a monitor subscription does not cause just one event, but it causes one event after the monitor is created and one event every time an event is received from the server.

The ChannelAccessMonitorListener has two methods. The monitorError method is called when the server sends an error notification. Typically, a server only sends an error notification when the monitor subscription could not be created for some reason. When the channel is disconnected, this does not cause an error notification because this is not considered a problem: As long as a monitor exists, it will automatically start sending events once the channel is (re-)connected. The monitorEvent method is called every time when an updated value is received from the server. This method is also called once after the monitor subscription has been created (and the first value has been received from the server). It is also called once after the connection with the server has been reestablished because the value on the server might have changed in the meantime.

Note

In the default implementation of the Channel Access client, the client does not keep a strong reference to a monitor. This means that a monitor will eventually be marked for garbage collection and destroyed if the application does not retain a strong reference to it. This happens even if there are active listeners attached to the monitor. However, if possible, an application should not rely solely on garbage collection for resource management because garbage collection is inherently unpredictable. The application should call the monitor’s destroy method as soon as it does not need the monitor any longer. This will ensure that network resources associated with the monitor are released immediately (for example, the server can stop sending updates if there are no other monitors sharing the same subscription). The automatic destruction during garbage collection is only intended as a last resort in case a bug in the application would otherwise cause a resource leak, very similarly to how the Java platform manages I/O resources. Please refer to Section 2.8, “Resource management” for more information about resource management in the EPICS Jackie Client.

For each get… method of the ChannelAccessChannel, there are two corresponding monitor… methods. One of them has the same parameters as the corresponding get… method. The other one takes an additional parameter of type ChannelAccessEventMask. This parameter defines the kind of events for which the server should send a notification. If not specified, the default event mask specified in the ChannelAccessClientConfiguration for the client is used.

There are four basic mask values (DBE_VALUE, DBE_ARCHIVE, DBE_ALARM, and DBE_PROPERTY). These mask values can be combined to build other masks. DBE_VALUE is used for retrieving notifications when the channel’s value changes. DBE_ARCHIVE is also used for notifications on value change, but a server can choose to use a larger dead-band compared to the one used for DBE_VALUE. This means that typically, only larger value changes (that are considered significant enough to be archived) result in a notification. Usually, only one of DBE_VALUE or DBE_ARCHIVE are specified in a mask. DBE_ALARM is used for being notified whenever a channel’s alarm state changes. DBE_PROPERTY is used for being notified when other properties of a channel (for example engineering units or limits) change. The default mask is the combination (binary or) of DBE_VALUE and DBE_ALARM.

Like when reading values, the type that is supposed to be used for a monitor subscription cannot always be determined at compile-time. For these cases, the ChannelAccessChannel provides the monitorNative and monitor methods.

The monitorNative methods create a monitor that always delivers values with the type that is native to the server. As a channel might be disconnected and reconnected to a different server (or the same server using a different configuration), the native type can change over the life-time of the monitor subscription. In this case, the type of the values delivered with monitor events will change accordingly, always representing the current native type.

The monitor method allows the user to specify the data type of the value that the server shall send with monitor events. This must be one of the types that is allowed for a read operation. Please refer to Section 2.4, “Reading from a channel” for details about specifying the data type for a read operation at run-time.

The Channel Access protocol allows a server to restrict access to a channel. There can be separate access restrictions for read and write operations. For example, a server might choose to allow read access to all clients but restrict write access to certain clients.

An application can query the access rights for a channel by using the ChannelAccessChannel’s isMayRead and isMayWrite method. The first one returns true if read operations (this means “get” and “monitor” operations) are allowed, the second one returns true if write (“put”) operations are allowed.

The access rights can only be checked when the channel is connected. Calling either of the methods when the channel is disconnected results in an IllegalStateException being thrown. Please note that when a channel is connected, then disconnected, and then connected again, the access rights might have changed compared to the first connection because the channel might now be hosted by a different server (or the same server, but using a different configuration).

Calling one of the get… or put… methods when the client does not have the corresponding access right results in the future returned by the method failing with a ChannelAccessException that has a status code of ECA_NORDACCESS or ECA_NOWTACCESS respectively.

In the same way, a monitor triggers an error notification with a status code of ECA_NORDACCESS when a monitor subscription cannot be created because of insufficient access rights.

The objects provided by the EPICS Jackie Client (the ChannelAccessChannels, the ChannelAccessMonitors, or even the ChannelAccessClient itself), are associated with network resources. For this reason, it is important that these objects are destroyed so that the corresponding network resources can be deleted when they are not needed any longer.

Each of these objects can be destroyed by calling its destroy method. Destroying a channel also destroys all its monitors and destroying a client also destroys all its channels.

Each time the ChannelAccessClient’s getChannel method is called, a separate ChannelAccessChannel instance is returned. Even though the resources of all the instances are shared internally, thus avoiding the redundant allocation of resources, each instance is destroyed separately. This means that the resources are only realeased after all instances of ChannelAccessChannel referring to the same channel name have been destroyed.

The same applies to ChannelAccessMonitors. Each time one of the monitor… methods is called, a new instance is returned. However, those instances internally share resources. This means that several monitor’s created for the same channel name and using the same parameters (monitor event mask, data type, and element count) internally use only one subscription. This subscription is cancelled when the last monitor referring to it is destroyed.

In order to avoid a resource leak when an application erroneously does not destroy a channel or monitor when it does not need it any longer, the default implementation (DefaultChannelAccessClient) does not keep strong references to channels and monitors. This means that a channel or monitor that is not referenced any longer will eventually be marked for garbage collection and destroyed. For this reason, it is important that application code wanting to keep a channel or monitor alive (typically because it has a listener attached to it and wants to keep getting notified of events) has to retain a strong reference to the channel or monitor.

For example, the following code will not work as naively expected:

ChannelAccessMonitorListener listener = ... // The details of the listener are
                                            // not relevant for this example.
// Bad example, do NOT write code like this:
channel.monitorDouble().addMonitorListener(listener);

First, the monitor listener might receive events as expected. After some time, however, the Java Virtual Machine might run the garbage collection, resulting in the monitor instance created by monitorDouble being destroyed because there is no strong reference to it.

Still, an application should not solely rely on garbage collection for destroying channels or monitors. Typically, the Java Virtual Machine initiates a garbage collection when there is demand for it because free memory is becoming scarce. However, channels and monitors not only consume memory, but also consume precious network and I/O resources (for example file descriptors). This means that there could be a situation in which these resource become scarce, but the garbage collection does not run because free memory is still abundant. This is the same reason why Java I/O objects (for example InputStream or OutputStream) should be closed explicitly instead of relying on garbage collection closing them.

When a strong reference to a monitor is kept, it is not necessary to also keep a strong reference to the corresponding channel. Each monitor keeps a strong reference to its channel (which can be retrieved using the getChannel method). For this reason, a channel will only be destroyed by the garbage collection after all monitors referencing it have been destroyed.

As a general guideline, an application should keep a separate channel or monitor instance for each of its components, even if they refer to the same channel. As described earlier, the ChannelAccessClient ensures internal sharing of resources so that the overhead is negligible. The resource management is simplified significantly by this approach: A component can create the channel or monitor when the component is created and destroy it when the component is destroyed.

For example, an application with a graphical user-interface (GUI) might have widgets that refer to channels for displaying purposes. In this case, it makes sense that each of these widgets has its own instance of ChannelAccessChannel. When a widget is destroyed, it can safely destroy its associated channel. This means, for example, that a window being closed would destroy all the widgets used in this window and thus indirectly all the channel instances. If the same channels were also used in other windows, the internal resources would be kept alive and thus the other widgets would continue working as expected. However, when the last window referencing a certain channel was closed, this would result in the immediate destruction of the last ChannelAccessChannel instance, thus immediately freeing the associated resources.

Basically, the same applies to instances of ChannelAccessClient. When a client is not needed any longer, it should be destroyed. However, most applications will need the client for their whole life-time. When the Java Virtual Machine is shutdown, the resources associated with a client are released implicitly, making it not strictly necessary to destroy the client. However, it is still considered good style to destroy the client explicitly when reasonably possible. Having more than one client instance per application should be avoided at all cost. Each client instance consumes precious resources (network sockets and background threads), so operation is most efficient when there is only one client. In addition to that, the sharing of resources for channels and monitors is realized on the client level. This means that if there is more than one client and each of these clients creates a channel instance referring to the same channel name, those channel instances will not share resources, increasing resource consumption significantly. In case of doubt, it is better to only have a single client instance and not being able to properly destroy the client than creating many client instances just for the sake of simpler resource management.

The ChannelAccessClientConfiguration is the top object in the configuration hierarchy used by the ChannelAccessClient. It encapsulates all the configuration options needed by a client, including an instance of BeaconDetecorConfiguration (explained in Section 3.2, “Beacon detector configuration”) and an instance of ChannelNameResolverConfiguration (explained in Section 3.3, “Channel-name resolver configuration”).

In most environments, the name resolution of channel names relies on UDP broadcast packets being sent to the network. In order to avoid flooding the network with these brodcast packets, a complex algorithm is used that limits the rate of name resolution requests. While the details of this algorithm are rather complex, one of its main effects is that the time interval between two resolution requests for the same channel name is increased with every failed attempt to resolve it. This has the effect that a channel name that can never be resolved (maybe because it has been mistyped) will still not put a significant load on the network. However, there is the undesired side effect that a channel that could not be resolved because its server was offline might take a very long time to be resolved after the server goes online. In order to mitigate this effect, there is a mechanism that (under certain circumstances) can detect when a server that has previously been offline becomes available. This mechanism is called “beacon detection” and works by decreasing the search interval for channels that could not be resolved for a long time when a “beacon anomaly” (an event that might indicate a previously offline server now being online) is detected.

The whole beacon detection and name resolution process is transparent to the user and the client internally handles it. However, there are a few configuration options regarding the beacon detection that can be configured in the BeaconDetectorConfiguration. Typically, the default values of this configuration are fine, an application only has to specify explicit values if it wants to override the default behavior of how the port numbers are determined.

The channel-name resolver is responsible for resolving channel names. This is the process of finding the server that hosts the channel identified by a certain name. The channel-name resolver is a vital part of the Channel Access client because without it, the client could not know which server(s) it has to connect to or whether a channel even exists at all.

In most environments, UDP is used for name resolution. In very recent protocol versions (since Channel Access version 4.12, introduced with EPICS Base 3.14.12 released in November 2010), name resolution via TCP is supported as well. However, unlike the name resolution via UDP, name resolution via TCP always requires explicit configuration (at least by setting the corresponding environment variable).

The behavior of the channel-name resolver (in particular the port numbers used) can be specified by explicitly constructing a ChannelNameResolverConfiguration and passing it to the ChannelAccessClientConfiguration.

The DefaultClientThreadingStrategy is the default implementation used by the DefaultChannelAccessClient if no other threading-strategy is specified. This threading strategy creates one thread that handles beacon detection and name resolution and one additional thread for each connection with a channel server. Channels that are hosted by the same server share a connection, so that the number of server connections is usually rather small.

By default, this threading strategy notifies listeners (like channel connection listeners, future completion listeners, and monitor event listeners) in the same thread that triggers the event. This implementation is very efficient and safe as long as the listeners do not block or need a considerable amount of processing time.

When being constructed explicitly (in contrast to being created implicitly by the DefaultChannelAccessClient), the DefaultClientThreadingStrategy allows for changing this behavior. The user can specify an ExecutorService that is used for calling listener methods. When this option is used, blocking listeners do not pose a threat to the stability of the client, provided that the ExecutorService’s execute method does not block.

Even if such a configuration is used, blocking listeners are still not desirable because they might cause the execution of other listeners to be delayed if a fixed-size thread-pool is used and all threads are occupied by blocking listeners. In addition to that, delegating the execution of listeners to an executor service causes significant overhead for coordination in order to ensure that event notifications are being delivered in the correct order. Last but not least, such a configuration cannot guarantee that a listener will not be called after it has been removed. If events have been queued before the listener is removed, the listener is still going to be called for those events.

For these reasons, the default option of notifying listeners in the calling thread should be preferred. The option of using an executor service should only be considered when implementing all listeners in a way so that they do not block is not feasible.

For some applications, the threading model provided by the DefaultClientThreadingStrategy might not be convenient. For example, there might be applications that connect to a large number of servers, but want to keep the number of threads to a minimum. Such an application could easily provide its own implementation of the ClientThreadingStrategy interface that only creates a single thread that takes care of handling all I/O operations, including the beacon detector, the channel-name resolver and all channel-server connections.

Creating such a threading strategy is as simple as creating a SimpleCommunicationController that is repeatedly called from the processing thread. The threading strategy can then simply pass this communication controller to all the CommunicationProcessors used for the beacon detector, the channel-name resolver, and the channel-server connections.

Another threading strategy might want to use a pool of threads for processing the various communication controllers. Such an implementation can also be built based on the SimpleCommunicationController. However, as soon as more than one thread is involved, care must be taken that a single communication processor is not processed by more than one thread because communication processors are not thread-safe.

There are two types of byte streams: A ByteSource acts as an input stream, providing data that has been read from some source (typically a network socket). Correspondingly, a ByteSink acts as an output stream, accepting data and writing it to some kind of sink (typically, this also is a network socket).

The interface of ByteSource and ByteSink resembles the interface of Java’s ByteBuffer class. The most notable difference is that there are no read and write methods taking an offset. The read methods always consume the bytes right at the beginning of the data remaining in the the source. In the same way, the write methods always append the bytes right at the end of the data already written to the sink.

Sometimes, a read or write operation only makes sense if a whole data-set can be read or written. The ByteSource and ByteSink provide atomic read and write operations for this purpose: When an atomic read operation fails, the source is rolled back to the state it was in before the atomic read operation started, so that the data consumed by the read operation is still available for the next read operation. In the same way, when an atomic write operation fails, the sink is rolled back to the state it was in before the atomic write operation started, so that none of the data written by the write operation is actually written. Internally, this works by using buffers that store the data.

This feature is very useful when processing a protocol that relies on some form of packets or messages. In this case, the code can fail if a message cannot be read or written completely, relieving it from the burden to keep track of which data has already been read or written and having to continue at the right point.

The ByteSource has a remaining method that returns the number of bytes that can be read from the byte source without a BufferUnderflowException being thrown. However, the value returned by this method only is a lower estimate, meaning that there might actually be more data available. Typical implementations will return the number of bytes available in the internal buffer and throw a BufferUnderflowException when reading beyond the limit of this buffer, but some implementations might choose copying additional bytes into the buffer when its end is reached, in which case the estimate might be too small.

The ByteBufferByteSource and ByteBufferByteSink are implementations that internally use a list of ByteBuffers for buffering data. These implemantations are very convenient when used with asynchronous I/O because they allow for an easy integration with Java’s Channel API that also works with ByteBuffers. The ByteBufferByteSource implements the remaining method so that the number of bytes remaining in the buffers is returned (unless this number exceeds Integer.MAX_VALUE in which case that number is returned instead). This means that an application reading from the byte source can check whether the data remaining in the byte source is sufficient for finishing an atomic read operation and can fail early with a BufferUnderflowException if the remaining bytes are not sufficient.

The AbstractSocketChannelConnection class described in Section 3.2, “Asynchronous I/O” provides a convenient way of connecting a SocketChannel with the ByteSource and ByteSink APIs.

In Java, asynchronous I/O is typically performed through the facilities of the Java NIO framework. This means that a Selector has to be created and Channels have to be registered with this selector in order to be notified when the operating system is ready for an I/O operation.

Managing the selector and its associated channels can be tedious because it means that the component responsible for a certain channel has to be identified and notified. In addition to that, components often want to perform certain operations in certain time intervals, independent of the I/O state of their channel. In this case, the select operation on the selector has to be limited in time so that the timed operation can be run at the right point in time.

The asynchronous I/O framework of EPICS Jackie provides a component that takes care of all these details. This component is called the CommunicationController. The communication controller allows for both kind of notifications: being notified, when a channel is ready for an I/O operation and being notified when a timer has expired.

The registerChannel method is used to register a ChannelProcessor that is notified when the corresponding Channel is ready for I/O. The return value of this method is a SelectionKey that can be used by the channel processor in order to configure when it wants to be notified. Most processors will want to always be notified when the channel is ready for a read operation (because new data has arrived), but will only be interested to be notified when the channel is ready for a write operation when they actually have data in their write buffer.

The registerTimer method is used to register a TimerProcessor that is notified after a certain time interval has passed.

It is assumed that a communication controller only uses a single thread so that channel and timer processors can be designed without having to worry about thread safety. As one component might register more than one channel or timer processor, a communication controller has to guarantee that this holds true, even for different processors that are registered with the same controller.

The SimpleCommunicationController is an implementation that deals with all the tasks of a communication controller, doing its work in a single method, processTimersAndIO, that has to be called repeatedly by an application thread.

The CommunicationProcessor interface is a simple interface that can be implemented by a component in order to get the CommunicationController injected. This way, a component using a communication controller can be designed without having any dependencies on how the communication controller (and its associated thread) is created or which implementation is used.

The AbstractSocketChannelConnection is a good starting point for writing a component that uses a SocketChannel for asynchronous I/O. Its constructor takes a socket channel and a communication controller and takes care of registering the channel with the communication controller. Internally, it uses instances of ByteBufferByteSource and ByteBufferByteSink that are connected with the channel so that data that arrives on the channel is made available in the byte source and data that is written to the byte sink is written to the channel.

The application code typically only has to implement (some of) the five event handler methods (onConnect, onDestroy, onReceive, onReceiveFinished, onSend) and can simply use the provided byte source and byte sink to read and write data from within these methods.