gov.aps.jca

Class JCALibrary

java.lang.Object

gov.aps.jca.JCALibrary

public final class JCALibrary
extends Object

The JCALibrary class is the entry point to all JCA enabled application. There is only one instance of this class which can be accessed by the static method getInstance(). This object can be used to retreive all JCA configuration and version and to create new contexts.
The JCALibrary can be configured with properties. See java.util.Properties for more details.

 Global      : The file <jre home>/lib/JCALibrary.properties defines global properties
 User        : The file <user home>/.JCALibrary/JCALibrary.properties defines per user's properties
 Command Line: Properties can also be passed as command line argument using the -D switch
 

The command line properties take precedence over the user's properties which take precedence over the global properties.

The JCALibrary class itself doesn't require any configuration however most classes implementation will refer to the properties defined in this files.
See the specification of the object's implementation you're planning on using.
The core JCA package comes with two Context's implementation:

 JNI_THREAD_SAFE
 JNI_SINGLE_THREADED
 CHANNEL_ACCESS_JAVA
 

This two implementations are using the Java Native Interface (JNI) to communicate with channel access servers. They are both accessing a JNI bridge which require a set of two special properties:

  gov.aps.jca.jni.epics.<your arch>.library.path: the path of you're epics distribution shared libraries.
  gov.aps.jca.jni.epics.<your arch>.caRepeater.path: the path of you're epics caRepeater executable.

Note: <your arch> represent you're epics host architecture, ie win32-x86, linux-x86, solaris-sparc, etc...
Note: The properties files can contain several sets of these properties with different host architectures.

Author:

Eric Boucher

Field Summary

Fields

Modifier and Type	Field and Description
static String	CHANNEL_ACCESS_JAVA Constant string representing the fully qualified class name of a 100% pure java channel access Context implementation.
static String	CHANNEL_ACCESS_SERVER_JAVA Constant string representing the fully qualified class name of a 100% pure java channel access ServerContext implementation.
static String	JNI_SINGLE_THREADED Constant string representing the fully qualified class name of a single-threaded Context implementation.
static String	JNI_THREAD_SAFE Constant string representing the fully qualified class name of a thread safe Context implementation.

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	JCALibrary() Construct and configure the JCALibrary.

Method Summary

Modifier and Type	Method and Description
Context	createContext(Configuration configuration) Create a new context instance using a Configuration object.
Context	createContext(String fqn) Create a new context instance using a fully qualified class name and using the Context's default configuration.
ServerContext	createServerContext(Configuration configuration, Server server) Create a new server context instance using a Configuration object.
ServerContext	createServerContext(String fqn, Server server) Create a new context instance using a fully qualified class name and using the ServerContext's default configuration.
static JCALibrary	getInstance() Getter method to the only instance of JCALibrary.
int	getModification() Getter method for the modification number.
String	getProperty(String name) Retreive a JCALibrary property.
String	getProperty(String name, String defaultValue) Retreive a JCALibrary property with a default value.
boolean	getPropertyAsBoolean(String name, boolean defaultValue) Retreive a JCALibrary property as a boolean with a default value.
double	getPropertyAsDouble(String name, double defaultValue) Retreive a JCALibrary property as a double with a default value.
float	getPropertyAsFloat(String name, float defaultValue) Retreive a JCALibrary property as a float with a default value.
int	getPropertyAsInt(String name, int defaultValue) Retreive a JCALibrary property as an int with a default value.
long	getPropertyAsLong(String name, long defaultValue) Retreive a JCALibrary property as a long with a default value.
int	getRevision() Getter method for the revision number.
int	getVersion() Getter method for the version number.
String	getVersionString() Getter method for the full version string.
void	listProperties() Print all JCALibrary properties to the standard output stream.
void	listProperties(PrintStream out) Print all JCALibrary properties to a specified output stream.
void	printInfo() Print some basic info about the JCALibrary to the standard output stream.
void	printInfo(PrintStream out) Print some basic info about the JCALibrary to the specified output stream.
String	toString()

Methods inherited from class java.lang.Object

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

Field Detail

JNI_THREAD_SAFE

public static final String JNI_THREAD_SAFE

Constant string representing the fully qualified class name of a thread safe Context implementation. This type of context is usefull if you don't want to worry (too much) about thread safety in your application. However you should be award that this feature comes with a price in term of complexity.
The internal implementation of this type of context is indeed quite complex and might affect the overall performance of your application.

You can configure this type of contexts either by using JCALibrary properties or at runtime by using a Configuration object.

