First Look: .NET Object Persistence with XEP
|
|
This First Look guide introduces the XEP API, which provides support for extremely fast .NET object storage and retrieval on the InterSystems IRIS Data Platform™. It gives you a high level overview of the XEP approach to .NET object persistence, and walks you through a simple scenario that demonstrates the main features of the API.
Object-oriented programming is at the core of the .NET framework, so it is natural for .NET applications to model data as objects. However, this can cause problems when the application needs to store that data in a database. If you use ADO.NET to store and retrieve objects, you are faced with the problem of transforming your object data into a set of relational tables, and then transforming query resultsets back into objects. The usual solution to this problem is to use an object-relational mapping (ORM) framework such as Entity Framework to automate the process. InterSystems IRIS does offer an Entity Framework interface, and InterSystems recommends it for large, complex object hierarchies. On the other hand, for applications that perform tasks such as real-time data acquisition, the main problem is speed rather than data complexity. Although Entity Framework is by no means slow (if properly optimized), XEP is a better alternative for tasks that require extremely fast storage and retrieval of simple or moderately complex data. In most cases, it will be considerably faster than either Entity Framework or ADO.NET.
XEP is a lightweight .NET API that projects .NET object data as
persistent events. A persistent event is an instance of an InterSystems IRIS class (normally a subclass of
%Persistent) containing a copy of the data fields in a .NET object. Like any such instance, it can be retrieved by object access, SQL query, or direct global access.
Before a persistent event can be created and stored, XEP must analyze the corresponding .NET class and
import a schema into the database. A schema defines the structure of the persistent event class that will be used to store the .NET objects. Importing the schema automatically creates a corresponding ObjectScript schema for the persistent event class if one does not already exist. The information from the analysis may be all that XEP needs to import a simple schema. For more complex structures, you can supply additional information that allows XEP to generate indexes and to override the default rules for importing fields.
After the schema has been created for a class, you can use various XEP methods to store, update, or delete events, run SQL queries, and iterate through query resultsets.
Now it’s time for you to try out XEP for yourself. This XepSimple demo is a very small program, but it provides examples for most of the key XEP features and will give you an overview of how the XEP API is used.
To run this demo you’ll need a machine with a running, licensed instance of InterSystems IRIS, the .NET framework, and Visual Studio.
Configuring the Visual Studio Project
Adding the Assembly Reference
-
-
-
-
-
Before creating the program source file, you will add a class that the main program will access to generate sample objects for storage. In Visual Studio, use
Project > Add Class to add a C# class file to the netxep project. The new file should appear under the project in the Solution Explorer.
Delete the default contents of the class file, and copy and paste the following code into the file.
using System;
namespace xep.samples
{
public class SingleStringSample {
public string name;
public SingleStringSample() { }
internal SingleStringSample(string str) {
name = str;
}
public static SingleStringSample[] generateSampleData(int objectCount) {
SingleStringSample[] data = new SingleStringSample[objectCount];
for (int i = 0; i < objectCount; i++)
{
data[i] = new SingleStringSample("single string test");
}
return data;
}
}
}
Because this class is very simple, XEP does not need any annotations to generate an effective schema from it. For more complex classes in a real-world application, you can use various options to optimize the import.
Now you are ready to create the XEPSimple demo program. In Visual Studio, find the default
program.cs file that was created when you created the project. Delete the default contents of the file and paste in the code below.
using System;
using InterSystems.XEP;
using xep.samples;
namespace XepSimpleNamespace
{
public class XepSimple
{
public static void Main(string[] args)
{
// Generate 12 SingleStringSample objects for use as test data
SingleStringSample[] sampleArray = SingleStringSample.generateSampleData(12);
// EventPersister
EventPersister xepPersister = PersisterFactory.CreatePersister();
String host = "127.0.0.1"; // localhost address for TCP/IP connection
int port = 51774; //port number for TCP/IP connection
String irisnamespace = "USER"; // InterSystems IRIS namespace
String username = "_system"; // Credentials for InterSystems IRIS
String password = "SYS"; //Credentials for InterSystems IRIS
xepPersister.Connect(host,port,irisnamespace,username,password); // connect to localhost
xepPersister.DeleteExtent("xep.samples.SingleStringSample"); // remove old test data
xepPersister.ImportSchema("xep.samples.SingleStringSample"); // import flat schema
// Event
Event xepEvent = xepPersister.GetEvent("xep.samples.SingleStringSample");
long[] itemIdList = xepEvent.Store(sampleArray);
int itemCount = 0;
for (int i = 0; i < itemIdList.Length; i++)
{
if (itemIdList[i] > 0) itemCount++;
}
Console.WriteLine("Stored " + itemCount + " of " + sampleArray.Length + " events");
// EventQuery
EventQuery<SingleStringSample> xepQuery = null;
String sqlQuery = "SELECT * FROM xep_samples.SingleStringSample WHERE %ID BETWEEN ? AND ?";
xepQuery = xepEvent.CreateQuery<SingleStringSample>(sqlQuery);
xepQuery.AddParameter(3); // assign value 3 to first SQL parameter
xepQuery.AddParameter(12); // assign value 12 to second SQL parameter
xepQuery.Execute(); // get resultset for IDs between 3 and 12
xepQuery.Close();
xepEvent.Close();
xepPersister.Close();
} // end main()
} // end class xepSimple
}
The demo program is divided into three sections, each of which demonstrates one of the three main XEP classes,
EventPersister,
Event, and
EventQuery. When run, the XepSimple demo program performs the following tasks:
-
-
It creates an instance named
xepPersister, which establishes a TCP/IP connection to the
User namespace in the database and deletes any existing sample data. It then calls
ImportSchema() to analyze the sample class and send the schema to the database, thus creating an the corresponding ObjectScript schema to hold persistent
SingleStringSample objects.
-
Once the schema has been generated,
xepPersister can create an
Event object named
xepEvent for the sample class. The
Store() method stores the array of .NET objects as persistent events.
-
-
When processing is done, it cleans up by calling the
close() methods for the XEP objects.
The code you have inserted into program.cs contains connection variables that must match your InterSystems IRIS environment. Make sure to edit the
superserverPort,
irisnamespace,
username, and
password variables to have accurate values.
-
-
The
irisnamespace variable is a valid InterSystems IRIS namespace.
-
The
username and
password are the credentials you used when installing InterSystems IRIS. If you chose to use the default account, the
username is
_system.
You are now ready to build and run the XEPSimple demo program. Press
Ctrl + F5 to run the program so the command prompt stays open when the program ends.
The XepSimple demo is designed to give you a taste of XEP without bogging you down in details, and is not a model for real production code it didn’t even bother with exception checking. The most important simplification was in the sample data. You persisted a few tiny .NET objects from a class that doesn’t require annotation or other mechanisms to aid in schema generation and optimization. Though you usually need annotations and other options in a real world application, these options are straightforward and easy to use. The APIs are similarly simple and easy to use.
InterSystems IRIS provides .NET APIs for easy database access via SQL tables, objects, and multidimensional storage. See the following books for detailed information on each type of access:
Content Date/Time: 2019-02-18 00:56:43