Type Library Importer

---

Contents

This chapter is organized as follows:

• Overview
• What Is a Type Library?
• Why Would I Want to Import Type Libraries into the Model?
• What COM Components Can Be Imported into the Model?
• How Is a Type Library Presented?
• Importing a Type Library into the Model
• Importing a New Version of an Existing Type Library
• Hiding Type Library Items
• Using an Imported Type Library
• Adding Class Members to a Quick Import Type Library
• Customizing the Type Library Importer

---

Overview

The Type Library Importer allows you to import a type library of a COM component into the model by dragging the COM component from Windows Explorer and dropping it in Rational Rose. You can also click Tools > COM > Import Type Library.

You can control several aspects of how type libraries are imported into the model. For example, you can control:

• What should happen with existing type libraries when importing new versions.
• The name and location of new type libraries in the model.
• The name and contents of the overview diagrams that are created when importing type libraries.

For further information, refer to the Customizing the Type Library Importer.

Note: Importing a component is not the same as reverse engineering a component into the model. Imported components are still external to the system, because you import only the type library of the components; whereas, reverse engineering a component means that a model of the component's source code is added to the model.

---

What Is a Type Library?

A type library contains a description of a COM (component object model) component as viewed from the outside. The description includes the coclasses, interface items, dispinterfaces, properties (called attributes in UML), methods (called operations in UML), data types, and so on of the component. Type library information is needed to provide a language-neutral description of the interfaces and data types that a COM component exposes.

This chapter does not explain the different kinds of type library items--coclasses, interfaces, dispinterfaces, and so on. For information about COM components and type libraries, refer to:

• Don Box, Essential COM, Addison-Wesley Pub Co, ISBN 0201634465
• http://msdn.microsoft.com/library--for example, the Inside OLE section in the Books section

---

Why Would I Want to Import Type Libraries into the Model?

By importing type libraries into the model, you can show how classes in the model use and depend upon classes in other components, regardless of their implementation language. For example, you can:

• Reuse COM components--that is, to show how the classes in the model instantiate, use, and communicate with the items in a COM component.
• Show how classes in the model implement (or realize) the interface items of a COM component.
• Show dependencies between components.
• Use the data types defined by a COM component when specifying attributes and operations on the classes in the model.

---

What COM Components Can Be Imported into the Model?

The following file types can be imported into a Rational Rose model:

• Dynamic Link Libraries (.dll)
• Executables (.exe)
• ActiveX Components (.ocx)
• Object Libraries (.olb)
• Type Libraries (.tlb)

The file must contain valid type information. If you drop a file without type information on an element in the browser, Rational Rose treats it as any file and attaches the dropped file to the model element that you drop it on. When you drop the file in Rational Rose, the cursor icon indicates whether the file will be imported or attached to a model element:

• A icon means that Rational Rose imports the file.
• A icon means that the file is attached to the model element that you drop it on.

---

How Is a Type Library Presented?

In Rational Rose, an imported type library is represented as a component in the component view and a logical package containing the type library items. In your implementation environment, a type library is presented differently in different implementation language environments.

A Type Library in Rational Rose

The Type Library Importer creates a component, such as Scripting Ver 1.0 (Microsoft Scripting Runtime) in Figure 101, in the component view for an imported type library.

Figure 101 Component View of the Microsoft Scripting Runtime Type Library

The Component Overview Diagram

The component is automatically inserted into a type library overview diagram in the component view. For example, the overview diagram in Figure 102 shows that two type libraries, Scripting and stdole, have been imported into this model and that the Scripting type library depends upon the stdole type library.

Figure 102 Component Overview Diagram for a Model

The Logical View of a Type Library

The logical view contains a package for the imported COM component, such as Scripting Ver 1.0 (Microsoft Scripting Runtime) in Figure 103.

Figure 103 Logical View of the Microsoft Scripting Runtime Type Library

Type Library Items

The logical package contains the type library items that are defined by the type information of the imported COM component--coclasses, interfaces, dispinterfaces, and so on.

Each item in the type library is represented by a class, such as the coclass FileSystemObject in Figure 103. The stereotype of the type library's classes in the model indicates the kind of project item--coclass, interface, enum, type, module, struct, and union (refer to COM Stereotypes). In Figure 103, you can see that coclasses have their own icon in the browser: .

The kind model property on an interface class indicates whether the class corresponds to an interface or a dispinterface in COM.

Note: If the type library was imported using a quick import, the Type Library Importer does not create any class members (attributes and operations) on the imported items. If you chose a full import, the class members are created. You can later import the class members for a type library item; refer to Adding Class Members to a Quick Import Type Library.

The Type Library Overview Diagram

An overview diagram is created in the logical view, which shows the contents of the imported type library. Figure 104 shows the overview diagram for the Microsoft Scripting Runtime type library. As you can see, coclasses, such as Encoder in Figure 104, are shaded (green) in type library overview diagrams.

Figure 104 Overview Diagram of the Microsoft Scripting Runtime Type Library

Hidden Items

