Learning
Community
Open Exchange
Global Masters
InterSystems IRIS Data Platform 2019.4 / Application Development / Using the Native API for Java / Native API for Java Quick Reference
Previous section   

Native API for Java Quick Reference

This is a quick reference for the InterSystems IRIS Native API for Java, providing information on the following classes in com.intersystems.jdbc:
Note:
This chapter is intended as a convenience for readers of this book, but it is not the definitive reference for the Native API. For the most complete and up-to-date information, see the online class documentation.

Class IRIS

Class IRIS is a member of com.intersystems.jdbc.
Instances of IRIS are created by calling static method IRIS.createIRIS().

Method Details

classMethodBoolean()
jdbc.IRIS.classMethodBoolean() calls an ObjectScript class method, passing zero or more arguments and returning an instance of Boolean. See “Calling ObjectScript Methods and Functions” for details and examples.
final Boolean classMethodBoolean(String className, String methodName, Object... args )
parameters:
  • className — fully qualified name of the class to which the called method belongs.
  • methodName — name of the class method.
  • args — zero or more arguments of supported types.
classMethodBytes()
jdbc.IRIS.classMethodBytes() calls an ObjectScript class method, passing zero or more arguments and returning an instance of byte[]. See “Calling ObjectScript Methods and Functions” for details and examples.
final byte [] classMethodBytes (String className, String methodName, Object... args )
parameters:
  • className — fully qualified name of the class to which the called method belongs.
  • methodName — name of the class method.
  • args — zero or more arguments of supported types.
classMethodDouble()
jdbc.IRIS.classMethodDouble() calls an ObjectScript class method, passing zero or more arguments and returning an instance of Double. See “Calling ObjectScript Methods and Functions” for details and examples.
final Double classMethodDouble (String className, String methodName, Object... args )
parameters:
  • className — fully qualified name of the class to which the called method belongs.
  • methodName — name of the class method.
  • args — zero or more arguments of supported types.
classMethodLong()
jdbc.IRIS.classMethodLong() calls an ObjectScript class method, passing zero or more arguments and returning an instance of Long. See “Calling ObjectScript Methods and Functions” for details and examples.
final Long classMethodLong (String className, String methodName, Object... args )
parameters:
  • className — fully qualified name of the class to which the called method belongs.
  • methodName — name of the class method.
  • args — zero or more arguments of supported types.
classMethodObject()
jdbc.IRIS.classMethodObject() calls an ObjectScript class method, passing zero or more arguments and returning an instance of Object. If the returned object is a valid OREF (for example, if %New() was called), classMethodObject() will generate and return a reverse proxy object (an instance of IRISObject) for the referenced object. See “Using Java Reverse Proxy Objects” for details and examples.
final Object classMethodObject (String className, String methodName, Object... args)
parameters:
  • className — fully qualified name of the class to which the called method belongs.
  • methodName — name of the class method.
  • args — zero or more arguments of supported types.
classMethodStatusCode()
jdbc.IRIS.classMethodStatusCode() tests whether an ObjectScript class method would throw an error if called with the specified arguments. See “Calling ObjectScript Methods and Functions” for details and examples.
This is an indirect way to catch exceptions when using classMethod[type] calls. If the call would run without error, this method returns without doing anything, meaning that you can safely make the call with the specified arguments. If call would fail, it throws a RuntimeException error containing the ObjectScript error status number and message.
final void classMethodStatusCode(String className, String methodName, Object... args)
parameters:
  • className — fully qualified name of the class to which the called method belongs.
  • methodName — name of the class method.
  • args — zero or more arguments of supported types.
classMethodString()
jdbc.IRIS.classMethodString() calls an ObjectScript class method, passing zero or more arguments and returning an instance of String. See “Calling ObjectScript Methods and Functions” for details and examples.
final String classMethodString (String className, String methodName, Object... args )
parameters:
  • className — fully qualified name of the class to which the called method belongs.
  • methodName — name of the class method.
  • args — zero or more arguments of supported types.
