Skip to main content
************* PRERELEASE CONTENT *************
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 extension classes in com.intersystems.jdbc:

  • Class IRIS provides the main functionality of the Native API.

  • Class IRISIterator provides methods to navigate a global array.

  • Class IRISList provides support for InterSystems $LIST serialization.

  • Class IRISObject provides methods to work with Object Gateway reverse proxy objects.

All of these classes are part of the InterSystems JDBC driver (com.intersystems.jdbc). They access the database through a standard JDBC connection, and can be used without any special setup or installation procedures. For complete information on JDBC connections, see Establishing JDBC Connections in Using Java with InterSystems Software.

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 for InterSystems IRIS JDBC Driver classes.

Class IRIS

Class IRIS is a member of com.intersystems.jdbc (the InterSystems JDBC driver).

IRIS has no public constructors. Instances of IRIS are created by calling static method IRIS.createIRIS().

IRIS Method Details

classMethodBoolean()

jdbc.IRIS.classMethodBoolean() calls an ObjectScript class method, passing zero or more arguments and returning an instance of Boolean.

final Boolean classMethodBoolean(String className, String methodName, Object... args)
Copy code to clipboard

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.

See “Calling ObjectScript Methods and Functions” for details and examples.

classMethodBytes()

jdbc.IRIS.classMethodBytes() calls an ObjectScript class method, passing zero or more arguments and returning an instance of byte[].

final byte[] classMethodBytes(String className, String methodName, Object... args)
Copy code to clipboard

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.

See “Calling ObjectScript Methods and Functions” for details and examples.

classMethodDouble()

jdbc.IRIS.classMethodDouble() calls an ObjectScript class method, passing zero or more arguments and returning an instance of Double.

final Double classMethodDouble(String className, String methodName, Object... args)
Copy code to clipboard

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.

See “Calling ObjectScript Methods and Functions” for details and examples.

classMethodIRISList()

jdbc.IRIS.classMethodIRISList() calls an ObjectScript class method, passing zero or more arguments and returning an instance of IRISList.

final IRISList classMethodIRISList(String className, String methodName, Object... args)
Copy code to clipboard

This method is equivalent to newList=(IRISList) classMethodBytes(className, methodName, 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.

See “Calling ObjectScript Methods and Functions” for details and examples.

classMethodLong()

jdbc.IRIS.classMethodLong() calls an ObjectScript class method, passing zero or more arguments and returning an instance of Long.

final Long classMethodLong(String className, String methodName, Object... args)
Copy code to clipboard

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.

See “Calling ObjectScript Methods and Functions” for details and examples.

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)
Copy code to clipboard

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 a class method that returns an ObjectScript $Status object would throw an error if called with the specified arguments. If the call would fail, this method throws a RuntimeException error containing the ObjectScript $Status error status number and message.

final void classMethodStatusCode(String className, String methodName, Object... args)
Copy code to clipboard

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.

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.

See “Calling ObjectScript Methods and Functions” for details and examples.

classMethodString()

jdbc.IRIS.classMethodString() calls an ObjectScript class method, passing zero or more arguments and returning an instance of String.

final String classMethodString(String className, String methodName, Object... args)
Copy code to clipboard

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.

See “Calling ObjectScript Methods and Functions” for details and examples.

classMethodVoid()

jdbc.IRIS.classMethodVoid() calls an ObjectScript class method with no return value, passing zero or more arguments.

final void classMethodVoid(String className, String methodName, Object... args)
Copy code to clipboard

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.

See “Calling ObjectScript Methods and Functions” for details and examples.

close()

jdbc.IRIS.close() closes the IRIS object.

final void close() throws Exception
Copy code to clipboard
createIRIS() [static]

jdbc.IRIS.createIRIS() returns an instance of jdbc.IRIS that uses the specified IRISConnection.

static IRIS createIRIS(IRISConnection conn) throws SQLException
Copy code to clipboard

parameters:

See “Introduction to Global Arrays” for more information and examples.

functionBoolean()

jdbc.IRIS.functionBoolean() calls an ObjectScript function, passing zero or more arguments and returning an instance of Boolean.

final Boolean functionBoolean(String functionName, String routineName, Object... args)
Copy code to clipboard

parameters:

  • functionName — name of the function to call.

  • routineName — name of the routine containing the function.

  • args — zero or more arguments of supported types.

See “Calling ObjectScript Methods and Functions” for details and examples.

