Level A — Business and Data Access Components

Why Two Levels?

You might wonder why the Island Hopper sample separates the business components from the data access components. Why the level of abstraction? Here's why: Separating the data access components makes it possible to use specialized querying rules that are not strictly business rules and that are not appropriate for building into the storage engines, particularly when data is decentralized, as is typical in many companies. For instance, one query may want all customers, but "James Smith" at a specific address and "Jim Smith" at the same address should be recognized as the same person. This is perhaps a contrived example, but the point is that the data access code often becomes extremely complex and yet really does not belong with the business logic nor stored with the storage engine.

A Note About Version Compatibility

All of the Visual Basic projects for the business and data access components in Level A have the Binary Compatibility option set. The Binary Compatibility option ensures, among other things, that when you recompile a component, its CLSID will remain constant. Binary version compatibility makes it possible for you to enhance the components while ensuring that applications compiled using previous versions will still work with the new versions of the components.

For More Information The Visual Basic documentation includes extensive information about version compatibility. See Version Compatibility in ActiveX Components online in MSDN Library Visual Studio 6.0 for information about the Visual Basic Version Compatibility feature, including a list of links to additional topics.

Why Use Microsoft Transaction Server?

The components for Level A all use Microsoft Transaction Server (MTS) for context. In MTS, context is a state that is implicitly associated with a given Microsoft Transaction Server object. Context contains information about the object's execution environment, such as the identity of the object's creator and, optionally, the transaction encompassing the work of the object. An object's context is similar in concept to the process context that an operating system maintains for an executing program. The Microsoft Transaction Server run-time environment manages a context for each object.

Context simplifies the development of components, because each object independently acquires its own resources, performs its work, and indicates its own internal state by calling the MTS methods SetComplete or SetAbort before returning.

Component Summary — Level A

Level A contains components described in the following tables. These are all written in Visual Basic.

Level A Business Component

Name	Description
bus_AdA (bus_AdA.cls, in the Ad class module in the bus_AdA project)	Manages classified ads. Creates instances of db_AdA and db_CategoryA where necessary to carry out database functions.

Level A Data Access Components

Name	Description
db_AdA (db_AdA.cls, in the Ad class module in the db_AdA project)	Sends data to and retrieves data from the Advertisements table of the Classified Ads database. Uses ADO for communication with the database.
db_CategoryA (db_CategoryA.cls, in the Category class module in the db_CategoryA project)	Sends data to and retrieves data from the Categories table of the Classified Ads database. Uses ADO for communication with the database.

Bus_AdA Methods

Bus_AdA consists of the methods described in the following table.

Method name	Description
Delete	Creates an instance of db_AdA and calls db_AdA's Delete method, passing it the unique ad ID.
GetByID	Creates an instance of db_AdA and calls db_AdA's GetByID method, passing it the unique ad ID. Also returns the requested ad information in a recordset.
ListByCategory	Creates an instance of db_AdA and calls db_AdA's ListByCategory method, passing it the unique category ID. Also returns the requested ad information in a recordset.
ListByEmail	Creates an instance of db_AdA and calls db_AdA's ListByEmail method, passing it the customer's e-mail address. Also returns the requested ad information in a recordset.
ListByPhoneNumber	Creates an instance of db_AdA and calls db_AdA's ListByPhoneNumber method, passing it the customer's phone number. Also returns the requested ad information in a recordset.
PlaceAd	Creates an instance of db_AdA and calls db_AdA's Add method, passing it all the ad information. Also creates an instance of TakeANumber and calls TakeANumber's GetANumber method to get a unique ID for the ad. Returns the unique ad ID after the ad is created in the database.
UpdateAd	Creates an instance of db_AdA and calls db_AdA's Update method, passing it the updated ad information.

DB_AdA Methods

DB_AdA consists of the methods described in the following table.

Method name	Description
Add	Adds a new classified ad to the database.
Delete	Deletes a classified ad from the database.
GetAdCountByCategory	Returns a count of all ads with a particular category ID.
GetByID	Retrieves an ad with a particular ID.
ListByCategory	Retrieves all ads for a particular category.
ListByEmail	Retrieves all ads for a particular customer e-mail address.
ListByPhoneNumber	Retrieves all ads for a particular customer phone number.
Update	Updates a classified ad in the database.

DB_CategoryA Methods

DB_CategoryA consists of the methods described in the following table.

Method name	Description
Add	Adds a new category to the database.
Delete	Deletes a category from the database.
ListAll	Retrieves an alphabetical list of all categories in the database.
GetByID	Retrieves a category with the specified ID.
GetByName	Retrieves a category with the specified name.
GetBySearchString	Retrieves all categories where the name contains the specified search string.
ListByRange	Retrieves all categories with IDs within a specified range.
Update	Updates a category in the database.

Component Relationships and Flow

Generally, the Visual Basic forms or .asp pages create an instance of the business object, bus_AdA. bus_AdA in turn creates an instance of the data access object it needs (db_AdA or db_CategoryA) to complete a task.