classMethodVoid()
jdbc.IRIS.classMethodVoid() calls an ObjectScript class method with no return value, passing zero or more arguments. See “Calling ObjectScript Methods and Functions” for details and examples.
final void classMethodVoid (String className, String methodName, Object... args )
parameters:
  • className — fully qualified name of the class to which the called method belongs.
  • methodName — name of the class method.
  • args — zero or more arguments of supported types.
close()
jdbc.IRIS.close() closes the IRIS object.
final void close() throws Exception 
createIRIS()
jdbc.IRIS.createIRIS() returns an instance of jdbc.IRIS that uses the specified IRISConnection. See “Introduction to Global Arrays” for more information and examples.
static IRIS createIRIS(IRISConnection conn) throws SQLException
parameters:
functionBoolean()
jdbc.IRIS.functionBoolean() calls an ObjectScript function, passing zero or more arguments and returning an instance of Boolean. See “Calling ObjectScript Methods and Functions” for details and examples.
final Boolean functionBoolean(String functionName, String routineName, Object... args )
parameters:
  • functionName — name of the function to call.
  • routineName — name of the routine containing the function.
  • args — zero or more arguments of supported types.
functionBytes()
jdbc.IRIS.functionBytes() calls an ObjectScript function, passing zero or more arguments and returning an instance of byte[]. See “Calling ObjectScript Methods and Functions” for details and examples.
final byte [] functionBytes(String functionName, String routineName, Object... args )
parameters:
  • functionName — name of the function to call.
  • routineName — name of the routine containing the function.
  • args — zero or more arguments of supported types.
functionDouble()
jdbc.IRIS.functionDouble() calls an ObjectScript function, passing zero or more arguments and returning an instance of Double. See “Calling ObjectScript Methods and Functions” for details and examples.
final Double functionDouble (String functionName, String routineName, Object... args )
parameters:
  • functionName — name of the function to call.
  • routineName — name of the routine containing the function.
  • args — zero or more arguments of supported types.
functionLong()
jdbc.IRIS.functionLong() calls an ObjectScript function, passing zero or more arguments and returning an instance of Long. See “Calling ObjectScript Methods and Functions” for details and examples.
final Long functionLong (String functionName, String routineName, Object... args )
parameters:
  • functionName — name of the function to call.
  • routineName — name of the routine containing the function.
  • args — zero or more arguments of supported types.
functionObject()
jdbc.IRIS.functionObject() calls an ObjectScript function, passing zero or more arguments and returning an instance of Object. If the returned object is a valid OREF, functionObject() will generate and return a reverse proxy object (an instance of IRISObject) for the referenced object. See “Using Java Reverse Proxy Objects” for details and examples.
final Object functionObject(String functionName, String routineName, Object... args)
parameters:
  • functionName — name of the function to call.
  • routineName — name of the routine containing the function.
  • args — zero or more arguments of supported types.
functionString()
jdbc.IRIS.functionString() calls an ObjectScript function, passing zero or more arguments and returning an instance of String. See “Calling ObjectScript Methods and Functions” for details and examples.
final String functionString (String functionName, String routineName, Object... args )
parameters:
  • functionName — name of the function to call.
  • routineName — name of the routine containing the function.
  • args — zero or more arguments of supported types.
getAPIVersion()
jdbc.IRIS.getAPIVersion() returns the IRIS Native API version string.
static final String getAPIVersion()
getBoolean()
jdbc.IRIS.getBoolean() gets the value of the global as a Boolean (or null if node does not exist). Returns false if node value is empty string.
final Boolean  getBoolean (String globalName, Object...subscripts)
parameters:
  • globalName — global name.
  • subscripts — zero or more subscripts specifying the target node.
getBytes()
jdbc.IRIS.getBytes() gets the value of the global as a byte[] (or null if node does not exist).
final byte[]  getBytes (String globalName, Object...subscripts)
parameters:
  • globalName — global name.
  • subscripts — zero or more subscripts specifying the target node.