functionBytes()

jdbc.IRIS.functionBytes() calls an ObjectScript function, passing zero or more arguments and returning an instance of byte[].

final byte[] functionBytes(String functionName, String routineName, Object... args)
Copy code to clipboard

parameters:

  • functionName — name of the function to call.

  • routineName — name of the routine containing the function.

  • args — zero or more arguments of supported types.

See “Calling ObjectScript Methods and Functions” for details and examples.

functionDouble()

jdbc.IRIS.functionDouble() calls an ObjectScript function, passing zero or more arguments and returning an instance of Double.

final Double functionDouble(String functionName, String routineName, Object... args)
Copy code to clipboard

parameters:

  • functionName — name of the function to call.

  • routineName — name of the routine containing the function.

  • args — zero or more arguments of supported types.

See “Calling ObjectScript Methods and Functions” for details and examples.

functionIRISList()

jdbc.IRIS.functionIRISList() calls an ObjectScript function, passing zero or more arguments and returning an instance of IRISList.

final IRISList functionIRISList(String functionName, String routineName, Object... args)
Copy code to clipboard

This function is equivalent to newList=(IRISList) functionBytes(functionName, routineName, 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.

See “Calling ObjectScript Methods and Functions” for details and examples.

functionLong()

jdbc.IRIS.functionLong() calls an ObjectScript function, passing zero or more arguments and returning an instance of Long.

final Long functionLong(String functionName, String routineName, Object... args)
Copy code to clipboard

parameters:

  • functionName — name of the function to call.

  • routineName — name of the routine containing the function.

  • args — zero or more arguments of supported types.

See “Calling ObjectScript Methods and Functions” for details and examples.

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)
Copy code to clipboard

parameters:

  • functionName — name of the function to call.

  • routineName — name of the routine containing the function.

  • args — zero or more arguments of supported types.

See “Class IRIS Supported Datatypes” for related information.

functionString()

jdbc.IRIS.functionString() calls an ObjectScript function, passing zero or more arguments and returning an instance of String.

final String functionString(String functionName, String routineName, Object... args)
Copy code to clipboard

parameters:

  • functionName — name of the function to call.

  • routineName — name of the routine containing the function.

  • args — zero or more arguments of supported types.

See “Calling ObjectScript Methods and Functions” for details and examples.

getAPIVersion() [static]

jdbc.IRIS.getAPIVersion() returns the IRIS Native API version string.

static final String getAPIVersion()
Copy code to clipboard
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)
Copy code to clipboard

parameters:

  • globalName — global name.

  • subscripts — zero or more subscripts specifying the target node.

See “Class IRIS Supported Datatypes” for related information.

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)
Copy code to clipboard

parameters:

  • globalName — global name.

  • subscripts — zero or more subscripts specifying the target node.

See “Class IRIS Supported Datatypes” for related information.

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)
Copy code to clipboard

parameters:

  • globalName — global name.

  • subscripts — zero or more subscripts specifying the target node.

See “Class IRIS Supported Datatypes” for related information.

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)
Copy code to clipboard

parameters:

  • globalName — global name.

  • subscripts — zero or more subscripts specifying the target node.

See “Class IRIS Supported Datatypes” for related information.

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)
Copy code to clipboard

parameters:

  • globalName — global name.

  • subscripts — zero or more subscripts specifying the target node.

See “Class IRIS Supported Datatypes” for related information.

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)
Copy code to clipboard

parameters:

  • globalName — global name.

  • subscripts — zero or more subscripts specifying the target node.

See “Class IRIS Supported Datatypes” for related information.

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)
Copy code to clipboard

parameters:

  • globalName — global name.

  • subscripts — zero or more subscripts specifying the target node.

See “Class IRIS Supported Datatypes” for related information.

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)
Copy code to clipboard

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.

See “Class IRIS Supported Datatypes” for related information.

getIRISList()

jdbc.IRIS.getIRISList() gets the value of the node as an IRISList (or null if node does not exist).

IRISList getIRISList(String globalName, Object... subscripts)
Copy code to clipboard

This is equivalent to calling newList=(IRISList) getBytes(globalName, subscripts)

parameters:

  • globalName — global name.

  • subscripts — zero or more subscripts specifying the target node.

See “Class IRIS Supported Datatypes” for related information.

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)
Copy code to clipboard

parameters:

  • globalName — global name.

  • subscripts — zero or more subscripts specifying the target node.

