Overview of Event Providers and Event Submission

In the context of SQL-NS applications, an event is usually some occurrence that is potentially interesting to a group of subscribers. For a SQL-NS application to match events against subscriptions, it needs to be given data that describes the events. Event providers are the components that detect events and submit the corresponding data about those events to SQL-NS applications. You can think of event providers as connectors between SQL-NS applications and event sources. A SQL-NS application may have several event providers submitting events from various event sources.

Note

SQL-NS terminology refers to the input of event data as event submission. Rarely is the distinction between the event data and the event itself called out; the term event is usually used to mean event data.

SQL-NS supports several kinds of event providers. In any SQL-NS application, the application domain and the sources of events usually determine the form of the event providers used. This section provides an overview of the various types of event providers and how to use them in SQL-NS applications. The remainder of this chapter goes into more detail about these event provider types.

Event Providers as Components Hosted in the SQL-NS Engine

As you've seen in previous chapters, the engine that drives a SQL-NS instance usually runs in a Windows service and connects to the database to perform processing. The SQL-NS engine hosts the running components of the instance's applications, including event providers, generators, and distributors.

Event providers that run inside the SQL-NS engine are called hosted event providers and can be thought of as part of the engine itself. SQL-NS provides three built-in hosted event providers: the FileSystemWatcherProvider, the SQLProvider, and the AnalysisServicesProvider. Each of these is described in more detail later in this chapter.

The framework for running event providers in the SQL-NS engine is extensible, so you can build your own custom hosted event providers. You write the code that implements the event provider operations, and the SQL-NS engine invokes it. Custom hosted event provider code is written in the form of a class that implements a SQL-NS event provider interface. In the ADF, you configure the SQL-NS application to use the event provider class. When the SQL-NS engine starts, it loads the event provider class and calls the event provider interface methods.

SQL-NS supports two kinds of custom hosted event providers: continuous and scheduled. Continuous event providers are started when the SQL-NS engine starts and run until the engine stops (or until an error condition forces them to stop). Scheduled event providers are started when the SQL-NS engine starts and then are periodically invoked according to a schedule configured in the ADF. The type of event provider appropriate for a given application depends on the event sources and the application semantics. The "Choosing an Event Provider Type" section (p. 265) later in this chapter provides some guidance on when to choose one type over the other.

Event Providers as Standalone Applications

SQL-NS also supports event providers that run as standalone applications, outside the SQL-NS engine. When implemented this way, event providers can take on any form and need not implement any particular interface mandated by SQL-NS.

Note

Standalone event providers are sometimes referred to as nonhosted event providers because they are not hosted within the SQL-NS engine. I find the term "nonhosted" a little awkward and prefer to use standalone when describing these event providers.

SQL-NS does not provide any built-in standalone event providers. If you want to use a standalone event provider in your application, you have to build it yourself. Building an event provider as a standalone application, rather than as a component hosted with the SQL-NS engine, offers several dimensions of flexibility. First, the event provider is not constrained within any particular framework or process model. Standalone event providers also give you complete control over their lifetime because they are not started and stopped with the SQL-NS engine. This usually makes them easier to invoke manually, for debugging or testing purposes. Furthermore, if you choose the standalone approach, the event provider functionality can be embedded within a larger application. In other words, although a standalone event provider can be a dedicated program whose sole purpose is to submit events, it can also be a feature in an application that has another primary purpose.

Standalone event providers can be written as console programs, Windows applications, web applications, or database applications. SQL-NS provides event submission APIs that can be used in all these kinds of applications. The "APIs for Building Custom Event Providers" section (p. 260) later in this chapter provides an overview of all the event submission APIs, and the code examples throughout the remainder of this chapter show them in use.

Building and Configuring Event Providers

If you're building a custom event provider, you first write the code that implements its operations and then configure it in the ADF. If you're using a built-in provider, you don't have to write any code, but you must still configure the provider in the ADF to customize it for your particular application.

When building a custom event provider, you then have a choice of three APIs that you can use to implement its event submission operations:

• The Event Object API, which represents each event as an object

• The XML Bulkload API, which reads event data from XML files

• The SQL-NS event submission stored procedures, which allow you to submit events from SQL code

These three APIs are described in more detail in the "APIs for Building Custom Event Providers" section (p. 260), later in this chapter.

Configuration information for event providers is specified in the <Providers> element of the ADF. Two types of subelements can go within the <Providers> element: <HostedProvider> and <NonHostedProvider>. The <HostedProvider> element declares a hosted event provider (one that runs within the SQL-NS engine), and the <NonHostedProvider> element declares a standalone event provider. You've already seen an example of the <NonHostedProvider> element in the configuration of the sample applications in earlier chapters.

For a hosted event provider, the configuration specifies the information that the SQL-NS engine needs to load the event provider on startup. For standalone event providers, the configuration is minimal: Only the event provider name is specified. We'll look at both the <HostedProvider> and <NonHostedProvider> elements in more detail as we work with the various event providers in this chapter.

You can add event providers to an existing application by adding the appropriate <HostedProvider> or <NonHostedProvider> elements to the ADF and then updating the instance (with nscontrol update or the Update Instance command in Management Studio). We'll use this technique in this chapter as we develop new event providers.