Using JCALibrary Properties

Property name	Range	Default value	Description
gov.aps.jca.jni.ThreadSafeContext.preemptive_callback	true/false	true	Define whether the context should use independant threads to send request callback notifications (events). If set to no, your application should periodically call pendEvent to process pending events.
gov.aps.jca.jni.ThreadSafeContext.addr_list	N.N.N.N N.N.N.N:P ...	empty string	A space-separated list of broadcast address for process variable name resolution. Each address must be of the form: ip.number:port or host.name:port
gov.aps.jca.jni.ThreadSafeContext.auto_addr_list	true/false	true	Define whether or not the network interfaces should be discovered at runtime.
gov.aps.jca.jni.ThreadSafeContext.connection_timeout	>0.1	30.0	If the context doesn't see a beacon from a server that it is connected to for connection_timeout seconds then a state-of-health message is sent to the server over TCP/IP. If this state-of-health message isn't promptly replied to then the context will assume that the server is no longer present on the network and disconnect.
gov.aps.jca.jni.ThreadSafeContext.beacon_period	>0.1	15.0	Period in second between two beacon signals
gov.aps.jca.jni.ThreadSafeContext.repeater_port	>5000	5065	Port number for the repeater to listen to
gov.aps.jca.jni.ThreadSafeContext.server_port	>5000	5064	Port number for the server to listen to
gov.aps.jca.jni.ThreadSafeContext.max_array_bytes	>=16384	16384	Length in bytes of the maximum array size that may pass through Channel Access
gov.aps.jca.jni.ThreadSafeContext.event_dispatcher_class		gov.aps.jca.event.DirectEventDispatcher	The fully qualified class name of the event dispatcher used to dispatch callback event. This class must have a default constructor with no arguments. Check the documentation of the event dispatcher to see how to configure it.

Note: If you use the prefix gov.aps.jca.Context or gov.aps.jca.jni.JNIContext instead of gov.aps.jca.jni.ThreadSafeContext then the property will affect both JNI_THREAD_SAFE and JNI_SINGLE_THREADED context configuration (specific configuration overrides default configurations).

Using a Configuration object

See Also:

Constant Field Values

JNI_SINGLE_THREADED

public static final String JNI_SINGLE_THREADED

Constant string representing the fully qualified class name of a single-threaded Context implementation.

Property name	Range	Default value	Description
gov.aps.jca.jni.SingleThreadedContext.preemptive_callback	true/false	true	Define whether the context should use independant threads to send request callback notifications (events). If set to no, your application should periodically call pendEvent to process pending events.
gov.aps.jca.jni.SingleThreadedContext.addr_list	N.N.N.N N.N.N.N:P ...	empty string	A space-separated list of broadcast address for process variable name resolution. Each address must be of the form: ip.number:port or host.name:port
gov.aps.jca.jni.SingleThreadedContext.auto_addr_list	true/false	true	Define whether or not the network interfaces should be discovered at runtime.
gov.aps.jca.jni.SingleThreadedContext.connection_timeout	>0.1	30.0	If the context doesn't see a beacon from a server that it is connected to for connection_timeout seconds then a state-of-health message is sent to the server over TCP/IP. If this state-of-health message isn't promptly replied to then the context will assume that the server is no longer present on the network and disconnect.
gov.aps.jca.jni.SingleThreadedContext.beacon_period	>0.1	15.0	Period in second between two beacon signals
gov.aps.jca.jni.SingleThreadedContext.repeater_port	>5000	5065	Port number for the repeater to listen to
gov.aps.jca.jni.SingleThreadedContext.server_port	>5000	5064	Port number for the server to listen to
gov.aps.jca.jni.SingleThreadedContext.max_array_bytes	>=16384	16384	Length in bytes of the maximum array size that may pass through Channel Access

Note: If you use the prefix gov.aps.jca.Context or gov.aps.jca.jni.JNIContext instead of gov.aps.jca.jni.SingleThreadedContext then the property will affect both JNI_THREAD_SAFE and JNI_SINGLE_THREADED context configuration (specific configuration overrides default configurations).

See Also:

Constant Field Values

CHANNEL_ACCESS_JAVA

public static final String CHANNEL_ACCESS_JAVA

Constant string representing the fully qualified class name of a 100% pure java channel access Context implementation.