See “Class IRIS Supported Datatypes” for related information.

getObject()

jdbc.IRIS.getObject() gets the value of the global as an Object (or null if node does not exist). See “Using Java Reverse Proxy Objects” for details and examples.

final Object getObject(String globalName, Object... subscripts)
Copy code to clipboard

parameters:

  • globalName — global name.

  • subscripts — zero or more subscripts specifying the target node.

Use this method to retrieve objects that implement java.io.Serializable. When the set() method accepts an instance of Serializable, the instance is stored in serialized form, and can be deserialized by casting the return value of getObject() to the appropriate class.

See “Class IRIS Supported Datatypes” for related information.

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, Object... subscripts)
Copy code to clipboard

parameters:

  • globalName — global name.

  • subscripts — zero or more subscripts specifying the target node.

See “Class IRIS Supported Datatypes” for related information.

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()
Copy code to clipboard
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, Object... subscripts)
Copy code to clipboard

parameters:

  • globalName — global name.

  • subscripts — zero or more subscripts specifying the target node.

See “Class IRIS Supported Datatypes” for related information.

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, Object... subscripts)
Copy code to clipboard

parameters:

  • globalName — global name.

  • subscripts — zero or more subscripts specifying the target node.

See “Class IRIS Supported Datatypes” for related information.

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, Object... subscripts)
Copy code to clipboard

parameters:

  • globalName — global name.

  • subscripts — zero or more subscripts specifying the target node.

See “Class IRIS Supported Datatypes” for related information.

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)
Copy code to clipboard

parameters:

  • globalName — global name.

  • subscripts — zero or more subscripts specifying the target node.

See “Class IRIS Supported Datatypes” for related information.

getTLevel()

jdbc.IRIS.getTLevel() gets the level of the current nested IRIS Native 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.

final Integer getTLevel()
Copy code to clipboard

This method uses the IRIS Native transaction model, and is not compatible with JDBC/SQL transaction methods. Never mix the two transaction models. See “Transactions and Locking” for more information and examples.

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, Accessing, and Deleting Nodes” for more information and examples.

final long increment(Integer value, String globalName, Object... subscripts)
Copy code to clipboard

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.

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, Object... subscripts)
Copy code to clipboard

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, Accessing, and Deleting Nodes” for more information and examples.

final void kill(String globalName, Object... subscripts)
Copy code to clipboard

parameters:

  • globalName — global name.

  • subscripts — zero or more subscripts specifying the target node.

lock()

jdbc.IRIS.lock() locks the global for an IRIS Native transaction, and 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.

final boolean lock(String lockMode, Integer timeout, String globalName, Object... subscripts)
Copy code to clipboard

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.

This method uses the IRIS Native transaction model, and is not compatible with JDBC/SQL transaction methods. Never mix the two transaction models. See “Transactions and Locking” for more information and examples.

procedure()

jdbc.IRIS.procedure() calls a procedure, passing zero or more arguments. Does not return a value.

final void procedure(String procedureName, String routineName, Object... args)
Copy code to clipboard

parameters:

  • procedureName — name of the procedure to call.

  • routineName — name of the routine containing the procedure.

  • args — zero or more arguments of supported types.

See “Calling ObjectScript Methods and Functions” for more information and examples.

releaseAllLocks()

jdbc.IRIS.releaseAllLocks() is an IRIS Native transaction method that releases all locks associated with the session.

final void releaseAllLocks()
Copy code to clipboard

This method uses the IRIS Native transaction model, and is not compatible with JDBC/SQL transaction methods. Never mix the two transaction models. See “Transactions and Locking” for more information and examples.

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, Accessing, and Deleting Nodes” for more information.

final void set(Boolean value, String globalName, Object... subscripts)
final void set(byte[] value, String globalName, Object... subscripts)
final void set(Short value, String globalName, Object... subscripts)
final void set(Integer value, String globalName, Object... subscripts)
final void set(Long value, String globalName, Object... subscripts)
final void set(Double value, String globalName, Object... subscripts)
final void set(Float value, String globalName, Object... subscripts)
final void set(String value, String globalName, Object... subscripts)

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

parameters:

  • value — value of a supported datatype (null value sets global to "").

  • globalName — global name.

  • subscripts — zero or more subscripts specifying the target node.

