Namespaces

A number of model kinds in the CommaSuite language support declaration of a namespace and definition of elements that become part of the namespace.

A CommaSuite model can import an element from a namespace or the entire namespace in a way similar to Java package import and can refer to the imported elements.

Support for namespaces is available since version 0.3.0. Before that, only explicit file import is supported. Using namespace and file imports in the same model is a subject of some restrictions. Please check further this page for more information.

Namespace Declaration

A model may optionally declare a namespace. The definitions in the model become elements of the namespace. It is possible that multiple models declare the same namespace. It is also possible that the files containing such models belong to different Eclipse projects and even residing outside the Eclipse workspace.

The following models can declare a namespace: types, interface signature, interface, component.

An example namespace declaration in a types model is:

namespace my.example

type long based on int

The namespace name contains at least one segment, segments are separated by dot ('.').

Fully Qualified Names

The most commonly used CommaSuite model elements have names. When defined in the context of a namespace, a model element can be unambiguously referred to by its fully qualified name.

The fully qualified name is formed by collecting the namespace segments (if any), the names of all the containers of the model element, and the simple name of the model element. The separator of the segments is dot ('.').

Examples:

Assume a type model with namespace org.example that contains type named Person. The fully qualified name will be:

org.example.Person

Now assume that type Student is defined in a signature named iX which is part of namespace org.example. The fully qualified name will concatenate the namespace and the name of the container (the signature):

org.example.iX.Student

Namespace Imports

A model may need to refer to an element defined in another model. If this second model declares a namespace, the element or the entire namespace can be imported without giving explicitly the file location of the model. Then the required element can be referred to.

The following is an example of namespace import:

import my.example.long // import of a single element from namespace my.example
import my.project.types.* // wildcard import: all elements of my.project.types namespace are imported

record R {
    long l // the imported type can be referred to with its simple name
}

The wildcard import shown above imports all elements in the namespace.

It is also possible to refer to an element without importing its namespace. A fully qualified name has to be used:

import my.project.types.*

record R {
    my.example.long l // my.example namespace is not imported. Fully qualified name is used instead.
}

Finally, if a model declares a namespace, it is automatically imported. For example:

File globals1.types

namespace project.globals

type wstring based on string
type double

File globals2.types

namespace project.globals

record Point {
    double x,
    double y
}

In the example, type double is used in the record type Point without importing its namespace. Both type models declare the same namespace so type double can be used with its simple name.

Using File Imports and Namespaces

We saw that a namespace import does not specify the physical location of the model that contains the imported definitions. It is also possible that multiple models contribute to a namespace.

CommaSuite language also supports explicit file imports (see the pages on the specific language elements on this topic).

Generally, the following restrictions apply for using file imports and namespaces together:

  • File imports and namespace imports cannot be used together in the same model. This works transitively: if a model imports another model, then this model cannot directly or indirectly import a namespace

  • It is possible to import a model that declares a namespace. In this case, the fully qualified names of model elements have to be used

Namespaces and Dependencies of CommaSuite Projects

CommaSuite models are usually created in the Eclipse IDE and are distributed across one or more Eclipse projects.

If a model imports a namespace, the underlying implementation will search for models from a given collection that provide the definitions belonging to this namespace.

This collection of models contains all the models in the current Eclipse project and all the models in the projects it depends on. Therefore, the namespace mechanism relies on the built-in Eclipse project dependency mechanism.

In summary, if a model in a given Eclipse project is using namespace import of content located in another Eclipse project then there should be a reference to the other project.

Adding a project reference is a standard Eclipse mechanism: right mouse click on the project (e.g. in the model or package explorer), select menu 'Properties', then item 'Project References' from the list on the left-hand side. Then from the right-hand side, select the projects which you refer to.

Using Models outside of Eclipse Workspace

In some cases, models that contribute to a namespace may be located in a library (or folder) that is not in a project in the Eclipse workspace. It is still possible to use these models and access their content by namespace import. However, you need to add Java nature to your project.

In order to use a collection of models outside the workspace, follow the steps:

  • Add Java nature to your project: right-click on the project and select 'Properties'. Select 'Project Natures', click 'Add' button and select Java nature

  • The folder that contains the external models has to be added as a library in the project build path: right-click on the project, then menu 'Properties'. Select 'Java Build Path' and then select tab 'Libraries' in the right-hand side.

  • Select the 'Classpath' item and then press button 'Add External Class Folder'. Navigate to and select the folder from the dialog box.

The steps above will include the content of the external folder in the collection of models whose content is used by the namespace import mechanism.

From the explanation until now it becomes clear that the namespace mechanism relies on Eclipse workspace concepts and project (or build path) dependencies. However, when CommaSuite is used from the command line interface, the Eclise workspace and Eclipse projects are not available. Please consult the documentation on the command line tool for relevant input arguments.