Sharing State

This chapter shows you how to use the Shared Property Manager to share state among multiple Microsoft Transaction Server objects running in the same process.

Scenario: A Receipt Number Generator That Uses the Shared Property Manager

This chapter introduces the Receipt component, which dispenses unique receipt numbers for fund transfers. When a bank transaction takes place, the MoveMoney object creates a Receipt object. The Receipt component contains a single method, GetNextReceipt.

GetNextReceipt uses the Shared Property Manager to get a unique receipt number. The Shared Property Manager has an object hierarchy as shown in the following figure:

Within a server process, there is only one instance of the SharedPropertyGroupManager object. The value of the receipt number is maintained by a SharedProperty object, which provides locking mechanisms to ensure that no two calls to GetNextReceipt retrieve the same value.

Creating the Receipt Component

The Receipt component contains a single method, GetNextReceipt. The Receipt object itself doesn't maintain the value of the receipt number between calls. The Shared Property Manager maintains these values. The Receipt object calls a SharedProperty object to get a new receipt number.

You will also add code to the MoveMoney component to call the Receipt component.

To create the Receipt Component

1. Start Microsoft Visual Basic and open the \Mts\Samples\Account.VB\Step5\Account.vbp project.

2. Build the component as a DLL and save it as \Mts\Samples\Account.VB\Step5\VBAcct.dll.

By adding a new class module, you add a new COM component to this DLL. Therefore, you need to delete the existing components in the Microsoft Transaction Server Explorer and then install the new components.

To reinstall your components

1. Remove the Account, MoveMoney, and CreateTable components from the Transaction Server Explorer.

2. Add the new components. Use the DLL you created in \Mts\Samples\Account.VB\Step5\VBAcct.dll.

To set the transaction attributes for your components

1. For the Account and MoveMoney components, set the transaction attribute to Requires a transaction.

2. For the CreateTable component, set the transaction attribute to Requires a new transaction.

3. For the Receipt component, set the transaction attribute to Does not support transactions. This is the default value.

   Note that the Receipt component is not transactional because the receipts are maintained as properties in memory and aren't durable.

When you run the Bank Client, select the MoveMoney button under Component. You should see the response Credit, balance is $ 1. (VB); Receipt No: #####.

The various object creation methods for Shared Property Manager objects are designed for simplified coding. If the object doesn't exist, it will be created. If it already exists, the object is returned. GetNextReceipt makes the following method call to access the shared property group manager:

Set spmMgr = CreateObject _
    ("MTxSpm.SharedPropertyGroupManager.1")

This code works every time it is called. There is no need to check if the shared property group manager has already been created. Such behavior also ensures that only one instance of the SharedPropertyGroupManager object exists per server process.

For the SharedPropertyGroup and SharedProperty objects, a flag is returned to indicate whether the property group or property already exists. The following code shows how this flag is used to determine if the property needs to be initialized:

Set spmPropNextReceipt = _
    spmGroup.CreateProperty("Next", bResult)
' Set the initial value of the SharedProperty to
' 0 if the SharedProperty didn't already exist.
If bResult = False Then
    spmPropNextReceipt.Value = 0
End If

Access to shared properties is controlled through the CreatePropertyGroup method:

Set spmGroup = _
    spmMgr.CreatePropertyGroup("Receipt", _
    LockMethod, Process, bResult)

CreatePropertyGroup has two parameters, isolation mode and release mode. The isolation mode for the Receipt property group is set to LockMethod, which ensures that two instances of the Receipt object can't read or write to the same property during a call to GetNextReceipt. The release mode for the Receipt property group is set to Process, which maintains the property group until the server process is terminated.

Application Design Notes: Sharing State by Using the Shared Property Manager

Using the Shared Property Manager makes sharing state in a multiuser environment as easy as it is in a single-user environment. Without the use of the Shared Property Manager, the application would require much more code that has nothing to do with the business problem at hand.

One alternate way to create the same functionality would be to maintain the receipt number as a member variable of the Receipt component. However, this complicates coding the Receipt component immensely. The Receipt component would have to remain persistent in memory during the life of the server process. This would require the following additional code:

• Referencing all instances of MoveMoney to the Receipt object.

• Maintaining a locking mechanism to prevent concurrent access to the Receipt object.

Even after adding this code, the application wouldn't be extensible for additional shared properties. The Shared Property Manager is another example of how Microsoft Transaction Server provides the infrastructure for server applications so that you can concentrate on coding business logic.

Location Transparency and the Shared Property Manager

For objects to share state, they all must be running in the same server process with the Shared Property Manager.

To maintain location transparency, it's a good idea to limit the use of a shared property group to objects created by the same component, or to objects created by components implemented within the same DLL. When components provided by different DLLs use the same shared property group, you run the risk of an administrator moving one or more of those components into a different package. Because components in different packages generally run in different processes, objects created by those components would no longer be able to share properties.