See “Class IRIS Supported Datatypes” for related information.

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 — if the value is an instance of an object that implements Serializable, it will be serialized prior to being set as the global value. Use getObject() to retrieve the value.

tCommit()

jdbc.IRIS.tCommit() commits the current IRIS Native transaction.

final void tCommit()
Copy code to clipboard

This method uses the IRIS Native transaction model, and is not compatible with JDBC/SQL transaction methods. Never mix the two transaction models. See “Transactions and Locking” for more information and examples.

tRollback()

jdbc.IRIS.tRollback() rolls back all open IRIS Native transactions in the session.

final void tRollback()
Copy code to clipboard

This method uses the IRIS Native transaction model, and is not compatible with JDBC/SQL transaction methods. Never mix the two transaction models. See “Transactions and Locking” for more information and examples.

tRollbackOne()

jdbc.IRIS.tRollbackOne() rolls back the current level IRIS Native transaction only. If this is a nested transaction, any higher-level transactions will not be rolled back.

final void tRollbackOne()
Copy code to clipboard

This method uses the IRIS Native transaction model, and is not compatible with JDBC/SQL transaction methods. Never mix the two transaction models. See “Transactions and Locking” for more information and examples.

tStart()

jdbc.IRIS.tStart() starts/opens an IRIS Native transaction.

final void tStart()
Copy code to clipboard

This method uses the IRIS Native transaction model, and is not compatible with JDBC/SQL transaction methods. Never mix the two transaction models. See “Transactions and Locking” for more information and examples.

unlock()

jdbc.IRIS.unlock() unlocks the global in an IRIS Native transaction. This method performs an incremental unlock, not the implicit unlock-before-lock feature that is also offered in ObjectScript.

final void unlock(String lockMode, String globalName, Object... subscripts)
Copy code to clipboard

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.

This method uses the IRIS Native transaction model, and is not compatible with JDBC/SQL transaction methods. Never mix the two transaction models. See “Transactions and Locking” for more information and examples.

Class IRISIterator

Class IRISIterator is a member of com.intersystems.jdbc (the InterSystems JDBC driver) and implements java.util.Iterator.

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

IRISIterator Method 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
Copy code to clipboard
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
Copy code to clipboard
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()
Copy code to clipboard
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()
Copy code to clipboard
next()

jdbc.IRISIterator.next() returns the next element in the iteration. Throws NoSuchElementException if the iteration has no more elements

String next() throws NoSuchElementException
Copy code to clipboard
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
Copy code to clipboard
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
Copy code to clipboard
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)
Copy code to clipboard

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 IRISList

Class IRISList is a member of com.intersystems.jdbc (the InterSystems JDBC driver). It implements a Java interface for InterSystems $LIST serialization. In addition to the IRISList constructors (described in the following section), it is also returned by the following jdbc.IRIS methods: classMethodIRISList(), functionIRISList(), getIRISList().

IRISList Constructors

Constructor jdbc.IRISList.IRISList() has the following signatures:

IRISList ()
IRISList (IRISList list)
IRISList (byte[] buffer, int length)
Copy code to clipboard

parameters:

  • list — instance of IRISList to be copied

  • buffer — buffer to be allocated

  • length — initial buffer size to be allocated

Instances of IRISList can be created in the following ways:

Create an empty IRISList
IRISList list = new IRISList();
Copy code to clipboard
Create a copy of another IRISList

Create a copy of the IRISList instance specified by argument list.

IRISList listcopy = new IRISList(myOtherList)
Copy code to clipboard
Construct an IRISList instance from a byte array

Construct an instance from a $LIST formatted byte array, such as that returned by IRIS.getBytes(). The constructor takes a buffer of size length:

byte[] listBuffer = myIris.getBytes("myGlobal",1);
IRISList listFromByte = new IRISList(listBuffer, listBuffer.length);
Copy code to clipboard

The returned list uses the buffer (not a copy) until changes to the list are visible in the buffer and a resize is required.

IRISList Method Details

add()

jdbc.IRISList.add() appends an Object, each element of an Object[], or each element of a Collection to the end of the IRISList. Throws RuntimeException if you attempt to add an unsupported datatype.

Supported datatypes are: Boolean, Short, Integer, Long, java.math.BigInteger, java.math.BigDecimal, Float, Double, String, Character, byte[],char[], IRISList, and null.

void add(Object value)
void add(Object[] array)
void add(Collection collection)
Copy code to clipboard

