Working With Items

Items and components

When you draw a symbol in a diagram editor, you create a component, which is a graphical element in the repository. When you specify property values for the component, you create an item, which is a semantic element in the repository. Diagram names are also items.

Implicit and explicit properties

You describe items and components by specifying their implicit and explicit properties.

Specify implicit properties through the diagrams. The UML suite creates these properties when you add components to a diagram and stores them in the diagram file. For example, in the CD, you use the multiplicity specifications at either end of an association to specify the multiplicity of the association.
Specify explicit properties through the Edit Properties dialog box, as described in Chapter 5, Properties and Stereotypes.

Identified by name and type

An item is identified by its name and its type.

Item name. An item name can be up to 80 characters in length. All printable ISO-Latin-1 characters, except space, tab, newline, slash, colon, and comma are allowed in item names.

Item type. The type of an item is determined by the symbol used to create it. The relationship between symbol and type is fixed internally in the UML suite and cannot be changed. The types used in the UML suite are as follows:


Type	Meaning
ce	collaboration editor
cl	class
de	data element
et	event trace
ie	instance (component/deployment) editor
pe	process element
rs	reserved word
st	state

Appendix A, Type and Scope of Diagram Components, lists the type of each diagram and diagram component.

Purpose of items

Items allow different graphical elements to refer to the same semantic element.

Example

When you create the Rental class in a CD, you create an item with the name Rental and type cl. By default, the UML suite associates this item with any other Rental class that you create in any other diagram in the same Phase.

Qualified items

Qualified items belong to another item. Operations and classes, for example, are both items. Because an operation always belongs to a class, an operation is a qualified item. The name of a qualified item consists of the owner item name and the qualified item name. For example, the getName operation on the Member class is named Member.getName.

The names of the following diagram types are also qualified by a class name: activity (AD), collaboration (COD), sequence (SD), and statechart (STD). For example, a Statechart diagram for the Member class might be named Member:lifecycle.

Defining and Viewing Items

Items and components

A graphical element in a diagram editor is a component. A semantic element in the repository is an item. In a complete model, each component is linked to an item.

How to define an item

ÿ To define an item explicitly:

Open a diagram, for example, a Sequence Diagram.
Add a component to the diagram; for example, add an object to the Sequence Diagram.
Select the component; for example, select the object.
Select Item | Edit Properties.
In the left pane of the Edit Properties dialog box, select the item.
The item properties appear in the right pane.
Click Define Item.
Note: If the item exists, the Define Item button appears dimmed.

Implicit definition of items for classes

When you create a class in a CD, you often specify its attributes and operations before specifying its properties. When you add an attribute or operation to a class symbol, the UML suite defines the class item. Therefore, you rarely use the previous procedure to define class items.

How to view items

You can view items using the Browser or reports:

In the Browser, move to Package level and select View | Defined Items. The UML suite lists all items that have scope phaseDef, phaseRef, or system. For each item, by default, the UML suite displays its name, type, scope, and status.
At any level in the Browser, or from a diagram editor, run the Items report. The report displays all items visible at the selected level, including those with scope File.

Renaming Items

Editing a label does not rename an item

Editing the label of a component creates a new item. It does not change the name of the item. To change the name of an item, you must rename it using either File | Change | Name in the Browser or Edit | Change Name in a diagram editor.

Renaming an item can affect multiple objects

In the UML suite, the names of diagrams and most diagram components are stored as items. For example, the name of a CD and the name of a class are both stored as items of type cl. If two items of the same type have the same name, they are the same item. For example, if a CD and a class have the same name, they refer to the same item. Changing the name of one also changes the name of the other.

Appendix B, Type and Scope of Diagram Components, lists the item type of diagram names and diagram components.

How to rename an item from the Browser

ÿ To rename a diagram item from the Browser:

In the Browser, move to the package that defines the item that you are interested in.
Select View | Defined Items.
In the information area, select the item that you want to rename.
Select File | Change | Name.
In the Change Name dialog box, type the new name and click OK.

How to rename an item from the diagram editor

When you rename an item, the UML suite updates the repository immediately. The new item name remains even when you close the diagram without saving changes.

ÿ To rename an item from a diagram editor:

Open the diagram in which the item is defined.
Select the object whose name you want to change or in which the object whose name you want to change appears.
Select Edit | Change Name.
Note: If more than one item is associated with the selected object, the Items dialog box appears. Select the item and click OK.
In the Change Name dialog box, type the new name and click OK.

Specifying Scope

Definition

An item's scope defines its name space and where it is defined. You specify an item's scope as Phase, Package, or File.

Appendix B, Type and Scope of Diagram Components, lists the item type and initial scope of each diagram component. An item keeps its initial scope unless you change it.

Scope and item name space

Scope defines the range within which an item's name must be unique.

Phase. The item's name must be unique within the phase. For example, if class Member appears in two packages that are in the same phase, and both classes have scope Phase, then both packages are referring to the same item.
Package. The item's name must be unique within the package. For example, if class Member appears in two packages that are in the same phase, and both classes have scope package, then the packages are referring to two different items.
Note: In the UML suite 8.2, references to system changed to package. However, this change did not propagate to the repository. In the Browser's information area, an item can still appear with a system scope despite having set the scope to the package level. Unless explicitly referring to what appears in the Browser's information area, references to scope are in terms of a package.
File. The item's name must be unique within the file. For example, if association Rents appears in two CDs in the same package, and both associations have scope File, then the CDs are referring to two different items.