If the Show hidden items check box in the COM Properties dialog box is cleared when a type library is imported, all hidden items and items with names beginning with "_" are placed in a separate logical package called "Hidden". Those items are not displayed on the overview diagram. The Microsoft Scripting Runtime type library in Figure 103 and Figure 104 was imported with the Show hidden items check box cleared.

For more information, refer to Hiding Type Library Items.

Referenced Type Libraries

Any referenced type libraries are automatically imported. When importing a type library item (for example, A), all items that A refers to must exist in the model. If the referenced items did not exist in the model before, the Type Library Importer automatically imports the type libraries of the corresponding COM components and adds dependency relationships between them. For example, the stdole type library in Figure 102 was automatically imported when the Scripting type library was imported, because Scripting refers to the stdole type library.

Referenced type libraries are imported using a quick import. Also, type library items that are referenced by the current type library, such as IDispatch in Figure 104 , are gray in the type library's overview diagram.

COM Stereotypes

The Type Library Importer uses the stereotypes in Table 17 for the model elements that represent a type library in the model.

Table 17 COM Stereotypes  

Stereotype	Description
Components
COM	The Type Library Importer assigns the stereotype and language "COM" to the component representing an imported type library.
Classes
coclass	Represents a coclass in a type library.
enum	Represents an enum type definition in a type library. The class members of the enum in the type library become attributes with initial values on the class in the model.
interface	Represents an interface or dispinterface in a type library. The "kind" model property on the class in Rational Rose indicates whether the class is an interface or a dispinterface. Type library interfaces are always abstract--that is, the Abstract box in the interface's Class Specification is checked.
module	Represents a module in a type library.
struct	Represents a struct type definition in a type library. The class members of the struct in the type library become typed attributes on the class in the model.
union	Represents a union type definition in a type library. The class members of the union in the type library become typed attributes on the class in the model.
Operations
propget	Corresponds to a property-accessor function on an interface or dispinterface.
propput	Corresponds to a property-setting function on an interface or dispinterface.
propputref	Corresponds to a property-setting function that uses a reference instead of a value.
Realize relationship
none	Represents any realize relationship between type library items.
source	Indicates that the realized interface contains the coclass' event procedures.
default	Indicates that the realized interface is the default interface of the coclass.
Dependency relationship
imports	Indicates that the supplier COM component was automatically imported when the client component was imported, because the supplier component is referenced by the client component.

Type Library in the OLE Viewer in Visual Studio

The contents of a type library as shown in the OLE Viewer correspond to how Rational Rose presents an imported type library. Figure 105 shows how the OLE Viewer in Visual Studio presents the Microsoft ActiveX Data Objects type library, MSADO15.dll. All the type library items displayed by the OLE Viewer can be found in the model after importing the type library.

Figure 105 OLE Viewer in Visual Studio

Type Library in the Object Browser in Visual Basic

Figure 106 shows how the Object Browser in Visual Basic presents the Microsoft ActiveX Data Objects type library, MSADO15.dll. The Object Browser in Visual Basic shows only those type library items that are relevant in Visual Basic. For example, it does not list the default interfaces of the coclasses, because Visual Basic assumes the default interface when referring to a coclass.

Figure 106 Object Browser in Visual Basic

Since Rational Rose supports many different programming languages, all items in an imported type library are shown in the model. However, by clearing the Show hidden items check box, the top level of the packages of the type libraries that you import, as well as their overview diagrams, give the same view of the libraries as the Object Browser in Visual Basic. For more information, refer to Hiding Type Library Items.

---

Importing a Type Library into the Model

The Type Library Importer in Rational Rose allows you to import a type library of a COM component into the model. By doing that, you can show how classes in the model use and depend upon classes in other components.

If you want to change the default behavior of the Type Library Importer, click Tools > COM > Properties to display the COM Properties dialog box. In it, you can control how to import type libraries. For more information, refer to Customizing the Type Library Importer.

To import a type library into the model:

1 If a type library is to be used by Visual Basic classes only, you may want to show only the type information that is relevant for Visual Basic classes. Refer to Hiding Type Library Items.

2 Drag the file--DLL, EXE, OCX, OLB, or TLB--from Windows Explorer and drop it in the browser or in a diagram. (The drop target is not important, because the type library is created in the packages defined by the Default package options in the COM Properties dialog box.)

Note: If the Rational Rose application window is hidden or minimized, point to the Rational Rose icon in the Windows task bar before dropping the file; this brings the application to the front. Instead of dragging and dropping the file, you can click Tools > COM > Import Type Library and select the appropriate file.

3 On the displayed menu, select whether to import the full component (Full Import), including all operations and attributes of the type library items, or to perform a Quick Import which excludes the members.

Note: You can later import the members of a quickly imported type library item, refer to Adding Class Members to a Quick Import Type Library.

The following results occur:

• If the selected COM component contains all the necessary type information, the Type Library Importer creates a representation of the type library in the model.
• If a dragged and dropped COM component does not contain valid type information, and if you have dropped the component on an element in the browser, Rational Rose attaches the dropped file to that element if possible. That is, if the cursor turns into an arrow with a icon, Rational Rose will attach and not import the file.

---

Importing a New Version of an Existing Type Library

