docs.intersystems.com
Home  /  Application Development: Language Bindings and Gateways  /  Persisting Java Objects with InterSystems IRIS XEP  /  XEP Quick Reference


Persisting Java Objects with InterSystems IRIS XEP
XEP Quick Reference
[Back] 
InterSystems: The power behind what matters   
Search:  


This chapter is a quick reference for the classes that are most important to an understanding of XEP. The com.intersys.xep package contains the public API described in Using XEP Event Persistence.
Note:
This is not the definitive reference for this API. For the most complete and up-to-date information, see the JavaDoc for the InterSystems Java Connectivity API, located in <install-dir>/dev/java/doc/index.html.
XEP Quick Reference
This section is a reference for the XEP API (namespace com.intersys.xep). See Using XEP Event Persistence for a details on how to use the API. It contains the following classes and interfaces:
List of XEP Methods
The following classes and methods of the XEP API are described in this reference:
PersisterFactory
EventPersister
Event
EventQuery<>
EventQueryIterator<>
InterfaceResolver
Class PersisterFactory
Class com.intersys.xep.PersisterFactory creates a new EventPersister object.
PersisterFactory() Constructor
Creates a new instance of PersisterFactory.
PersisterFactory()
createPersister()
PersisterFactory.createPersister() returns an instance of EventPersister.
static EventPersister createPersister()  [inline, static] 
see also:
Creating and Connecting an EventPersister
Class EventPersister
Class com.intersys.xep.EventPersister is the main entry point for the XEP module. It provides methods that can be used to control XEP options, establish a TCP/IP connection, import schema, and produce XEP Event objects. It also provides methods to control transactions and perform other tasks.
In most applications, instances of EventPersister should be created by PersisterFactory.createPersister(). The constructor should only be used to extend the class.
EventPersister() Constructor
Creates a new instance of EventPersister.
EventPersister()
close()
EventPersister.close() releases all resources held by this instance. Always call close() on the EventPersister object before it goes out of scope to ensure that all locks, licenses, and other resources associated with the connection are released.
void close()
commit()
EventPersister.commit() commits one level of transaction
void commit()
connect()
EventPersister.connect() establishes a TCP/IP connection to the specified InterSystems IRIS namespace.
void connect(String host, int port, String namespace, String username, String password) 
parameters:
see also:
Creating and Connecting an EventPersister
deleteClass()
EventPersister.deleteClass() deletes an InterSystems IRIS class definition. It does not delete objects associated with the extent (since objects can belong to more than one extent), and does not delete any dependencies (for example, inner or embedded classes).
void deleteClass(String className)
parameter:
If the specified class does not exist, the call silently fails (no error is thrown).
see also:
“Deleting Test Data” in Accessing Stored Events
deleteExtent()
EventPersister.deleteExtent() deletes the extent definition associated with a Java event, but does not destroy associated data (since objects can belong to more than one extent). See Extents in Defining and Using Classes for more information on managing extents.
void deleteExtent(String className)
Do not confuse this method with the deprecated Event.deleteExtent(), which destroys all extent data as well as with the extent definition.
see also:
“Deleting Test Data” in Accessing Stored Events
getEvent()
EventPersister.getEvent() returns an Event object that corresponds to the class name supplied, and optionally specifies the indexing mode to be used.
Event getEvent(String className)
Event getEvent(String className, int indexMode)
parameter:
The following indexMode options are available:
The same instance of Event can be used to store or retrieve all instances of a class, so a process should only call the getEvent() method once per class. Avoid instantiating multiple Event objects for a single class, since this can affect performance and may cause memory leaks.
see also:
Creating Event Instances and Storing Persistent Events, Controlling Index Updating
getInterfaceResolver()
EventPersister.getInterfaceResolver() — returns the currently set instance of InterfaceResolver that will be used by importSchema() (see Implementing an InterfaceResolver). Returns null if no instance has been set.
InterfaceResolver getInterfaceResolver()
see also:
setInterfaceResolver(), importSchema()
getTransactionLevel()
EventPersister.getTransactionLevel() returns the current transaction level (0 if not in a transaction)
int getTransactionLevel()
importSchema()
EventPersister.importSchema() produces a flat schema (see Schema Import Models) that embeds all referenced objects as serialized objects. The method imports the schema of each event declared in the class or a .jar file specified (including dependencies), and returns an array of class names for the imported events.
String[] importSchema(String classOrJarFileName)
String[] importSchema(String[] classes)
parameters:
If the argument is a class name, the corresponding class and any dependencies will be imported. If the argument is a .jar file, all classes in the file and any dependencies will be imported. If such schema already exists, and it appears to be in sync with the Java schema, import will be skipped. Should a schema already exist, but it appears different, a check will be performed to see if there is any data. If there is no data, a new schema will be generated. If there is existing data, an exception will be thrown.
see also:
Importing a Schema
importSchemaFull()
EventPersister.importSchemaFull() — produces a full schema (see Schema Import Models) that preserves the object hierarchy of the source classes. The method imports the schema of each event declared in the class or .jar file specified (including dependencies), and returns an array of class names for the imported events.
String[] importSchemaFull(String classOrJarFileName)
String[] importSchemaFull(String[] classes)
parameters:
If the argument is a class name, the corresponding class and any dependencies will be imported. If the argument is a .jar file, all classes in the file and any dependencies will be imported. If such schema already exists, and it appears to be in sync with the Java schema, import will be skipped. Should a schema already exist, but it appears different, a check will be performed to see if there is any data. If there is no data, a new schema will be generated. If there is existing data, an exception will be thrown.
see also:
Importing a Schema
rollback()
EventPersister.rollback() rolls back the specified number of levels of transaction, where level is a positive integer, or roll back all levels of transaction if no level is specified.
void rollback()
void rollback(int level)
parameter:
This method does nothing if level is less than 0, and stops rolling back once the transaction level reaches 0 if level is greater than the initial transaction level.
setInterfaceResolver()
EventPersister.setInterfaceResolver() — sets the instance of InterfaceResolver to be used by importSchema() (see Implementing an InterfaceResolver). All instances of Event created by this EventPersiser will share the specified InterfaceResolver (which defaults to null if this method is not called).
void setInterfaceResolver(InterfaceResolver interfaceResolver)
parameters:
see also:
getInterfaceResolver(), importSchema()
startTransaction()
EventPersister.startTransaction() starts a transaction (which may be a nested transaction)
void startTransaction()
Class Event
Class com.intersys.xep.Event provides methods that operate on XEP events (storing events, creating a query, indexing etc.). It is created by the EventPersister.getEvent() method.
close()
Event.close() releases all resources held by this instance. Always call close() on the Event object before it goes out of scope to ensure that all locks, licenses, and other resources associated with the connection are released.
void close()
createQuery()
Event.createQuery() takes a String argument containing the text of the SQL query and returns an instance of EventQuery<E>, where parameter E is the target class of the parent Event.
<E> EventQuery<E> createQuery (String sqlText)
parameter:
see also:
Creating and Executing a Query
deleteObject()
Event.deleteObject() deletes an event identified by its database object ID or IdKey.
void deleteObject(long id)
void deleteObject(Object[] idkeys)
parameter:
see also:
Accessing Stored Events
getObject()
Event.getObject() fetches an event identified by its database object ID or IdKey. Returns null if the specified object does not exist.
Object getObject(long id)
Object getObject(Object[] idkeys)
parameter:
see also:
Accessing Stored Events
isEvent()
Event.isEvent() throws an XEPException if the object (or class) is not an event in the XEP sense (see Requirements for Imported Classes). The exception message will explain why the object is not an XEP event.
static void isEvent(Object objectOrClass)
parameter:
startIndexing()
Event.startIndexing() starts asynchronous index building for the extent of the target class. Throws an exception if the index mode is Event.INDEX_MODE_SYNC (see Controlling Index Updating).
void startIndexing()
stopIndexing()
Event.stopIndexing() stops asynchronous index building for the extent. If you do not want the index to be updated when the Event instance is closed, call this method before calling Event.close().
void stopIndexing()
see also:
Controlling Index Updating
store()
Event.store() stores a Java object or array of objects as persistent events. There is no significant performance difference between passing an array and passing individual objects in a loop, but all objects in the array must be of the same type. Returns a long database ID for each newly inserted object, or 0 if the ID could not be returned or the event uses an IdKey.
long store(Object object)
long[] store(Object[] objects)
parameters:
updateObject()
Event.updateObject() updates an event identified by its database ID or IdKey.
void updateObject(long id, Object object)
void updateObject(Object[] idkeys, Object object)
parameter:
see also:
Accessing Stored Events
waitForIndexing()
Event.waitForIndexing() waits for asynchronous indexing to be completed, returning true if indexing has been completed, or false if the wait timed out before indexing was completed. Throws an exception if the index mode is Event.INDEX_MODE_SYNC.
boolean waitForIndexing(int timeout)
parameter:
see also:
Controlling Index Updating
Class EventQuery<>
Class com.intersys.xep.EventQuery<> can be used to retrieve, update and delete individual events from the database.
close()
EventQuery<>.close() releases all resources held by this instance. Always call close() before the EventQuery<> object goes out of scope to ensure that all locks, licenses, and other resources associated with the connection are released.
void close()
deleteCurrent()
EventQuery<>.deleteCurrent() deletes the event most recently fetched by getNext().
void deleteCurrent()
see also:
Processing Query Data
execute()
EventQuery<>.execute() executes the SQL query associated with this EventQuery<>. If the query is successful, this EventQuery<> will contain a resultset that can be accessed by other EventQuery<> or EventQueryIterator<> methods.
void execute()
see also:
Creating and Executing a Query
getAll()
EventQuery<>.getAll() returns objects of target class E from all rows in the resultset as a single list.
java.util.List<E> getAll()
Uses getNext() to get all target class E objects in the resultset, and returns them in a List. The list cannot be used for updating or deleting (although Event methods updateObject() and deleteObject() can be used if you have some way of obtaining the Id or IdKey of each object). getAll() and getNext() cannot access the same resultset — once either method has been called, the other method cannot be used until execute() is called again.
see also:
Processing Query Data, Event.updateObject(), Event.deleteObject()
getFetchLevel()
EventQuery<>.getFetchLevel() returns the current fetch level (see Defining the Fetch Level).
int getFetchLevel()
getIterator()
EventQuery<>.getIterator() returns an EventQueryIterator<> that can be used to iterate over query results (see Using EventQueryIterator<>).
EventQueryIterator<E> getIterator()
getNext()
EventQuery<>.getNext() returns an object of target class E from the resultset. It returns the first item in the resultset if the argument is null, or takes the object returned by the previous call to getNext() as an argument and returns the next item in the resultset. Returns null if there are no more items in the resultset.
E getNext(E obj)
parameter:
see also:
Processing Query Data
setFetchLevel()
EventQuery<>.setFetchLevel() controls the amount of data returned by setting a fetch level (see Defining the Fetch Level).
For example, by setting the fetch level to Event.FETCH_LEVEL_DATATYPES_ONLY, objects returned by this query will only have their datatype fields set, and any object type, array, or collection fields will not get populated. Using this option can dramatically improve query performance.
void setFetchLevel(int level)
parameter:
Supported fetch levels are:
setParameter()
EventQuery<>.setParameter() binds a parameter for the SQL query associated with this EventQuery<>.
void setParameter(int index, java.lang.Object value)
parameters:
see also:
Creating and Executing a Query
updateCurrent()
EventQuery<>.updateCurrent() updates the event most recently fetched by getNext().
void updateCurrent(E obj)
parameter:
see also:
Processing Query Data
Class EventQueryIterator<>
Class com.intersys.xep.EventQueryIterator<> is the primary way to retrieve, update and delete XEP events (the same task can be also achieved by direct use of EventQuery<> methods).
hasNext()
EventQueryIterator<>.hasNext() returns true if the query resultset has more items.
boolean hasNext()
next()
EventQueryIterator<>.next() fetches the next event in the query resultset.
E next()
remove()
EventQueryIterator<>.remove() deletes the last event fetched by next().
void remove()
set()
EventQueryIterator<>.set() replaces the last event fetched by next().
void set(E obj)
parameter:
Interface InterfaceResolver
By default, fields declared as interfaces are ignored during schema generation. To change this behavior, an implementation of InterfaceResolver can be passed to the importSchema() method, providing it with information that allows it to replace an interface type with the correct concrete type.
getImplementationClass()
InterfaceResolver.getImplementationClass() returns the actual type of a field declared as an interface. See Implementing an InterfaceResolver for details.
Class<?>  getImplementationClass (Class declaringClass, String fieldName, Class<?> interfaceClass) 
parameters:
Class XEPException
Class com.intersys.xep.XEPException implements the exception thrown by most methods of Event, EventPersister, and EventQuery<>. This class inherits from java.lang.RuntimeException.
Constructors
  XEPException (String message)
  XEPException (Throwable x, String message)
  XEPException (Throwable x)