gov.aps.jca
Class JCALibrary

java.lang.Object
  |
  +--gov.aps.jca.JCALibrary

public final class JCALibrary

extends java.lang.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
 

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

static java.lang.String	JNI_SINGLE_THREADED Constant string representing the fully qualified class name of a single-threaded Context implementation.
static java.lang.String	JNI_THREAD_SAFE Constant string representing the fully qualified class name of a thread safe Context implementation.

Method Summary

Context	createContext(Configuration configuration) Create a new context instance using a Configuration object.
Context	createContext(java.lang.String fqn) Create a new context instance using a fully qualified class name and using the Context's default configuration.
static JCALibrary	getInstance() Getter method to the only instance of JCALibrary.
int	getModification() Getter method for the modification number.
java.lang.String	getProperty(java.lang.String name) Retreive a JCALibrary property.
java.lang.String	getProperty(java.lang.String name, java.lang.String defaultValue) Retreive a JCALibrary property with a default value.
boolean	getPropertyAsBoolean(java.lang.String name, boolean defaultValue) Retreive a JCALibrary property as a boolean with a default value.
double	getPropertyAsDouble(java.lang.String name, double defaultValue) Retreive a JCALibrary property as a double with a default value.
float	getPropertyAsFloat(java.lang.String name, float defaultValue) Retreive a JCALibrary property as a float with a default value.
int	getPropertyAsInt(java.lang.String name, int defaultValue) Retreive a JCALibrary property as an int with a default value.
long	getPropertyAsLong(java.lang.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.
java.lang.String	getVersionString() Getter method for the full version string.
void	listProperties() Print all JCALibrary properties to the standard output stream.
void	listProperties(java.io.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(java.io.PrintStream out) Print some basic info about the JCALibrary to the specified output stream.
java.lang.String	toString()

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

JNI_THREAD_SAFE

public static final java.lang.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.jni.JNIContext instead of gov.aps.jca.jni.ThreadSafeContext then the property will affect both JNI_THREAD_SAFE and JNI_SINGLE_THREADED context configuration.

Using a Configuration object

See Also:

Constant Field Values

JNI_SINGLE_THREADED

public static final java.lang.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

See Also:

Constant Field Values

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 java.lang.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(java.io.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 java.lang.String toString()

Overrides:

toString in class java.lang.Object

getProperty

public java.lang.String getProperty(java.lang.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 java.lang.String getProperty(java.lang.String name,
                                    java.lang.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(java.lang.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(java.lang.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(java.lang.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(java.lang.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(java.lang.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(java.io.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(java.lang.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