getDate()
jdbc.IRIS.getDate() gets the value of the global as a java.sql.Date (or null if node does not exist).
final java.sql.Date  getDate (String globalName, Object...subscripts)
parameters:
  • globalName — global name.
  • subscripts — zero or more subscripts specifying the target node.
getDouble()
jdbc.IRIS.getDouble() gets the value of the global as a Double (or null if node does not exist). Returns 0.0 if node value is empty string.
final Double  getDouble (String globalName, Object...subscripts)
parameters:
  • globalName — global name.
  • subscripts — zero or more subscripts specifying the target node.
getFloat()
jdbc.IRIS.getFloat() gets the value of the global as a Float (or null if node does not exist). Returns 0.0 if node value is empty string.
final Float  getFloat (String globalName, Object...subscripts)
parameters:
  • globalName — global name.
  • subscripts — zero or more subscripts specifying the target node.
getInputStream()
jdbc.IRIS.getInputStream() gets the value of the global as a java.io.InputStream (or null if node does not exist).
final InputStream  getInputStream (String globalName, Object...subscripts)
parameters:
  • globalName — global name.
  • subscripts — zero or more subscripts specifying the target node.
getInstanceProperty()
jdbc.IRIS.getInstanceProperty() gets the value of the specified instance property as an Object (also see IRISObject method get()). See “Using Java Reverse Proxy Objects” for details and examples.
public final Object getInstanceProperty(IRISObject instance, String propertyName)
parameters:
  • instance — the IRISObject instance to be accessed.
  • propertyName — name of the instance property.
getInteger()
jdbc.IRIS.getInteger() gets the value of the global as an Integer (or null if node does not exist). Returns 0 if node value is empty string.
final Integer  getInteger (String globalName, Object...subscripts)
parameters:
  • globalName — global name.
  • subscripts — zero or more subscripts specifying the target node.
getIRISIterator()
jdbc.IRIS.getIRISIterator() returns an IRISIterator object (see “Class IRISIterator”) for the specified node. See “Iterating Over a Set of Child Nodes” for more information and examples.
final IRISIterator getIRISIterator(String globalName, Object... subscripts)
final IRISIterator getIRISIterator(int  prefetchSizeHint, String globalName, Object... subscripts)
parameters:
  • prefetchSizeHint — (optional) hints number of bytes to fetch when getting data from server.
  • globalName — global name.
  • subscripts — zero or more subscripts specifying the target node.
getLong()
jdbc.IRIS.getLong() gets the value of the global as a Long (or null if node does not exist). Returns 0 if node value is empty string.
final Long  getLong (String globalName, Object...subscripts)
parameters:
  • globalName — global name.
  • subscripts — zero or more subscripts specifying the target node.
getObject()
jdbc.IRIS.getObject() gets the value of the global as an Object (or null if node does not exist).
final Object getObject (String globalName, String... subscripts )
parameters:
  • globalName — global name.
  • subscripts — zero or more subscripts specifying the target node.
getReader()
jdbc.IRIS.getReader() gets the value of the global as a java.io.Reader (or null if node does not exist).
final Reader getReader (String globalName, String... subscripts )
parameters:
  • globalName — global name.
  • subscripts — zero or more subscripts specifying the target node.
getServerVersion()
jdbc.IRIS.getServerVersion() returns the server version string for the current connection. This is equivalent to calling $system.Version.GetVersion() in ObjectScript.
final String getServerVersion()
getShort()
jdbc.IRIS.getShort() gets the value of the global as a Short (or null if node does not exist). Returns 0.0 if node value is an empty string.
final Short getShort (String globalName, String... subscripts )
parameters:
  • globalName — global name.
  • subscripts — zero or more subscripts specifying the target node.