Property name	Range	Default value	Description
com.cosylab.epics.caj.CAJContext.addr_list	N.N.N.N N.N.N.N:P ...	empty string	A space-separated list of broadcast address for process variable name resolution. Each address must be of the form: ip.number:port or host.name:port
com.cosylab.epics.caj.CAJContext.auto_addr_list	true/false	true	Define whether or not the network interfaces should be discovered at runtime.
com.cosylab.epics.caj.CAJContext.connection_timeout	>0.1	30.0	If the context doesn't see a beacon from a server that it is connected to for connection_timeout seconds then a state-of-health message is sent to the server over TCP/IP. If this state-of-health message isn't promptly replied to then the context will assume that the server is no longer present on the network and disconnect.
com.cosylab.epics.caj.CAJContext.beacon_period	>0.1	15.0	Period in second between two beacon signals
com.cosylab.epics.caj.CAJContext.repeater_port	>5000	5065	Port number for the repeater to listen to
com.cosylab.epics.caj.CAJContext.server_port	>5000	5064	Port number for the server to listen to
com.cosylab.epics.caj.CAJContext.max_array_bytes	>=16384	16384	Length in bytes of the maximum array size that may pass through Channel Access
com.cosylab.epics.caj.impl.reactor.lf.LeaderFollowersThreadPool.thread_pool_size	>=2	5	Number of threads to be used to process network events

Note: prefix gov.aps.jca.Context can be used instead of com.cosylab.epics.caj.CAJContext to set global context configuration (specific configuration overrides default configurations).

See Also:

Constant Field Values

CHANNEL_ACCESS_SERVER_JAVA

public static final String CHANNEL_ACCESS_SERVER_JAVA

Constant string representing the fully qualified class name of a 100% pure java channel access ServerContext implementation. The following properties to be supported:

Property name	Range	Default value	Description
com.cosylab.epics.caj.cas.CAJServerContext.beacon_addr_list	N.N.N.N N.N.N.N:P ...	com.cosylab.epics.caj.CAJContext.addr_list (empty string)	A space-separated list of broadcast address which to send beacons. Each address must be of the form: ip.number:port or host.name:port
com.cosylab.epics.caj.cas.CAJServerContext.auto_beacon_addr_list	true/false	com.cosylab.epics.caj.CAJContext.auto_addr_list (true)	Define whether or not the network interfaces should be discovered at runtime.
com.cosylab.epics.caj.cas.CAJServerContext.beacon_period	>0.1	com.cosylab.epics.caj.CAJContext.beacon_period (15.0)	Period in second between two beacon signals
com.cosylab.epics.caj.cas.CAJServerContext.beacon_port	>5000	com.cosylab.epics.caj.CAJContext.repeater_port (5065)	Port number which to sends beacons
com.cosylab.epics.caj.cas.CAJServerContext.server_port	>5000	com.cosylab.epics.caj.CAJContext.server_port (5064)	Port number for the server to listen to
com.cosylab.epics.caj.cas.CAJServerContext.ignore_addr_list	N.N.N.N N.N.N.N:P ...	empty string	A space-separated list of addresses which name resolution request to ignore from. Each address must be of the form: ip.number:port or host.name:port
com.cosylab.epics.caj.cas.CAJServerContext.max_array_bytes	>=16384	com.cosylab.epics.caj.CAJContext.max_array_bytes (16384)	Length in bytes of the maximum array size that may pass through Channel Access
com.cosylab.epics.caj.impl.reactor.lf.LeaderFollowersThreadPool.thread_pool_size	>=2	5	Number of threads to be used to process network events

Note: prefix gov.aps.jca.Context can be used instead of com.cosylab.epics.caj.CAJServerContext to set global context configuration (specific configuration overrides default configurations).

See Also:

Constant Field Values

Constructor Detail

JCALibrary

protected JCALibrary()

Construct and configure the JCALibrary.

Method Detail

getInstance

public static JCALibrary getInstance()

Getter method to the only instance of JCALibrary.

Returns:

the singleton instance of JCALibrary.

getVersion

public int getVersion()

Getter method for the version number.

Returns:

the JCALibrary version number.

getRevision

public int getRevision()

Getter method for the revision number.

Returns:

the JCALibrary revision number.

getModification

public int getModification()

Getter method for the modification number.

Returns:

the JCALIbrary modification number.

getVersionString

public String getVersionString()

Getter method for the full version string.

Returns:

the JCALibrary version string.

printInfo

public void printInfo()

Print some basic info about the JCALibrary to the standard output stream.

printInfo

public void printInfo(PrintStream out)

Print some basic info about the JCALibrary to the specified output stream.

Parameters:

out - the output stream to send info to.

toString

public String toString()

Overrides:

toString in class Object

getProperty

