Using Java with Caché eXTreme
Quick Reference for eXTreme Classes
[Back] 
   
Server:docs1
Instance:LATEST
User:UnknownUser
 
-
Go to:
Search:    

This chapter is a quick reference for the classes that are most important to an understanding of the Caché eXTreme APIs:

Note:
This is not the definitive reference for these APIs. For the most complete and up-to-date information, see the JavaDoc for the InterSystems Java Connectivity API, located in <install-dir>/dev/java/doc/index.html.
XEP Quick Reference
This section is a reference for the XEP API (eXTreme Event Persistence — namespace com.intersys.xep). See Using eXTreme Event Persistence for a details on how to use the API. It contains the following classes and interfaces:
List of XEP Methods
The following classes and methods of the XEP API are described in this reference:
PersisterFactory
EventPersister
Event
EventQuery<>
EventQueryIterator<>
InterfaceResolver
Class PersisterFactory
Class com.intersys.xep.PersisterFactory creates a new EventPersister object.
PersisterFactory() Constructor
Creates a new instance of PersisterFactory.
PersisterFactory()
createPersister()
PersisterFactory.createPersister() returns an instance of EventPersister.
static EventPersister createPersister()  [inline, static] 
see also:
Creating and Connecting an EventPersister
Class EventPersister
Class com.intersys.xep.EventPersister is the main entry point for the XEP module. It provides methods that can be used to control XEP options, establish an XEP connection, import schema, and produce XEP Event objects. It also provides methods to control transactions and perform other tasks.
In most applications, instances of EventPersister should be created by PersisterFactory.createPersister(). The constructor should only be used to extend the class.
EventPersister() Constructor
Creates a new instance of EventPersister.
EventPersister()
callBytesClassMethod()
EventPersister.callBytesClassMethod() — calls a Caché ObjectScript class method and returns an Object that may be of type int, long, double, or byte[].
This method is identical to callClassMethod() except that it returns string values as instances of byte[] rather than String.
Object callBytesClassMethod(String className, String methodName, Object... args)
parameters:
callBytesFunction()
EventPersister.callBytesFunction() calls a Caché ObjectScript function (see User-defined Code in Using Caché ObjectScript) and returns an Object that may be of type int, long, double, or byte[].
This method is identical to callFunction() except that it returns string values as instances of byte[] rather than String.
Object callBytesFunction(String functionName, String routineName, Object... args)
parameters:
callClassMethod()
EventPersister.callClassMethod() — calls a Caché ObjectScript class method and returns an Object that may be of type int, long, double, or String. Use callVoidClassMethod() to call a method that doesn’t return a value, callBytesClassMethod() to return string values as byte[], or callListClassMethod() to return string values as ValueList.
Object callClassMethod(String className, String methodName, Object... args)
parameters:
callFunction()
EventPersister.callFunction() — calls a Caché ObjectScript function (see User-defined Code in Using Caché ObjectScript) and returns an Object that may be of type int, long, double, or String. Use callBytesFunction() to return string values as byte[], or callListFunction() to return string values as ValueList.
Object callFunction(String functionName, String routineName, Object... args)
parameters:
callListClassMethod()
EventPersister.callListClassMethod() — calls a Caché ObjectScript class method and returns an Object that may be of type int, long, double, or ValueList.
This method is identical to callClassMethod() except that it returns string values as instances of ValueList rather than String.
Object CallListClassMethod(string className, string methodName, params Object[] args)
Throws an exception if the return value is a string but is not in valid ValueList format.
parameters:
callListFunction()
EventPersister.callListFunction() calls a Caché ObjectScript function (see User-defined Code in Using Caché ObjectScript) and returns an Object that may be of type int, long, double, or ValueList.
This method is identical to callFunction() except that it returns string values as instances of ValueList rather than String.
Object CallListFunction(string functionName, string routineName, params Object[] args)
Throws an exception if the return value is a string but is not in valid ValueList format.
parameters:
callProcedure()
EventPersister.callProcedure() calls a Caché ObjectScript procedure (see User-defined Code in Using Caché ObjectScript).
void callProcedure(String procedureName, String routineName, Object... args)
parameters:
callVoidClassMethod()
EventPersister.callVoidClassMethod() — calls a Caché ObjectScript class method with no return value, passing 0 or more arguments. This method may be used to call any Caché class method (regardless of whether it normally returns a value) when the caller does not need the return value. Use callClassMethod() to call a method that returns a value.
void callVoidClassMethod(String className, String methodName, Object... args)
parameters:
close()
EventPersister.close() releases all resources held by this instance.
void close()
It is important to always call close() on an instance of EventPersister before it goes out of scope. Failing to close it can cause serious memory leaks because Java garbage collection cannot release resources allocated by native code.
commit()
EventPersister.commit() commits one level of transaction
void commit()
connect()
EventPersister.connect() establishes a TCP/IP connection to Caché.
void connect(String host, int port, String namespace, String username, String password) 
parameters:
see also:
Creating and Connecting an EventPersister
connect() Deprecated in-process connection
EventPersister.connect() uses a Globals API in-process connection if only the namespace, username, and password arguments are specified.
void connect(String namespace, String username, String password) 
This overload is deprecated. For XEP applications, the TCP/IP connection (described in the previous entry) is preferable in all respects, including bulk insert/load speed.
In this release, it is still possible for XEP to use the same in-process connection as the Globals API (see Using the Globals API). This in-process connection is deprecated for XEP, and should only be used by the Globals API. All in-process connections use the same underlying connection object, so conflicts can occur if both APIs are used in the same process. For example, a call to the Globals API setNamespace() method would change the connected namespace for both the globals.Connection object and the EventPersister object.
deleteClass()
EventPersister.deleteClass() deletes a Caché class definition. It does not delete objects associated with the extent (since objects can belong to more than one extent), and does not delete any dependencies (for example, inner or embedded classes).
void deleteClass(String className)
parameter:
If the specified class does not exist, the call silently fails (no error is thrown).
see also:
“Deleting Test Data” in Accessing Stored Events
deleteExtent()
EventPersister.deleteExtent() deletes the extent definition associated with a Java event, but does not destroy associated data (since objects can belong to more than one extent). See Extents in Using Caché Objects for more information on managing extents.
void deleteExtent(String className)
Do not confuse this method with the deprecated Event.deleteExtent(), which destroys all extent data as well as with the extent definition.
see also:
“Deleting Test Data” in Accessing Stored Events
getConnection()
EventPersister.getConnection() — returns the instance of com.intersys.globals.Connection underlying an EventPersister in-process connection. Throws an exception if the EventPersister has a TCP/IP connection.
The in-process connection is deprecated (see connect() Deprecated in-process connection for more information).
com.intersys.globals.Connection getConnection()
getEvent()
EventPersister.getEvent() returns an Event object that corresponds to the class name supplied, and optionally specifies the indexing mode to be used.
Event getEvent(String className)
Event getEvent(String className, int indexMode)
parameter:
The following indexMode options are available:
The same instance of Event can be used to store or retrieve all instances of a class, so a process should only call the getEvent() method once per class. Avoid instantiating multiple Event objects for a single class, since this can affect performance and may cause memory leaks.
see also:
Creating Event Instances and Storing Persistent Events, Controlling Index Updating
getInterfaceResolver()
EventPersister.getInterfaceResolver() — returns the currently set instance of InterfaceResolver that will be used by importSchema() (see Implementing an InterfaceResolver). Returns null if no instance has been set.
InterfaceResolver getInterfaceResolver()
see also:
setInterfaceResolver(), importSchema()
getJDBCConnection()
EventPersister.getJDBCConnection() returns the JDBC Connection object underlying an EventPersister connection.
java.sql.Connection getJDBCConnection()
see also:
Creating and Connecting an EventPersister
getTransactionLevel()
EventPersister.getTransactionLevel() returns the current transaction level (0 if not in a transaction)
int getTransactionLevel()
importSchema()
EventPersister.importSchema() produces a flat schema (see Schema Import Models) that embeds all referenced objects as serialized objects. The method imports the schema of each event declared in the class or a .jar file specified (including dependencies), and returns an array of class names for the imported events.
String[] importSchema(String classOrJarFileName)
String[] importSchema(String[] classes)
parameters:
If the argument is a class name, the corresponding class and any dependencies will be imported. If the argument is a .jar file, all classes in the file and any dependencies will be imported. If such schema already exists, and it appears to be in sync with the Java schema, import will be skipped. Should a schema already exist, but it appears different, a check will be performed to see if there is any data. If there is no data, a new schema will be generated. If there is existing data, an exception will be thrown.
see also:
Importing a Schema
importSchemaFull()
EventPersister.importSchemaFull() — produces a full schema (see Schema Import Models) that preserves the object hierarchy of the source classes. The method imports the schema of each event declared in the class or .jar file specified (including dependencies), and returns an array of class names for the imported events.
String[] importSchemaFull(String classOrJarFileName)
String[] importSchemaFull(String[] classes)
parameters:
If the argument is a class name, the corresponding class and any dependencies will be imported. If the argument is a .jar file, all classes in the file and any dependencies will be imported. If such schema already exists, and it appears to be in sync with the Java schema, import will be skipped. Should a schema already exist, but it appears different, a check will be performed to see if there is any data. If there is no data, a new schema will be generated. If there is existing data, an exception will be thrown.
see also:
Importing a Schema
rollback()
EventPersister.rollback() rolls back the specified number of levels of transaction, where level is a positive integer, or roll back all levels of transaction if no level is specified.
void rollback()
void rollback(int level)
parameter:
This method does nothing if level is less than 0, and stops rolling back once the transaction level reaches 0 if level is greater than the initial transaction level.
setInterfaceResolver()
EventPersister.setInterfaceResolver() — sets the instance of InterfaceResolver to be used by importSchema() (see Implementing an InterfaceResolver). All instances of Event created by this EventPersiser will share the specified InterfaceResolver (which defaults to null if this method is not called).
void setInterfaceResolver(InterfaceResolver interfaceResolver)
parameters:
see also:
getInterfaceResolver(), importSchema()
startTransaction()
EventPersister.startTransaction() starts a transaction (which may be a nested transaction)
void startTransaction()
Class Event
Class com.intersys.xep.Event provides methods that operate on XEP events (storing events, creating a query, indexing etc.). It is created by the EventPersister.getEvent() method.
close()
Event.close() releases all resources held by this instance.
void close()
It is important to always call close() on an instance of Event before it goes out of scope. Failing to close it can cause serious memory leaks because Java garbage collection cannot release resources allocated by native code.
createQuery()
Event.createQuery() takes a String argument containing the text of the SQL query and returns an instance of EventQuery<E>, where parameter E is the target class of the parent Event.
<E> EventQuery<E> createQuery (String sqlText)
parameter:
see also:
Creating and Executing a Query
deleteObject()
Event.deleteObject() deletes an event identified by its database object ID or IdKey.
void deleteObject(long id)
void deleteObject(Object[] idkeys)
parameter:
see also:
Accessing Stored Events
getObject()
Event.getObject() fetches an event identified by its database object ID or IdKey. Returns null if the specified object does not exist.
Object getObject(long id)
Object getObject(Object[] idkeys)
parameter:
see also:
Accessing Stored Events
isEvent()
Event.isEvent() throws an XEPException if the object (or class) is not an event in the XEP sense (see Requirements forImported Classes). The exception message will explain why the object is not an XEP event.
static void isEvent(Object objectOrClass)
parameter:
startIndexing()
Event.startIndexing() starts asynchronous index building for the extent of the target class. Throws an exception if the index mode is Event.INDEX_MODE_SYNC (see Controlling Index Updating).
void startIndexing()
stopIndexing()
Event.stopIndexing() stops asynchronous index building for the extent. If you do not want the index to be updated when the Event instance is closed, call this method before calling Event.close().
void stopIndexing()
see also:
Controlling Index Updating
store()
Event.store() stores a Java object or array of objects as persistent events. There is no significant performance difference between passing an array and passing individual objects in a loop, but all objects in the array must be of the same type. Returns a long database ID for each newly inserted object, or 0 if the ID could not be returned or the event uses an IdKey.
long store(Object object)
long[] store(Object[] objects)
parameters:
updateObject()
Event.updateObject() updates an event identified by its database ID or IdKey.
void updateObject(long id, Object object)
void updateObject(Object[] idkeys, Object object)
parameter:
see also:
Accessing Stored Events
waitForIndexing()
Event.waitForIndexing() waits for asynchronous indexing to be completed, returning true if indexing has been completed, or false if the wait timed out before indexing was completed. Throws an exception if the index mode is Event.INDEX_MODE_SYNC.
boolean waitForIndexing(int timeout)
parameter:
see also:
Controlling Index Updating
Class EventQuery<>
Class com.intersys.xep.EventQuery<> can be used to retrieve, update and delete individual events from the database.
close()
EventQuery<>.close() releases all resources held by this instance.
void close()
It is important to always call close() on an instance of EventQuery<> before it goes out of scope. Failing to close it can cause serious memory leaks because Java garbage collection cannot release resources allocated by native code.
deleteCurrent()
EventQuery<>.deleteCurrent() deletes the event most recently fetched by getNext().
void deleteCurrent()
see also:
Processing Query Data
execute()
EventQuery<>.execute() executes the SQL query associated with this EventQuery<>. If the query is successful, this EventQuery<> will contain a resultset that can be accessed by other EventQuery<> or EventQueryIterator<> methods.
void execute()
see also:
Creating and Executing a Query
getAll()
EventQuery<>.getAll() returns objects of target class E from all rows in the resultset as a single list.
java.util.List<E> getAll()
Uses getNext() to get all target class E objects in the resultset, and returns them in a List. The list cannot be used for updating or deleting (although Event methods updateObject() and deleteObject() can be used if you have some way of obtaining the Id or IdKey of each object). getAll() and getNext() cannot access the same resultset — once either method has been called, the other method cannot be used until execute() is called again.
see also:
Processing Query Data, Event.updateObject(), Event.deleteObject()
getFetchLevel()
EventQuery<>.getFetchLevel() returns the current fetch level (see Defining the Fetch Level).
int getFetchLevel()
getIterator()
EventQuery<>.getIterator() returns an EventQueryIterator<> that can be used to iterate over query results (see Using EventQueryIterator<>).
EventQueryIterator<E> getIterator()
getNext()
EventQuery<>.getNext() returns an object of target class E from the resultset. It returns the first item in the resultset if the argument is null, or takes the object returned by the previous call to getNext() as an argument and returns the next item in the resultset. Returns null if there are no more items in the resultset.
E getNext(E obj)
parameter:
see also:
Processing Query Data
setFetchLevel()
EventQuery<>.setFetchLevel() controls the amount of data returned by setting a fetch level (see Defining the Fetch Level).
For example, by setting the fetch level to Event.FETCH_LEVEL_DATATYPES_ONLY, objects returned by this query will only have their datatype fields set, and any object type, array, or collection fields will not get populated. Using this option can dramatically improve query performance.
void setFetchLevel(int level)
parameter:
Supported fetch levels are:
setParameter()
EventQuery<>.setParameter() binds a parameter for the SQL query associated with this EventQuery<>.
void setParameter(int index, java.lang.Object value)
parameters:
see also:
Creating and Executing a Query
updateCurrent()
EventQuery<>.updateCurrent() updates the event most recently fetched by getNext().
void updateCurrent(E obj)
parameter:
see also:
Processing Query Data
Class EventQueryIterator<>
Class com.intersys.xep.EventQueryIterator<> is an alternative way of retrieving, updating and deleting XEP events (the same task can be also achieved by direct use of EventQuery<> methods).
hasNext()
EventQueryIterator<>.hasNext() returns true if the query resultset has more items.
boolean hasNext()
next()
EventQueryIterator<>.next() fetches the next event in the query resultset.
E next()
remove()
EventQueryIterator<>.remove() deletes the last event fetched by next().
void remove()
set()
EventQueryIterator<>.set() replaces the last event fetched by next().
void set(E obj)
parameter:
Interface InterfaceResolver
By default, fields declared as interfaces are ignored during schema generation. To change this behavior, an implementation of InterfaceResolver can be passed to the importSchema() method, providing it with information that allows it to replace an interface type with the correct concrete type.
getImplementationClass()
InterfaceResolver.getImplementationClass() returns the actual type of a field declared as an interface. See Implementing an InterfaceResolver for details.
Class<?>  getImplementationClass (Class declaringClass, String fieldName, Class<?> interfaceClass) 
parameters:
Class XEPException
Class com.intersys.xep.XEPException implements the exception thrown by most methods of Event, EventPersister, and EventQuery<>. This class inherits from java.lang.RuntimeException.
Constructors
  XEPException (String message) 
  XEPException (Throwable x, String message) 
  XEPException (Throwable x) 