parameters:

  • valueObject instance of any supported type.

  • arrayObject[] containing Object elements of supported types. Each Object in the array will be appended to the list as a separate element.

  • collectionCollection containing Object elements of supported types. Each Object in the collection will be appended to the list in the order that it is returned by the collection’s iterator.

Adding an IRISList element

The add() method never concatenates two instances of IRISList. Whenever add() encounters an IRISList instance (either as a single value or as an element of an array or collection), the instance is appended as a single IRISList element.

However, you can use IRISList.toArray() to convert an IRISList to an Object[]. Calling add() on the resulting array will append each element separately.

clear()

jdbc.IRISList.clear() resets the list by removing all elements from the list.

void clear()
Copy code to clipboard
count()

jdbc.IRISList.count() iterates over the list and returns the number of elements encountered.

int count()
Copy code to clipboard
DateToHorolog() [static]

jdbc.IRISList.DateToHorolog() converts a Date to the day field (int) of a $Horolog string. Also see HorologToDate().

static int DateToHorolog(Date value, Calendar calendar)
Copy code to clipboard

parameters:

  • valueDate value to convert.

  • calendarCalendar used to determine GMT and DST offsets. Can be null for default calendar

equals()

jdbc.IRISList.equals() compares the specified list with this instance of IRISList, and returns true if they are identical. To be equal, both lists must contain the same number of elements in the same order with identical serialized values.

boolean equals (Object list)
Copy code to clipboard

parameters:

  • list — instance of IRISList to compare.

get()

jdbc.IRISList.get() returns the element at index as Object. Throws IndexOutOfBoundsException if the index is less than 1 or past the end of the list.

Object get(int index)
Copy code to clipboard

parameters:

  • index — integer specifying the list element to be retrieved.

getList()

jdbc.IRISList.getList() gets the element at index as an IRISList. Throws IndexOutOfBoundsException if the index is less then 1 or past the end of the list.

IRISList getList(int index)
Copy code to clipboard

parameters:

  • index — integer specifying the list element to return

HorologToDate() [static]

jdbc.IRISList.HorologToDate() converts the day field of a $Horolog string to a Date value. Also see DateToHorolog().

static Date HorologToDate(int HorologValue, Calendar calendar)
Copy code to clipboard

parameters:

  • HorologValueint representing the day field of a $Horolog string. The time field will be zeroed out (i.e., midnight), so a Date will not round trip if its time fields are not zero to begin with.

  • calendarCalendar used to determine GMT and DST offsets. Can be null for default calendar.

HorologToTime() [static]

jdbc.IRISList.HorologToTime() converts the time field of a $Horolog string to a Time value. Also see TimeToHorolog().

static Time HorologToTime(int HorologValue, Calendar calendar)
Copy code to clipboard

parameters:

  • HorologValueint representing the time field of a $Horolog string. The date field will be zeroed out (set to the epoch), so a Time with a milliseconds value outside the range 0L to 86399999L does not round trip.

  • calendarCalendar used to determine GMT and DST offsets. Can be null for default calendar

PosixToTimestamp() [static]

jdbc.IRISList.PosixToTimestamp() converts a %Library.PosixTime value to a Timestamp. Treats the %PosixTime as local time using the supplied Calendar (if null, uses the default time zone). To round trip, you must supply equivalent calendars. Also see TimestampToPosix().

static Timestamp PosixToTimestamp(long PosixValue, Calendar calendar)
Copy code to clipboard

parameters:

  • PosixValue — the %PosixTime value (a 64-bit signed integer).

  • calendarCalendar, used to determine GMT and DST offsets. Can be null for default calendar

remove()

jdbc.IRISList.remove() removes the element at index from the list. Returns true if the element existed and was removed, false otherwise. This method can be expensive, since it will usually have to reallocate the list.

boolean remove(int index)
Copy code to clipboard

parameters:

  • index — integer specifying the list element to remove.

set()

jdbc.IRISList.set() sets or replaces the list element at index with value. If value is an array, each array element is inserted into the list, starting at index, and any existing list elements after index are shifted to make room for the new values. If index is beyond the end of the list, value will be stored at index and the list will be padded with nulls up to that position.

void set(int index, Object value)
void set(int index, Object[] value)
Copy code to clipboard

parameters:

  • index — integer indicating the list element to be set or replaced

  • valueObject value or Object array to insert at index

