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 the SQL-NS engine 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.
Table 3.1 Basic Structure of the ADF
|
XML Element |
Purpose |
|
<?xml version="1.0" encoding="utf-8" ?> |
Standard XML header |
|
<Application xmlns:xsd="http://www.w3.org/2001/XMLSchema"xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="..."> |
Root element that contains all of the application definition |
|
<Database> |
Specifies the database in which the application's tables, views, stored procedures, and other objects should be created |
|
<EventClasses> |
Defines schemas for the events the application will receive |
|
<SubscriptionClasses> |
Defines schemas and matching logic for the subscriptions the application will support |
|
<NotificationClasses> |
Defines schemas for the notifications the application will send |
|
<Providers> |
Configures the application's event providers |
|
<Generator> |
Configures the generator component that matches events with subscriptions |
|
<Distributors> |
Configures the distributor components that deliver notifications |
|
<ApplicationExecutionSettings> </ApplicationExecutionSettings> |
Contains operational settings that control various aspects of the application's behavior |
|
</Application> |
Closing tag for the root element |
The <EventClasses>, <SubscriptionClasses>, and <NotificationClasses> subelements under <Application> contain all the schemas and logic. The other elements provide configuration information used by the SQL-NS compiler and the SQL-NS engine.
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 end 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=http://www.w3.org/2001/XMLSchemaxmlns:xsi=http://www.w3.org/2001/XMLSchema-instancexmlns="http://www.microsoft.com/MicrosoftNotificationServices/ApplicationDefinitionFileSchema">
<Database>
<DatabaseName>StockBroker</DatabaseName>
<SchemaName>StockWatcher</SchemaName>
</Database>
<EventClasses>
<EventClass>
<EventClassName>StockPriceChange</EventClassName>
<Schema>
<Field>
<FieldName>StockSymbol</FieldName>
<FieldType>NVARCHAR(10)</FieldType>
<FieldTypeMods>NOT NULL</FieldTypeMods>
</Field>
<Field>
<FieldName>StockPrice</FieldName>
<FieldType>SMALLMONEY</FieldType>
<FieldTypeMods>NOT NULL</FieldTypeMods>
</Field>
</Schema>
</EventClass>
</EventClasses>
<SubscriptionClasses>
<SubscriptionClass>
<SubscriptionClassName>StockPriceHitsTarget</SubscriptionClassName>
<Schema>
<Field>
<FieldName>StockSymbol</FieldName>
<FieldType>NVARCHAR(10)</FieldType>
<FieldTypeMods>NOT NULL</FieldTypeMods>
</Field>
<Field>
<FieldName>StockPriceTarget</FieldName>
<FieldType>SMALLMONEY</FieldType>
<FieldTypeMods>NOT NULL</FieldTypeMods>
</Field>
</Schema>
<EventRules>
<EventRule>
<RuleName>MatchStockPricesWithTargets</RuleName>
<Action>
INSERT INTO [StockWatcher].[StockAlert]
SELECT subscriptions.SubscriberId,
N'DefaultDevice',
N'en-US',
events.StockSymbol,
events.StockPrice,
subscriptions.StockPriceTarget
FROM [StockWatcher].[StockPriceChange] events
JOIN [StockWatcher].[StockPriceHitsTarget] subscriptions
ON events.StockSymbol = subscriptions.StockSymbol
WHERE events.StockPrice >= subscriptions.StockPriceTarget
</Action>
<EventClassName>StockPriceChange</EventClassName>
</EventRule>
</EventRules>
</SubscriptionClass>
</SubscriptionClasses>
<NotificationClasses>
<NotificationClass>
<NotificationClassName>StockAlert</NotificationClassName>
<Schema>
<Fields>
<Field>
<FieldName>StockSymbol</FieldName>
<FieldType>NVARCHAR(10)</FieldType>
</Field>
<Field>
<FieldName>StockPrice</FieldName>
<FieldType>SMALLMONEY</FieldType>
</Field>
<Field>
<FieldName>StockPriceTarget</FieldName>
<FieldType>SMALLMONEY</FieldType>
</Field>
</Fields>
</Schema>
<ContentFormatter>
<ClassName>XsltFormatter</ClassName>
<Arguments>
<Argument>
<Name>XsltBaseDirectoryPath</Name>
<Value>%_ApplicationBaseDirectoryPath_%\XslTransforms</Value>
</Argument>
<Argument>
<Name>XsltFileName</Name>
<Value>StockAlert.xslt</Value>
</Argument>
</Arguments>
</ContentFormatter>
<Protocols>
<Protocol>
<ProtocolName>File</ProtocolName>
</Protocol>
</Protocols>
</NotificationClass>
</NotificationClasses>
<Providers>
<NonHostedProvider>
<ProviderName>TestEventProvider</ProviderName>
</NonHostedProvider>
</Providers>
<Generator>
<SystemName>%_NSServer_%</SystemName>
</Generator>
<Distributors>
<Distributor>
<SystemName>%_NSServer_%</SystemName>
<QuantumDuration>PT15S</QuantumDuration>
</Distributor>
</Distributors>
<ApplicationExecutionSettings>
<QuantumDuration>PT15S</QuantumDuration>
</ApplicationExecutionSettings>
</Application>
Before you continue reading, you should open the stock application’s source code on your system so that you can browse the ADF as you go. Use the following instructions to open the project in Management Studio and bring up the ADF in the built-in XML editor:
- Start Management Studio (from the Start menu, choose All Programs, SQL Server 2005, Microsoft SQL Server Management Studio) and connect to your SQL Server.
- From the File menu, choose Open, Project/Solution.
- In the File Open dialog box, browse to the C:\SQL-NS\Samples\StockBroker directory and select the StockBroker.ssmssln solution file.
- If the Solution Explorer window is not visible, open it by selecting Solution Explorer from the View menu or by pressing Ctrl+Alt+L.
- In the Solution Explorer, you should see two projects: StockBroker and StockWatcher. Expand the StockWatcher project node and the Miscellaneous folder beneath it.
- Open the ApplicationDefinition.xml file.
The Database Element in the ADF
As described earlier in the "Programming to the SQL-NS Application Model" section (p. 47), the SQL-NS compiler creates database objects (including tables, views, and stored procedures) based on the information in the ADF. You can choose where these database objects are installed: in the <Database> element of the ADF, you can provide a target database name and a schema name. When you compile the ADF, the resulting database objects are installed in the database and schema you specify (see the sidebar titled "User-Schema Separation in SQL Server 2005," for an explanation of the term schema in this context).
In the case of the stock application’s ADF, shown in Listing 3.1, the <Database> element specifies a database name as StockBroker and the schema name as StockWatcher. I chose these names arbitrarily. StockBroker seemed like a fitting name for a database related to stockbroker operations and StockWatcher aptly describes the purpose of this application. All database objects for this application created by the SQL-NS compiler will be placed in the StockWatcher schema in the StockBroker database. In the later sections of this chapter, you’ll see these database objects referred to by their schema-qualified names.
Schemas and Logic
This section describes the ADF syntax used to define the event, subscription, and notification data schemas (here I’m referring to the usual meaning of schemas—the definition of the data’s structure). 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>SMALLMONEY</FieldType>
<FieldTypeMods>NOT NULL</FieldTypeMods>
</Field>
</Schema>
</EventClass>
The declaration provides a name, StockPriceChange, for the event class and a schema for the event data. The schema declaration 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 a table that will ultimately store the events. It creates a column for each of the fields declared in the event class and adds some other columns used for internal tracking.
The SQL-NS compiler also builds a view over the events table. The columns in the view match the fields declared in the event class exactly—the extra columns created in the events table for SQL-NS internal tracking are not present in the view. This view becomes the primary means by which events are manipulated in the application. To submit event data for processing, you insert rows into the view. Triggers on the view (also created by the SQL-NS compiler) handle inserting the appropriate values into the internal columns in the events table. When matching against subscriptions, event data is read from the view.
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>SMALLMONEY</FieldType>
<FieldTypeMods>NOT NULL</FieldTypeMods>
</Field>
</Schema>
<EventRules>
...
</EventRules>
</SubscriptionClass>
The subscription class declaration has three subelements: a name, a schema, and a set of event rules (content is not shown in the fragment in Listing 3.3).
The schema subelement defines the size and shape of the subscription data. In this application, we’re using developer-defined matching logic and constraining subscriptions to 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.
Just as it does with the event class schema declaration, the SQL-NS compiler constructs a table for subscription data from the subscription class schema declaration. Like the events table, the subscriptions table contains a column for each field declared and some extra columns used internally by SQL-NS. Also, the SQL-NS compiler constructs a view over the subscriptions table, with columns matching the declared subscription class fields. When you need to add subscriptions of this subscription class, you insert rows into the subscriptions view. When you define the logic that matches subscriptions against events, you access subscription data by selecting from the subscriptions view.
The matching logic for the subscription class is declared in the <EventRules> subelement. 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 definitions for several types of notifications, but because this stock application example 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>SMALLMONEY</FieldType>
</Field>
<Field>
<FieldName>StockPriceTarget</FieldName>
<FieldType>SMALLMONEY</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 more thoroughly in Chapters 5, 9, and 10.
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 for delivery to the subscribers, such as
"XYZ is now trading at: $55.55. This is greater than or equal to the target price of $50.00."
As you might expect, the SQL-NS compiler constructs a table for the notification data (based on the declared schema) and a view over this table. The output of the matching logic query is inserted into the notifications view to queue notifications for delivery.
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 SQL-NS executes 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 query to execute), 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 to fire this event rule whenever events of the StockPriceChange event class arrive.
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 query is specified in the rule’s <Action> element. Listing 3.6 shows the contents of the <Action> element from the stock application’s ADF.
Listing 3.6 The SQL Matching Logic from the Event Rule’s <Action> Element
INSERT INTO [StockWatcher].[StockAlert]
SELECT subscriptions.SubscriberId,
N’DefaultDevice’,
N’en-US’,
events.StockSymbol,
events.StockPrice,
subscriptions.StockPriceTarget
FROM [StockWatcher].[StockPriceChange] events
JOIN [StockWatcher].[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 becomes notification data.
The first thing to look at in this query is the FROM clause. It selects data from the events view joined with the subscriptions view. Notice that the names of these views are the names of the event class and the subscription class, respectively (with the StockWatcher schema qualifiers). The aliases, events and subscriptions, have been assigned to these views for clarity (these aliases are not mandated by SQL-NS).
The event and subscription views, StockPriceChange and StockPriceHitsTarget, can be thought of as the SQL-NS platform’s public interface to the event and subscription data collected. The platform guarantees that these views will contain only the event and subscription data against which the rule should operate, at the time the rule is invoked. In other words, the events view will contain only the events just submitted that have triggered the rule firing, and the subscriptions view will contain 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.)
Given the guarantee that the views always contain only the relevant data when the rule is invoked, the matching query in the ADF doesn’t require any custom logic to determine which portions of the data are in scope. This is a great benefit of using SQL-NS: the application logic can be written at a high level of abstraction, leaving the platform to take care of details such as managing the data against which the logic executes.
Going back to the query in Listing 3.6, the WHERE clause 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 logic specified in the query 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.) This is an example of developer-defined logic; users cannot change this definition of what a match means.
The results obtained when the matching query is executed determine what notifications will ultimately be delivered. Each row in the resultset represents one notification. Notice that the results of the SELECT query are inserted into the notification class view (which, as you might expect, has the same name as the notification class, StockAlert, defined in Listing 3.4). Inserting rows into a notification class view causes notifications of that notification class to be generated. As is the case for event and subscription classes, the view is the SQL-NS platform’s interface to the notification class. Rows inserted into the notification class view will eventually be picked up by the SQL-NS distributors for final formatting and delivery.
The notification class view has a column for each field declared in the notification class. Given the definition of the notification class schema in Listing 3.4, the StockAlert view has columns for StockSymbol, StockPrice, and StockPriceTarget. SQL-NS also adds three other columns to every notification class view:
- SubscriberId—Specifies the ID of the subscriber to receive the notification.
- DeviceName—Specifies the name of the subscriber’s device to which the notification should be sent. (Subscriber devices are discussed in more detail in Chapter 7 and Chapter 10, "Delivery Protocols.")
- SubscriberLocale—Specifies the locale for which the notification data should be formatted.
The SELECT clause in Listing 3.6 provides a value in the resultset for each of the columns in the notification class view. 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, the subscription, and the notification schemas and the associated rule logic. This section examines the component configuration elements of the ADF. Specifically, these include the <Providers>, <Generator>, <Distributors>, and <ApplicationExecutionSettings> 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:
- 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
Figure 3.6 shows these phases.
)
Figure 3.6 Phases of processing in notification applications.
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.
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. Event providers can be components that run within the SQL-NS engine, or they can be standalone programs that submit event data to your application. 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 your having to write any code. You can also build your own event provider for your application that talks to a custom event source. Chapter 8, "Event Providers," 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> <NonHostedProvider> <ProviderName>TestEventProvider</ProviderName> </NonHostedProvider> </Providers>
In this application, rather than using a real event source, we’re just going to submit some test events manually. Therefore, the ADF declares a single nonhosted event provider. The term "nonhosted" just means that the event provider is not hosted within the SQL-NS engine; the declaration in Listing 3.7 indicates that events will enter the application from an external program (in fact, we’ll use a simple T-SQL script to submit events). Because there’s only one event source in this application example, the event provider name is arbitrary. I’ve chosen the name TestEventProvider to signify that this is a placeholder used for testing. In a real application, which might have several real hosted and nonhosted event providers, event provider names can be useful to associate events with the providers that submitted them.
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 such as the one in this chapter might provide a website that a user can visit to enter a subscription. A line-of-business application might provide a way to subscribe for notifications in its standard Windows user interface.
Whatever the form of the external interface, subscription data must be ultimately transferred to the tables in the application’s database. The implementation of the subscription management system can either insert rows into the subscription class views directly or use an API provided by SQL-NS to enter subscriptions. The subscription management API is covered in detail in Chapter 7.
There is no subscription management configuration in the ADF. The ADF 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. For the purposes of testing the application example in this chapter, we’ll just enter subscription data directly into the views using a T-SQL script.
Generation
Generation is the phase during which events are matched with subscriptions to produce notifications. The generation component is provided by SQL-NS and uses either developer-defined or user-defined logic to determine whether a particular event matches a subscription.
SQL-NS exposes a variety of configuration options for controlling notification generation. Some of these options specify, for example, how and when matching logic is applied. These are configured in the ADF in the <Generator> and <ApplicationExecutionSettings> elements. 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> ... <ApplicationExecutionSettings> <QuantumDuration>PT15S</QuantumDuration> </ApplicationExecutionSettings>
The <Generator> element specifies the system name, which tells the SQL-NS engine on which machine the generator should run. The <ApplicationExecutionSettings> element specifies a quantum duration, which controls how often the generator looks for new events to process. In this case, the quantum duration is set to 15 seconds. Chapters 11, "Debugging Notification Generation," and 12, "Performance Tuning," describe in more detail these and other options you can use to fine-tune generator operation.
Distribution
The distribution phase handles the formatting of notification data for a variety of delivery devices (email, cell phones, pagers, and so on) and the routing of the formatted notifications to delivery systems that gets 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> <QuantumDuration>PT15S</QuantumDuration> </Distributor> </Distributors>
The stock application uses only one distributor, and this is declared in the single <Distributor> element. The configuration in Listing 3.9 specifies the distributor system name (the computer on which the distributor should run) and the distributor quantum duration (which controls how often the distributor polls for new batches of notifications to format and deliver—15 seconds, in this case). Chapter 12 covers these and other distributor configuration options in greater detail.