Scope and item definitions

Scope also defines where an item's definition is stored. (Qualified items always have the same scope as the owner item.)

Phase. An item that has scope Phase is defined in one package, but can be referred to by many packages.
- The package in which you defined the item contains the item definition. In this package, the UML suite creates the item with scope phaseDef.
- Any package that references the item contains a reference to the item. In these packages, the UML suite creates the item with scope phaseRef.
Package. The package in which you defined the item contains the item definition. the UML suite creates the item with scope System.
File. The file in which you defined the item contains the item definition. The UML suite creates the item with scope File.

Editing items

Generally, if you can see an item in a diagram editor, and the diagram editor is not loaded read-only, you can edit the item. The following items are useful to keep in mind when editing:

If an item has scope Phase or System, editing it can affect packages or diagrams other than the current diagram. To see the scope of an item, select the item and then select Edit | Scope. The Edit Scope dialog box indicates the current scope of the item.
If a class has scope Phase, you can edit its name (Item | Change Name) and properties (Item | Edit Properties) from any package in which it appears. However, the class's attributes and operations are only visible in, and can only be edited in, the package that contains the class definition.

Locating items

On each level, at most one item with a given name and type can exist. The levels form a nested structure -- file, package, phase -- in which items can be found. Items are searched for (by name and type) starting at a given level. If the item is not present at that level, the UML suite searches the next highest level until a matching item is found, or the highest level is reached.

How to change an item's scope

Note: When you change an item's scope, the UML suite updates the repository immediately. The item's new scope remains even if you close the diagram without saving changes.

ÿ To change an item's scope:

In the diagram, select the object.
Select Item | Edit Scope.
Note: If more than one item is associated with the selected object, the Items dialog box appears. Select the item and click OK.
In the Edit Scope dialog box, select an option. The options that appear depend on the type and scope of the selected item. Then click OK
An item's scope determines where its definition is stored. Changing its scope can change its definition. Use the options to determine the item definition for the new scope.

Changing the scope downward

Changing the scope downward means changing it from a higher level to a lower level, for example, from Phase to Package. Typically, when you change the scope downward, you copy the item definition. The item definition also remains on the higher level. The Edit Scope dialog box, presents the following options:


Option	Scope Change
Create empty definition on File/Package level Create a new item definition, with default property values, in the current file or package.	System to File Phase to File Phase to System
Copy definition to File/Package level Copy the existing item definition, including its property values, to the current file or package.	System to File Phase to File Phase(Ref) to System
Restrict definition to Package level Item is defined in the current package. Do not modify item definition; instead change scope.	Phase(Def) to System

Changing the scope upward

Changing the scope upward means changing it from a lower level to a higher level; for example, from Package to Phase. Typically, when you change the scope upward, you move the item definition. The Edit Scope dialog box presents the following options:


Option	Scope Change
Export definition to Package/Phase level Move the existing item definition, including its property values, to the current package. The item definition in the file is deleted.	File to System File to Phase(Def)
Make definition available on Phase level Item is defined in the current package. Do not modify item definition; instead change scope.	System to Phase(Def)
Refer to (not yet existing definition) on Package level Create a new item definition, with default property values, in the current package. The item definition in the file is deleted.	File to System
Refer to (not yet existing definition) on Phase level The item definition in the file is deleted. The item is undefined.	File to Phase(Ref)
Refer to definition on Phase level The item definition in the file is deleted. The item definition exists in another package. Note: If the item is a class and the package contains the CDM, the item definition cannot be deleted; the scope cannot be changed.	Package to Phase(Ref)

Note: If you attempt to create an item definition in a package that already contains a definition for that item, an error message appears. You must delete the existing definition before you can create a new one.

Removing and Moving Items

Purpose

You can remove items that are no longer referenced and move item definitions from one package to another.

Removing unreferenced items

When you name a diagram component, you create an item. If you delete the diagram symbol, the item remains in the repository and can be used in other diagrams. If you do not use the item, removing it from the repository improves performance and avoids unexpected name conflicts.

How to remove unreferenced items

ÿ To remove unreferenced items:

In the Browser, move to the appropriate level.
- To remove unreferenced items from selected packages, move to Phase level.
- To remove unreferenced items from selected files, move to Package level.
Select the packages or files from which you want to remove unreferenced items.
Select Utilities | Delete Unreferenced Items.

Also available from diagram editors

Use Utilities | Delete Unreferenced Items to remove unreferenced items from the current diagram file.

To move an item definition

You can move the definition of any unqualified item that has scope phaseDef from one package to another. When you move an item's definition, the definitions of all items that it qualifies are also moved.

ÿ To move an item definition:

In the Browser, move to the package that defines the item that you are interested in.
Select View | Defined Items.
In the information area, select the items you want to move.
Note: You can only select items with scope phaseDef.
Select Utilities | Move Definition.
In the Move Definition dialog box, select the package that you want to move the selected items to, and then click OK.