```
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	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 Description

protected JCALibrary()
Construct and configure the JCALibrary.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method	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

Class JCALibrary

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

JNI_THREAD_SAFE

JNI_SINGLE_THREADED

CHANNEL_ACCESS_JAVA

CHANNEL_ACCESS_SERVER_JAVA

Constructor Detail

JCALibrary

Method Detail

getInstance

getVersion

getRevision

getModification

getVersionString

printInfo

printInfo

toString

getProperty

getProperty

getPropertyAsFloat

getPropertyAsInt

getPropertyAsBoolean

getPropertyAsDouble

getPropertyAsLong

listProperties

listProperties

createContext

createContext

createServerContext

createServerContext