Globals Quick Reference
This section is a reference for the Globals API (namespace com.intersys.globals). See Using the Globals API for a details on how to use the API. It contains the following public classes and interfaces:
Namespace com.intersys.globals:
List of Globals API Methods
The following classes and methods of the Globals API are described in this reference:
Class ConnectionContext
Interface Connection
Interface GlobalsDirectory
Interface NodeReference
Also see Acquiring and Releasing Locks in the chapter on Using the Globals API for a list of valid arguments used by the acquireLock() and releaseLock(). See Controlling the Timeout Interval for more on the arguments used by setOption(), and getOption().
Interface ValueList
Class ByteArrayRegion
Globals Exception Classes
Globals Implementation Classes
Class ConnectionContext
Class com.intersys.globals.ConnectionContext is required to create a Globals API Connection object. See the section on Creating a Connection in Using the Globals API for information on usage. See the Caché JavaDoc (<install-dir>/dev/java/doc/index.html) for more details on connection options.
getConnection()
ConnectionContext.getConnection() creates an instance of com.intersys.globals.Connection.
static synchronized Connection getConnection()
Interface Connection
Interface com.intersys.globals.Connection represents a connection to the Caché database. Instances of Connection are created by calls to the getConnection() method of class ConnectionContext. All instances of Connection in a process reference the same underlying connection. Use Connection.isConnected() to determine if the underlying connection already exists. See Creating a Connection in the Globals API chapter for more information on how connections work.
callBytesClassMethod()
Connection.callBytesClassMethod() — calls a Caché ObjectScript class method and returns an Object that may be of type int, long, double, or byte[].
This method is identical to callClassMethod() except that it returns string values as instances of byte[] rather than String.
Object callBytesClassMethod(String className, String methodName, Object... args)
parameters:
callBytesFunction()
Connection.callBytesFunction() calls a Caché ObjectScript function (see User-defined Code in Using Caché ObjectScript) and returns an Object that may be of type int, long, double, or byte[].
This method is identical to callFunction() except that it returns string values as instances of byte[] rather than String.
Object callBytesFunction(String functionName, String routineName, Object... args)
parameters:
callClassMethod()
Connection.callClassMethod() — calls a Caché ObjectScript class method and returns an Object that may be of type int, long, double, or String. Use callVoidClassMethod() to call a method that doesn’t return a value, callBytesClassMethod() to return string values as byte[], or callListClassMethod() to return string values as ValueList.
Object callClassMethod(String className, String methodName, Object... args)
parameters:
callFunction()
Connection.callFunction() — calls a Caché ObjectScript function (see User-defined Code in Using Caché ObjectScript) and returns an Object that may be of type int, long, double, or String. Use callBytesFunction() to return string values as byte[], or callListFunction() to return string values as ValueList.
Object callFunction(String functionName, String routineName, Object... args)
parameters:
callListClassMethod()
Connection.callListClassMethod() — calls a Caché ObjectScript class method and returns an Object that may be of type int, long, double, or ValueList.
This method is identical to callClassMethod() except that it returns string values as instances of ValueList rather than String.
Object CallListClassMethod(string className, string methodName, params Object[] args)
Throws an exception if the return value is a string but is not in valid ValueList format.
parameters:
callListFunction()
Connection.callListFunction() calls a Caché ObjectScript function (see User-defined Code in Using Caché ObjectScript) and returns an Object that may be of type int, long, double, or ValueList.
This method is identical to callFunction() except that it returns string values as instances of ValueList rather than String.
Object CallListFunction(string functionName, string routineName, params Object[] args)
Throws an exception if the return value is a string but is not in valid ValueList format.
parameters:
callProcedure()
Connection.callProcedure() calls a Caché ObjectScript procedure (see User-defined Code in Using Caché ObjectScript).
void callProcedure(String procedureName, String routineName, Object... args)
parameters:
callVoidClassMethod()
Connection.callVoidClassMethod() — calls a Caché ObjectScript class method with no return value, passing 0 or more arguments. This method may be used to call any Caché class method (regardless of whether it normally returns a value) when the caller does not need the return value. Use callClassMethod() to call a method that returns a value.
void callVoidClassMethod(String className, String methodName, Object... args)
parameters:
close()
Connection.close() releases all resources held by this instance.
void close()
It is important to always call close() on an instance of Connection before it goes out of scope. Failing to close it can cause serious memory leaks because Java garbage collection cannot release resources allocated by native code.
commit()
Connection.commit() commits one level of transaction (see transactionLevel()) for the current session.
void commit()
If the level is greater than 1, the current transaction is merged with the enclosing transaction, and can still be rolled back by calling rollback(). When the transaction level is 1, any changes made during the transaction are permanently commited.
connect()
Connection.connect() connects the Connection object to the specified database. GlobalsException is thrown if the object is already connected.
void connect()
void connect(String namespace, String user, String password)
parameters:
If no arguments are specified, method call defaults to connect("User","",""). This method uses the GLOBALS_HOME environment variable to locate the Caché instance (see Required Environment Variables for All Platforms).
createGlobalsDirectory()
Connection.createGlobalsDirectory() creates a browsable directory of the global names in the current namespace, with the cursor positioned before the first global name in collating sequence.
GlobalsDirectory createGlobalsDirectory()
createList()
Connection.createList() returns a ValueList object, and optionally specifies a buffer size.
ValueList createList()
ValueList createList(int bufferSize)
parameter:
If bufferSize is not specified, the ValueList is created with a 1 kbyte buffer, which grows if needed but never gets smaller. Specifying a smaller bufferSize may save memory if a list is known to need significantly less than 1 kbyte. Specifying a larger bufferSize may enhance performance by avoiding repeated reallocation to grow the buffer, if a list is known to need significantly more than 1 kbytes.
createNodeReference()
Connection.createNodeReference() returns a NodeReference object, and optionally specifies the name of the global to be referenced.
NodeReference createNodeReference()
NodeReference createNodeReference(String name)
parameter:
If name is not specified, the node reference object's setName() method must be called in order to specify a global array (see Setting and Changing Global Names).
getNamespace()
Connection.getNamespace() returns the name of the currently connected namespace.
String getNamespace()
Throws GlobalsException if called when this instance is not connected.
getProductVersion()
Connection.getProductVersion() returns the version number of the connected Caché instance.
String getProductVersion()
isConnected()
Connection.isConnected() returns true if this object is connected to a database.
boolean isConnected()
releaseAllLocks()
Connection.releaseAllLocks() releases all locks currently held in this connection
void releaseAllLocks()
see also: Transactions and Locking
rollback()
Connection.rollback() rolls back levelCount levels of transaction, or roll back all levels of transaction if levelCount is not specified.
void rollback()
void rollback(int levelCount)
parameter:
Stops rolling back once transaction level reaches 0, if levelCount is greater than initial transaction level. Does nothing if levelCount is less than 1.
see also: Transactions and Locking
setNamespace()
Connection.setNamespace() sets the current namespace
void setNamespace(String namespace)
parameter:
startTransaction()
Connection.startTransaction() starts a transaction (which may be a nested transaction).
void startTransaction()
see also: Transactions and Locking
transactionLevel()
Connection.transactionLevel() returns an int that indicates current transaction level (0 if not in a transaction).
int transactionLevel()
see also: Transactions and Locking
Interface GlobalsDirectory
Interface com.intersys.globals.GlobalsDirectory represents a browsable directory of the names of globals in the current namespace. Global names may be browsed in ascending or descending collating sequence. These names may be passed to Connection.createNodeReference(String) to create instances of NodeReference that can be used to perform operations on globals.
Instances of GlobalsDirectory are created by calling the Connection.createGlobalsDirectory() method, or by using the GlobalsDirectoryImpl constructor.
close()
GlobalsDirectory.close() releases all resources held by this instance.
void close()
It is important to always call close() on an instance of GlobalsDirectory before it goes out of scope. Failing to close it can cause serious memory leaks because Java garbage collection cannot release resources allocated by native code.
nextGlobalName()
GlobalsDirectory.nextGlobalName() returns the next global name in collating sequence after the specified name (or after the current position if no global name is specified). Returns an empty string if there is no next name.
String nextGlobalName()
String nextGlobalName(String globalName)
parameter:
previousGlobalName()
GlobalsDirectory.previousGlobalName() returns the previous global name in collating sequence before the specified name (or before the current position if no global name is specified). Returns an empty string if there is no previous name.
String previousGlobalName()
String previousGlobalName(String globalName)
parameter:
refresh
GlobalsDirectory.refresh() updates the list of global names, adding or deleting names to reflect any changes made since the instance was created or refresh() was last called.
void refresh()
Interface NodeReference
Interface com.intersys.globals.NodeReference represents a reference to a global node. It provides methods for specifying the node's name and subscripts, as well as methods to manipulate the node, including setting and getting its value, killing it, determining its state, and incrementing its value.
Instances of NodeReference are created by calls to the Connection createNodeReference() method. See the chapter on Using the Globals API for information on usage.
acquireLock()
NodeReference.acquireLock() locks an object, using the specified locking arguments.
void acquireLock(int lockType, int lockMode)
void acquireLock(int lockType, int lockMode, Object... subscripts)
parameters:
see also: Transactions and Locking
appendSubscript()
NodeReference.appendSubscript() adds a new subscript at the end of the subscript list of a node reference object.
void appendSubscript(int sub)
void appendSubscript(long sub)
void appendSubscript(double sub)
void appendSubscript(String sub)
parameter:
For example, the method could add subscript "a" to ^myGlobal(1), changing the reference to ^myGlobal(1,"a").
close()
NodeReference.close() releases all resources held by this instance.
void close()
It is important to always call close() on an instance of NodeReference before it goes out of scope. Failing to close it can cause serious memory leaks because Java garbage collection cannot release resources allocated by native code.
exists()
Deprecated: replaced by hasData().
NodeReference.exists() returns true if the node has data. Returns false if the node is valueless or does not exist.
boolean exists()
boolean exists(Object... subscripts)
parameter:
getBytes()
NodeReference.getInt() returns the value of this node as a byte[]. A null is returned if the referenced node is valueless or does not exist.
byte[] getBytes()
byte[] getBytes(Object... subscripts)
parameter:
getDouble()
NodeReference.getDouble() returns the value of this node as a double. This method should never be used if the node value might be a String.
double getDouble()
double getDouble(Object... subscripts)
parameter:
String values are not converted even if they are numeric. The method will attempt to interpret the string as a valid double, and will return a meaningless and unpredictable value.
Throws UndefinedException if the referenced node is valueless or does not exist.
getDoubleSubscript()
NodeReference.getDoubleSubscript() reads the subscript specified by subscriptPosition and returns it as a double value.
double getDoubleSubscript(int subscriptPosition)
parameter:
Throws GlobalsException if subscriptPosition is greater than the current number of subscripts, or if the subscript is the wrong datatype.
getInt()
NodeReference.getInt() returns the value of this node as an int.
int getInt()
int getInt(Object... subscripts)
parameter:
If the node value was originally set as a double, the returned value will be truncated to a long value. If the node value is a non-numeric string (one that does not start with +, -, or a digit), a 0 will be returned.
Throws UndefinedException if the referenced node is valueless or does not exist.
getIntSubscript()
NodeReference.getIntSubscript() reads the subscript specified by subscriptPosition and returns it as an int value.
int getIntSubscript(int subscriptPosition)
parameter:
Throws GlobalsException if subscriptPosition is greater than the current number of subscripts, or if the subscript is the wrong datatype.
getList()
NodeReference.getList() returns the value of this node as a ValueList. A null is returned if the referenced node is valueless or does not exist.
ValueList getList()
ValueList getList(Object... subscripts)
ValueList getList(ValueList reuseList)
ValueList getList(ValueList reuseList, Object... subscripts)
parameter:
Throws GlobalsException if the value is not a string in valid $LIST format.
getLong()
NodeReference.getLong() returns the value of this node as a long.
long getLong()
long getLong(Object... subscripts)
parameter:
Throws UndefinedException if the referenced node is valueless or does not exist.
getLongSubscript()
NodeReference.getLongSubscript() reads the subscript specified by subscriptPosition and returns it as a long value.
long getLongSubscript(int subscriptPosition)
parameter:
Throws GlobalsException if subscriptPosition is greater than the current number of subscripts, or if the subscript is the wrong datatype (int values are permitted).
getName()
NodeReference.getName() returns the name of the global array containing this node.
String getName()
getObject()
NodeReference.getObject() returns the node value as an Object, which will be an instance of int, long, double, or String (instances of byte[] and ValueList are returned as instances of String). Returns null if the node is valueless.
Object getObject()
Object getObject(Object... subscripts)
parameter:
getObjectSubscript()
NodeReference.getObjectSubscript() returns the subscript specified by subscriptPosition as an Object, which will be an instance of int, long, double, or String.
Object getObjectSubscript(int subscriptPosition)
Throws GlobalsException if subscriptPosition is greater than current number of subscripts.
getOption()
NodeReference.getOption() returns the current lock timeout setting (see setOption()).
int getOption(int option)
parameter:
see also: Transactions and Locking
getString()
NodeReference.getString() returns the value of this node as a String. A null is returned if the referenced node is valueless or does not exist.
String getString()
String getString(Object... subscripts)
parameter:
Any global value can be accessed as a string, although the string may be meaningless or misleading in the context of your application. For example, if a node is set to a double value of 19.95, the string returned by this method will be 19.949999999999999289, which is the internal representation of the double.
getStringSubscript()
NodeReference.getStringSubscript() reads the subscript specified by subscriptPosition and returns it as a String value.
String getStringSubscript(int subscriptPosition)
parameter:
Throws GlobalsException if subscriptPosition is greater than the current number of subscripts, or if the subscript is the wrong datatype.
getSubscriptCount()
NodeReference.getSubscriptCount() returns an int that indicates the current number of subscripts
int getSubscriptCount()
For example, if the node reference points to ^myGlobal(1,"a"), the method returns 2.
hasData()
NodeReference.hasData() returns true if the node has data. Returns false if the node is valueless or does not exist.
boolean hasData()
boolean hasData(Object... subscripts)
parameter:
hasSubnodes()
NodeReference.hasSubnodes() returns true if the referenced node has descendants.
boolean hasSubnodes()
boolean hasSubnodes(Object... subscripts)
parameter:
increment()
NodeReference.increment() increments or decrements the value of the current node by the specified int value, and returns the new value as a long. If the incremented node value is a double, the returned value will be truncated. This is an atomic operation (lock-free, thread-safe).
long increment(int number)
long increment(int number, Object... subscripts)
parameter:
If no node exists at the current reference, a node with a value of 0 is created and incremented.
kill()
NodeReference.kill() deletes the node at the current node reference and all of its descendants.
void kill()
void kill(Object... subscripts)
parameter:
This method is equivalent to the Caché KILL command.
killNode()
NodeReference.killNode() deletes the value of the node at the current node reference, but does not affect its subnodes. If the node does not have subnodes, it is deleted from the database.
void killNode()
void killNode(Object... subscripts)
parameter:
This method is equivalent to the Caché ZKILL command.
nextSubscript()
NodeReference.nextSubscript() returns a String containing the subscript of the next node in collation order on the current level. Returns an empty string ("") if there is no next subscript.
String nextSubscript()
String nextSubscript(Object... subscripts)
parameter:
previousSubscript()
NodeReference.previousSubscript() returns a String containing the subscript of the previous node in collation order on the current level. Returns an empty string ("") if there is no previous subscript.
String previousSubscript()
String previousSubscript(Object... subscripts)
parameter:
releaseLock()
NodeReference.releaseLock() releases the lock on the current node.
void releaseLock(int lockType, int releaseMode)
void releaseLock(int lockType, int releaseMode, Object... subscripts)
parameter:
see also: Transactions and Locking, Connection.releaseAllLocks()
set()
NodeReference.set() assigns the specified value to the referenced node.
void set(int value)
void set(int value, Object... subscripts)
void set(long value)
void set(long value, Object... subscripts)
void set(double value)
void set(double value, Object... subscripts)
void set(String value)
void set(String value, Object... subscripts)
void set(byte[] value)
void set(byte[] value, Object... subscripts)
void set(ValueList value)
void set(ValueList value, Object... subscripts)
parameter:
If no persistent node exists at the current reference, a new one is created and set to the specified value.
setName()
NodeReference.setName() specifies the name of the global to be referenced by this node object.
void setName(String name)
parameter:
setOption()
NodeReference.setOption() sets the number of seconds that acquireLock() should wait for a lock before timing out. Other options will be added in future releases.
void setOption(int option, int value)
parameter:
setSubscript()
NodeReference.setSubscript() changes the specified subscript, or adds a new subscript.
void setSubscript(int subscriptPosition, double value)
void setSubscript(int subscriptPosition, int value)
void setSubscript(int subscriptPosition, long value)
void setSubscript(int subscriptPosition, String value)
parameter:
For example, if the node reference pointed to ^myGlobal(1,"a"), a call to setSubscript(1,8) would set the reference to ^myGlobal(8,"a").
This method is equivalent to appendSubscript() if subscriptPosition is equal to getSubscriptCount()+1. For example, a call to setSubscript(3,"x") would set it to ^myGlobal(1,"a","x").
If subscriptPosition is less than 1, a value of 1 will be used.
Throws GlobalsException if subscriptPosition is greater than getSubscriptCount()+1.
setSubscriptCount()
NodeReference.setSubscriptCount() shortens the subscript list by removing all subscripts after the one specified by num.
void setSubscriptCount(int num)
parameter:
For example, if the reference points to ^myGlobal(1,"a",35), calling setSubscriptCount(1) would remove all subscripts except the first, changing the reference to ^myGlobal(1).
Throws GlobalsException if num is greater than the current number of subscripts.
Interface ValueList
Interface com.intersys.globals.ValueList encapsulates a Java representation of a simple Caché $LIST object. The following datatypes are supported: int, int, long, long, double, double, String, byte[], and nested instances of ValueList. See Storing Multiple Items in a Node with ValueList for information on usage.ValueList objects are created by calling the Connection.createList() method, or by using ValueListImpl constructors.
append()
ValueList.append() appends a value of the specified datatype to the list.
void append(byte[] value)
void append(int value)
void append(Integer value)
void append(long value)
void append(Long value)
void append(double value)
void append(Double value)
void append(String value)
void append(ValueList value)
Multiple values can be specified in a single call to append():
void append(Object... objects)
parameter:
Throws GlobalsException if the argument is an invalid datatype.
clear()
ValueList.clear() clears the list, causing it to contain 0 items.
void clear()
Throws GlobalsException.
close()
ValueList.close() releases all resources held by this instance.
void close()
It is important to always call close() on an instance of ValueList before it goes out of scope. Failing to close it can cause serious memory leaks because Java garbage collection cannot release resources allocated by native code.
Throws GlobalsException if the instance of ValueList calls any other method after this one.
getAll()
ValueList.getAll() returns all items from the list as an array of Object, or returns null if the list is empty. Each returned Object is an instance of int, long, double, String, or byte[], depending on the type and value of the item in the list. An Object is null if the corresponding list item is null. This method leaves the list cursor positioned beyond last item in the list.
Object[] getAll()
Object[] getAll(boolean returnBytes)
parameter:
Throws GlobalsException.
getNextBytes()
ValueList.getNextBytes() returns the next item from the list as byte[]. Returns null if list item is null.
byte[] getNextBytes()
Throws GlobalsException if the cursor is already at the end of the list.
getNextDouble()
ValueList.getNextDouble() returns the next item from the list as a double. Returns 0 if list item is null.
double getNextDouble()
Throws GlobalsException if the cursor is already at the end of the list.
getNextInt()
ValueList.getNextInt() returns the next item from the list as an int. Returns 0 if list item is null.
int getNextInt()
Throws GlobalsException if the cursor is already at the end of the list.
getNextList()
ValueList.getNextList() returns the next item from the list as a ValueList. Returns null if list item is null.
ValueList getNextList()
ValueList getNextList(ValueList reuseList)
parameter:
Throws GlobalsException if the cursor is already at the end of the list, or if the list item is not a valid ValueList.
getNextLong()
ValueList.getNextLong() returns the next item from the list as a long. Returns 0 if list item is null.
long getNextLong()
Throws GlobalsException if the cursor is already at the end of the list.
getNextObject()
ValueList.getNextObject() returns the next item from the list as an Object. The type of the returned object depends on the type and value of the item in the list, and on the setting of the optional returnBytes parameter.
A null is returned if the list item is null. All integer values are returned as int if they are within the range of int, else they are returned as long. Double values are always returned as double. If optional returnBytes is specified as true, both byte[] and String are returned as byte[]. If it is false or not specified, both types are returned as String.
Object getNextObject()
Object getNextObject(boolean returnBytes)
parameter:
Throws GlobalsException if the cursor is already at the end of the list.
getNextString()
ValueList.getNextString() returns the next item from the list as a String. Returns null if list item is null.
String getNextString()
Throws GlobalsException if the cursor is already at the end of the list.
length()
ValueList.length() returns the number of items in the list.
int length()
Throws GlobalsException.
resetToFirst()
ValueList.resetToFirst() resets the cursor to the beginning of the list.
void resetToFirst()
Throws GlobalsException.
skipNext()
ValueList.skipNext() advances the cursor past the number of list items specified by count without getting their values.
void skipNext(int count)
parameter:
Throws GlobalsException if fewer than count items remain in the list beyond the cursor position.
Class ByteArrayRegion
Class com.intersys.globals.ByteArrayRegion specifies a region of a byte array, encapsulating the source array, the starting offset, and the length of the region. This class provides a convenient and efficient way to pass a byte array region as an argument to the Connection methods that call ObjectScript methods and functions (see Calling Caché Methods) without having to copy the region to a separate byte[] instance.
ByteArrayRegion() Constructors
Create a new instance of ByteArrayRegion. Can optionally specify the source array, offset, and number of bytes in the region.
ByteArrayRegion() 
ByteArrayRegion(byte[] sourceArray, int offset, int length)
parameters:
getLength()
ByteArrayRegion.getLength() returns the number of bytes in the specified region.
int getLength()
getOffset()
ByteArrayRegion.getOffset() returns the starting offset of the region within the source array.
int getOffset()
getSourceArray()
ByteArrayRegion.getSourceArray() returns the source array containing the region.
byte[] getSourceArray()
set()
ByteArrayRegion.set() defines all attributes of the region.
void set(byte[] sourceArray, int offset, int length)
parameter:
setLength()
ByteArrayRegion.setLength() sets the number of bytes to be included in the region.
void setLength(int length)
parameter:
setOffset()
ByteArrayRegion.setOffset() sets the starting offset of the region within the source array.
void setOffset(int offset)
parameter:
setSourceArray()
ByteArrayRegion.setSourceArray() sets the source array containing the region.
void setSourceArray(byte[] sourceArray)
parameter:
Globals Exception Classes
The Globals API implements the following exceptions:
Class GlobalsException
Class com.intersys.globals.GlobalsException implements an exception thrown by all classes of the Globals API. This class inherits from java.lang.RuntimeException.
Constructors
In addition to the parameters defined for RuntimeException constructors, the GlobalsException constructors provide an error code parameter for errors specific to the Globals API:
GlobalsException(String msg)
GlobalsException(String msg, int code)
GlobalsException(Throwable cause)
GlobalsException(Throwable cause, String msg)
parameters:
Method getErrorCode()
Returns a numeric error code that can be used to distinguish some specific Globals API errors. Error code UNDEFINED means that no specific error code is defined for this situation.
int getErrorCode()
The following error codes are defined:
Class LockException
Class com.intersys.globals.LockException implements an exception thrown by NodeReference method acquireLock(). It is thrown if a request to acquire a lock fails, due to timing out waiting for the lock to become available. See Transactions and Locking for information on usage.
Constructors
  LockException()
  LockException(String msg)
