This chapter is from the book
This chapter is from the book
This chapter is from the book
Building the Stock Application's ADF
The ADF for the stock application defines its schemas and logic, as well as its component configuration. The schemas describe the size and shape of events, subscriptions, and notifications; the logic defines how events and subscriptions are matched to produce notifications. The component configuration tells SQL-NS how to actually run the application.
Table 3.1 shows the high-level structure of the ADF (with the application-specific details removed). Think of this as a basic outline for every ADF you will ever write. A root <Application> element contains various other XML elements that define the parts of the application. This section describes the content that goes in each of these XML elements to create a real application.
NOTE
I've left some optional ADF elements out of Table 3.1 for clarity. These include the <History>, <Version>, <ApplicationExecutionSettings>, and <Database> elements. These elements are described in the SQL-NS Books Online, and some of them are discussed in Chapter 11, "Debugging Notification Generation"; Chapter 12, "Performance Tuning"; and Chapter 13, "Deploying a Notification Services Application."
Table 3.1 Basic Structure of the ADF
|
XML Element |
Purpose |
|
<?xml version="1.0" |
Standard XML header encoding="utf-8" ?> |
|
<Application xmlns:xsd=http://www.w3.org/2001/XMLSchema |
Root element that contains all of the application definition |
|
<EventClasses></EventClasses> |
Defines schemas for the events the application will receive |
|
<SubscriptionClasses></SubscriptionClasses> |
Defines schemas and matching logic for the subscriptions the application will support |
|
<NotificationClasses></NotificationClasses> |
Defines schemas for the notifications the application will send |
|
<Providers></Providers> |
Configures the application's event providers |
|
<Generator></Generator> |
Configures the generator component that matches events with subscriptions |
|
<Distributors></Distributors> |
Configures the distributor components that deliver notifications |
|
</Application> |
Closing tag for the root element |
The first three sub-elements under <Application>, <Event Classes>, <SubscriptionClasses>, and <NotificationClasses>, contain all the schemas and logic. The rest of the elements provide the component configuration.
The Completed ADF
Before delving into the details of each specific section, take a look at the completed ADF, shown in Listing 3.1. I'm including this here, even before I explain what any of it means, because I find that with almost any program, it helps to get a feel for the code by looking at it from beginning to end. Just by glancing at it, the ADF will probably make some sense to you, even without further explanation. The following sections describe the important parts in detail.
Listing 3.1 The Completed Stock ADF
<?xml version="1.0" encoding="utf-8" ?> <Application xmlns:xsd="xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
Schemas and Logic
This section describes the ADF syntax used to define the event, subscription, and notification schemas. This section also shows how the matching logic, expressed as a SQL join, is specified in the ADF.
Event Schemas
For each type of event that the application receives (there can be more than one), you must declare an event class in the <EventClasses> element of the ADF.
The stock application uses only a single type of event: a change in the trading price of a stock. Within the <EventClasses> element of the ADF, you declare an <EventClass> for this type of event, as shown in Listing 3.2.
Listing 3.2 Declaration of the StockPriceChange Event Class
<EventClass>
<EventClassName>StockPriceChange</EventClassName>
<Schema>
<Field>
<FieldName>StockSymbol</FieldName>
<FieldType>nvarchar(10)</FieldType>
<FieldTypeMods>not null</FieldTypeMods>
</Field>
<Field>
<FieldName>StockPrice</FieldName>
<FieldType>decimal(10,2)</FieldType>
<FieldTypeMods>not null</FieldTypeMods>
</Field>
</Schema>
</EventClass>
The declaration provides a name, StockPriceChanges, for the event class and a schema for the event data. The schema declaration should look familiar to you if you've built database schemas before: The syntax is basically an XML version of a SQL CREATE TABLE statement. It declares a set of fields, specifying a data type and, optionally, a type modifier (such as not null) for each.
When building the application's database, the SQL-NS compiler processes this event class declaration and constructs the underlying table that ultimately stores the events. It creates a column for each of the fields declared and adds some other columns used for internal tracking.
Subscription Schemas
Just as you have to declare an event class for each type of event the application receives, you also have to declare a subscription class for each type of subscription that the application supports. This simple stock application has only one type of subscription: a request to be notified when a stock hits a particular price target. In the completed ADF, this subscription class declaration goes within the <SubscriptionClasses> element. Listing 3.3 shows the subscription class declaration.
Listing 3.3 Declaration of the StockPriceHitsTarget Subscription Class
<SubscriptionClass>
<SubscriptionClassName>StockPriceHitsTarget</SubscriptionClassName>
<Schema>
<Field>
<FieldName>StockSymbol</FieldName>
<FieldType>nvarchar(10)</FieldType>
<FieldTypeMods>not null</FieldTypeMods>
</Field>
<Field>
<FieldName>StockPriceTarget</FieldName>
<FieldType>decimal(10,2)</FieldType>
<FieldTypeMods>not null</FieldTypeMods>
</Field>
</Schema>
<EventRules>
...
</EventRules>
</SubscriptionClass>
The subscription class declaration has three subelements: a name, schema, and set of event rules (content not shown in the fragment in Listing 3.3). The schema subelement defines the size and shape of the subscription data. We've said that subscriptions of this class will have the form
"Notify me when the price of stock S goes above price target T."
The subscription data for each subscription then just consists of values for S and T. In the subscription class schema, we've given these fields the more descriptive names StockSymbol and StockPriceTarget and provided their data types and type modifiers.
The rules section, declared in the <EventRules> subelement, contains logic that matches events with subscriptions. This is discussed in the "Matching Logic" section.
Notification Schemas
The <EventClasses> and <SubscriptionClasses> elements define the schemas for the application's events and subscriptions. When the matching logic is applied, the result is a set of notification data that represents the notifications to be sent to subscribers. This notification data has a schema as well, and must be declared in the <NotificationClasses> element of the ADF. This section can contain schema definitions for several types of notifications, but because this example stock application just sends one type of notification, there is just a single <NotificationClass> declaration, shown in Listing 3.4.
Listing 3.4 Declaration of the StockAlert Notification Class
<NotificationClass>
<NotificationClassName>StockAlert</NotificationClassName>
<Schema>
<Fields>
<Field>
<FieldName>StockSymbol</FieldName>
<FieldType>nvarchar(10)</FieldType>
</Field>
<Field>
<FieldName>StockPrice</FieldName>
<FieldType>decimal(10,2)</FieldType>
</Field>
<Field>
<FieldName>StockPriceTarget</FieldName>
<FieldType>decimal(10,2)</FieldType>
</Field>
</Fields>
</Schema>
<ContentFormatter>
...
</ContentFormatter>
<Protocols>
...
</Protocols>
</NotificationClass>
Much like in the event and subscription class declarations, the <Schema> element provides the names and data types of the notification fields. The <ContentFormatter> section describes how the notification data is formatted for receipt by the subscriber, and the <Protocols> section declares which delivery protocols can be used to actually send the notifications. The <ContentFormatter> and <Protocols> elements are discussed in later chapters.
The StockAlert notification schema has three fields: the stock symbol, stock price, and stock price target. Each row of notification data produced by the matching join contains a value for each of these fields. The stock price field contains the current price of the stock (as indicated by the stock event), and the stock price target field contains the price target specified in the subscription. From this notification data, the application can synthesize formatted stock alert messages such as
"XYZ is now trading at: $55.55. This is greater than or equal to the target price of $50.00."
for delivery to the subscribers.
Matching Logic
The stock application's matching logic is specified in the <EventRules> section of the subscription class. This section contains one or more SQL statements that get executed when events arrive. Each of these SQL statements is called a rule and is declared in an <EventRule> element. Each rule specifies a name, an action (the SQL code that gets executed), and the name of the event class that triggers it.
Listing 3.5 shows the <EventRules> element of the StockPriceHitsTarget subscription class. It declares a single rule, MatchStockPricesWithTargets, that simply matches incoming events with StockPriceHitsTarget subscriptions. The <EventClassName> element of the rule declaration specifies the name of the triggering event class, in this case, StockPriceChange. This instructs the SQL-NS execution engine that, whenever events of the StockPriceChange event class arrive, this event rule must be fired.
Listing 3.5 Event Rules Declaration Within the StockPriceHitsTarget Subscription Class
<EventRules>
<EventRule>
<RuleName>MatchStockPricesWithTargets</RuleName>
<Action>
...
</Action>
<EventClassName>StockPriceChange</EventClassName>
</EventRule>
</EventRules>
The matching logic is really specified in the rule's <Action> element. Listing 3.6 shows the contents of the <Action> element.
Listing 3.6 The SQL Matching Logic from the Event Rule's <Action> Element
SELECT dbo.StockAlertNotify(
subscriptions.SubscriberId,
N'DefaultDevice',
N'en-US',
events.StockSymbol,
events.StockPrice,
subscriptions.StockPriceTarget)
FROM StockPriceChange events
JOIN StockPriceHitsTarget subscriptions
ON events.StockSymbol = subscriptions.StockSymbol
WHERE events.StockPrice >= subscriptions.StockPriceTarget
This logic is just a SQL join that produces a set of rows that become notification data.
The first thing to look at in this join is the FROM clause. It selects from StockPriceChange joined with StockPriceHitsTarget. Note that these are just the names of the event class and subscription class declared earlier. SQL-NS allows you to use these names directly in the join statement, as though they were SQL tables containing the event and subscription data. StockPriceChange is given the table alias events, and StockPriceHitsTarget is given the table alias subscriptions for clarity. (The names "events" and "subscriptions" are not mandated by SQL-NS; you may use any aliases you want.) Note that the join is on the stock symbol field.
StockPriceChange and StockPriceHitsTarget are not in fact tables, but rather views that SQL-NS sets up at runtime. These views contain just the data against which the rule should operate: The events view contains only the events just submitted that have triggered the rule firing, and the subscriptions view contains only the active subscriptions. (In this simple application, all subscriptions are active, but you'll see in Chapter 6, "Completing the Application Prototype: Scheduled Subscriptions and Application State," and Chapter 7, "The SQL-NS Subscription Management API," that subscriptions can be disabled or scheduled to fire only at certain times.)
The WHERE clause of the join defines a filter that selects only the rows in which the stock price in the event is greater than or equal to the stock price target in the subscription. Note that the XML escape sequence, > is used in place of the > character because this statement appears within an XML document. Use of the > character directly would prevent the document from being well-formed XML.
The join defined in the FROM clause, along with the filter defined in the WHERE clause, implement the matching criteria; the rule defines what it means for an event to match a subscription. (The stock symbols must be the same, and the stock price greater than or equal to the price target.)
The SELECT clause of the join statement calls a function, StockAlertNotify(). It passes this function a set of arguments whose values come from the joined data. Among these arguments are values for the fields in the notification class. The StockAlertNotify() function is provided by SQL-NS: It is created specifically for the notification class, when the notification class is compiled. In fact, SQL-NS creates one such function per notification class, named <NotificationClassName>Notify(). In this application, the notification class name is StockAlert, so the name of the function is StockAlertNotify(). In SQL-NS terms, the function created for any notification class is referred to as the notify function.
Calling the notify function for a particular notification class causes a notification of that notification class to be queued for delivery. Calling the StockAlertNotify() function indicates that the result of a match by this rule should be a StockAlert notification. Internally, the notify function writes the data it is passed into a notification table and updates the internal SQL-NS state to tell the distribution components that the notification data is ready to be formatted and delivered.
The first three parameters to the notify function, as shown in Listing 3.6, are always the same. They are
-
The ID of the subscriber to receive the notification. (Note that even though the subscriber ID is not a declared field in the subscription class schema, it is always present in the subscription class view.)
-
The name of the subscriber's device to which the notification should be sent. (Note that subscriber devices are discussed in more detail in Chapter 7 and Chapter 10, "Delivery Protocols.")
-
The locale for which the notification data should be formatted.
The additional parameters to the notify function are obtained from the fields in the notification class declaration. There is one parameter for each declared field, with the same name and data type as that field. Values of these parameters in the notify function call become values for the corresponding notification fields. If you look at the call to the StockAlertNotify() notify function in Listing 3.6, you'll see that the subscriber ID is obtained from the subscription, the device name and locale are constants, two of the notification fields come from data in the event, and the third comes from data in the subscription.
Component Configuration and the Phases of Processing
Previous sections examined the event, subscription, and notification schemas and the associated rule logic. This section examines the component configuration elements of the ADF. Specifically, these include the <Providers>, <Generator>, and <Distributors> elements.
Each of the components configured in the ADF plays a specific role in the functioning of the application. Before looking at these components and how they're configured, it's important to understand the processing that happens inside a notification application.
SQL-NS separates the functions of a notification application into separate processing phases (see Figure 3.6):
-
Event collection—Gathering events and submitting them to the application
-
Subscription management—Creation, deletion, and alteration of subscriptions
-
Generation—Matching events with subscriptions
-
Distribution—Routing notifications to delivery systems
Each phase is considered independent and is handled by a separate component in the execution engine. The SQL-NS engine may run all these phases concurrently: While one batch of events is being collected, another may be being matched with subscriptions, and an older batch of notifications may be being distributed. The following subsections describe these phases of processing and the components that execute them.
){kind=small}
Figure 3.6
Phases of processing in notification applications.
Event Collection
Event providers are components that collect events and submit them to notification applications. Event providers can gather event data from the outside world proactively, or act as sinks to which external event sources push information. For example, an event provider could be a component that constantly polls an external data source, or it could be a Web service that receives data passed to it by external callers.
An application can have several event providers, each potentially submitting events from a different event source. In the <Providers> element of the ADF, you declare which event providers your application will use and configure the options that control their operation.
SQL-NS provides several built-in event providers that can be used in an application without you having to write any code. You can also build your own event provider for your application that talks to a custom event source. Chapter 7 provides details on all the built-in event providers, as well as the process of building a custom event provider for your application.
Listing 3.7 shows the <Providers> element from the stock application's ADF.
Listing 3.7 The Event Provider Configuration in the ADF
<Providers>
<HostedProvider>
<ProviderName>StockEventProvider</ProviderName>
<ClassName>FileSystemWatcherProvider</ClassName>
<SystemName>%_NSServer_%</SystemName>
<Arguments>
<Argument>
<Name>WatchDirectory</Name>
<Value>%_ApplicationBaseDirectoryPath_%\
EventsWatchDirectory</Value>
</Argument>
<Argument>
<Name>SchemaFile</Name>
<Value>%_ApplicationBaseDirectoryPath_%\
StockPriceChangeEventSchema.xsd</Value>
</Argument>
<Argument>
<Name>EventClassName</Name>
<Value>StockPriceChange</Value>
</Argument>
</Arguments>
</HostedProvider>
</Providers>
This application uses a single hosted event provider to submit stock events. This event provider is declared and configured in a <HostedProvider> element. The configuration specifies a name for the event provider, the event provider class (which identifies a particular event provider implementation), the server on which it should run, and a set of runtime arguments that it gets passed at startup time.
NOTE
A hosted event provider is one that runs within the SQL-NS Windows Service; an application can also use nonhosted event providers that run as part of a standalone process. Chapter 8, "Event Providers," offers more details on both types and describes when it's appropriate to use each one.
The event provider class name tells the SQL-NS engine which event provider implementation to use. The class name can be either the name of a class that you implement (as described in Chapter 8) or the name of a "built-in" event provider class, provided by SQL-NS. In this case, the stock application uses the built-in event provider class called the FileSystemWatcher. This event provider works by monitoring a directory in the filesystem; when it sees a new XML file added to that directory, it opens the file and submits the data in it as events.
Subscription Management
Most notification applications provide users with a visual interface by which they can manipulate and manage their subscriptions. The form of this interface varies depending on the nature of the pub-sub system. A stock quote application might provide a Web site that a user can use to enter a subscription. A line-of-business application might provide a way to subscribe for notifications directly in its standard Windows user interface.
Whatever the form of the external interface, the implementation of the subscription management system uses an API provided by SQL-NS to insert subscriptions into the notification application. This API also provides facilities for modifying or deleting subscriptions.
There is no subscription management configuration in the ADF. The ADF just contains declarations of subscription classes, but the systems by which subscriptions of those subscription classes are created and submitted to the application are treated as standalone entities that are not configured in the ADF.
Generation
Generation is the phase during which events are matched with subscriptions to produce notifications. The generation component of an application is provided by SQL-NS, but the logic it uses to determine whether a particular event matches a subscription is provided by the application developer.
SQL-NS exposes a variety of options for controlling how generation occurs, including customizing batch sizes and specifying how and when matching logic is applied. These are configured in the ADF in the <Generator> element. Listing 3.8 shows the generator configuration for the stock application.
Listing 3.8 The Generator Configuration in the ADF
<Generator> <SystemName>%_NSServer_%</SystemName> </Generator>
In this simple example, the only configuration option supplied is the system name, which tells the SQL-NS engine on which machine the generator should run. Chapters 11 and 12 describe more options you can use to fine-tune generator operation.
Distribution
The distribution phase handles the formatting of notification data appropriately for a variety of delivery devices (email, cell phones, pagers, and so on) and the routing of those formatted notifications to delivery systems that get them to their final destinations.
An application can have one or more distributors, possibly running on different servers. These are configured in the ADF's <Distributors> element. Listing 3.9 shows the <Distributors> element from the stock application's ADF.
Listing 3.9 The Distributor Configuration in the ADF
<Distributors>
<Distributor>
<SystemName>%_NSServer_%</SystemName>
</Distributor>
</Distributors>
The stock application uses only one distributor, and this is declared in the single <Distributor> element. Again, because this is a simple example, the only configuration option specified is the system name: the computer on which the distributor should run. Chapter 12 describes additional distributor configuration options that you can specify.
CAUTION
If you are using the Standard Edition of SQL-NS, the event providers, generator, and distributor in your application must run on the same machine. This means that the <SystemName> element must have the same value in all the event provider, generator, and distributor declarations in your ADF. If you specify different system name values with SQL-NS Standard Edition, you'll get an error when compiling your application.
If you are using the Enterprise Edition of SQL-NS, you may configure the various components to run on different machines by specifying different values for the <SystemName> elements. This allows your application to scale out for better performance. Chapter 13 covers the additional configuration steps (beyond specifying system names in the ADF) required to enable a scale out deployment.