To import a new version of a type library that already exists in the model, right-click the component that represents the imported type library and click Upgrade to Latest Version.

---

Hiding Type Library Items

When importing a type library, the created type library in the model is represented differently depending on whether the Show hidden items check box is selected in the COM Properties dialog box. Click Tools > COM > Properties to display the COM Properties dialog box.

Show Hidden Items Selected

If the Show hidden items check box is selected when importing a type library, all type library items, including coclasses, dispinterfaces, and interfaces, are shown on the type library's overview diagram. Also, the type library items are inserted directly under the type libraries package in the browser.

Figure 107 shows how the Microsoft Scripting Runtime component, scrrun.dll, is presented when imported with the Show hidden items check box selected. This view is recommended when developing clients in languages other than Visual Basic.

Figure 107 Type Library with Show Hidden Items Option Selected

Show Hidden Items Cleared

If the Show hidden items check box is cleared when importing scrrun.dll, no hidden type library items are shown on the type library's overview diagram. Also, the hidden type library items are inserted into a separate package called "Hidden" in the type library's package in the browser.

Figure 108 shows how the Microsoft Scripting Runtime component, scrrun.dll, is presented when imported with the Show hidden items check box is cleared.

Figure 108 Type Library with Show Hidden Items Option Cleared

In this view, only the type information that is relevant for Visual Basic clients is shown on the type libraries overview diagram, and all hidden type library items are inserted into a separate package called Hidden. This view is recommended when developing Visual Basic clients because it corresponds to the view that is shown by the Object Browser in Visual Basic (see Figure 106 ).

---

Using an Imported Type Library

By importing type libraries into the model, you are able to show how classes in the model use and depend upon classes in other components, regardless of their implementation language. The application you are modeling can use a type library in several ways, for example:

• Classes can use the data types defined by a type library.
• Classes in the model can implement the interface of a COM component.
• A COM component can be reused by the application.

How to use a type library depends on the programming language. For more information, refer to the Rational Rose documentation of each language integration.

---

Adding Class Members to a Quick Import Type Library

If a type library was imported using a quick import, the Type Library Importer did not create any class members (attributes and operations) on the imported items. You can later import the class members of a type library item by doing a full import of that item.

To add class members to a type library:

1 In the browser or in a diagram, right-click:

• an interface to import its class members into the model.
• a coclass to import the class members of its interfaces into the model.
• a COM component to import the class members of all the items in that type library.

2 Click Full Import on the displayed menu.

Note: It may take several minutes for Rational Rose to perform a full import of an entire COM component. If you do not want to import the entire type library, perform a full import of only those type library items that you are using.

---

Customizing the Type Library Importer

In the COM Properties dialog box, you can control how type libraries are imported into the model. For example, you can control:

• What should happen with existing type libraries when importing new versions.
• The name and location of new type libraries in the model.
• The name, location, and contents of the overview diagrams that are created when importing type libraries.

To open the COM Properties dialog box, click Tools > COM > Properties.

Figure 109 COM Properties Dialog Box

Note: Changing the settings in the COM Properties dialog box affects only type libraries that are imported after the settings are changed.

To replace existing type libraries when importing new versions:

Select the Upgrade older type libraries check box in the COM Properties dialog box.

The next time you import a new version of a type library, the current version is replaced by the new version. If this check box is cleared when you import a new version of a type library, the model will contain both versions.

To hide items that are defined as hidden or called "_item":

Refer to Hiding Type Library Items.

To show the composition hierarchy for imported type libraries:

Select the Construct composition hierarchy check box. The next time you import a type library, the Type Library Importer adds association relationships between its related interfaces, which indicate the type library's composition hierarchy.

To change the name of the logical packages in which type libraries are created:

In the Default package box under Logical view in the COM Properties dialog box, type the name of the package including the path of any enclosing packages. You can use the following variables in the package name:

• $library -- the name of the imported type library, which corresponds to the library model property
• $version -- the version of the imported type library, which corresponds to the version model property
• $helpstring -- a description of the type library, which corresponds to the helpstring model property

For example, COM/$library Ver $version ($helpstring) means that the following logical package is created for a new type library called stdole:

Logical View

COM

stdole Ver 2.0 (OLE Automation)

To change the name of the component packages in which type library components are created:

In the Default package box under Component view in the COM Properties dialog box, type the name of the package including the path of any enclosing packages. You can use the same variables as above.

For example, COM/$library Ver $version ($helpstring) means that the following component package is created for a new type library called stdole:

Component View

COM

stdole Ver 2.0 (OLE Automation)

You can change the name and location of the diagrams on which type libraries are displayed. In the Overview diagram box under Logical view or Component view in the COM Properties dialog box, type the name of the diagram including the path of any enclosing packages. You can use the same variables as above in the diagram name.

For example, the default value for the logical view is COM/$library Ver $version ($helpstring)/Overview of $library, which means that the Type Library Importer creates a diagram called Overview of stdole Ver 2.0 (OLE Automation) when you import a COM component called stdole.

The default value for the component view is COM/Overview of type libraries. This means that the Type Library Importer inserts all imported type library components into the same diagram, which is called Overview of type libraries.