Objects can be any of the following types: Boolean, Short, Integer, Long, java.math.BigInteger, java.math.BigDecimal, Float, Double, String, Character, byte[],char[], IRISList, and null.

size()

jdbc.IRISList.size() returns the byte length of the serialized value for this IRISList.

int size()
Copy code to clipboard
subList()

jdbc.IRISList.subList() returns a new IRISList containing the elements in the closed range [from, to]. Throws IndexOutOfBoundsException if from is greater than count() or to is less than from.

IRISList subList(int from, int to)
Copy code to clipboard

parameters:

  • from — index of first element to add to the new list.

  • to — index of last element to add to the new list.

TimestampToPosix() [static]

jdbc.IRISList.TimestampToPosix() converts a Timestamp object to a %Library.PosixTime value (a 64-bit signed integer). Converts the Timestamp to local time using the supplied Calendar (if null, uses the default time zone). To round trip, you must supply equivalent calendars. Also see PosixToTimestamp().

static long TimestampToPosix(Timestamp Value, Calendar calendar)
Copy code to clipboard

parameters:

  • ValueTimestamp to be converted.

  • calendarCalendar used to determine GMT and DST offsets. Can be null for default calendar

TimeToHorolog() [static]

jdbc.IRISList.TimeToHorolog() converts a Time value to the time field of a $Horolog string. Also see HorologToTime().

static int TimeToHorolog(Time value, Calendar calendar)
Copy code to clipboard

parameters:

  • valueTime to be converted.

  • calendarCalendar used to determine GMT and DST offsets. Can be null for default calendar

toArray()

jdbc.IRISList.toArray() returns an array of Object containing all of the elements in this list. If the list is empty, a zero length array will be returned.

Object[] toArray()
Copy code to clipboard
toList()

jdbc.IRISList.toList() returns a java.util.ArrayList<Object> containing all of the elements in this IRISList. If the list is empty, a zero length ArrayList will be returned.

ArrayList< Object> toList()
Copy code to clipboard
toString()

jdbc.IRISList.toString() returns a printable representation of the list.

String toString()
Copy code to clipboard

Some element types are represented differently than they would be in ObjectScript:

  • An empty list ("" in ObjectScript) is displayed as "$lb()".

  • Empty elements (where $lb()=$c(1)) are displayed as "null".

  • Strings are not quoted.

  • Doubles format with sixteen significant digits

Class IRISObject

Class IRISObject is a member of com.intersystems.jdbc (the InterSystems JDBC driver). It provides methods to work with Object Gateway reverse proxy objects (see “Using Java Reverse Proxy Objects” for details and examples).

IRISObject has no public constructors. 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()
Copy code to clipboard
get()

jdbc.IRISObject.get() returns a property value of the proxy object as an instance of Object.

Object get(String propertyName)
Copy code to clipboard

parameters:

  • propertyName — name of the property to be returned.

getBoolean()

jdbc.IRISObject.getBoolean() returns a property value of the proxy object as an instance of Boolean.

Boolean getBoolean(String propertyName)
Copy code to clipboard

parameters:

  • propertyName — name of the property to be returned.

See “IRISObject Supported Datatypes” for related information.

getBytes()

jdbc.IRISObject.getBytes() returns a property value of the proxy object as an instance of byte[].

byte[] getBytes(String propertyName)
Copy code to clipboard

parameters:

  • propertyName — name of the property to be returned.

See “IRISObject Supported Datatypes” for related information.

getDouble()

jdbc.IRISObject.getDouble() returns a property value of the proxy object as an instance of Double.

Double getDouble(String propertyName)
Copy code to clipboard

parameters:

  • propertyName — name of the property to be returned.

See “IRISObject Supported Datatypes” for related information.

getIRISList()

jdbc.IRISObject.getIRISList() returns a property value of the proxy object as an instance of IRISList.

IRISList getIRISList(String propertyName)
Copy code to clipboard

parameters:

  • propertyName — name of the property to be returned.

See “IRISObject Supported Datatypes” for related information.

getLong()

jdbc.IRISObject.getLong() returns a property value of the proxy object as an instance of Long.

Long getLong(String propertyName)
Copy code to clipboard

parameters:

  • propertyName — name of the property to be returned.

See “IRISObject Supported Datatypes” for related information.

getObject()

jdbc.IRISObject.getObject() returns a property value of the proxy object as an instance of Object.

Object getObject(String propertyName)
Copy code to clipboard

