Fully-Qualified NamesWorking with Classes

A package in the Unified Modeling Language is used to "group elements, and to provide a namespace for the grouped elements". Pretty much all UML elements can be grouped into packages. A package may even contain other packages, thus allowing hierarchical nesting of packages.

QM™ supports packages and allows a package to contain:

other packages
classes
free attributes
free operations
directories

Adding a Package

In the Model Explorer right-click on the Model or a Package item to which you want to add a new package and select Add Package from the popup menu.

Adding a Package to the Model

Note: Alternatively, you can also add an External Package by importing it.

Package Property Sheet

A QM™ package item can be configured by the Package-Specific Property Sheet.

Package Property Sheet

The package-item property sheet allows you to set the following properties:

package name
package stereotype
package file (see External Packages)
package namespace

Package Stereotype

A QM™ package can have a configurable "stereotype", which you set through the Property Editor for the package. The purpose of the package stereotype is to provide concise information about the contents of the package and currently has no other function or implications for code generation.

Setting Stereotype for a Package

QM™ currently supports the following package stereotypes:

Package Stereotype	Explorer Icon
undefined
events
components
diagrams
framework

Package Namespace

As mentioned at the top of this section, one of the main jobs of a package is to provide a namespace for the grouped elements. QM™ supports this feature through the namespace field in the Property Editor for the package.

Note: By using a namespace (or possibly multiple namespaces) you can avoid name conflicts with other code, such as any 3rd party libraries, in which you cannot easily change names.

Setting Namespace for a Package (C++ case)

If you choose to set a non-empty namespace in the package's property sheet, your choice will be reflected in the Model Explorer by showing the namespace in parentheses in front of the package name. For example, in the screen shot above the namespace DPP:: is shown as the string (DPP::) prepended to the package name AOs (active objects). In contrast to the package stereotype, the package namespace has important implications for code generation.

Namespaces in C++

If you use a package with a namespace in C++ (i.e., your model is based on the qpcpp framework), the QM code generator will surround all the appropriate code sections with the C++ namespace as follows:

namespace DPP {
    . . .
} // namespace DPP

Attention: In C++ (see below), a package namespace must be specified with the trailing scope-resolution operator :: (double colon).

Moreover, QM™ will also handle correctly the case of nesting packages with namespaces. For example, if a package with namespace BAR:: nests inside a package with namespace FOO::, any element from the nested package will be surrounded by the correctly nested namespaces as well:

namespace FOO {
namespace BAR {
    . . .
} // namespace BAR
} // namespace FOO

Namespaces in C

QM™ also supports namespaces in C (i.e., in models based on the qpc framework). In C, the QM code generator will prepend the namespace to the names of elements included in the package, such as classes, class operations, free attributes, and free operations.

Note: For improved code readability in C, it is recommended to use the underscore _ as the last character in the namespace string. QM™ will not insert any characters between the namespace and the name of the element.

For example, if your package defines a namespace string as "FOO_", the code generated for any elements inside this package will look as follows:

typedef struct {
    . . .
} FOO_Test_QMsm;
 
static QState FOO_Test_QMsm_initial(FOO_Test_QMsm * const me,
                                    QEvt const * const e);
. . .

Again, also in C, the QM code generator supports the case of nesting packages with namespaces. For example, if a package with a namespace BAR_ nests inside a package with a namespace FOO_, the generated code will correctly nest namespaces as follows:

typedef struct {
    . . .
} FOO_BAR_Test_QMsm;

static QState FOO_BAR_Test_QMsm_initial(FOO_BAR_Test_QMsm * const me,
                                        QEvt const * const e);
. . .

External Packages

QM™ supports external packages, which are are saved to the specified files instead of being saved as part of the main Model File. In other words, the use of external packages allows you to split the Abstract Model into multiple model files, which then can be owned by different team members and tracked separately in a Version Control System (VCS)↑.

Also, an external package can be imported into many QM™ models, thus such an external package can be shared and reused among all these models. In fact, the intent for reuse should be the main consideration for deciding whether or not a package should be made external.

Exporting a Package

To export a package (thus making it an external package), you simply provide an non-empty file_property in the Package Property Sheet:

External Package with a Non-Empty File Name

The package file_property can contain the whole path to the package file, which is always relative to the Model File. For example, in the screen shot above, the package "tcp_ip" will be saved to the package file "tcp_ip.qmp" in the parent directory (..) relative to the model file.

The default extension of the package file name is .qmp (QM Package). If you don't provide this extension, QM™ will append it for you.

Note: To give you quick visual feedback that a package is external, the Model Explorer adorns the package icon with a red arrow, like so: package

Attention: If an external package contains any directories and files (for code generation), the generated code is relative to the package file, as opposed to be directly relative to the model file.

Importing a Package

To import an external package into your QM™ model, go to the Model Explorer view and right-click the mouse over the model item or a package item into which you wish to import the external package. This will open a popup-menu, from which you need to select the option "Import package".

Importing a Package

This action will launch the standard file-open dialog box, through which you can select the package-file you wish to import. Select the desired package file and click "Open". Note that by default, the dialog box shows only the files with extension .qmp.

Selecting the Package File to Import

QM™ allows you to import an exported package into any number of models. All these models will then be able to use the package and to change it as well.

Note: If you want to avoid inadvertent modification of the imported package you can lock it from editing.

Fully-Qualified NamesWorking with Classes