public String getProperty(String name)

Retreive a JCALibrary property.

Parameters:

name - the name of the property to search for.

Returns:

the string value of the property if it exists, null otherwise.

getProperty

public String getProperty(String name,
                          String defaultValue)

Retreive a JCALibrary property with a default value.

Parameters:

name - the name of the property to search for.

defaultValue - the default value to use if the property doesn't exist.

Returns:

the string value of the property if it exists, the defaultValue otherwise.

getPropertyAsFloat

public float getPropertyAsFloat(String name,
                                float defaultValue)

Retreive a JCALibrary property as a float with a default value.

Parameters:

name - the name of the property to search for.

defaultValue - the default value to use if the property doesn't exist.

Returns:

the value of the property converted as a float if it exists, the defaultValue otherwise.

getPropertyAsInt

public int getPropertyAsInt(String name,
                            int defaultValue)

Retreive a JCALibrary property as an int with a default value.

Parameters:

name - the name of the property to search for.

defaultValue - the default value to use if the property doesn't exist.

Returns:

the value of the property converted as a int if it exists, the defaultValue otherwise.

getPropertyAsBoolean

public boolean getPropertyAsBoolean(String name,
                                    boolean defaultValue)

Retreive a JCALibrary property as a boolean with a default value.

Parameters:

name - the name of the property to search for.

defaultValue - the default value to use if the property doesn't exist.

Returns:

the value of the property converted as a boolean if it exists, the defaultValue otherwise.

getPropertyAsDouble

public double getPropertyAsDouble(String name,
                                  double defaultValue)

Retreive a JCALibrary property as a double with a default value.

Parameters:

name - the name of the property to search for.

defaultValue - the default value to use if the property doesn't exist.

Returns:

the value of the property converted as a double if it exists, the defaultValue otherwise.

getPropertyAsLong

public long getPropertyAsLong(String name,
                              long defaultValue)

Retreive a JCALibrary property as a long with a default value.

Parameters:

name - the name of the property to search for.

defaultValue - the default value to use if the property doesn't exist.

Returns:

the value of the property converted as a long if it exists, the defaultValue otherwise.

listProperties

public void listProperties()

Print all JCALibrary properties to the standard output stream.

listProperties

public void listProperties(PrintStream out)

Print all JCALibrary properties to a specified output stream.

Parameters:

out - the output stream to print the properties to.

createContext

public Context createContext(String fqn)
                      throws CAException

Create a new context instance using a fully qualified class name and using the Context's default configuration. The context class should define a default constructor with no argument.

Parameters:

fqn - the fully qualified class name of the context to create.

Returns:

the new context.

Throws:

CAException - is thrown if the context could not be instanciated.

See Also:

JNI_THREAD_SAFE, JNI_SINGLE_THREADED, createContext(gov.aps.jca.configuration.Configuration configuration)

createContext

public Context createContext(Configuration configuration)
                      throws CAException

Create a new context instance using a Configuration object. The Configuration object must define an attribute called class with the fully qualified class name of the Context as a value. All other attributes or values are specific to the Context to create.

Parameters:

configuration - the Configuration object containing the Context's class name and configuration.

Returns:

the new context.

Throws:

CAException - is thrown if the context could not be instanciated.

See Also:

JNI_THREAD_SAFE, JNI_SINGLE_THREADED, Configuration

createServerContext

public ServerContext createServerContext(String fqn,
                                         Server server)
                                  throws CAException

Create a new context instance using a fully qualified class name and using the ServerContext's default configuration. The context class should define a default constructor with no argument.

Parameters:

fqn - the fully qualified class name of the context to create.

server - Server implementation providing ProcessVariable access (existance test and attach).

Returns:

the new context.

Throws:

CAException - is thrown if the context could not be instantiated.

See Also:

CHANNEL_ACCESS_SERVER_JAVA, createServerContext(gov.aps.jca.configuration.Configuration configuration, gov.aps.jca.cas.Server server)

createServerContext

public ServerContext createServerContext(Configuration configuration,
                                         Server server)
                                  throws CAException

Create a new server context instance using a Configuration object. The Configuration object must define an attribute called class with the fully qualified class name of the Context as a value. All other attributes or values are specific to the Context to create.

Parameters:

configuration - the Configuration object containing the ServerContext's class name and configuration.

server - Server implementation providing ProcessVariable access (existance test and attach).

Returns:

the new context.

Throws:

CAException - is thrown if the context could not be instanciated.

See Also:

CHANNEL_ACCESS_SERVER_JAVA, Configuration