Page #123 (Overview)
| < BACK NEXT > |
[oR]COM+ Administration Object Model
The COMAdmin objects offer a simple object model for accessing the catalog.
-
The data stored in the catalog is treated as a hierarchy of collections. Collections serve as a container of homogeneous items. For instance, a COM+ application contains a collection of components; each component contains a collection of interfaces; each interface contains a collection of methods, and so on.
-
Each item in a collection exposes a set of properties that is consistent across the collection. For instance, every item in the Applications collection will expose a Name property, an AppId property, and so forth. Depending on how the properties are accessed, some properties are read-only while others can be read or written to.
Table 12.1 lists some of the collection types that are currently exposed through the COMAdmin object model.
| Collection | Description |
|---|---|
| Applications | List of all COM+ applications installed on the local machine |
| Components | List of all components in an application |
| DCOMProtocols | List of all the protocols used by DCOM |
| ErrorInfo | Extended error information when a method on any COMAdmin object fails |
| InprocServers | List of all the in-process COM servers registered with the system |
| InterfacesForComponent | List of all the interfaces exposed by a component |
| LocalComputer | List of computer-level settings information |
| MethodsForInterface | List of all the methods on an interface |
| PropertyInfo | List of all the properties that a specified collection supports |
| RelatedCollectionInfo | List of other collections related to the collection from which this method is called |
| Roles | List of roles for an application |
| UsersInRole | List of users in a role |
The hierarchy of collection objects is shown in Figure 12.1.
Figure 12.1. Hierarchy of COM+ administrative collections. Adapted from [Pla-99].
Note that three collections are missing from the hierarchical representation: ErrorInfo, RelatedCollectionInfo, and PropertyInfo. This is because these three collections have special meaning and can be obtained from any other collection.
The ErrorInfo collection provides extended error information in case of failure while using COMAdmin methods to read or write to the catalog.
The PropertyInfo collection provides information about the properties that a specified collection supports.
The RelatedCollectionInfo collection provides information about other collections related to the collection from which it is called.
We will see the programming usage of these three collections later in the chapter.
In order to access the catalog, the collections in the catalog, the items in the collections, and the properties on these items, the COMAdmin library provides three (and only three) generic objects: COMAdminCatalog, COMAdminCatalogCollection, and COMAdminCatalogObject. Each object implements a dual interface, making it convenient to be used from early bound development tools as well as late bound development tools such as VB, VBScript, JScript, etc.
COMAdminCatalog Object
The COMAdminCatalog object is used to represent the catalog itself. It is the fundamental object that is used for any programmatic administration. It supports an interface, ICOMAdminCatalog, that provides methods to implement a variety of administrative tasks. Some of these tasks are listed below:
-
Connect to a catalog server, on either the local or the remote machine.
-
Retrieve various collections from the catalog.
-
Install, export, start, shutdown, and obtain information regarding COM+ applications.
-
Install or import single COM+ components, that is, components that are not part of any COM+ applications.
-
Start and stop COM+ services.
Table 12.2 describes some selected methods from ICOMAdminCatalog interface.
| Method | Description |
|---|---|
| Administrative Methods | |
|
| |
| Connect | Opens a session with the catalog server on the specified machine |
| GetCollection | Retrieves the specified collection |
| GetCollectionByQuery | Retrieves any collection anywhere in the hierarchy |
| Component Methods | |
|
| |
| ImportComponent | Places an already registered component into the catalog |
| InstallComponent | Installs a new component into the catalog |
| GetMultipleComponentsInfo | Retrieves information about one or more components |
| Application Methods | |
|
| |
| ShutdownApplication | Shuts down a running server application |
| ExportApplication | Produces a self-contained installation file (.MSI) for installing the application onto other machines |
| InstallApplication | Reads an MSI file and installs the application |
| Services Methods | |
|
| |
| StartRouter | Starts the load-balancing router service (if installed) |
| StopRouter | Stops the load-balancing router service (if installed) |
| StartIMDB | Starts the in-memory database service (if installed) |
| StopIMDB | Stops the in-memory database service (if installed) |
| ServiceCheck | Checks the status of a COM related service |
| Events Method | |
|
| |
| InstallEventClass | Installs an event class into an application |
| GetEventClassesForIID | Gets a list of event classes matching the specified interface |
| Backup Methods | |
|
| |
| BackupREGDB | Backup RegDB into a file |
| RestoreREGDB | Restore RegDB from a file |
COMAdminCatalog can be instantiated using the PROGID COMAdmin.COMAdminCatalog, as shown in the following VBScript code fragment:
Set Catalog = CreateObject("COMAdmin.COMAdminCatalog") When COMAdminCatalog is instantiated, it opens a session with the local catalog server. To open a session to a remote catalog server, the Connect method on the object can be called, as illustrated in the following VBScript code fragment:
Catalog.Connect("myremotemachinename") We will cover some other methods later in the chapter.
COMAdminCatalogCollection Object
COMAdminCatalogCollection is a generic object used to represent any collection. It supports an interface, ICatalogCollection, that enables you to:
-
enumerate through the items contained within the collection
-
add or remove items to or from the collection
-
save or discard any pending changes made to the collection or to the items it contains
-
retrieve a related collection from the catalog
Table 12.3 describes some selected methods from the ICatalogCollection interface.
| Method | Description |
|---|---|
| Populate the collection | |
|
| |
| Populate | Reads in current data from the catalog for all objects in the collection |
| PopulateByKey | Reads in data only for the specified objects |
| PopulateByQuery | Reads in data for the objects matching the query. Not implemented in the current release |
| Information Retrieval | |
|
| |
| Count | Obtains the number of items in the collection |
| Item | Obtains an item given its index from the collection |
| _NewEnum | Obtains an enumerator for the collection |
| Item Manipulation | |
|
| |
| Add | Adds a new element to the collection |
| Remove | Removes a specified element from the collection |
| SaveChanges | Saves any changes made to the collection or its objects |
| Related Collection | |
|
| |
| GetCollection | Gets a collection related to this collection s specific object |
A collection can be obtained in two ways:
-
By calling GetCollection on the COMAdminCatalog object.
-
By calling GetCollection on the COMAdminCatalogCollection object.
Actually, GetCollection just sets up the returned list to be filled. The list is not filled until Populate (or its variants) is called, in which case the list gets filled up with the current items from the catalog. The usage is illustrated in the following lines of code:
set Applications = Catalog.GetCollection("Applications") Applications.Populate Populate can be called as many times as desired. Each call just synchronizes the list with the latest data from the catalog. Note that it is possible that some other application would have changed the collection that you are holding.
When a collection is retrieved, the data is actually stored in a transient cache. If an item is added, removed, or modified in the collection, the transient cache gets modified, not the actual catalog. To commit the changes to the catalog, you should call SaveChanges. After calling SaveChanges you would need to reload the collection list (by calling Populate), as shown in the following code fragment:
' Add a new appliction Dim newApplication Set newApplication = applications.Add ... ' Set various properties on newApplication ' Commit new application and reload the list applications.SaveChanges applications.Populate
It is possible that multiple programs may be working on the catalog simultaneously. While you are working on your transient copy of the data, someone else may have modified the catalog, either programmatically or through the Component Services snap-in. If there is any contention when the changes are being saved, the general rule is that the last writer wins, that is, the data stored in the catalog is the one that came from the last one to save it.
COMAdminCatalogObject Object
COMAdminCatalogObject is a generic object that can be used to represent any item contained in a collection. It exposes an interface, ICatalogObject, that can be used to:
-
obtain information about an item (in the collection) and its properties
-
modify the properties of the item
Table 12.4 shows some properties available on the ICatalogObject interface.
| Method | Description |
|---|---|
| Name | Gets the name of the item |
| Key | Gets the unique ID of the item |
| Value | Gets or sets a named property on the item |
Each item in a collection has a name and a unique key. The key serves as the primary identifier for the item. In some cases it is a GUID, such as the CLSID for a component; in some cases it is the name of the item itself.
Each item in a collection contains properties that apply to that type of item. For example, every item in the applications collection represents an application object. Each application object has properties such as activation. (This property indicates if the application is a library application or a server application.)
Each property of a specific collection is uniquely identified by a name. The Value property on the ICatalogObject interface is used to obtain or save a specific named property exposed by an item.
The following VBScript code fragment lists each application installed on the local system. For each application, the code displays the application s key and whether the application is a library application or a server application.
' Instantiate a COMAdminCatalog object Set Catalog = CreateObject("ComAdmin.COMAdminCatalog") ' Get the "Applications" collection and populate it set Applications = Catalog.GetCollection("Applications") Applications.Populate ' Display the name of each application for each AppObject in Applications DispString = AppObject.Name & " " & AppObject.Key if AppObject.Value("Activation") = 0 then DispString = DispString & " - INPROC" else DispString = DispString & " - LOCAL" end if wscript.Echo DispString next Some collections may expose the name and key of an item as properties as well. For example, the key of an application object can also be obtained as AppObject.Value("ID"). If you add a new object and save it with the key property of an existing object, you will overwrite the existing object.
 | Beware of setting the key property on an item. In most cases, it is better to let the catalog generate the key for you. |
If a property is modified, the change is not committed until SaveChanges is called on the collection.
 | All the COMAdmin classes are served by one DLL ComAdmin.DLL. It can be found in the system32\COM subdirectory. |
| < BACK NEXT > |
EAN: N/A
Pages: 129