The SQL-NS Subscription Management API

The SQL-NS Subscription Management API provides the core facilities required to build the logic layer of the SMI. This section presents an overview of the API and the classes that it contains. The next section looks at how to use this API to build the logic layer of the music store SMI.

Note

From here on, I refer to the SQL-NS Subscription Management API as the "SQL-NS API" for simplicity. Although SQL-NS does offer APIs other than those used for subscription management, and the general term SQL-NS API technically includes those other APIs as well, in the context of this chapter, we'll ignore this detail.

Fundamental Entities in the Subscription Management API

The SQL-NS API primarily focuses on three entities: subscribers, subscriber devices, and subscriptions. Before looking at the actual API, it's important that we clarify what these entities represent.

A subscriber is an entity that requests notifications by means of subscriptions. A subscriber is usually a person, although in some cases, programs can be subscribers. A subscriber is identified by a subscriber ID. All subscribers in an instance are shared among applications in that instance.

A subscriber device represents a delivery endpoint for notifications. A subscriber device might be a physical device, such as a cell phone that receives text messages, or a less tangible device, such as an email address to which notifications can be sent. Each subscriber device is associated with a subscriber, and each subscriber can have several subscriber devices. Because subscriber devices are associated with subscribers, they are stored at the instance level and can be referred to by all applications in the instance.

Each subscriber device is also associated with a delivery channel. The delivery channel represents the gateway used to get notifications to the subscriber device. As described in Chapter 4, delivery channels are configured in the ICF and shared by all applications in the instance. A delivery channel might represent, for example, a particular SMTP server used to route email notifications. In general, you have a delivery channel in your instance for each delivery system your application uses. Every subscriber device is associated with one of those delivery channels. Chapter 10, "Delivery Protocols," describes delivery channels and the ways they are used, in detail.

A subscription is a subscriber's request for a notification. Each subscription is an instance of a subscription class defined in some application and is owned by a subscriber. Unlike subscribers and subscriber devices, which are stored at the instance level, subscriptions are stored at the application level. Each subscription specifies values for the fields defined in the schema of its subscription class.

Classes in the Subscription Management API

The SQL-NS API provides classes that represent each of the entities described in the previous section. These classes allow you to examine and modify the properties of existing subscribers, subscriber devices, and subscriptions, as well as create new ones.

Table 7.1 lists the main classes in the SQL-NS API. All classes listed are defined in the Microsoft.SqlServer.NotificationServices namespace. I'll refer to this as the SQL-NS namespace from now on.

Table 7.1. Classes in the SQL-NS Subscription Management API

Class Name	Purpose
NSInstance	Represents a connection to a SQL-NS instance
NSApplication	Represents a connection to an application within a SQL-NS instance
NSException	Represents a SQL-NS exception (thrown by SQL-NS API methods in response to error conditions)
Subscriber	Represents a subscriber
SubscriberEnumeration	Provides enumeration capabilities over a collection of subscribers
SubscriberDevice	Represents a subscriber device
SubscriberDeviceEnumeration	Provides enumeration capabilities over a collection of subscriber devices
Subscription	Represents a subscription
SubscriptionEnumeration	Provides enumeration capabilities over a collection of subscriptions
TimeZone	Represents a time zone used in the specification of a schedule in a scheduled subscription
TimeZoneEnumeration	Enumerates the collection of all time zones supported by SQL-NS

Figure 7.3 shows how some of these classes are used. The NSInstance and NSApplication classes can be thought of as connectors to the SQL-NS instance and application, respectively. The other classes in the API use these connection objects to refer to a particular instance and application.

Figure 7.3. Classes in the SQL-NS Subscription Management API.

The NSException class encapsulates all exceptions thrown by SQL-NS APIs. Code that uses the SQL-NS API will typically catch exceptions of the NSException type to handle SQL-NS-specific errors. Properties on the NSException class provide detailed information about the exact error that a thrown NSException object represents.

As their names suggest, the Subscriber, SubscriberDevice, and Subscription classes represent subscribers, subscriber devices, and subscriptions, respectively. Each class provides methods to create, delete, and modify instances of the entity it represents. Each class also has a corresponding enumeration class that provides strongly typed collection capabilities.

When defining the schedules for scheduled subscriptions, you'll need to specify time zones. SQL-NS provides TimeZone and TimeZoneEnumeration classes with which you can do this.

Note

This chapter shows examples of all these classes in use. However, the information in this chapter is not intended to replace or duplicate the exhaustive class reference in the SQL-NS Books Online. This chapter's examples show the use of these classes in particular contexts, but not every method and property is shown. Always consult the SQL-NS Books Online for complete information on any class you need to use. In many cases, there are properties and methods on these classes that I have not mentioned in this chapter but that may still be useful to you.