getString()
jdbc.IRIS.getString() gets the value of the global as a String (or null if node does not exist).
Empty string and null values require some translation. An empty string "" in Java is translated to the null string character $CHAR(0) in ObjectScript. A null in Java is translated to the empty string in ObjectScript. This translation is consistent with the way JDBC handles these values.
final String getString (String globalName, String... subscripts )
parameters:
  • globalName — global name.
  • subscripts — zero or more subscripts specifying the target node.
getTime()
jdbc.IRIS.getTime() gets the value of the global as a java.sql.Time (or null if node does not exist).
final java.sql.Time getTime (String globalName, String... subscripts )
parameters:
  • globalName — global name.
  • subscripts — zero or more subscripts specifying the target node.
getTimestamp()
jdbc.IRIS.getTimestamp() gets the value of the global as a java.sql.Timestamp (or null if node does not exist).
final java.sql.Timestamp  getTimestamp (String globalName, Object...subscripts)
parameters:
  • globalName — global name.
  • subscripts — zero or more subscripts specifying the target node.
getTLevel()
jdbc.IRIS.getTLevel() gets the level of the current nested transaction. Returns 1 if there is only a single transaction open. Returns 0 if there are no transactions open. This is equivalent to fetching the value of the $TLEVEL special variable. See “Transactions and Locking” for more information and examples.
final Integer getTLevel ( )
increment()
jdbc.IRIS.increment() increments the specified global with the passed value. If there is no node at the specified address, a new node is created with value as the value. A null value is interpreted as 0. Returns the new value of the global node. See “Creating, Updating, and Deleting Nodes” for more information.
final long increment (Integer value, String globalName, String... subscripts )
parameters:
  • valueInteger value to which to set this node (null value sets global to 0).
  • globalName — global name.
  • subscripts — zero or more subscripts specifying the target node.
instanceMethodObject()
jdbc.IRIS.instanceMethodObject() invokes an instance method of the proxy object, returning the value as Object. See “Using Java Reverse Proxy Objects” for details and examples.
final Object instanceMethodObject(IRISObject instance, String methodName, Object... args)
parameters:
  • instance — the IRISObject instance to be used.
  • methodName — name of the instance method.
  • args — zero or more arguments of supported types.
instanceMethodVoid()
jdbc.IRIS.instanceMethodVoid() invokes an instance method of the proxy object, but does not return a value. See “Using Java Reverse Proxy Objects” for details and examples.
final void instanceMethodVoid(IRISObject instance, String methodName, Object... args)
parameters:
  • instance — the IRISObject instance to be used.
  • methodName — name of the instance method.
  • args — zero or more arguments of supported types.
isDefined()
jdbc.IRIS.isDefined() returns a value indicating whether the specified node exists and if it contains a value. See “Finding Subnodes on All Levels” for more information and examples.
final int isDefined (String globalName, String... subscripts )
parameters:
  • globalName — global name.
  • subscripts — zero or more subscripts specifying the target node.
return values:
  • 0 — the specified node does not exist
  • 1 — the node exists and has a value
  • 10 — the node is valueless but has subnodes
  • 11 — the node has both a value and subnodes
kill()
jdbc.IRIS.kill() deletes the global node including any descendants. See “Creating, Updating, and Deleting Nodes” for more information and examples.
final void kill (String globalName, String... subscripts )
parameters:
  • globalName — global name.
  • subscripts — zero or more subscripts specifying the target node.
lock()
jdbc.IRIS.lock() locks the global, returns true on success. Note that this method performs an incremental lock and not the implicit unlock before lock feature that is also offered in ObjectScript. See “Transactions and Locking” for more information and examples.
final boolean lock (String lockMode, Integer timeout, String globalName, String... subscripts )
parameters:
  • lockMode — character S for shared lock, E for escalating lock, or SE for both. Default is empty string (exclusive and non-escalating).
  • timeout — amount to wait to acquire the lock in seconds.
  • globalName — global name.
  • subscripts — zero or more subscripts specifying the target node.
