APIs for Building Custom Event Providers
| The previous section explained the use of two SQL-NS built-in event providers. The built-in event providers are convenient and flexible enough to use in most applications, just by supplying the required configuration information in the ADF. But if your application needs event provider capabilities beyond those available in the built-in event providers, you will need to implement a custom event provider. Building a custom event provider involves writing code that implements the event submission operations. For example, the code for a custom event provider might read event data from an event source on the network, transform that data in some way, and then submit it as events to a SQL-NS application. The next two sections of this chapter cover custom event provider implementation in detail. In preparation for that material, this section explains the SQL-NS APIs used in event provider development. These APIs, called event submission APIs, offer convenient ways to transfer event data into the events tables in SQL-NS application databases. Note The event submission APIs are common to all the event provider forms. Regardless of whether you're building a hosted, scheduled event provider or a standalone event provider, you use the APIs described in this section to submit events to your SQL-NS application. For this reason, the APIs are described here independently of any particular event provider type. In the code samples later in this chapter, you'll see these APIs put to practical use in various kinds of event providers. SQL-NS has three sets of event submission APIs, each of which provides a different way to submit events. This section is an overview that describes the facilities that the three APIs offer. Which API is appropriate for your event provider depends largely on the form in which you obtain event data from the event source. When you understand these APIs, you'll be able to determine which is the most natural fit for the particular event source and event data you're working with. As with all other descriptions of APIs in this book, the information presented here is not intended to replace the exhaustive reference information provided in the SQL-NS Books Online. This book's examples show the most useful parts of the APIs and illustrate some typical usage patterns, but you should always consult the SQL-NS Books Online as the ultimate reference. The Event Object APIAs its name suggests, the Event Object API represents events as objects that the event provider code can manipulate. Event provider implementations can create event objects, set data properties on them, and then submit them to the SQL-NS application in batches. Internally, the Event Object API writes the data stored in the properties of the event objects to the events tables. The Event Object API consists of two classes: Event and EventCollector. Typically, an event provider instantiates one event collector object (an instance of the EventCollector class), which acts as a gathering point for events. It creates Event objects to represent individual events and submits these to the event collector to form a batch. The event collector then writes the event data to the events table in the SQL-NS application database. Note It turns out that Event was a poor choice for the name of the class that represents events. When someone says "event class," it can be unclear whether he is referring to the class, Event, in the Event Object API, or the ADF concept of an event class (which defines a type of event that an application may receive). However, despite this apparent confusion, the meaning should be discernable from the context in which the term is used. When you create an EventCollector object, you initialize it with an NSApplication object (that represents a connection to the SQL-NS application) and the event provider name. It is then ready to start collecting events. To submit a single event, you create an Event object. You initialize it with an NSApplication object and the name of the event class (as declared in the ADF) to which the event belongs. You then provide a value for each of the event class fields by setting properties in the object. After you have provided values for all the event fields, you call the event collector's Write() method, passing the event object as an argument. You then repeat this process for each event you want to submit, creating a new Event object each time. The first time you call the event collector's Write() method, it starts a new event batch. Each subsequent call adds a new event to that same batch. After you have submitted all the events that make up an event batch, you can call the event collector's Commit() method to commit all the collected events to the application database. Until you call the Commit() method on the event collector, the batch is treated as incomplete, and none of the events will be processed. After calling Commit(), the event batch will be marked complete and is eventually picked up by the generator for processing. Figure 8.6 illustrates this sequence of calls. Several sample event providers described later in this chapter use the Event Object API. Figure 8.6. Objects and calls in the Event Object API. The EventCollector class also provides a facility for aborting the collection of an event batch. If, instead of calling Commit(), you call the Abort() method, the event batch will be abandoned in its current state, and none of the events submitted up to that point will ever be processed. The first call to the event collector's Write() method after calling either Commit() or Abort() begins a new event batch. Thereafter, all subsequent events passed to the Write() method become part of that same batch, until either Commit() or Abort() is called again. The XML Bulkload Event APIThe XML Bulkload Event API provides a way to submit event data represented in XML form. The API takes a single XML document that contains the data for a whole batch of events and submits those events to the SQL-NS application. This saves the event provider implementation from having to manually parse the event data in the XML file. The FileSystemWatcherProvider built-in event provider uses this API: When it detects a new XML file in the events watch directory, it passes the file to the XML Bulkload API for processing. In custom event providers, you can use this API to submit events, but you need not use the file watching mechanism that the FileSystemWatcherProvider employs. Instead, you can obtain the XML event data from a web service or another XML-based event source. The XML Bulkload API consists of a single class, EventLoader. In event provider implementation, you create an EventLoader object and initialize it with an NSApplication object, the event provider name, the name of an event class, and the name of an XSD schema file that describes the structure of the XML files it will process. To submit an XML file containing events, you call the LoadXml() method, passing the name of the XML file. The file must contain events of the event class specified in the call to the EventLoader constructor. All the events in the file will be submitted as a single batch. Figure 8.7 illustrates this process. The XML Bulkload API is used in the sample standalone event provider developed later in this chapter (see the section, "A Dedicated Program: The XML Event Provider," p. 292). Figure 8.7. Event submission with the XML Bulkload API. SQL Stored Procedures for Event SubmissionSQL-NS provides a set of stored procedures that you can use to submit events directly from SQL code. The SQL-NS compiler creates these stored procedures in the application database when it compiles the event classes declared in the ADF. For each event class, the compiler generates the following four stored procedures:
You use the first three stored procedures if you want to submit events one at a time, and you use the fourth, NSEventSubmitBatch<EventClass>, if you want to submit a whole set of events in a single call. Figure 8.8 shows these stored procedures in use. Figure 8.8. Use of the event submission stored procedures. In the names of the actual stored procedures, <EventClass> is replaced by the event class name. For example, the stored procedure that starts a new event batch of the SongAdded event class in the music store application will be called NSEventBeginBatchSongAdded. You can call these stored procedures from any context in which SQL code can be invoked. One common practice is to call these stored procedures in triggers defined on tables in your application. When changes occur that invoke the triggers, the trigger code can submit the appropriate events to your SQL-NS application. In the "Submitting Events with SQL Stored Procedures" section (p. 302) later in this chapter, you'll see code that invokes these stored procedures. Note As you saw in previous chapters, the SQL-NS compiler also creates event class views that can be used to submit event data from SQL code via direct inserts. The main reason to use the stored procedures instead of the views is that the stored procedures offer you control over how events are grouped into batches. When you insert into an event view, each event row becomes its own batch; using the view, there is no way to group two or more events into a single batch. Note It's important to distinguish the stored procedures described here from the built-in SQLProvider event provider described earlier. These stored procedures are just APIs that you can use to build your own custom event provider, using SQL code. In contrast, the SQLProvider is a complete event provider that happens to use SQL queries to obtain event data. You can use the SQLProvider in your application by just customizing the SQL queries that it uses. |
EAN: 2147483647
Pages: 166