parameters:
This class inherits the methods and constants defined in GlobalsException.
Class UndefinedException
Class com.intersys.globals.UndefinedException implements an exception thrown by methods that get the value of a node. The exception is thrown if the referenced node is valueless or does not exist.
Constructor
UndefinedException(String msg)
parameters:
This class inherits the methods and constants defined in GlobalsException.
Globals Implementation Classes
The following classes are implementations of the main Globals API interfaces. They all provide constructors, allowing them to be extended for special purposes:
Class ConnectionImpl
Class com.intersys.globals.imp.ConnectionImpl is an implementation of interface Connection. Extend this class to develop specialized connection types for APIs implemented using the Globals API. In addition to the methods listed for the interface, it provides the following constructor:
ConnectionImpl() Constructor
Creates a new instance of ConnectionImpl, whose underlying connection implementation is a singleton connection instance managed by ConnectionContext.
ConnectionImpl()
Class GlobalsDirectoryImpl
Class com.intersys.globals.imp.GlobalsDirectoryImpl is an implementation of interface GlobalsDirectory. In addition to the methods listed for the interface, it provides the following constructor:
GlobalsDirectoryImpl() Constructor
Creates a directory of the global names in the current namespace, positioned before the first global name in collating sequence.
GlobalsDirectoryImpl()
Throws GlobalsException if there is no existing connection to the globals database.
Note:
The method ConnectionImpl.createGlobalsDirectory() creates a generic GlobalsDirectory instance. Developers extending this API may choose to override this method, or provide an additional ConnectionImpl method, to create instances of classes derived from GlobalsDirectory, or they may expose a public constructor for these derived classes, which calls the public constructor of GlobalsDirectoryImpl. Either way, an instance of Connection must have already been connected before creating an instance of GlobalsDirectoryImpl, or a GlobalsException is thrown.
Class NodeReferenceImpl
Class com.intersys.globals.imp.NodeReferenceImpl is an implementation of interface NodeReference. In addition to the methods listed for the interface, it provides the following constructors:
NodeReferenceImpl() Constructors
Creates a NodeReference instance.
NodeReferenceImpl()
NodeReferenceImpl(String name)
parameter:
Throws GlobalsException if there is no existing connection to the globals database.
Class ValueListImpl
Class com.intersys.globals.imp.ValueListImpl is an implementation of interface ValueList. In addition to the methods listed for the interface, it provides the following constructors:
ValueListImpl() Constructors
Creates an empty ValueListImpl instance, optionally specifying the initial buffer size.
ValueListImpl()
ValueListImpl(int bufferSize)
parameter:
The bufferSize parameter permits optional tuning of the amount of memory used for a list's underlying implementation. By default, a ValueList is created with a 1 kbyte buffer, which grows if needed but never gets smaller. Specifying a smaller bufferSize may save memory if a list is known to need significantly less than 1 kbytes. Specifying a larger bufferSize may enhance performance by avoiding repeated reallocation to grow the buffer, if a list is known to need significantly more than 1 kbytes.
Throws GlobalsException if there is no existing connection to the globals database.