procedure()
jdbc.IRIS.procedure() calls a procedure, passing zero or more arguments. Does not return a value. See “Calling ObjectScript Methods and Functions” for more information and examples.
final void procedure (String procedureName, String routineName, Object... args )
parameters:
  • procedureName — name of the procedure to call.
  • routineName — name of the routine containing the procedure.
  • args — zero or more arguments of supported types.
releaseAllLocks()
jdbc.IRIS.releaseAllLocks() releases all locks associated with the session. See “Transactions and Locking” for more information and examples.
final void releaseAllLocks ( )
set()
jdbc.IRIS.set() sets the current node to a value of a supported datatype (or "" if the value is null). If there is no node at the specified node address, a new node will be created with the specified value. See “Creating, Updating, and Deleting Nodes” for more information.
final void set (Boolean value, String globalName, String... subscripts )
final void set (Short value, String globalName, String... subscripts )
final void set (Integer value, String globalName, String... subscripts )
final void set (Long value, String globalName, String... subscripts )
final void set (Double value, String globalName, String... subscripts )
final void set (Float value, String globalName, String... subscripts )
final void set (String value, String globalName, String... subscripts )
final void set (byte[] value, String globalName, String... subscripts )

final void set (java.sql.Date value, String globalName, String... subscripts )
final void set (java.sql.Time value, String globalName, String... subscripts )
final void set (java.sql.Timestamp value, String globalName, String... subscripts )
final void set (java.io.InputStream value, String globalName, String... subscripts )
final void set (java.io.Reader value, String globalName, String... subscripts )
final void set (Object value, String globalName, String... subscripts )
final<T extends Serializable> void set (T value, String globalName, String... subscripts )

parameters:
  • value — value of a supported datatype (null value sets global to "").
  • globalName — global name.
  • subscripts — zero or more subscripts specifying the target node.
Notes on specific datatypes
The following datatypes have some extra features:
  • String — empty string and null values require some translation. An empty string "" in Java is translated to the null string character $CHAR(0) in ObjectScript. A null in Java is translated to the empty string in ObjectScript. This translation is consistent with the way Java handles these values.
  • java.io.InputStream — currently limited to the maximum size of a single global node.
  • java.io.Reader — currently limited to the maximum size of a single global node.
  • java.io.Serializable — value can be set to an instance of an object that implements java.io.Serializable. The Java object will be serialized prior to being set as the global value. Use getObject() to retrieve the value.
setInstanceProperty()
jdbc.IRIS.setInstanceProperty() sets a property of the proxy object. Also see IRISObject method set(). See “Using Java Reverse Proxy Objects” for details and examples.
final void setInstanceProperty(IRISObject instance, String propertyName, Object value)
parameters:
  • instance — the IRISObject instance to be accessed.
  • propertyName — name of the property.
  • value — the property value to be assigned.
tCommit()
jdbc.IRIS.tCommit() commits the current transaction. See “Transactions and Locking” for more information and examples.
final void tCommit ( )
tRollback()
jdbc.IRIS.tRollback() rolls back all open transactions in the session. See “Transactions and Locking” for more information and examples.
final void tRollback ( )
tRollbackOne()
jdbc.IRIS.tRollbackOne() rolls back the current level transaction only. If this is a nested transaction, any higher-level transactions will not be rolled back. See “Transactions and Locking” for more information and examples.
final void tRollbackOne ( )
tStart()
jdbc.IRIS.tStart() starts/opens a transaction. See “Transactions and Locking” for more information and examples.
final void tStart ( )
unlock()
jdbc.IRIS.unlock() unlocks the global. This method performs an incremental unlock, not the implicit unlock-before-lock feature that is also offered in ObjectScript. See “Transactions and Locking” for more information and examples.
final void unlock (String lockMode, String globalName, String... subscripts )
parameters:
  • lockMode — Character S for shared lock, E for escalating lock, or SE for both. Default is empty string (exclusive and non-escalating).
  • globalName — global name.
  • subscripts — zero or more subscripts specifying the target node.

Class IRISIterator

