XEP Quick Reference
This chapter is a quick reference for the classes that are most important to an understanding of XEP. The InterSystems.XEP namespace contains the public API described in Using XEP Event Persistence.
This is not the definitive reference for this API. For the most complete and up-to-date information, see the help file, located in <install-dir>/dev/dotnet/help/CacheExtreme.chm.
XEP Quick Reference
This section is a reference for the XEP API (namespace InterSystems.XEP). See Using XEP Event Persistence for a details on how to use the API. It contains the following classes and interfaces:
-
Class PersisterFactory — provides a factory method to create EventPersister objects.
-
Class EventPersister — encapsulates an XEP database connection. It provides methods that set XEP options, establish a connection or get an existing connection object, import schema, produce XEP Event objects, call Caché functions and methods on the server, and control transactions.
-
Class Event — encapsulates a reference to an XEP persistent event. It provides methods to store or delete events, create a query, and start or stop index creation.
-
Class EventQuery<> — encapsulates a query that retrieves individual events of a specific type from the database for update or deletion.
-
Interface InterfaceResolver — resolves the actual type of a property during flat schema importation if the property was declared as an interface.
-
Class XEPException — is the exception thrown by most XEP methods.
List of XEP Methods
The following classes and methods of the XEP API are described in this reference:
-
CreatePersister() — creates a new EventPersister object.
-
CallBytesClassMethod() — calls a Caché class method, returning strings as byte[].
-
CallBytesFunction() — calls a Caché function, returning strings as byte[].
-
CallClassMethod() — calls a Caché class method.
-
CallFunction() — calls a Caché function.
-
CallListClassMethod() — calls a Caché class method, returning strings as ValueList.
-
CallListFunction() — calls a Caché function, returning strings as ValueList.
-
CallProcedure() — calls a Caché procedure.
-
CallVoidClassMethod() — calls a Caché class method with no return value.
-
Close() — releases all resources held by this instance.
-
Commit() — commits one level of transaction.
-
Connect() — connects to Caché via TCP/IP using the arguments specified.
-
DeleteClass() — deletes a Caché class.
-
DeleteExtent() — deletes all objects in the given extent.
-
GetAdoNetConnection() — returns the .NET DbConnection object.
-
GetEvent() — returns an event object that corresponds to the class name supplied.
-
GetInterfaceResolver() — returns the currently specified instance of InterfaceResolver.
-
GetTransactionLevel() — returns the current transaction level (or 0 if not in a transaction).
-
ImportSchema() — imports a flat schema.
-
ImportSchemaFull() — imports a full schema.
-
Rollback() — rolls back the specified number of transaction levels, or all levels if no level is specified.
-
SetInterfaceResolver() — specifies the InterfaceResolver object to be used.
-
StartTransaction() — starts a transaction (which may be a nested transaction).
-
Close() — releases all resources held by this instance.
-
CreateQuery() — creates an EventQuery<> instance.
-
DeleteObject() — deletes an event given its database Id or IdKey.
-
GetObject() — returns an event given its database Id or IdKey.
-
IsEvent() — checks whether an object (or class) is an event in the XEP sense.
-
StartIndexing() — starts index building for the underlying class.
-
StopIndexing() — stops index building for the underlying class.
-
Store() — stores the specified object or array of objects.
-
UpdateObject() — updates an event given its database Id or IdKey.
-
WaitForIndexing() — waits for asynchronous indexing to be completed for this class.
-
AddParameter() — binds a parameter for this query.
-
Close() — releases all resources held by this instance.
-
DeleteCurrent() — deletes the event most recently fetched by GetNext().
-
Execute() — executes this XEP query.
-
GetAll() — fetches all events in the resultset as an array.
-
GetFetchLevel() — returns the current fetch level.
-
GetNext() — fetches the next event in the resultset.
-
SetFetchLevel() — controls the amount of data returned.
-
UpdateCurrent() — updates the event most recently fetched by GetNext()
-
GetImplementationClass() — if a property was declared as an interface, an implementation of this method can be used to resolve the actual property type during schema importation.
Class PersisterFactory
Class InterSystems.XEP.PersisterFactory creates a new EventPersister object.
Creates a new instance of PersisterFactory.
PersisterFactory()
PersisterFactory.CreatePersister() returns an instance of EventPersister.
static EventPersister CreatePersister()
see also:
Class EventPersister
Class InterSystems.XEP.EventPersister is the main entry point for the XEP module. It provides methods that can be used to control XEP options, establish a connection, import schema, and produce XEP Event objects. It also provides methods to control transactions and perform other tasks.
EventPersister.CallBytesClassMethod() — calls an ObjectScript class method and returns an Object that may be of type int, long, double, or byte[].
This method is identical to CallClassMethod() except that it returns string values as instances of byte[] rather than String.
Object CallBytesClassMethod(string className, string methodName, params Object[] args)
parameters:
-
className — fully qualified name of the Caché class to which the called method belongs.
-
methodName — name of the Caché class method.
-
args — a list of 0 or more arguments to pass to the class method.
Arguments may be of type int, long, double, String, or byte[]. Trailing arguments may be omitted, causing default values to be used for those arguments, either by passing fewer than the full number of arguments, or by passing null for trailing arguments. Throws an exception if a non-null argument is passed to the right of a null argument.
EventPersister.CallBytesFunction() calls an ObjectScript function (see “User-defined Code” in Using Caché ObjectScript) and returns an Object that may be of type int, long, double, or byte[].
This method is identical to CallFunction() except that it returns string values as instances of byte[] rather than String.
Object CallBytesFunction(string functionName, string routineName, params Object[] args)
parameters:
-
functionName — name of the function.
-
routineName — name of the routine containing the function.
-
args — a list of 0 or more arguments to pass to the function.
Arguments may be of type int, long, double, String, or byte[]. Trailing arguments may be omitted, causing default values to be used for those arguments, either by passing fewer than the full number of arguments, or by passing null for trailing arguments. Throws an exception if a non-null argument is passed to the right of a null argument.
EventPersister.CallClassMethod() — calls an ObjectScript class method and returns an Object that may be of type int, long, double, or String. Use CallVoidClassMethod() to call a method that doesn’t return a value, CallBytesClassMethod() to return string values as byte[], or CallListClassMethod() to return string values as ValueList.
Object CallClassMethod(string className, string methodName, params Object[] args)
parameters:
-
className — fully qualified name of the Caché class to which the called method belongs.
-
methodName — name of the Caché class method.
-
args — a list of 0 or more arguments to pass to the class method.
Arguments may be of type int, long, double, String, or byte[]. Trailing arguments may be omitted, causing default values to be used for those arguments, either by passing fewer than the full number of arguments, or by passing null for trailing arguments. Throws an exception if a non-null argument is passed to the right of a null argument.
EventPersister.CallFunction() — calls an ObjectScript function (see “User-defined Code” in Using Caché ObjectScript) and returns an Object that may be of type int, long, double, or String. Use CallBytesFunction() to return string values as byte[], or CallListFunction() to return string values as ValueList.
Object CallFunction(string functionName, string routineName, params Object[] args)
parameters:
-
functionName — name of the function.
-
routineName — name of the routine containing the function.
-
args — a list of 0 or more arguments to pass to the function.
Arguments may be of type int, long, double, String, or byte[]. Trailing arguments may be omitted, causing default values to be used for those arguments, either by passing fewer than the full number of arguments, or by passing null for trailing arguments. Throws an exception if a non-null argument is passed to the right of a null argument.
EventPersister.CallListClassMethod() — calls an ObjectScript class method and returns an Object that may be of type int, long, double, or ValueList.
This method is identical to CallClassMethod() except that it returns string values as instances of ValueList rather than String.
Object CallListClassMethod(string className, string methodName, params Object[] args)
Throws an exception if the return value is a string but is not in valid ValueList format.
parameters:
-
className — fully qualified name of the Caché class to which the called method belongs.
-
methodName — name of the Caché class method.
-
args — a list of 0 or more arguments to pass to the class method.
Arguments may be of type int, long, double, String, or byte[]. Trailing arguments may be omitted, causing default values to be used for those arguments, either by passing fewer than the full number of arguments, or by passing null for trailing arguments. Throws an exception if a non-null argument is passed to the right of a null argument.
EventPersister.CallListFunction() calls an ObjectScript function (see “User-defined Code” in Using Caché ObjectScript) and returns an Object that may be of type int, long, double, or ValueList.
This method is identical to CallFunction() except that it returns string values as instances of ValueList rather than String.
Object CallListFunction(string functionName, string routineName, params Object[] args)
Throws an exception if the return value is a string but is not in valid ValueList format.
parameters:
-
functionName — name of the function.
-
routineName — name of the routine containing the function.
-
args — a list of 0 or more arguments to pass to the function.
Arguments may be of type int, long, double, String, or byte[]. Trailing arguments may be omitted, causing default values to be used for those arguments, either by passing fewer than the full number of arguments, or by passing null for trailing arguments. Throws an exception if a non-null argument is passed to the right of a null argument.
EventPersister.CallProcedure() calls an ObjectScript procedure (see “User-defined Code” in Using Caché ObjectScript).
void CallProcedure(string procedureName, string routineName, params Object[] args)
parameters:
-
procedureName — name of the procedure.
-
routineName — name of the routine containing the procedure.
-
args — a list of 0 or more arguments to pass to the procedure.
Arguments may be of type int, long, double, String, or byte[]. Trailing arguments may be omitted, causing default values to be used for those arguments, either by passing fewer than the full number of arguments, or by passing null for trailing arguments. Throws an exception if a non-null argument is passed to the right of a null argument.
EventPersister.CallVoidClassMethod() — calls an ObjectScript class method with no return value, passing 0 or more arguments. This method may be used to call any Caché class method (regardless of whether it normally returns a value) when the caller does not need the return value. Use CallClassMethod() to call a method that returns a value.
void CallVoidClassMethod(string className, string methodName, params Object[] args)
parameters:
-
className — fully qualified name of the Caché class to which the called method belongs.
-
methodName — name of the Caché class method.
-
args — a list of 0 or more arguments to pass to the class method.
-
Arguments may be of any of the types int, long, double, String, or byte[]. Trailing arguments may be omitted, causing default values to be used for those arguments, either by passing fewer than the full number of arguments, or by passing null for trailing arguments. Throws an exception if a non-null argument is passed to the right of a null argument.
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()
EventPersister.Commit() commits one level of transaction
void Commit()
EventPersister.Connect() establishes a connection to the specified namespace.
void Connect(string host, int port, string nmspace, string username, string password)
parameters:
-
nmspace — namespace to be accessed.
-
username — username for this connection.
-
password — password for this connection.
-
host — host address for TCP/IP connection.
-
port — port number for TCP/IP connection.
see also:
EventPersister.DeleteClass() deletes a Caché class definition. It does not delete objects associated with the extent (since objects can belong to more than one extent), and does not delete any dependencies (for example, inner or embedded classes).
void DeleteClass(string className)
parameter:
-
className — name of the class to be deleted.
If the specified class does not exist, the call silently fails (no error is thrown).
see also:
“Deleting Test Data” in Accessing Stored Events
EventPersister.DeleteExtent() deletes the extent definition associated with a .NET event, but does not destroy associated data (since objects can belong to more than one extent). See “Extents” in Using Caché Objects for more information on managing extents.
void DeleteExtent(string className)
-
className — name of the extent.
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
EventPersister.GetAdoNetConnection() returns the .NET DbConnection object underlying an EventPersister connection.
System.Data.Common.DbConnection GetAdoNetConnection()
see also:
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:
-
className — class name of the object to be returned.
-
indexMode — indexing mode to be used.
The following indexMode options are available:
-
Event.INDEX_MODE_ASYNC_ON — enables asynchronous indexing. This is the default when the indexMode parameter is not specified.
-
Event.INDEX_MODE_ASYNC_OFF — no indexing will be performed unless the StartIndexing() method is called.
-
Event.INDEX_MODE_SYNC — indexing will be performed each time the extent is changed, which can be inefficient for large numbers of transactions. This index mode must be specified if the class has a user-assigned IdKey.
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
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:
EventPersister.GetTransactionLevel() returns the current transaction level (0 if not in a transaction)
int GetTransactionLevel()
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 .dll file specified (including dependencies), and returns an array of class names for the imported events.
string[] ImportSchema(string classOrDLLName) string[] ImportSchema(string[] classes)
parameters:
-
classes — an array containing the names of the classes to be imported.
-
classOrDLLName — a class name or the name of a .dll file containing the classes to be imported. If a .dll file is specified, all classes in the file will be imported.
If the argument is a class name, the corresponding class and any dependencies will be imported. If the argument is a .dll 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 .NET 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:
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 .dll file specified (including dependencies), and returns an array of class names for the imported events.
string[] ImportSchemaFull(string classOrDLLName) string[] ImportSchemaFull(string[] classes)
parameters:
-
classes — an array containing the names of the classes to be imported.
-
classOrDLLName — a class name or the name of a .dll file containing the classes to be imported. If a .dll file is specified, all classes in the file will be imported.
If the argument is a class name, the corresponding class and any dependencies will be imported. If the argument is a .dll 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 .NET 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:
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:
-
level — optional number of levels to roll back.
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.
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:
-
interfaceResolver — an implementation of InterfaceResolver that will be used by ImportSchema() to determine the actual type of properties declared as interfaces. This argument can be null.
see also:
EventPersister.StartTransaction() starts a transaction (which may be a nested transaction)
void StartTransaction()
Class Event
Class InterSystems.XEP.Event provides methods that operate on XEP events (storing events, creating a query, indexing etc.). It is created by the EventPersister.GetEvent() method.
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()
Event.CreateQuery() takes a String argument containing the text of the SQL query and returns an instance of EventQuery<T>, where parameter T is the target class of the parent Event.
EventQuery<T> CreateQuery(string sqlText)
parameter:
-
sqlText — text of the SQL query.
see also:
Event.DeleteObject() deletes an event identified by its database object ID or IdKey.
void DeleteObject(long id) void DeleteObject(object[] idkeys)
parameter:
-
id — database object ID
-
idkeys — an array of objects that make up the IdKey (see “Using IdKeys”). An XEPException will be thrown if the underlying class has no IdKeys or if any of the keys supplied is equal to null or of an invalid type.
see also:
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:
-
id — database object ID
-
idkeys — an array of objects that make up the IdKey (see “Using IdKeys”). An XEPException will be thrown if the underlying class has no IdKeys or if any of the keys supplied is equal to null or of an invalid type.
see also:
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:
-
objectOrClass — the object to be tested.
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()
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:
Event.Store() stores a .NET object or array of objects as persistent events. 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 obj) long[] Store(object[] objects)
parameters:
-
obj — .NET object to be added to the database.
-
objects — array of .NET objects to be added to the database. All objects must be of the same type.
Event.UpdateObject() updates an event identified by its database ID or IdKey.
void UpdateObject(long id, object obj) void UpdateObject(object[] idkeys, object obj)
parameter:
-
id — database object ID
-
idkeys — an array of objects that make up the IdKey (see “Using IdKeys”). An XEPException will be thrown if the underlying class has no IdKeys or if any of the keys supplied is equal to null or of an invalid type.
-
obj — new object that will replace the specified event.
see also:
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.
bool WaitForIndexing(int timeout)
parameter:
-
timeout — number of seconds to wait before timing out (wait forever if -1, return immediately if 0).
see also:
Class EventQuery<>
Class InterSystems.XEP.EventQuery<> can be used to retrieve, update and delete individual events from the database.
EventQuery<>.AddParameter() binds the next parameter in sequence for the SQL query associated with this EventQuery<>.
void AddParameter(object val)
parameter:
-
val — the value to be used for the next parameter in this query string.
see also:
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()
EventQuery<>.DeleteCurrent() deletes the event most recently fetched by GetNext().
void DeleteCurrent()
see also:
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<> methods.
void Execute()
see also:
EventQuery<>.GetAll() returns objects of target class E from all rows in the resultset as a single list.
System.Collections.Generic.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()
EventQuery<>.GetFetchLevel() returns the current fetch level (see “Defining the Fetch Level”).
int GetFetchLevel()
EventQuery<>.GetNext() returns an object of target class E from the next row of the resultset. Returns null if there are no more items in the resultset.
E GetNext()
see also:
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 properties set, and any object type, array, or collection properties will not get populated. Using this option can dramatically improve query performance.
void SetFetchLevel(int level)
parameter:
-
level — fetch level constant (defined in the Event class).
Supported fetch levels are:
-
Event.FETCH_LEVEL_ALL —default, all properties populated
-
Event.FETCH_LEVEL_DATATYPES_ONLY —only datatype properties filled in
-
Event.FETCH_LEVEL_NO_ARRAY_TYPES —all arrays will be skipped
-
Event.FETCH_LEVEL_NO_OBJECT_TYPES —all object types will be skipped
-
Event.FETCH_LEVEL_NO_COLLECTIONS —all collections will be skipped
EventQuery<>.UpdateCurrent() updates the event most recently fetched by GetNext().
void UpdateCurrent(E obj)
parameter:
-
obj — the .NET object that will replace the current event.
see also:
Interface InterfaceResolver
By default, properties 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.
InterfaceResolver.GetImplementationClass() returns the actual type of a property declared as an interface. See “Implementing an InterfaceResolver” for details.
Type GetImplementationType(Type declaringClass, string fieldName, Type interfaceClass)
parameters:
-
declaringClass — class where fieldName is declared as interfaceClass.
-
fieldName — name of the property in declaringClass that has been declared as an interface.
-
interfaceClass — the interface to be resolved.
Class XEPException
Class InterSystems.XEP.XEPException implements the exception thrown by most methods of Event, EventPersister, and EventQuery<>. This class inherits methods and properties from System.SystemException.
