Skip to main content

Java Native SDK Quick Reference

This is a quick reference for the InterSystems IRIS Native SDK for Java, providing information on the following extension classes in com.intersystems.jdbc:

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

  • Class IRISIterator provides methods to navigate a global array.

  • Class IRISList provides support for InterSystems $LIST serialization.

  • Class IRISObject provides methods to work with Java inverse 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 Java Native SDK. 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)

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)

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)

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)

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)

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 an inverse proxy object (an instance of IRISObject) for the referenced object. See “Using Java Inverse 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 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)

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)

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)

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
createIRIS() [static]

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

static IRIS createIRIS(IRISConnection conn) throws SQLException

parameters:

  • conn — an instance of IRISConnection.

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)

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)

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)

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)

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)

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 an inverse proxy object (an instance of IRISObject) for the referenced object. See “Using Java Inverse 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.

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)

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 SDK 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.

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)

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)

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)

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)

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)

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)

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)

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)

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)

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 Inverse Proxy Objects” for details and examples.

final Object getObject(String globalName, Object... subscripts)

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)

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()
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)

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)

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)

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)

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()

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)

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)

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)

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)

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)

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()

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)

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()

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()

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()

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()

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)

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
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 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)

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();
Create a copy of another IRISList

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

IRISList listcopy = new IRISList(myOtherList)
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);

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)

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()
count()

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

int count()
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)

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)

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)

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)

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)

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)

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)

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)

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)

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()
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)

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)

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)

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()
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()
toString()

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

String toString()

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 inverse proxy objects (see “Using Java Inverse 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, an inverse 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 Inverse 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 value of the proxy object as an instance of Object.

Object get(String propertyName)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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

See “IRISObject Supported Datatypes” for related information.

set()

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

void set(String propertyName, Object propertyValue)

parameters:

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

  • value — property value to assign.

Feedback