Instances of IRISIterator are created by calling jdbc.IRIS.getIRISIterator().
See “Iterating Over a Set of Child Nodes” for more information and examples.

Method and Property Details

getSubscriptValue()
jdbc.IRISIterator.getSubscriptValue() gets the lowest level subscript for the node at the current iterator position. For example, if the iterator points to node ^myGlobal(23,"somenode"), the returned value will be "somenode".
Throws IllegalStateException if remove() has been called on the current node with this iterator, or there is no last element returned by this iterator (i.e. no successful next() or previous() calls).
String  getSubscriptValue() throws IllegalStateException 
getValue()
jdbc.IRISIterator.getValue() gets the value of the node at the current iterator position. Throws IllegalStateException if remove() has been called on the current node with this iterator, or there is no last element returned by this iterator (i.e. no successful next() or previous() calls).
Object  getValue () throws IllegalStateException 
hasNext()
jdbc.IRISIterator.hasNext() returns true if the iteration has more elements. (In other words, returns true if next() would return an element rather than throwing an exception.)
boolean  hasNext () 
hasPrevious()
jdbc.IRISIterator.hasPrevious() returns true if the iteration has a previous element. (In other words, returns true if previous() would return an element rather than throwing an exception.)
boolean  hasPrevious () 
next()
jdbc.IRISIterator.next() returns the next element in the iteration. Throws NoSuchElementException if the iteration has no more elements
String  next () throws NoSuchElementException 
previous()
jdbc.IRISIterator.previous() returns the previous element in the iteration. Throws NoSuchElementException if the iteration does not have a previous element
String  previous () throws NoSuchElementException 
remove()
jdbc.IRISIterator.remove() removes from the underlying collection the last element returned by this iterator. This method can be called only once per call to next() or previous(). Throws IllegalStateException if remove() has been called on the current node with this iterator, or there is no last element returned by this iterator (i.e. no successful next() or previous() calls).
void  remove () throws IllegalStateException 
startFrom()
jdbc.IRISIterator.startFrom() sets the iterator's starting position to the specified subscript. The subscript is an arbitrary starting point, and does not have to specify an existing node.
void  startFrom(Object subscript)
After calling this method, use next() or previous() to advance the iterator to the next defined sub-node in alphabetic collating sequence. The iterator will not be positioned at a defined sub-node until one of these methods is called. If you call getSubscriptValue() or getValue() before the iterator is advanced, an IllegalStateException will be thrown.

Class IRISObject

Class IRISObject is a member of com.intersystems.jdbc.
Instances of IRISObject can be created by calling one of the following IRIS methods:
If the called method or function returns an object that is a valid OREF, a reverse proxy object (an instance of IRISObject) for the referenced object will be generated and returned. For example, classMethodObject() will return a proxy object for an object created by %New().
See “Using Java Reverse Proxy Objects” for details and examples.

IRISObject Method Details

close()
jdbc.IRISObject.close() closes the object.
void close()
get()
jdbc.IRISObject.get() returns a property of the object as Object (also see jdbc.IRIS.getInstanceProperty()).
Object get(String propertyName)
parameters:
  • propertyName — name of the property to be returned.
invoke()
jdbc.IRISObject.invoke() invokes an instance method of the object, returning value as Object. (also see jdbc.IRIS.instanceMethodObject()).
Object invoke(String methodName, Object... args)
parameters:
  • methodName — name of the instance method to be called.
  • args — zero or more arguments of supported types.
invokeVoid()
jdbc.IRISObject.invokeVoid() invokes an instance method of the object, but does not return a value (also see jdbc.IRIS.instanceMethodVoid()).
void invokeVoid(String methodName, Object... args)
parameters:
  • methodName — name of the instance method to be called.
  • args — zero or more arguments of supported types.
set()
jdbc.IRISObject.set() sets a property of the object (also see jdbc.IRIS.setInstanceProperty()).
void set(String propertyName, Object value) 
parameters:
  • propertyName — name of the property to which value will be assigned.
  • value — property value to assign.
Previous section