|
Using .NET with Caché eXTreme
XEP Quick Reference
|
|
-
-
Class
EventPersister — encapsulates an XEP database connection. It provides methods that set XEP options, establish an XEP 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:
PersisterFactory
EventPersister
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
Rollback() — rolls back the specified number of transaction levels, or all levels if no level is specified.
-
-
Event
EventQuery<>
InterfaceResolver
static EventPersister CreatePersister()
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 TCP/IP connection, import schema, and produce XEP Event objects. It also provides methods to control transactions and perform other tasks.
Object CallBytesClassMethod(string className, string methodName, params Object[] args)
-
className — fully qualified name of the Caché class to which the called method belongs.
-
-
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.
Object CallBytesFunction(string functionName, string routineName, params Object[] args)
-
-
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.
Object CallClassMethod(string className, string methodName, params Object[] args)
-
className — fully qualified name of the Caché class to which the called method belongs.
-
-
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.
Object CallFunction(string functionName, string routineName, params Object[] args)
-
-
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.
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.
-
className — fully qualified name of the Caché class to which the called method belongs.
-
-
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.
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.
-
-
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.
void CallProcedure(string procedureName, string routineName, params Object[] args)
-
-
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.
void CallVoidClassMethod(string className, string methodName, params Object[] args)
-
className — fully qualified name of the Caché class to which the called method belongs.
-
-
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()
void Connect(string host, int port, string nmspace, string username, string password)
-
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.
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)
If the specified class does not exist, the call silently fails (no error is thrown).
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.
System.Data.Common.DbConnection GetAdoNetConnection()
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)
-
className — class name of the object to be returned.
-
The following
indexMode options are available:
-
-
-
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.
InterfaceResolver GetInterfaceResolver()
int GetTransactionLevel()
string[] ImportSchema(string classOrDLLName)
string[] ImportSchema(string[] classes)
-
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.
string[] ImportSchemaFull(string classOrDLLName)
string[] ImportSchemaFull(string[] classes)
-
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.
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)
-
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.
void SetInterfaceResolver(InterfaceResolver interfaceResolver)
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()
EventQuery<T> CreateQuery(string sqlText)
void DeleteObject(long id)
void DeleteObject(object[] idkeys)
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)
static void IsEvent(object objectOrClass)
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()
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)
-
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.
void UpdateObject(long id, object obj)
void UpdateObject(object[] idkeys, object obj)
-
-
-
obj — new object that will replace the specified event.
bool WaitForIndexing(int timeout)
-
timeout — number of seconds to wait before timing out (wait forever if
-1, return immediately if
0).
void AddParameter(object val)
-
val — the value to be used for the next parameter in this query string.
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()
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.
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()
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)
-
level — fetch level constant (defined in the
Event class).
Supported fetch levels are:
void UpdateCurrent(E obj)
-
obj — the .NET object that will replace the current event.
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.
Type GetImplementationType(Type declaringClass, string fieldName, Type interfaceClass)