parameters:

  • propertyName — name of the property to be returned.

See “IRISObject Supported Datatypes” for related information.

getString()

jdbc.IRISObject.getString() returns a property value of the proxy object as an instance of String.

String getString(String propertyName)
Copy code to clipboard

parameters:

  • propertyName — name of the property to be returned.

See “IRISObject Supported Datatypes” for related information.

invoke()

jdbc.IRISObject.invoke() invokes an instance method of the object, returning value as Object.

Object invoke(String methodName, Object... args)
Copy code to clipboard

parameters:

  • methodName — name of the instance method to be called.

  • args — zero or more arguments of supported types.

See “IRISObject Supported Datatypes” for related information.

invokeBoolean()

jdbc.IRISObject.invokeBoolean() invokes an instance method of the object, returning value as Boolean.

Boolean invokeBoolean(String methodName, Object... args)
Copy code to clipboard

parameters:

  • methodName — name of the instance method to be called.

  • args — zero or more arguments of supported types.

See “IRISObject Supported Datatypes” for related information.

invokeBytes()

jdbc.IRISObject.invokeBytes() invokes an instance method of the object, returning value as byte[].

byte[] invokeBytes(String methodName, Object... args)
Copy code to clipboard

parameters:

  • methodName — name of the instance method to be called.

  • args — zero or more arguments of supported types.

See “IRISObject Supported Datatypes” for related information.

invokeDouble()

jdbc.IRISObject.invokeDouble() invokes an instance method of the object, returning value as Double.

Double invokeDouble(String methodName, Object... args)
Copy code to clipboard

parameters:

  • methodName — name of the instance method to be called.

  • args — zero or more arguments of supported types.

See “IRISObject Supported Datatypes” for related information.

invokeIRISList()

jdbc.IRISObject.invokeIRISList() invokes an instance method of the object, returning value as IRISList.

IRISList invokeIRISList(String methodName, Object... args)
Copy code to clipboard

parameters:

  • methodName — name of the instance method to be called.

  • args — zero or more arguments of supported types.

See “IRISObject Supported Datatypes” for related information.

invokeLong()

jdbc.IRISObject.invokeLong() invokes an instance method of the object, returning value as Long.

Long invokeLong(String methodName, Object... args)
Copy code to clipboard

parameters:

  • methodName — name of the instance method to be called.

  • args — zero or more arguments of supported types.

See “IRISObject Supported Datatypes” for related information.

invokeObject()

jdbc.IRISObject.invokeObject() invokes an instance method of the object, returning value as Object

Object invokeObject(String methodName, Object... args)
Copy code to clipboard

parameters:

  • methodName — name of the instance method to be called.

  • args — zero or more arguments of supported types.

See “IRISObject Supported Datatypes” for related information.

invokeStatusCode()

jdbc.IRISObject.invokeStatusCode() tests whether an invoke method that returns an ObjectScript $Status object would throw an error if called with the specified arguments. If the call would fail, this method throws a RuntimeException error containing the ObjectScript $Status error number and message. See “Catching %Status Error Codes” for details and examples.

void invokeStatusCode(String methodName, Object... args)
Copy code to clipboard

parameters:

  • methodName — name of the instance method to be called.

  • args — zero or more arguments of supported types.

See “IRISObject Supported Datatypes” for related information.

invokeString()

jdbc.IRISObject.invokeString() invokes an instance method of the object, returning value as String.

String invokeString(String methodName, Object... args)
Copy code to clipboard

parameters:

  • methodName — name of the instance method to be called.

  • args — zero or more arguments of supported types.

See “IRISObject Supported Datatypes” for related information.

invokeVoid()

jdbc.IRISObject.invokeVoid() invokes an instance method of the object, but does not return a value.

void invokeVoid(String methodName, Object... args)
Copy code to clipboard

parameters:

  • methodName — name of the instance method to be called.

  • args — zero or more arguments of supported types.

See “IRISObject Supported Datatypes” for related information.

iris [attribute]

jdbc.IRISObject.iris is a public field that provides access to the instance of IRIS associated with this object.

public IRIS iris
Copy code to clipboard

See “IRISObject Supported Datatypes” for related information.

set()

jdbc.IRISObject.set() sets a property of the proxy object.

void set(String propertyName, Object propertyValue)
Copy code to clipboard

parameters:

  • propertyName — name of the property to which value will be assigned.

  • value — property value to assign.