| Icon | Meaning |
| <img src="images/2a05f87a4292bfecb242bff603249f384f86fc8d046326ed5c2af664e82a5224.jpg"/> | Item of special significance or where caution needs to be taken. |
| <img src="images/2f8a03184f07ba6929c0610d462b5baa13e1b03d87dee3b76889cd5a2761eb27.jpg"/> | Item contains helpful hint or special information. |
| <img src="images/42957640ce78c593274572bbd2ed7b41b0e3a7ee6d892d77bf0a4bde27b9d456.jpg"/> | Information applies to Windows (e.g. XP, 2003, Windows 7) only. |
| <img src="images/55135cc7581523fce7ddd1eb66b08f8e6fd95ab167383231a59a4998a53ee470.jpg"/> | Information applies to Unix-based systems (e.g. Solaris) only. |
| <img src="images/9eae80ba39b971221a39b756acb5003851dffcba4553f7c89fcc83909adcdaea.jpg"/> | Information applies to Linux-based systems (e.g. Ubuntu) only. |
| <img src="images/91471bff6143cec77d9971f90dd0183064b07925feb0bfc5b70d3ca70049d5d0.jpg"/> | C language specific. |
| <img src="images/8fe49bbc4d91c23f63d75b43394c20f1cdf8f4f6a4c730c1d71c4c74c43e09b2.jpg"/> | C++ language specific. |
| [78BA] | C# language specific. |
| <img src="images/caf1c16636805907234a94893aca2e9f2dff6f072bd8e1138785df6cbcfa7879.jpg"/> | Java language specific. |
# 2
# Introduction
The Vortex OpenSplice Modeler is an integrated Eclipse-based tool chain based on Data Distribution Service (DDS) domain-specific model driven techniques. It provides the essential productivity tools of ADLINK’s third generation OMG-DDS suite.
Vortex OpenSplice is a suite of software products comprised of a high-performance, low-overhead run-time environment, development tools for modeling information and applications, and run-time tools for monitoring system performance.
The Vortex OpenSplice Modeler conforms to the Object Management Group’s (OMG’s) Data Distribution Service for Real-Time Systems Specification for the high-performance, high-integrity systems required in defence, airtraffic control, SCADA, and other applications, where RT distributed data is a requirement for acceptable systems performance.
The Vortex OpenSplice Modeler is designed to provide developers of these RT systems with an easy-to-use, graphical modeling environment that dramatically increases their productivity, and 2nd generation DDS middleware offering superior performance, scalability, robustness, fault-tolerance, flexibility, and ease-of-use.
The objective of the Vortex OpenSplice Modeler is to reduce complexity, shorten time-to-market, raise quality, and ensure Standards compliance and code correctness; all in a single integrated suite of tools from a proven and trusted vendor.
The Vortex OpenSplice Modeler facilitate DDS-based system development by clearly distinguishing between the various scopes and lifecycle stages of the system supported by visual composition, configuration and round-trip engineering. This purpose is realized by the following means:
• Guidance - the tools provide context-aware guidance regarding the overall DDS concept, patterns and bestpractices.
• Well-defined hierarchical steps - includes information modeling (topic definitions in IDL, code-generation for topic QoS), application design (code-generation for application frameworks and DDS entities such as publishers/writers, subscribers/readers) and system deployment (information partitioning, networkconfiguration and durability configuration resulting in XML-based Vortex OpenSplice configuration data).
The Vortex OpenSplice Modeler includes these tools:
• Vortex OpenSplice Information Modeler - graphical information-modeling tool for system-wide Types and Topics.
• Vortex OpenSplice Application Modeler - graphical application-modeling tool for application codegeneration based on a DDS meta-model and related palette of DDS-entities and application frameworks, including of DomainParticipants, Publishers, Subscribers, DataWriters, DataReaders and Listeners.
A future release will also include:
• Vortex OpenSplice Deployment Modeler - graphical deployment-control environment supporting real-time connectivity with the deployed target system both for configuration-purposes as well as run-time control and monitoring (by integrating the OpenSplice Tuner features in the Eclipse-based framework).
• Round-trip engineering between the modeling environment and the actual deployed target system.
Linux
Windows
The Vortex OpenSplice Modeler is currently available for Windows and Linux running Sun’s Java SE JDK 6 and Eclipse 3.6.
The Vortex OpenSplice Modeler product is supplied as profiles: individual, tailored packages specific to each modeling area, including:
• information modeling
• application modeling
• deployment modeling (to be supported in a future release)
# 3
# Installation
# 3.1 General Installation Instructions
Follow the steps shown below to install the Vortex OpenSplice Modeler.
Step 1: Prerequisites
Ensure that Java Version 6 (required) and the Vortex OpenSplice Host Development Environment 1 (recommended), plus any other supporting software (such as native compilers, for example), are installed and working.
C++
The prerequisites for C++ Code Generation are given in the Release Notes included with odeler product distribution.
The Release Notes can be viewed by opening index.html located in the root (or base) directory of your Vortex OpenSplice installation and following the Release Notes link.
Step 2: Run the Vortex OpenSplice Modeler installer
Unix
Linux
On Unix-based platforms (including Linux), run from the command line:
```txt
VortexOpenSpliceModeler-<version>-<platform>-installer.bin
```
where <version> is the release version number and <platform> is the build for your platform. Ensure that the execute permission is enabled first, then follow the on-screen instructions. For example:
```matlab
% chmod u+x VortexOpenSpliceModeler-2.5.12-linux-installer.bin
% ./VortexOpenSpliceModeler-2.5.12-linux-installer.bin
```
# Windows
On Windows-based platforms, run by double-clicking on the filename in Windows Explorer:
```txt
VortexOpenSpliceModeler-<version>-windows-installer.exe
```
where <version> is the release version number, then follow the on-screen instructions. For example:
```batch
> VortexOpenSpliceModeler-2.5.12-windows-installer.exe
```
Step 3: Install the license file
A license file must be obtained from ADLINK, then copied to the eclipse or eclipse/etc subdirectories where the Vortex OpenSplice Modeler has been installed, or copied to the ADLINK/Vortex\_v2/license directory, or have the ADLINK\_LICENSE environment variable defined with the file path to the license file.
For example:
# Unix
# Linux
/home/myHomeDir/ADLINK/Vortex\_v2/Tools/VortexModeler/2.5.12/eclipse/etc
# Windows
\ADLINK\Vortex\_v2\Tools\VortexModeler\2.5.12\eclipse
For more information about licensing, please refer to the Getting Started Guide.
# 3.2 Setting Vortex OpenSplice Preferences
After installing the Vortex OpenSplice Modeler it is necessary to specify the location of the Vortex OpenSplice installation to be used.
Step 1: Start the Vortex OpenSplice Modeler.
Step 2: Choose Window > Preferences.
Step 3: Select OpenSplice.
Step 4: Add the location of the Vortex OpenSplice installation to OSPL\_HOME.
In the OSPL\_HOME path field enter (for example)
/home/apps/ADLINK/Vortex\_v2/Device/VortexOpenSplice/6.6.0p1/HDE/x86\_64.linux
The Browse button can be used to navigate through your file system to point to the installation.
You can also set the OSPL\_URI path if this is different from the default location.
Step 5: If you are modelling DDS applications for Vortex Lite:
Set the LITE\_HOME path field, e.g.
/home/apps/ADLINK/Device/VortexLite/2.0.0
As before, you can set the LITE\_URI path to a Vortex Lite configuration file if required.
# The Vortex OpenSplice Preferences
The license location can also be specified using the Licensing Preferences page, which is below the Vortex OpenSplice Preferences page described above.
Vortex OpenSplice licensing
# 3.3 Uninstallation Instructions
The uninstaller cleans the Vortex OpenSplice Modeler install directory by removing any file created during the installation process.
# 3.3. Uninstallation Instructions
Files created by users (such as project files in the workspace directory) are not removed by the uninstaller so that users do not lose their work.
A normal uninstallation typically removes all folders except for the eclipse folder (with the workspace, p2, plugins and configuration sub-folders).
Follow the steps below to uninstall the Vortex OpenSplice Modeler.
Step 1: Navigate to the uninstall folder of your Vortex OpenSplice Modeler installation.
# Unix
# Linux
On Unix-based platforms (including Linux), the default path will be:
```txt
/home/myHomeDir/ADLINK/Vortex_v2/Tools/VortexModeler/<version>/uninstall
```
where <version> is the release version number.
# Windows
On Windows-based platforms, the default path will be:
```txt
\ADLINK\Vortex_v2\Tools\VortexModeler\<version>\uninstall
```
where <version> is the release version number.
Step 2: Run the Vortex OpenSplice Modeler uninstaller.
# Unix
# Linux
On Unix-based platforms (including Linux), run from the command line:
```txt
uninstall-Vortex OpenSplice Modeler <version>
```
where <version> is the release version number, then follow the on-screen instructions. For example:
```batch
% ./uninstall-Vortex\ OpenSplice\ Modeler\ V2.5.12
```
# Windows
On Windows-based platforms, run by double-clicking on the filename in Windows Explorer:
```txt
uninstall-Vortex OpenSplice Modeler <version>.exe
```
where <version> is the release version number, then follow the on-screen instructions. For example:
```txt
> uninstall-Vortex OpenSplice Modeler V2.5.12.exe
```
On Windows, if certain files are still in use by a process (or by the operating system), the uninstaller will skip them but prompt you to restart your machine. Restarting the machine removes locks on the files and ensures that the uninstaller processes them.
Note: To install a new version of Vortex OpenSplice Modeler on top of an existing one, it is recommended that you uninstall the current version first. Because the uninstaller leaves the workspace folder untouched, installing a new version of Modeler should be seamless and you should be able to continue working with your existing projects.
# 4
# Modeler Described
This section describes the features and specialized tools available in Vortex OpenSplice Modeler, and outlines how to use them for modeling and assembling resources (such as DDS entities) as well as for generating DDScompliant source code.
# 4.1 Overview
The Vortex OpenSplice Modeler is an integrated Eclipse-based tool chain based on DDS domain-specific modeldriven techniques.
The Vortex OpenSplice Modeler modeling tool provides both Information and Application modeling:
• Information modeling includes the modeling of Types and Topics
• Application modeling includes the modeling of DomainParticipants, Publishers, Subscribers, DataWriters, DataReaders, Listeners, WaitSets and Conditions.
Future releases will also include Deployment modeling (a graphical deployment-control environment supporting real-time connectivity).
A detailed example showing how to model a publisher-subscriber application is provided in the Tutorial. Readers should be familiar with the Vortex OpenSplice product, the OMG’s Data Distribution Service for Real-Time Systems Specification, Version 1.2, and the Eclipse IDE before reading these sections or using the Vortex OpenSplice Modeler.
# 4.1.1 The Vortex OpenSplice Modeler and Eclipse
Eclipse (http://www.eclipse.org) is an extensible, Open Source, Integrated Development Environment (IDE) for developing software.
The Vortex OpenSplice Modeler (also referred to simply as Modeler for convenience) is a set of plug-ins for Eclipse. The Vortex OpenSplice Modeler plug-in enables the model-driven development of the Information Model together with the software components (the Application Model) that operate on it. Distinguishing between information and application modeling allows a clear ‘separation of concerns’ for users. System architects can model the information and software engineers can model their applications on this model.
The Modeler can generate the source code and descriptors needed for any of the supported OpenSplice architectures and platforms.
# 4.2 The Modeler GUI
The Vortex OpenSplice Modeler Graphical User Interface (GUI) is composed of:
• views - panels within the GUI which provide information about the components which constitute the models.
• editing tools - editors which are used to create, manage, and modify the models and components.
• a Vortex OpenSplice Design Perspective - a collection of specific views, menus and editors which are particular to the Modeler plug-in.
The GUI elements are introduced below.
# 4.2.1 Eclipse Workbench and Perspectives
The Workbench is the Eclipse main window and working area. The Workbench contains the editors and views that are used to develop, modify and view your software project and its components (see Vortex OpenSplice Design Perspective and Example Project).
A Perspective defines what actions are available in the Eclipse menus and tool bars as well as arranging the available editors and views. A Perspective’s views can be customized to suit individual needs. Any number of Perspectives can be open at one time, but only one is visible at a time. The Perspective Switch icon, located in the upper right-hand corner of the Workbench, is used to change the currently displayed perspective.
# The Vortex OpenSplice Design Perspective
The Vortex OpenSplice Design Perspective is an Eclipse perspective containing the views, menus and editors needed by users to perform tasks within the Modeler.
The Vortex OpenSplice Design Perspective
• is displayed when using the Vortex OpenSplice Modeler
• populates the Menu and Tool Bars with OpenSplice-specific items.
The Vortex OpenSplice Design Perspective with an open project, editors and Outline View is shown below.
Vortex OpenSplice Design Perspective and Example Project
The Vortex OpenSplice Design Perspective contains the views listed below. These views can be seen in the illustration above.
• Project Explorer (located on the left-hand side of the Workbench) - This view shows all of the Vortex OpenSplice and other Eclipse projects loaded in the Eclipse Workbench, with their contents.
• Editor Area (located in the centre of the Workbench) - This area is where all editors are displayed. More than one editor can be loaded into the editor area: they are accessed by clicking the tabs appearing along the top of the editing area. The specialized Modeler editors are described in detail in the section Specialized Editors.
• Outline (located along the right-hand side of the Workbench) - This view shows an outline of the component or entity being edited in the current editor. Selecting a component in the Outline will change the focus in the editor to that component. This is useful for finding a component in a diagram when the diagram too large to fit within the visible area of the editor. Various types of outline can be shown, including hierarchical and zoomable thumbnail views of the editor contents: the type of outline(s) available depends on the editor being used.
• Properties View (located at the bottom of the Workbench) - The Properties View displays an object’s properties: the object can be selected in either the Project Explorer or in an editor.
• Problems View (located at the bottom of the Workbench) - The Problems View displays all Problem Markers on all resources in the users Workspace, including errors and warnings in Vortex OpenSplice projects.
# 4.3 Creating and Using a Vortex OpenSplice Project
A Vortex OpenSplice project contains the components and entities that are used to generate the source code and interfaces for Vortex OpenSplice-based DDS applications.
The following basic steps describes how to create a Vortex OpenSplice project.
# Step 1
Open the Create a Vortex OpenSplice Project wizard, by
• choosing File > New > Vortex OpenSplice Project from the Menu Bar
OR
• clicking the New Vortex OpenSplice Project icon located in the Tool Bar
OR
• right-clicking in the Project Explorer window to display the pop-up menu, then choosing New > Other > Vortex OpenSplice Project (see New Vortex OpenSplice Project dialog and New Vortex OpenSplice Project.).
# Step 2
Enter a name for the project into the Project Name text box (in the Create a Vortex OpenSplice Project wizard). The Location text box shows where the project will be saved: you can change the location if desired, however the Use Default Location check box must be cleared before the Location text box can be edited.
Click the Finish button to create your new project.
Your newly-created project should appear in the Project Explorer window (located on the left-hand side of the Eclipse Workbench). The project will contain a single Vortex OpenSplice Model called model. The model will contain the global or default module, appearing as default in the Project Explorer view.
The project, complete with its basic file structure, will be saved to the location specified in the Location text box of the Create a Vortex OpenSplice Project wizard.
A project’s contents can be displayed in the Project Explorer window by clicking the expansion icon appearing at the left of the project name.
# New Vortex OpenSplice Project dialog
# 4.3. Creating and Using a Vortex OpenSplice Project
New Vortex OpenSplice Project
# Step 3
Add all of the DDS entities, Modeler components and resources that are needed for your DDS software application.
Steps 3 through 5 can be done in any order, using the Diagram Editor or Project Explorer.
A diagram is just one specific view on the model: it does not necessarily show all model components and/or relationships. Consider the model a UML diagram, for example: one diagram can be used to clarify the inheritance relationships without showing the attributes of the objects, while another shows exactly the same objects with attributes and associations to other objects.
Accordingly, components that are in the diagram are always in the model, but components in the model do not need to be in the diagram.
# Step 4
Set each DDS entity’s properties and QoS policy values as needed.
# Step 5
Create Diagram component(s). Use the Diagram Editor to assemble your projects entities into a model of your software application in the diagram components. This model will be used to generate your project’s source code and interfaces.
# Step 6
Generate the DDS source code using your completed Vortex OpenSplice project model.
# Step 7
Implement your application’s interfaces (using the generated class names).
# 4.3. Creating and Using a Vortex OpenSplice Project
Creating different versions of your application can easily be done by simply re-using the generated DDS code (created in Step 6), then writing different implementations of the interfaces.
# Step 8
Compile your software application using your chosen compiler.
# 4.4 Project Components
Vortex OpenSplice projects consists of components. The project components include:
1. Generic Components - items which are used by the modeling tool to contain and structure the software project’s DDS entities and include
(a) Diagrams - graphically model the software project’s structure, entities and properties, as well as defining the associations between the entities
(b) Modules - a container for other components or elements within the model
(c) QoS Sets - sets containing QoS policy instances which can be associated with one or more Application Modeling Components; QoS sets can also be associated with one or more Information Modeling Components 1
(d) Specialized Editors - these include editors which are used to create and modify the Diagram and QoS Set components
(e) Resources - directory folders, files, or other items which are used by the project
# 2. Information Modeling Components
(a) IDL Type - the specification (or definition) of the information that will be used or transmitted by the application (as a data type) 2
(b) Topic - a DDS entity which provides the most basic description of the data to be published and subscribed to
(c) Content Filtered Topic - a DDS entity that is a specialization of ‘TopicDescription’ that allows for content-based subscriptions
# 3. Application Modeling Components
(a) Application - In the context of Vortex OpenSplice Modeler, an application is a deployable software component that uses DDS for the distribution of information. An application is associated with a set of entities, which determine the incoming and/or outgoing information as well as how the information is obtained and or published.
(b) DomainParticipant - contains and associates DDS entities such publishers and subscribers; represents the local membership of the application in a domain
(c) Publisher - responsible for data distribution: it publishes data types using a DataWriter
(d) Subscriber - responsible for receiving published data and making it available to the receiving application
(e) DataWriter - used by the application to communicate with a Publisher
(f) DataReader - used by the application to communicate with a Subscriber
(g) Partition - a logical partition for associating matching topics between Publishers and Subscribers
(h) Listeners - a mechanism for the Vortex OpenSplice middleware to asynchronously alert the application of the occurrence of relevant status changes
(i) WaitSets - a mechanism for the Vortex OpenSplice middleware to synchronously alert the application of the occurrence of relevant status changes
(j) Conditions - objects which filter the status changes that applications are advised of
The project’s components are displayed as a hierarchical tree in the Project Explorer: higher level items contain lower level or dependent items. For example, the Model component (which is the top-level entity for all projects in the tool) contains Modules, which contain Applications, which in turn contain DomainParticipants.
All project components have properties which can be displayed in the Properties panel. The Properties view is located in the bottom section of the Workbench.
If the Properties view is not visible, then choose Window > Show View > Properties from the Menu Bar to display the panel.
# 4.4.1 Component Descriptions
The following table provides detailed descriptions of the project components listed above. These components are used for creating project applications and are added to projects from either the Project Explorer, by using the Eclipse File > New menu dialogs and pop-ups or by using a specialized editor (see Specialized Editors).
Detailed Descriptions of Modeler’s Project Components
| Generic Components |
| Diagram | This is a graphical representation of the project's model and is a main component of a modeling project. Diagrams:perform the actual modeling of the project and its applicationsshow the structure and relationships of the project's applications and associated elementsare used to create components, including all low-level componentslink and associate application components with each other, as required by the application |
| Module | A module is used to provide a logical separation for users. It can be used topackageitems together that are related, in order to improve the readability. A module in the Modeler is like apackagein UML. |
| QoS Set | A Modeler component which contains the set of QoS policy instances which can be associated with one or more modeled DDS entities. |
| Resources | Directory folders, files, or other items which are used by the project. |
| Information Modeling Components |
| IDL Type, Data Type | The specification (or definition) of the information that will be used or transmitted by the application (as a data type). |
| Topic | A Topic is a DDS entity which provides the most basic description of the data to be published and subscribed. A Topic is identified by its name, which must be unique in the whole DDS Domain. It fully specifies the type of the data that can be communicated when publishing or subscribing to the Topic. |
| Content Filter Topic | A DDS entity that is a specialization of ‘TopicDescription’ that allows for content-based subscriptions. Based on an existing topic, the ContentFilteredTopic allows DataReaders to subscribe to a subset of the topic content. |
| Application Modeling Components |
| Application | An application is a Modeler component that uses DDS to publish information or subscribe to information. An application contains or helps to organise related DDS entities. DDS entities are:DomainParticipantPublisherSubscriberDataWriterDataReaderTopicTopic typeQoS Sets with QoS policiesApplications will only communicate with each other if they publish or subscribe from or to the same Topic and their mutual sets of QoS policies are compatible. Developers should refer to the OMG'sDDS Specificationto ascertain the appropriate settings for the relevant QoS policies.Note that the Partition QoS is shown separately as thePartitionbuilding block. |
| DomainParticipant | A DDS entity, needed by all DDS applications, which holds and associates DDS entities such publishers and subscribers.Developers should refer to the OMG'sDDS Specificationfor the complete description. |
| Publisher | This is responsible for data distribution; it publishes data types using a DataWriter. |
| Subscriber | This is responsible for receiving published data and making it available to the receiving application. |
| DataWriter | This is used by the application to communicate to a Publisher. |
| DataReader | This is used by the application to communicate to a Subscriber. |
| Partition | This is a logical partition for associating matching topics between Publishers and Subscribers and represents a Partition QoS policy. Publishers and Subscribers connect to one or more Partitions.The Partition is shown as a separate building block (in theDiagram Editor) |
| Listener | A mechanism for the Vortex OpenSplice middleware to asynchronously alert the application of the occurrence of relevant status changes, such as a missed deadline, violation of a QosPolicy settingetc. |
| WaitSet | A mechanism for the Vortex OpenSplice middleware to asynchronously alert the application of the occurrence of relevant status changes, such as missed deadlines, violation of a QosPolicy settingetc. WaitSets allow application threads to wait until one or more of the attached Condition objects have a trigger value of TRUEor until a specified timeout expires. |
| GuardCondition | A GuardCondition is a specific Condition whose trigger value is completely under the control of the application. The purpose of a GuardCondition is to provide the means for an application to manually wake a WaitSet. |
| StatusCondition | Entity objects that have status attributes also have a StatusCondition. StatusConditions can be set to monitor various communication statuses of the Entity which are enabled by setting a status mask. When attached to a WaitSet, a StatusCondition causes the WaitSet to trigger when one or more of the enabled status attributes becomes TRUE. |
| ReadCondition | ReadCondition objects are associated with a DataReader and provide an alternative communication style between the Data Distribution Service and the application (in other words, wait-based rather than notification-based).A ReadCondition allows a DataReader to specify the data samples it is interested in by specifying the desired sample-states, view-states and instance-states.A ReadCondition object can be used on its own to read from a DataReader or it can be attached to a WaitSet. When attached to a WaitSet a ReadCondition causes the WaitSet to trigger when data is available which satisfies the settings of the ReadCondition. |
| QueryCondition | QueryCondition objects are specialized ReadCondition objects. A subset of an SQL expression can be used to allow the application to filter out newly arrived data, in addition to the notification of new arrivals. |
# 4.4. Project Components
All of the components shown in the table can be added to a project by following the steps shown below. The Diagram Editor (see Diagram Editor and Diagrams) can also be used to add the components to the project.
# Step 1
Select (click on) the project’s name located in the Eclipse Project Explorer panel.
# Step 2
Either
• choose File > New > <item> from the Eclipse Menu Bar
OR
• right-click on the project name and choose New > Other > Vortex OpenSplice > <item> from the pop-up dialog
where <item> is the name of the required component or resource, for example Module. This opens a pop-up dialog for adding details about the new component.
# Step 3
Provide details about the new component in the pop-up dialog’s text boxes, including the component’s intended root (the parent or container that the component is to be added to), the component’s name, plus any other requested information. Click Next or Finish to add the component (after providing all requested details).
Components are context- and container-sensitive: they can only be added to the appropriate parts of a project or other components.
Components are context- and container-sensitive: they can only be added to the appropriate parts of a project or other components.
# 4.5 Specialized Editors
Certain modeling components, including Diagrams and QoS Sets (see Component Descriptions) are created and/or edited using the Modeler’s specialized editors: the QoS Set Editor (QoS Set Editor and QoS Sets) and Diagram Editor (Diagram Editor and Diagrams).
The editors are displayed in the Workbench’s centre panel and are opened by:
# Step 1
Locating the component to be edited in the Project Explorer.
# Step 2
Right-clicking the component, then clicking on the required editor when it is displayed in the pop-up dialog that appears.
OR
Double-clicking the component or its parent (container).
The use of these specialized editors is described in QoS Set Editor and QoS Sets and Diagram Editor and Diagrams.
More than one editor can be open at one time, but only one editor is visible at a time. Each editor can be played by clicking on its tab (displayed along the top of the Workbench’s centre panel).
# 4.5.1 QoS Set Editor and QoS Sets
A QoS Set is a set of Quality of Service policies and associated values 3 . A Qos Set can be assigned to a particular DDS entity or it may exist as an independent set within a module.
A QoS Set is added to a module by:
• choosing File > New > QoS Set from the Eclipse Menu Bar
OR
• right-clicking on the module and choosing QoS Set from the pop-up dialog
The QoS Set Editor is an editing tool specifically designed to quickly and easily add and set Quality of Service (QoS) policies.
The QoS Set Editor is opened by double-clicking on a QoS Set component, or right-clicking on it and then choosing Edit QoS Set from the pop-up menu.
The QoS Set Editor is a multi-page editor with three pages:
• The Overview page provides general information about the QoS Set (see QoSSet Editor and Overview page).
• The Edit QoS Policy Values page is used to manage and display the set’s QoS properties (see Edit QoS Policy Values page).
• The Edit Imported QoS Sets page page has facilities for managing imported QoS sets (see Edit Imported QoS Sets page).
The pages are opened by clicking on their tabs located along the bottom of the editor (see QoSSet Editor and Overview page).
Each page contains widgets that are specific to the page such as combo boxes, buttons and lists. The combo boxes are opened and closed by clicking on the icons located at the left of each list.
In addition to the page-specific widgets, there is also a Resultant QoS Set tree viewer; this widget is common to all pages. The Resultant QoS Set is the actual set of policies and values that will be assigned to the QoS Set’s owner, using both the current QoS Set and imported QoS Sets. The Resultant QoS Set is determined by an algorithm which compares the current QoS Set’s values with the values of its imported QoS Sets, then calculates which values should be used (see QoS Resultant Set).
# Overview Page
The Overview page contains the following lists and information:
General Information - general information about the QoS set including its name, path (relationship with ancestor components) and name of its parent - the set’s owner
Imports - QoS sets which have been imported into this QoS set.
# QoSSet Editor and Overview page
# Edit QoS Policy Values Page
The Edit QoS Policy Values page contains a QoS Policies list section and <Policy> Values section (in addition to the Resultant QoS Set list):
• the QoS Policies displays the list of QoS policies which users can alter the property values of
• the <Policy> Values section displays the properties and value for the policy, <Policy>, selected in the QoS Policies list.
The <Policy> Values section is only visible when a QoS policy is selected in the QoS Policies list.
Edit QoS Policy Values page
# Adding a QoS Policy
This process adds a QoS Policy to the QoS Policies list.
All appropriate QoS Policies already exist for the entity; however, only those QoS Policies which appear in the list are able to have their values changed or edited using the QoS Policy Values section.
# Step 1
Click the Add button located at the right of the QoS Policies list. This displays the Add QoS Value dialog.
# Step 2
Click the icon adjacent to the Type drop-down list. The list displays the policies which are appropriate for the entity that the QoS Set is assigned to. Scroll down the list of available policies to find and select the one required. Click the OK button when finished. The new policy will be added to the QoS Policies and Resultant QoS Set lists.
# Step 3
Select the newly-added policy from the QoS Policies list (if it is not already selected). The properties and values for the selected policy will be displayed in the <Policy> Values list, where <Policy> is the policy’s name. The values and selection methods shown are specific to each policy type. Select and set the policy values by choosing them from the displayed drop-down lists, check boxes or text boxes.
# 4.5. Specialized Editors
Check boxes are used to enter boolean values: setting the check box (displaying an ‘X’ mark) sets the associated value to TRUE.
The data types and values displayed for each policy are in accordance with the OMG’s DDS Specification. However, it is the developer’s responsibility to correctly select or set the values that are appropriate for the selected policy and component (entity) the QoS Set will be assigned to. It is recommended that reference is made to the DDS Specification when setting these values.
# Removing a QoS Policy
Select the policy to be removed from the QoS Value list, then click the Remove button.
The QoS policy still exists but it is removed from the QoS Policies list and its properties are reset to their default values.
# Changing a QoS Property Value
A policy’s values can be changed if needed: select the policy from the QoS Policies list, then change the values which are displayed in the <Policy> Values section, where <Policy> is the policy’s name.
It is recommended that users refer to the DDS Specification to ensure that the values used for a policy are appropriate.
# Edit Imported QoS Sets Page
The Edit Imported QoS Sets page contains an Imports list and Imported Set Detail section (in addition to the Resultant QoS Set list):
• Imports displays an ordered list of the QoS sets which have been imported into the current QoS Set: sets can be added, removed and reordered.
The order that the QoS Sets are displayed in the Imports list is used by the Resultant QoS Set to resolve conflicts and determine the priority of each set’s policy values. The order is changed using the Promote and Demote buttons.
• Imported Set Details - displays the Resultant QoS Sets for the selected imported sets.
This section is only visible when a QoS Set is selected from the Imports section Imported Set Details.
Edit Imported QoS Sets page
# Importing a QoS Set
# Step 1
Click the Add button located at the right of the Imports list. This displays the QoS Set Selection dialog.
# Step 2
Click the expansion icons adjacent to the project name and component containing the QoS Set you want to import. Expand the project-component tree until the desired QoS Set appears (see the Project Explorer tree shown in the QoSSet Editor and Overview page screen).
Only QoS Sets that have not already been imported will be displayed in order to prevent inadvertently importing the same QoS Set more than once.
# Step 3
Select the desired QoS Set, then click the OK button.
The newly-imported QoS set will appear in the Imports list and its details will appear in the Imported Set Details list.
# 4.5. Specialized Editors
# Removing an Imported QoS Set
Select the required QoS Set from the Imports list, then click the Remove button.
# Changing the Order of Imported QoS Sets
An imported QoS Set can be moved up or down the Imports list by clicking the Promote or Demote buttons, respectively. However, default QoS Sets and QoS Sets from a topic (datawriters and datareaders) can not be moved.
The order that the QoS Sets are displayed in the Imports list is used by the Resultant QoS Set to resolves conflicts and determine the priority of each set’s policy values.
# QoS Resultant Set
A QoS Set can import other, stand-alone QoS sets. The imported sets are merged with the current set’s policy values to create a Resultant Set.
Strict rules of precedence are followed when computing the Resultant Set, since different QoS sets may contain duplicate values. Starting with an empty working set, values are merged to form the Resultant Set, where duplicate values overwrite values already in the working set and the steps are applied recursively:
1. Merge the Resultant Set into the working set for each QoS set in the imports list.
2. Merge the values into the working set to produce the final Resultant Set.
# Default QoS Sets
The modeling tool contains default QoS Sets. The default QoS Sets contain all the values that are required for a particular entity. There are six hidden global default sets for each type of entity. DomainParticipants and Topics import this set as the first set in the imports list. The default QoS Set cannot be removed.
The default QoS Set does not appear in the QoS Policies list.
The DomainParticipant also has an extra three default sets for the Subscriber, Publisher and Topic which contain the global default for the entity type and extend it. This is equivalent to the Vortex OpenSplice factory defaults. Subscribers and Publishers then inherit the default QoS set from their parent DomainParticipant (again restricted to being first in list and compulsory). Subscribers and Publishers contain extended default sets for DataReaders and DataWriters and their child DataReaders/Writers pick these default sets up.
DataReaders/DataWriters also by default inherit the topic’s QoS if they are connected to one. This is placed second in the imports list and it can be removed (this is equivalent to the optional copy\_from\_topic\_qos() DDS method).
# 4.5.2 Diagram Editor and Diagrams
A project’s diagram is a graphical representation of the project’s Application Model (see the illustration Diagram Editor with Tool Palette and Example Components). A diagram is a main component of a modeling project.
The Diagram Editor and diagrams:
• perform the actual modeling of the project and it application(s)
• show the relationships of the project’s applications and associated elements
• are used to create components
• associate application components with each other, as required by the application
The Diagram Editor contains a tool palette and a canvas.
# 4.5. Specialized Editors
• The tool palette, located on the left-hand side of the editor, contains a list of components and connection tools (see Diagram Editor with Tool Palette and Example Components). The palette can be used to add components to the model and create connection between components.
– Tools are selected by clicking on the tool in the palette; its associated component is added to the diagram by the clicking in the diagram’s canvas (see below).
– A tool can be de-selected by pressing the [Esc] key on the keyboard.
• The canvas, the large area located on the right-hand side of the editor, is where symbols representing the model’s component are placed and edited.
Components’ symbols appearing on the diagram can be ‘collapsed’ and ‘expanded’.
• Collapsing a component’s symbol reduces the symbol to a simple box and hides the items it contain. This is useful for hiding unwanted detail in the diagram.
– Collapse a symbol by clicking on the minus (‘-‘) icon located at the top-left corner of the symbol.
– The minus icon changes to an addition (‘+’) icon.
• Expanding a component’s symbol returns the symbol to its normal size and shape revealing the items it contains.
– Expand the symbol by clicking on the addition (‘+’) icon located at the top-left corner of the symbol.
Diagram Editor with Tool Palette and Example Components
# Adding Components
Components which are added to the diagram using the Diagram Editor’s palette are added to the project’s model: they are automatically displayed in the Project Explorer (as well as on the canvas).
Components in the Project Explorer can be added to diagram by clicking on the component then dragging it from the Project Explorer to the diagram’s canvas. If the component is already displayed in the canvas, then rather than being duplicated, it will only be moved to the location where the mouse button is released.
Detailed instructions for adding components to the model are given in the section Application Modeling.
# Deleting Components
Deleting a Modeler’s component or DDS entities removes it from the project.
Components that are deleted from Diagram Editor’s canvas are also deleted from the project’s model. There is NO UNDO function! Do not delete a component using the Diagram Editor unless you want to permanently delete it from the model.
It is strongly advised that the project be saved before deleting items.
However, an item can be removed from a diagram without deleting it from the project by right-clicking the item, then choosing Remove from the pop-up dialog.
A component or entity can be deleted by:
• right-clicking on it, then choosing the Delete option from the pop-up dialog
• selecting it in the Diagram, then choosing Edit > Delete from the Menu Bar
• selecting it in the Diagram, then pressing the [Shift]+[Delete] keys
Pressing the [Delete] key when an entity is selected in a Diagram will just remove the entity from the Diagram, but not actually delete it.
# Renaming Components
Components and entities can be renamed in either the Project Explorer or Diagram Editor by:
• Right-clicking on the component, then choosing the Rename option from the context menu.
• Entering the desired name in the Name text box in the pop-up dialog, then clicking the Return button. OR
The name of a component in the Diagram can be edited directly by double-clicking on the component.
# 5
# Modeling
This section describes in detail how to use the tools in Vortex OpenSplice Modeler for modeling and assembling resources (such as DDS entities).
The Vortex OpenSplice Modeler provides separate Information and Application modeling. This section describes the use of these two modeling paradigms in a project.
# 5.1 Information Modeling
The following sections describe how to use and add components to a project’s information model. Information modeling includes the modeling of Types and Topics. The following sections describe how to add and use Types and Topics in a project
# 5.1.1 Types and their IDL Specification
A data type, which is part of the Information Model 1 and will be distributed by the application, can be regarded as a table in a database where the database consists of a number of named columns, and each column is assigned its own primitive type. Just like a database table, the type has a set of keys, which is a subset of the set of columns.
Data types are specified using the Interface Definition Language (IDL). Using the Interface Definition Language to specify the data types ensures that they will be platform and (implementation or native) language independent.
A data type’s IDL specification is subsequently mapped (in other words, converted) to a data type of the target programming language that the application will be implemented in. For example, if the programming language that the application will be implemented in is Java, then the IDL specification for the data type would be mapped to attributes in a Java class. However, if the implementation language is C++, then the data type would be mapped to members in a C struct.
The same data type can communicate between applications implemented in different languages without difficulty.
A data type’s IDL specification is imported from a file containing the specification. The IDL specification is imported into a project by following these steps:
# Step 1
Choose File > Import from the Eclipse menu. This displays the Import dialog.
Expand the Vortex OpenSplice folder (displayed in the dialog), select Vortex OpenSplice IDL Import Wizard, then click the Next button. This will display the Vortex OpenSplice IDL Import Wizard (see the illustration below).
# Vortex OpenSplice IDL Import Wizard
# Step 2
Enter the folder which the IDL specification is to be imported into in the Destination Folder text box by using the adjacent Browse button and navigating the Project Explorer’s projects (recommended method) or by writing the folder pathname in the text box.
# Step 3
Enter the full pathname of the file containing IDL specification into the IDL Source text box using the adjacent Browse button to navigate through the file system to locate the required IDL specification file.
# Step 4
Click the Finish button when all entries are completed in order to import the IDL specification into the project.
The IDL file being imported should appear in the Project Explorer in the destination folder.
When the import is complete, a new model will be generated from the specification defined in the IDL file. The model will have the same name as the IDL file.
OR
Create an empty IDL file in a Vortex OpenSplice project, open it in the Eclipse text editor, then write the IDL specification. A model with the same name as the IDL file will be automatically generated. The model will contain the data types defined in the IDL specification. Any changes to the original IDL file will be reflected in the generated model.
Models generated from an IDL file are ‘read only’ and they appear in the Project Explorer with grey label text. It is not possible to add additional items to these models.
Example Imported Data Type Definitions
# 5.1.2 TopicDescription
TopicDescription is the base class for Topic, ContentFilteredTopic and MultiTopic (in accordance with the DDS Specification).
TopicDescription represents the situation where both publications and subscriptions are associated with a single data-type.
MultiTopics are not supported by this release.
# 5.1.3 Topics
A Topic binds a name to an associated data type. Further, multiple Topics can be created for one specific type.
A Topic can be added to a project or specific application (noting that Topics are associated with data types) by:
# Step 1
In the Project Explorer, right-clicking on the Module containing the application the Topic is to be added to, choosing New Topic from the pop-up dialog.
OR
Choosing File > New > Topic from the Eclipse Menu Bar (not recommended, since an additional step is required).
OR
In the Diagram Editor (if the application is in an open diagram) by choosing the Topic tool from the Diagram Editor’s tool palette, then clicking in a free area of the canvas.
Either of these last two methods will display the New Topic dialog (see New Topic dialog).
# Step 2
In the New Topic dialog:
• Select the Module that the Topic is to be added to into the Module field (using the adjacent Browse button). This will automatically set the Model.
• Enter the Topic’s name into the Name text box.
# 5.1. Information Modeling
• Select the data type, using the Browse button adjacent to the Data Type text box to find and select the data type the Topic is to be associated with; the data type should appear in the Data Type text box similar to the example in New Topic dialog.
# Step 3
Click Finish when complete. The new Topic should appear in the Project Explorer under the selected Module (and, if the Diagram Editor’s palette tool was used, in the diagram as well).
Topics are connected to DataWriters and DataReaders with the Topic Connection Tool: the instructions are given in Using the Connection Tool for Topics.
New Topic dialog
# 5.1.4 ContentFilteredTopic
The ContentFilteredTopic DDS entity, derived from the TopicDescription base class, can be used to do content-based subscriptions.
A ContentFilteredTopic can be added to a Module by:
# Step 1
Right-click on the Module and choose New ContentFilteredTopic from the pop-up menu.
OR
In the Diagram Editor, select Content Filtered Topic from the Diagram Editor’s palette and click on the diagram.
# Step 2
When using the New ContentFilteredTopic dialog:
• In the Module field, select the Module the ContentFilteredTopic is to be added to using the adjacent Browse button. This will automatically set the Model field.
• Use the Browse button to browse for the Topic that the ContentFilteredTopic will be based on.
• Enter a filter expression for the ContentFilteredTopic (refer to the OMG’s DDS Specification for the syntax)
ContentFilteredTopics are connected to DataReaders using the Topic Connection Tool (refer to Using the Connection Tool for Topics).
# 5.1. Information Modeling
# 5.2 Application Modeling
The following sections describe how to use and add components to a project’s application model. Application modeling includes the modeling of DomainParticipants, Publishers, Subscribers, DataWriters, DataReaders, Listeners, WaitSets and Conditions.
# 5.2.1 Applications
A Vortex OpenSplice Modeler Application represents an executable application. An application contains DDS entities such as DomainParticipants, Publishers, Subscribers, DataReaders and DataWriters.
An application can be added to the project by following these steps:
# Step 1
Right-click on a module in the Project Explorer, then choose New Application from the pop-up dialog OR
In the Diagram Editor, choose the Application tool from the tool palette, then click in the canvas.
Either of these methods will display the New Application dialog.
# Step 2
Enter the application’s name into the Name text box in the New Application dialog.
# Step 3
Select the Module that the application is to be added to by clicking the Browse button adjacent to the Module text box, then navigating the project.
# Step 4
Click the Finish button. The new application component should appear in the Project Explorer under the selected module. The application will also appear in the diagram if the Diagram Editor’s tool palette was used.
New Application dialog
# 5.2.2 DomainParticipants
DomainParticipants can be added to an application by:
# 5.2. Application Modeling
# Step 1
In the Project Explorer, right-click on the application the DomanParticipant is to be added to, then choose New Domain Participant from the pop-up dialog.
OR
If the application is in a diagram, then open it in the Diagram Editor, select the DomanParticipant tool from the tool palette, then click inside the target application’s symbol appearing on the canvas.
Either of these methods will display the New Domain Participant dialog.
New DomainParticipant dialog
# Step 2
Enter the DomainParticipant’s name into the Name text box in the New Domain Participant dialog.
# Step 3
The desired target Application should appear in the Application text box: if not, then click the Browse button adjacent to the Application text box, and navigate the project to locate the parent Application.
# Step 4
Click the Finish button. The new DomainParticipant should appear in the Project Explorer under the selected application. The DomainParticipant will also appear in the diagram, inside the application, if the Diagram Editor’s tool palette was used.
# 5.2.3 Publishers and Subscribers
Publishers and subscribers can be added to DomainParticipants using the Diagram Editor’s palette as well as the Project Explorer. When using the palette, drag the palette’s icon for the entity instance to the DomainParticipant.
# 5.2.4 DataWriters and DataReaders
DataWriters and DataReaders are contained inside publishers and subscribers, respectively. They are added using Diagram Editor’s palette: drag the palette’s icon for the entity instance to the appropriate publisher or subscriber.
Individual DataWriter and DataReader instances can be associated with only one particular Topic. The association is created using Topic Connectors.
# 5.2. Application Modeling
# 5.2.5 Partition
A DDS Partition entity is associated with Publishers and Subscribers: one or more Publishers and Subscribers can be connected to a single Partition.
A Partition is added to a model using the Diagram Editor and a Model’s diagram, noting that a diagram should already exist which contains the Publishers and/or Subscribers the Partition is to be associated with.
A Partition can also be added by clicking the toolbar’s partition icon and the New Partition context menu item for Modules. Either of these methods will launch a ‘new partition’ wizard.
# Step 1
Open a Model’s Diagram.
# Step 2
Select the Partition tool from the Diagram Editor’s palette.
# Step 3
Click in a free area of the diagram’s canvas: a new Partition will appear in the diagram and in the Project Explorer under the selected Model and Module.
# Partition Symbol
# Partition1
Partitions are associated with (or connected to) Publishers and Subscribers using the Partition Connection Tool; instructions are in Using the Connection Tool for Partitions.
# 5.2.6 Listeners
The Vortex OpenSplice Modeler supports the modeling of listeners. Listeners enable the application to asynchronously become aware of DCPS communication status changes. Using listeners is an alternative method to using conditions and WaitSets. A detailed description of each communication status is given in the OMG’s Data Distribution Service for Real-time Systems Specification, Version 1.2, formal/07-01-01.
The communication statuses, whose changes can be communicated to the application, depend on the specific Entity being communicated with. A listener can be attached to any DDS Entity.
Modeled listeners are associated with entities within an application or a Topic. When modeling listeners, users can choose which communication statuses that their application is interested in by selecting the Listener, opening the Properties view and modifying the Status Mask entries.
The user can also define the Listener type; this affects the values appearing in the Status Mask field.
The Listener Type property defines values for each type of DDS Entity that a listener can be connected to (Topic, DomainParticipant, Publisher, Subscriber, DataReader or DataWriter). These values are defined as:
# • Derived
If and only if the Listener is connected to an Entity of this type, will the Status Mask assume the Status Mask properties of this type of entity.
For example, if the Listener is connected to a DataReader and the Listener Type property value for DataReader is set to Derived, then the Status Mask for the Listener will include all Status values for a DataReader and we will be able to model an interest in those statuses.
Derived is the default value since it only provides Status Mask properties for any entities that the listener is actually connected to.
# 5.2. Application Modeling
# • Enabled
This value ensures that the Status Mask properties for this type of entity always appear in the Status Mask for the Listener, regardless of whether the Listener is connected to an Entity of that type.
This is useful, for example, if it is desirable to express an interest in Listening to an Entity that has not been modeled using the tool.
# • Disabled
This value ensures that the Listener can not listen to Entities of that type. If an Entity is Disabled, then the user will not be able to connect the Listener to an Entity of that type using the Listener Connection Tool. Similarly, if a connection already exists to an Entity of that type, then the user will receive an Error in the Problems view.
A Listener can be created in the tool by
# EITHER
# Step 1
Opening a Model in the Diagram Editor.
# Step 2
Choosing the Listener tool from the Diagram Editor’s Palette.
# Step 3
Clicking on the Application which the Listener should be associated with (in the Diagram Editor).
# OR
# Step 1
Right-click on an Application in the Project Explorer.
# Step 2
Select New Listener.
Listeners are associated with entities by using the Listener Connection Tool. (See Using the Connection Tool for Listeners for details.)
# 5.2.7 WaitSets
WaitSets are contained within an Application and are associated with certain Condition objects. WaitSets enable applications to be made synchronously aware of DCPS communication status changes and are an alternative method to using Listeners (see Listeners).
A WaitSet is a wait-based scheme. It is used in conjunction with Condition objects (see Conditions) to block the current thread of the application until a specified condition is satisfied or until the timeout expires. This is the alternative to the listener-based scheme which uses notification for awareness of status changes.
A WaitSet can be associated with one or more Condition objects.
# Modeling WaitSets
A WaitSet can be created using either the Diagram Editor or the Project Explorer.
Using the Diagram Editor
# Step 1
Open a model in the Diagram Editor.
# Step 2
# 5.2. Application Modeling
Select the WaitSet tool from the Diagram Editor’s Tool palette.
# Step 3
Click on the Application symbol which the WaitSet should be associated with in the Diagram Editor. This will add a WaitSet symbol to the diagram.
Using the Project Explorer
# Step 1
Right-click on an Application in the Project Explorer. A pop-up dialog will appear.
# Step 2
Select New WaitSet in the pop-up dialog. Provide the requested details.
Condition objects now need to be created and associated with the WaitSet.
# 5.2.8 Conditions
WaitSets use Condition objects to determine which status changes an application should be notified of.
There are different types of Condition object (referred to herein simply as Conditions for brevity). The following Condition types are specified in the OMG’s DDS Specification and are supported by the Vortex OpenSplice Modeler.
# StatusCondition
A StatusCondition defines a specific condition which is associated with each Entity.
The StatusCondition’s status mask determines which status changes the application is notified of (for its associated Entity).
The StatusCondition contains properties of type boolean. These properties determine the communication statuses. The properties can be set in the Status Mask field of the Properties View. Further, when associating a StatusCondition with a Topic, the related Domain Participant for that Topic must be specified in the Properties View.
See the OMG’s DDS Specification for detailed information about communication statuses.
# ReadCondition
ReadCondition objects are conditions specifically dedicated to read operations.
An application can specify the data samples it is interested in by setting a ReadCondition’s sample, view and instance states. More than one ReadCondition can be associated with a DataReader. A ReadCondition’s states can be set in the Vortex OpenSplice Modeler Properties View.
# QueryCondition
QueryCondition objects are specialized ReadCondition objects. A subset of an SQL expression can be used to allow the application to filter out newly-arrived data, in addition to the notification of new arrivals.
# GuardCondition
Unlike the other conditions, the GuardCondition is completely under the control of the application.
The application has the functionality to manually wake a WaitSet by attaching the GuardCondition to it and setting the trigger value of the Condition. See the OMG’s DDS Specification for detailed information.
# Modeling Conditions
Conditions are created, in a similar way to WaitSets, by using either the Diagram Editor or the Project Explorer.
Using the Diagram Editor
# 5.2. Application Modeling
# Step 1
Open a model in the Diagram Editor.
# Step 2
Select the desired Condition tool from the Diagram Editor’s Tool palette
# Step 3
Click on the Application symbol which the Condition should be associated with in the Diagram Editor. This will add the appropriate Condition symbol to the diagram.
Using the Project Explorer
# Step 1
Right-click on an Application in the Project Explorer. A pop-up dialog will appear.
# Step 2
Choose the desired New Condition option in the pop-up dialog. Provide the requested details.
# 5.2.9 Connecting Components
The Diagram Editor has a single generic connection tool. This tool is selected by clicking it in the Diagram Editor’s Tool Palette.
The connection tool connects:
• Topics to DataWriters and DataReaders, and specifies which data that the DataWriter or DataReader will write or read, respectively
• Partitions to Publishers and Subscribers, and specifies where the data will be written to or read from, respectively
• Listeners to Domain Participants, Publishers, Subscribers, DataReaders, DataWriters and Topics
• StatusConditions to DomainParticipants, Publishers, Subscribers, DataReaders, DataWriters and Topics
• ReadConditions and QueryConditions to DataReaders
• Conditions (GuardCondition, StatusCondition, ReadCondition and QueryCondition) to WaitSets
# Using the Connection Tool for Topics
# Step 1
Select the Connection Tool from the Diagram Editor’s palette.
# Step 2
Click on the topic to be connected, then click on the entity (for example, a data writer) that the topic is to be connected to.
An entity can only be connected to one topic; an existing connection between a topic and an entity will be removed whenever the entity is connected to another topic.
# Using the Connection Tool for Partitions
# Step 1
Select the Connection Tool from the Diagram Editor’s palette.
# Step 2
# 5.2. Application Modeling
Start the connection from the Partition to the publisher or subscriber.
# Step 3
Click on the Partition to be connected, then click on the Publisher or Subscriber that the Partition is to be connected to.
Publishers and Subscribers can be connected to more than one Partition.
# Using the Connection Tool for Listeners
# Step 1
Select the Connection Tool from the Diagram Editor’s palette.
# Step 2
Click on the Listener to be connected, then click on the Topic, DomainParticipant, Publisher, Subscriber, DataReader or DataWriter that the Listener is to be connected to.
Listeners can be connected to more than one entity.
# Using the Connection Tool to connect StatusConditions to an Entity
# Step 1
Select the Connection Tool from the Diagram Editor’s palette.
# Step 2
Click on the StatusCondition to be connected, then click on the Topic, DomainParticipant, Publisher, Subscriber, DataReader or DataWriter that the Listener is to be connected to.
Only one StatusCondition can be attached to DomainParticipants, Publishers, Subscribers, DataWriters and DataReaders.
Multiple StatusConditions may be attached to a Topic but each StatusCondition must have a different related DomainParticipant specified.
# Using the Connection Tool to connect ReadConditions and QueryConditions to a DataReader
# Step 1
Select the Connection Tool from the Diagram Editor’s palette.
# Step 2
Click on the ReadConditions or QueryConditions to be connected, then click on the DataReader or DataWriter that the Condition is to be connected to.
Multiple ReadConditions and QueryConditions can be attached to each DataReader.
# Using the Connection Tool to connect Conditions to a WaitSet
# Step 1
Select the Connection Tool from the Diagram Editor’s palette.
# Step 2
Click on the Condition to be connected, then click on the WaitSet that the Condition is to be connected to.
# 5.2. Application Modeling
# 6
# Code Generation
This section describes how to use the Vortex OpenSplice Modeler for generating DDS-compliant source code. The DDS code generated by the Vortex OpenSplice Modeler removes the need for programmers to manually write the DDS components of their applications; the Modeler does it for them using an easy-to-use, Eclipse-based graphical interface.
The Vortex OpenSplice HDE (version 6.1 or above) must be installed and configured in order to generate code for Vortex OpenSplice from Vortex OpenSplice Modeler.
Vortex Lite (version 1.2 or above) must be installed and configured in order to generate code targeting Vortex Lite from Vortex OpenSplice Modeler.
The principal purpose of the Vortex OpenSplice Modeler is to generate DDS-compliant source code. The Modeler achieves this aim and is able to generate:
• code for DDS data types, including
– IDL specifications for Vortex OpenSplice Data Types
– Native language interfaces for Vortex OpenSplice Data Types (via the Vortex OpenSplice IDL Pre-Processor)
– Typed interface code
• Native Language code, in Java or C++, for Applications
The Modeler can generate code either at the Module or Application level. If a Module is exported, then this simply exports all Applications within the Module. This will automatically generate the Vortex OpenSplice IDL and typed interfaces for any data types used by that Application when generating code for an Application.
Code generation can be set to target either of the following DDS Implementations:
• Vortex OpenSplice
• Vortex Lite.
# 6.1 Saving to Eclipse Projects
The code generated by the Modeler can be saved to either a Java or C++ Project within the user’s workspace.
# Java
These folders are created in Java-based projects:
src - an empty folder where users can place their own source code
generated - contains the generated DDS type and application code
The generated folder and its contents must not be edited by users.
idl - contains generated IDL specification files
# C++
These folders are created in C++-based projects:
src - an empty folder where users can place their own source code generated - contains the generated DDS type and application code
The generated folder and its contents must not be edited by users. idl - contains generated IDL specification files
# Windows
Additionally for Windows, the code generated by the Modeler can be saved to a Visual Studio Project 1 .
The folders created are exactly the same as described above. However, additional Visual Studio-specific files are created that allow the project to be imported into Visual Studio. These files are:
• For Visual Studio 2005 and 2008:
```txt
<project_name>.vcproj
OBJS.mak
Makefile
Makefile.release
```
• For Visual Studio 2013:
```txt
<project_name>.vcxproj
<project_name>.vcxproj.filters
```
# 6.2 Exporting Applications
An application can be exported by:
# Step 1
Right-clicking on the Application in the Project Explorer OR the Diagram Editor.
# Step 2
Choosing Generate Application Code.
All of the Applications within a module can be exported by:
# Step 1
Right-clicking on the Module containing the Applications to be exported.
# Step 2
Choosing Export Module. The Export Application dialog will be displayed (whether one or more applications are selected for code exportation).
# Export Application dialog
# Step 3
The Project Name text box contains the name of the export project. Accept the default name or enter a new project name.
# Step 4
Select the desired DDS target platform from the Target DDS Implementation drop-down menu.
# Step 5
Select the desired target language from the Target Language drop-down menu.
# Step 6
In the Contents panel, choose to create a new project, to merge with an exisiting project, or to overwrite an existing project.
Note that a ‘merge’ will only overwrite the generated folder, whereas an ‘overwrite’ will rwrite the whole project.
# Step 7
When creating a project with a new name you can save the project in a location of your choice. Do this by using the Browse button or by directly changing the fields in the Directory text box.
# Step 8
Check the Generate main method check box to generate a class containing a main method for the chosen language.
# Step 9
The Language Options expandable gives additional options for the project creation.
# 6.2. Exporting Applications
# Step 10
The IDL Options expandable enables you to export additional IDL Types that have not been associated with any entities in the model. To do this you must:
1. Expand IDL Options
2. Click the Add button
4. Click the OK button.
3. Choose the IDL Types to be exported (supported Types are Struct, Constant, and Enum) in the Selection dialog
# Step 11
Click the Finish button to accept the options and export the Application.
# 6.3 Java Code Generation
# Java
The conditions and details relating to the generation of the Java source code for each model component is described in this section.
All generated entities (except Partitions, Topics, ContentFilteredTopics and code generated by the Vortex Open-Splice IDL Pre-Processor) exist in a single Java class file. This class file has the same name as the Application that it represents, and it contains static wrapper classes for all of the DDS entities contained by that Application in the model.
The class hierarchy within an Application class file closely follows the hierarchy which appears in the model.
The following conditions apply for all generated entities:
• All underlying DDS Entities (DomainParticipants, Publishers, Subscribers, DataReaders, DataWriters, Partitions, Topics) in an application can be obtained by using accessor methods on the relevant generated wrapper.
• When the code for an Application component is generated, all DDS entities that are associated to or contained within it are created and configured, including DomainParticipants, Publishers, Subscribers, DataReaders, DataWriters and associated Topics.
• Each generated entity is set to the QoS policy values of its associated QoSSet (from the model).
• Default QoSSet policy values are also set on the relevant Entities.
• A specific entity’s QoS policy values are set when the entity is started (when the start() method is invoked on the Application class).
# 6.3.1 Applications
An Application component contains the configured DDS entities that you wish to use in your own application code.
Code can only be generated for modeled DDS entities such as DomainParticipants, Publishers, Subscribers, Listeners, DataReaders, DataWriters, Partitions, Waitsets and Conditions if they are contained or connected to entities within the Application component.
Each Application is generated into its own Eclipse Java project, with both project name and Java class name reflecting the fully scoped name of the Application in the model.
# Example 1
For example, an Application called MyApplication located in the com/prismtech module would result in a Java project called MyApplication. Within that project, located in the generated folder, there would be a source file called MyApplication.java under the com.prismtech package.
There are a number of generated artefacts in the Application class, itself:
• static classes for all Listeners, Waitsets and Conditions associated with the Application and its contained Entities
• static classes for all DomainParticipants contained by that Application (these classes, in turn, contain static classes for the entities that they contain - this is explained in subsequent sections)
• a static WrapperException Wrapper class for error handling at runtime
• a start() method for creating and initializing all Entities contained by the Application
Although Topics and ContentFilteredTopics are not directly contained within an Application, any DataReaders or DataWriters that use them will create them.
• a stop() method for deleting all Entities contained by the Application
– Listeners are explained under Listeners.
– Waitsets and Conditions are explained under WaitSets.
– The nested classes generated for DomainParticipants and their contained entities are explained under DomainParticipants.
– The WrapperException class is described under Error Handling.
The start() and stop() methods are used to control Application lifecycle. The start() method will configure and start all contained Entities, whilst the stop() method will attempt to cleanly shutdown the Application and delete all Entities.
# Example 2
The following code would be used to start an Application called com.prismtech.MyApplication:
```txt
com.prismtech.MyApplication.start();
```
Alternatively, the MyApplication class can be imported using a Java import statement, simplifying the code:
```txt
MyApplication.start();
```
All DDS entities contained by the Application should be configured and ready to use after invoking the start() method. The QoS Policy values for these entities will be set, according to values of their QoS Sets, and any default QoS policy values will be set on the appropriate Entities.
# 6.3.2 DomainParticipants
DomainParticipants are generated as nested static classes contained directly by the generated Application class.
A DomainParticipant wrapper class contains:
• a getDomainParticipant() method for access to the DDS Entity
• static wrapper classes for all contained Publishers and Subscribers
• typed attach() and detach() methods for any associated Listeners
The getDomainParticipant() method will return the underlying DDS DomainParticipant Entity. This method is statically invoked.
# Example
Continuing with the com.prismtech.MyApplication Application class example from above, if this class contains a DomainParticipant called MyAppDP, then the code to access the DomainParticipant would be:
```javascript
DDS.DomainParticipant participant = com.prismtech.MyApplication.MyAppDP.getDomainParticipant();
```
The containing Application must have been started via its start() method, otherwise a null object reference will be returned.
The typed attach() and detach() listener methods are described under Listeners.
# 6.3.3 Publishers
Publishers are generated as nested static classes contained directly by a generated DomainParticipant class.
A Publisher wrapper class contains :
• a getPublisher() method for gaining access to the DDS Entity
• static wrapper classes for all contained DataWriters
• typed attach() and detach() methods for any associated Listeners
The getPublisher() method will return the underlying DDS Publisher Entity. This method is statically invoked.
# Example
Continuing with the com.prismtech.MyApplication Application class from above, if this class contains a DomainParticipant called MyAppDP, and a Publisher called MyPublisher, then the code to access the Publisher would be:
```txt
DDS.Publisher publisher =
com.prismtech.MyApplication.MyAppDP.MyPublisher.getPublisher();
```
A The containing Application must have been started via its start() method, otherwise a null object reference will be returned.
# 6.3.4 Subscribers
Subscribers are generated as nested static classes contained directly by a generated DomainParticipant class.
A Subscriber wrapper class contains:
• a getSubscriber() method for access to the DDS Entity
• static wrapper classes for all contained DataReaders
• typed attach() and detach() methods for any associated Listeners
The getSubscriber() method will return the underlying DDS Subscriber Entity. This method is statically invoked.
# Example
Continuing with the com.prismtech.MyApplication Application class from above, if this class contained a DomainParticipant called MyAppDP, and a Subscriber called MySubscriber, then the code to access the Subscriber would be:
```javascript
DDS.Subscriber subscriber =
com.prismtech.MyApplication.MyAppDP.MySubscriber.
getSubscriber();
```
The containing Application must have been started via its start() method, otherwise a null object reference will be returned.
# 6.3.5 Data Readers
DataReaders are generated as nested static classes contained directly by a generated Subscriber class.
A DataReader wrapper class contains:
• a getDataReader() method for access to the DDS Entity
• typed attach() and detach() methods for any associated Listeners
The getDataReader() method will return the typed underlying DDS DataReader Entity. This method is statically invoked.
# Example
Continuing with the com.prismtech.MyApplication Application class from above, if this class contained a DomainParticipant called MyAppDP, a Subscriber called MySubscriber, and a DataReader called MyReader, then the code to access the DataReader would be:
```java
<typed DataReader class> reader = com.prismtech.MyApplication.MyAppDP.MySubscriber.MyReader.getDataReader();
```
The containing Application must have been started via its start() method, otherwise a null object reference will be returned.
# 6.3.6 Data Writers
DataWriters are generated as nested static classes contained directly by a generated Publisher class.
A DataWriter wrapper class contains:
• a getDataWriter() method for access to the DDS Entity
• typed attach() and detach() methods for any associated Listeners
The getDataWriter() method will return the typed underlying DDS DataWriter Entity. This method is statically invoked.
# Example
Continuing with the com.prismtech.MyApplication Application class from above, if this class contained a DomainParticipant called MyAppDP, a Subscriber called MySubscriber, and a DataWriter called MyWriter, then the code to access the DataWriter would be:
```java
<typed DataWriter class> writer = com.prismtech.MyApplication.MyAppDP.MySubscriber.MyWriter.getDataWriter();
```
The containing Application must have been started via its start() method, otherwise a null object reference will be returned.
# 6.3.7 Listeners
Listeners are generated as abstract nested static classes contained directly by the generated Application class. This class acts as a base class for the user’s Listener implementation.
The user must:
• extend the generated Listener class and implement all abstract methods.
• attach an instance of the class to the appropriate Entity via the typed ‘attach’ method on the wrapper class for that Entity.
• detach the Listener if notifications are no longer required, via the typed ‘detach’ method on the wrapper class for that Entity.
Each Listener class contains:
• abstract methods for each status condition in which an interest was expressed. Other communication status callback methods do nothing and are defined as ‘final’ so that they cannot be overridden.
• a status mask indicating which statuses the Listener is interested in.
For each generated Application that contained Entities with associated listeners, typed methods for attaching and detaching listeners will be generated on that Entity’s nested wrapper class.
The user must extend the generated Listener class, then instantiate the class within their own application code, and finally install the listener on the relevant entity via the appropriate typed attach() method.
# Example
For a listener called Listener1, with an interest in the communication status on\_data\_available, the following base class would be generated:
```java
public abstract class Listener1 implements DDS.DomainParticipantListener {
public final int STATUS_MASK =
DDS.DATA_AVAILABLE_STATUS.value;
public final void on_data_on_readers(DDS.Subscriber subscriber) {
}
public final void on_offered_incompatible_qos(
DDS.DataWriter dataWriter,
DDS.OfferedIncompatibleQosStatus status) {
}
public abstract void on_data_available(DDS.DataReader dataReader);
public final void on_requested_incompatible_qos(
DDS.DataReader dataReader,
DDS.RequestedIncompatibleQosStatus status) {
}
public final void on_subscription_match(
DDS.DataReader dataReader,
DDS.SubscriptionMatchStatus status) {
}
public final void on_requested_deadline_missed(
DDS.DataReader dataReader,
DDS.RequestedDeadlineMissedStatus status) {
}
public final void on_offered_deadline_missed(
DDS.DataWriter dataWriter,
DDS.OfferedDeadlineMissedStatus status) {
}
public final void on_sample_rejected(
DDS.DataReader dataReader,
DDS.SampleRejectedStatus status) {
}
public final void on_liveliness_lost(
DDS.DataWriter dataWriter,
DDS.LivelinessLostStatus status) {
}
```
```swift
public final void on_inconsistent_topic(
DDS.Topic topic,
DDS.InconsistentTopicStatus status) {
}
public final void on_publication_match(
DDS.DataWriter dataWriter,
DDS.PublicationMatchStatus status) {
}
public final void on_sample_lost(
DDS.DataReader dataReader,
DDS.SampleLostStatus status) {
}
public final void on_liveliness_changed(
DDS.DataReader dataReader,
DDS.LivelinessChangedStatus status) {
}
```
The user should then extend this class and implement the on\_data\_available() method.
If the Listener is attached to the DomainParticipant MyParticipant in the model, then within the class, for the application containing MyParticipant, we would find a static wrapper class representing MyParticipant containing the methods :
```txt
public static int attach (Listener1 listener);
public static int detach (Listener1 listener);
```
The user would instantiate the class that they implemented before passing the object reference to the attach() method to connect the listener. The user would call the detach() method to disconnect the listener.
# 6.3.8 WaitSets
WaitSets are generated as nested static classes contained directly in the generated Application class.
A WaitSet wrapper class has:
• a getWaitSet() method for access to the DDS Entity
• a start() method which creates the WaitSet and attaches the appropriate Conditions
• a stop() method which detaches the WaitSet’s Conditions and deletes the WaitSet itself
# Example
Continuing with the com.prismtech.MyApplication Application class example from above, if this class contains a WaitSet called MyWaitSet, then the code to access the WaitSet would be:
```javascript
DDS.WaitSet waitset = com.prismtech.MyApplication.MyWaitSet.getWaitSet();
```
The Application must be running before the WaitSet is started. Also, the WaitSet must be started using the start() method or a null object reference will be returned by the getWaitSet() method.
# 6.3.9 Conditions
All Conditions are generated as nested static classes contained directly in the generated Application class.
# 6.3. Java Code Generation
# StatusCondition
A StatusCondition wrapper class has:
• a start() method for accessing the DDS StatusCondition
• a getStatusCondition() method for accessing the wrapped StatusCondition
• a setDefaultStatusMask() method returns the value of the Status Mask to its original (modelled) state
• a stop() method to set the StatusCondition back to null, allowing for a future garbage collection
# Example
In DDS, each Entity owns exactly one StatusCondition. Therefore, a StatusCondition does not need to be created, but only retrieved through the Entity which it is associated within the model. (Note that the start() method does not start the statusCondition; it just gets a handle on the DDS entity.)
Continuing with the com.prismtech.MyApplication Application class example from above, if this class contains a StatusCondition called MySC, a DomainParticipant called MyAppDP and a Subscriber called MySubscriber which is associated with the MySC, then the code for accessing the StatusCondition would be:
```javascript
DDS.StatusCondition statusCondition = com.prismtech.MyApplication.MySC.等情况();
```
# ReadCondition
A ReadCondition wrapper class has:
• a start() method for creating the DDS ReadCondition
• a getReadCondition() method for accessing the wrapped ReadCondition
• a stop() method for deleting the ReadCondition from its associated DataReader and setting the Read-Condition to null
# Example
Continuing with the com.prismtech.MyApplication Application class example, if this class contained a DomainParticipant called MyAddDP, a Subscriber called MySubscriber, a WaitSet called MyWaitSet, and a ReadCondition called MyRC, then the code to access the ReadCondition would be:
```txt
DDS.ReadCondition readCondition = com.prismtech.MyApplication.MyRC.getReadCondition();
```
All ReadConditions are created lazily when the getReadCondition() method is called.
# QueryCondition
A QueryCondition wrapper class has:
• a start() method for creating the DDS QueryCondition
• a getQueryCondition() method for accessing the wrapped QueryCondition
• a stop() method for deleting the QueryCondition from its associated DataReader and setting the QueryCondition to null
• a setQueryParameter() method for setting the parameters for the QueryExpression associated with the QueryCondition
# Example
Continuing with the com.prismtech.MyApplication Application class example, if this class contained a DomainParticipant called MyAddDP, a Subscriber called MySubscriber, a WaitSet called MyWaitSet, and a QueryCondition called MyQC, then the code to access the QueryCondition would be:
```java
DDS.QueryCondition queryCondition = com.prismtech.MyApplication.MyQC.getQueryCondition();
```
QueryConditions are created lazily when the getQueryCondition() method is called, like the ReadCondition.
A The setQueryParameters() method must be called with the appropriate argument before the getQueryCondition() method is called, otherwise an exception is raised.
# GuardCondition
A GuardCondition wrapper class contains:
• a start() method for creating the DDS GuardCondition
• a getGuardCondition() method that returns the wrapped GuardCondition
• a stop() method that sets the value of the GuardCondition to null allowing a future garbage collection
# Example
Continuing with the com.prismtech.MyApplication Application class example, if this class contained a WaitSet called MyWaitSet, and a GuardCondition called MyGC, then the code to access the GuardCondition would be:
```java
DDS.GuardCondition guardCondition = com.prismtech.MyApplication.MyGC.getGuardCondition();
```
The GuardConditions are created lazily by the getGuardCondition() method.
# 6.3.10 Partitions
The Java code for the Modeler Partition component (in the model) is generated as an abstract class; this class can be used to get and set a name in the Partition QoS of connected Publishers and Subscribers.
The generated Partition class is assigned the name of the Partition used in the name model.
A class containing static methods to get and set the name of that Partition is generated for each Partition connected to a Publisher or Subscriber, as defined in the model. The methods listed below are defined in this class:
public static void setName (String partitionName) - This method sets the Partition’s QoS for all registered DDS Publishers and Subscribers when it is invoked.
public static String getName () - Return the current DDS name for this partition.
The Partition wrapper class also contains the following methods:
• an addPublisher()/Subscriber() method that adds a publisher/subscriber to the list of publishers/subscribers connected to the partition.
• a removePublisher()/Subscriber() method that removes a publisher/subscriber from the list of publishers/subscribers connected to the partition.
# 6.3.11 Error Handling
Exceptions are used to handle errors in the Wrappers. Most Entity Wrappers’ methods can throw a WrapperException.
# 6.3. Java Code Generation
A WrapperException is thrown when an error is encountered while performing a DDS API call or, less frequently, when an internal error in the Wrapper occurs.
An example of the first case is when a Wrapper must create a DomainParticipant but a call to create\_participant fails.
An example of the second case is when the user starts a QueryCondition Wrapper but the QueryParameters have not been defined.
In all cases, WrapperException provides enough information to know where the errors occurred; for example, what was the error code returned by the DDS call.
The WrapperException class is generated as a direct nested class in generated Application and Topic wrapper classes.
# 6.4 C++ Code Generation
# ++
The C++ generated files are placed in a project’s generated folder. All modules, entities and other (scoped) items placed in this folder will correspond to a folder in the Project Manager tree.
All entity names are postfixed by the word Wrapper in order to avoid conflicts between C++ name spaces and class names.
Three files are generated for each entity. Their filenames use a convention whereby they take the entity’s name and add it to a suffix associated with the file type. The generated files and their filename conventions are:
• An abstract base class called Wrapper.h.
An entity called Publisher1, for example, would produce Publisher1Wrapper.h. Publisher1Wrapper.h is the interface that the application developer should use.
• A class header file called WrapperImplementation.h.
Publisher1WrapperImplementation.h would be produced for a Publisher1 entity. This class implements the abstract base class and should not be used by application developers.
• An implementation file called WrapperImplementation.cpp.
Publisher1WrapperImplementation.cpp would be generated for a Publisher1 entity. This file contains the class method’s implementations.
The following conditions apply for all generated entities:
• All underlying DDS Entities (DomainParticipants, Publishers, Subscribers, DataReaders, DataWriters, Partitions, Topics) in an application can be obtained by using accessor member functions on the relevant generated wrapper.
• When the code for an Application component is generated, all DDS Entities that are associated to or contained within it are created and configured, including DomainParticipants, Publishers, Subscribers, DataReaders, DataWriters and associated Topics.
• Each generated entity is set to the QoS policy values of its associated QoSSet (from the model). Default QoSSet policy values are also set on the relevant Entities.
• A specific entity’s QoS policy values are set when the entity is started (in other words, when the start() member function is invoked on the Application class).
• The default behaviour for error handling is to call the stop() member function and throw a WrapperException. The WrapperException is always generated within the application’s name space.
# 6.4.1 Applications
An Application component contains the configured DDS Entities that you wish to use in your application code.
Each application is generated into its own Eclipse C++, Visual Studio 2005, or Visual Studio 2008 project.
For example, an application called MyApplication located in the com/prismtech module would result in a source file called MyApplicationWrapper.h in the com::prismtech namespace.
The Application class contains several generated methods:
• a get<entity\_name>Wrapper() member function for all entities that are the application’s children, including partitions and topics
• a start() member function which creates and initializes all Entities contained by the Application
• a stop() member function which deletes all Entities contained by the Application
The start() and stop() methods are used to control the Application’s lifecycle. The start() member function configures and starts all contained Entities, whilst the stop() member function attempts to cleanly shut down the Application and delete all Entities.
# Example
The following code starts an Application called com::prismtech::MyApplication:
```txt
com::prismtech::MyApplicationWrapper* myApp = new com::prismtech::MyApplicationWrapperImplementation; myApp->start();
```
It is important to note that for all entities in the model, only the generated abstract base classes (\*Wrapper.h) should be included in the business logic. The only exception is when the application wrapper has to be instantiated, then the application wrapper implementation header must be included. For example:
```c
#include "com/prismtech/MyApplicationWrapperImplementation.h"
#include "com/prismtech/MyApplicationWrapper.h"
```
All DDS entities contained by the Application should be configured and ready to use after the start() member function is invoked. The QoS Policy values for these entities are set according to values of their QoS Sets. Any default QoS policy values will be set on the appropriate Entities.
# 6.4.2 DomainParticipants
DomainParticipants are generated in the <domainparticipant\_name>Wrapper.h, <domainparticipant\_name>WrapperImplementation.h and <domainparticipant\_name>WrapperImplem class files.
A DomainParticipant wrapper class contains:
• a getDomainParticipant() member function for accessing the DDS Entity
• a get<entity\_name>Wrapper() member function for retrieving the DomainParticipant’s Publishers and Subscribers and their associated Topics
• typed attach() and detach() member functions for attaching a Listener to and detaching it from the DDS Entity.
The getDomainParticipant() member function returns the underlying DDS DomainParticipant Entity.
The get<entity\_name>Wrapper() member function returns the modeled entity’s wrappers, which are then used, in turn, to retrieve the underlying DDS Entity.
The attach() member function can either be used on the corresponding wrapper class or on the desired DDS entity directly.
Listeners are described in Listeners.
# Example
Continuing with the com::prismtech::MyApplication Application class example from above, if the MyApplication model contains a DomainParticipant called MyDP, then the code to access the DomainParticipant would be:
```cpp
DDS::DomainParticipant* domainparticipant = myApp->getMyDPWrapper()->getDomainParticipant();
```
The containing Application must have been started with its start() member function or a null pointer will returned.
# 6.4.3 Publishers
Publishers are generated in the <publisher\_name>Wrapper.h, <publisher\_name>WrapperImplementation.h and <publisher\_name>WrapperImplementation.cpp class files.
A Publisher wrapper class contains:
• a getPublisher() member function for gaining access to the DDS Entity
• a get<datawriter\_name>Wrapper() member function for retrieving the data writer
• typed attach() and detach() member functions for attaching a Listener to and detaching it from the DDS Entity.
The getPublisher() member function returns the underlying DDS Publisher Entity.
The get<entity\_name>Wrapper() member function returns the modeled entity’s wrapper, which is used in turn to retrieve the underlying DDS Entity.
The attach() member function can either be used on the corresponding wrapper class or called on the desired DDS entity directly.
Listeners are described in Listeners.
# Example
Continuing with the com::prismtech::MyApplication Application class example from above, if this class contains a DomainParticipant called MyDP and a Publisher called MyPublisher, then the code to access the Publisher is:
```cpp
DDS::Publisher* publisher =
myApp->getMyDPWrapper()->getMyPublisherWrapper()->getPublisher();
```
The containing Application must have been started with its start() member function or a null pointer will eturned.
# 6.4.4 Subscribers
Subscribers are generated in the <subscriber\_name>Wrapper.h, <subscriber\_name>WrapperImplementation.h and <subscriber\_name>WrapperImplementation.cpp class files.
A Subscriber wrapper class contains:
• a getSubscriber() member function for access to the DDS Entity
• a get<reader\_name>Wrapper() member function for retrieving the data reader
• typed attach() and detach() member functions for attaching a Listener to and detaching it from the DDS Entity.
The getSubscriber() member function returns the underlying DDS Subscriber Entity.
get<entity\_name>Wrapper() returns the modeled entity’s wrapper with which the underlying DDS Entity can be retrieved.
The attach() member function can either be used on the corresponding wrapper class, or called on the desired DDS entity directly.
Listeners are described in Listeners.
# Example
Continuing with the com::prismtech::MyApplication Application class from above, if this class contains a DomainParticipant called MyDP, and a Subscriber called MySubscriber, then the code to access the Subscriber would be:
```cpp
DDS::Subscriber* subscriber =
myApp->getMyDPWrapper()->getMySubscriberWrapper()->getSubscriber();
```
The containing Application must have been started with its start() member function or a null pointer will be returned.
# 6.4.5 Data Readers
DataReaders are generated in the <reader\_name>Wrapper.h, <reader\_name>WrapperImplementation.h and <reader\_name>WrapperImplementation.cpp class files.
A DataReader wrapper class contains:
• a getDataReader() member function for access to the DDS Entity
• typed attach() and detach() member functions for attaching a Listener to and detaching it from the DDS Entity.
The getDataReader() member function returns the typed underlying DDS DataReader Entity.
The attach() member function can either be used on the corresponding wrapper class or called on the desired DDS entity directly.
Listeners are described in Listeners.
# Example
Continuing with the com::prismtech::MyApplication Application class from above, if this class contains a DomainParticipant called MyDP, a Subscriber called MySubscriber, and a DataReader called MyReader, then the code to access the DataReader would be:
```cpp
DDS::DataReader* reader =
myApp->getMyDPWrapper()->getMySubscriberWrapper()->getMyReaderWrapper()->getDataReader();
```
！！ The containing Application must have been started with its start() member function or a null pointer will be returned.
# 6.4.6 Data Writers
DataWriters are generated in the <writer\_name>Wrapper.h, <writer\_name>WrapperImplementation.h and <writer\_name>WrapperImplementation.cpp class files.
A DataWriterswrapper class contains:
• a getDataWriter() member function for access to the DDS Entity • typed attach() and detach() member functions for attaching a Listener to and detaching it from the DDS Entity.
The getDataWriter() member function returns the typed underlying DDS DataWriters Entity.
The attach() member function can either be used on the corresponding wrapper class or called on the desired DDS entity directly.
Listeners are described in Listeners.
# Example
Continuing with the com::prismtech::MyApplication Application class from above, if this class contains a DomainParticipant called MyDP, a Publisher called MyPublisher and a DataWriter called MyWriter, then the code to access the DataWriter would be:
```cpp
DDS::DataWriter* writer =
myApp->getMyDPWrapper()->getMyPublisherWrapper()->getMyWriterWrapper()->getDataWriter();
```
The containing Application must have been started with its start() member function or a null pointer will be returned.
# 6.4.7 Listeners
Each listener that is defined in the model has a file, <listener name>.h 2 , generated for it which acts as a base class for the user’s listener implementation. This class must be subclassed.
The generated class subclasses the corresponding entity listener from the OMG DDS DCPS API for the DDS entity that the listener is connected to in the model.
Function declarations are inserted as comments for all the enabled listener functions. These serve as an easy reference for what users must provide in their implementation.
The generated listener class also contains the status mask (as defined in the model). The value is accessible through the getStatusMask() member function.
A dummy implementation is inserted for all disabled listener member functions so these functions do not need to be present in the user’s listener implementations.
These listeners can be used by either invoking the attach() member function on the corresponding wrapper class or directly on the desired DDS entity.
When the listener must be attached to the DDS entity at its creation time, then the wrapper’s attach() member function should be used. In this case, it must be called before invoking start(), so as to be aware of all triggered events.
Please note that when calling attach() on the wrapper class, the listener will be duplicated and held in a \_var auto pointer. Once the user’s code is not interested any more in receiving notifications through a listener, detach() should be called.
# Example
For a listener called Listener1, with an interest in the communication status on\_data\_available, the following base class will be generated:
```c
#ifndef _MODULE1_APPLICATION1_LISTENER1_H_
#define _MODULE1_APPLICATION1_LISTENER1_H_
#include <ccpp_dds_dcps.h>
namespace Module1
{
```
```cpp
namespace Application1
{
class Listener1 : virtual public DDS::DataReaderListener
{
public:
Listener1() :
m_statusMask(0 | DDS::DATA_AVAILABLE_STATUS)
{
}
int getStatusMask() const
{
return m_statusMask;
}
DDS::Boolean _local_is_a (const char * repositoryID)
{
return false || DDS::DataReaderListener::_local_is_a (repositoryID);
}
// DO NOT OVERRIDE THIS METHOD
// It is disabled in the status mask
void on_sample_rejected (DDS::DataReader_ptr dataReader,
const DDS::SampleRejectedStatus& status)
{
}
// Implement this method, it's enabled in the status mask
// void on_data_available (DDS::DataReader_ptr dataReader)
// DO NOT OVERRIDE THIS METHOD
// It is disabled in the status mask
void on Subscription_matched (DDS::DataReader_ptr dataReader,
const DDS::SubscriptionMatchedStatus& status)
{
}
// DO NOT OVERRIDE THIS METHOD
// It is disabled in the status mask
void on requested_incompatible_qos (
DDS::DataReader_ptr dataReader,
const DDS::RequestedIncompatibleQosStatus& status)
{
}
// DO NOT OVERRIDE THIS METHOD
// It is disabled in the status mask
void on_sample_lost (DDS::DataReader_ptr dataReader,
const DDS::SampleLostStatus& status)
{
}
// DO NOT OVERRIDE THIS METHOD
// It is disabled in the status mask
void on_liveliness_changed (DDS::DataReader_ptr dataReader,
const DDS::LivelinessChangedStatus& status)
{
}
// DO NOT OVERRIDE THIS METHOD
// It is disabled in the status mask
```
```c
void on_requested_deadline_missed(DDS::DataReader_ptr dataReader, const DDS::RequestedDeadlineMissedStatus& status)
{
}
private:
const DDS::StatusMask m_statusMask;
};
};
#endif
// _MODULE1_APPLICATION1_LISTENER1_H_
```
The user should now inherit from this class and implement the on\_data\_available() method.
If the Listener is attached to the DomainParticipant Participant1 in the model, then within the generated wrapper implementation class, for Participant1, we would find a method:
```cpp
virtual void attach (Module1::Application1::Listener1* listener) = 0;
```
The user would call the detach() member function to disconnect the listener.
# 6.4.8 WaitSets
Waitsets are generated in the <waitset\_name>Wrapper.h, <waitset\_name>WrapperImplementation.h and <waitset\_name>WrapperImplementation.cpp class files.
A WaitSet wrapper class has:
• a getWaitSet() member function for accessing the DDS Entity
• a start() member function which creates the WaitSet and attaches the appropriate Conditions
• a stop() member function which detaches the WaitSet’s Conditions and deletes the WaitSet itself
# Example
Continuing the com::prismtech::MyApplication Application class example from above, if this class contains a WaitSet called MyWaitSet, then the code to access the WaitSet would be:
```cpp
DDS::WaitSet* waitset =
myApp->getMyWaitSetWrapper()->getWaitSet();
```
# 6.4.9 Conditions
All Conditions are generated in the <condition\_name>Wrapper.h, <condition\_name>WrapperImplementation.h and <condition\_name>WrapperImplementation.cpp class files.
！ It is important to note that before accessing the DDS Condition with the getCondition() member function, the condition wrapper must have been started with start(). If the condition is attached to a WaitSets, it will be started upon the start of the WaitSet.
# StatusCondition
A StatusCondition wrapper class has:
• a getCondition() member function for accessing the DDS StatusCondition
• a getStatusMask() member function which returns the value of the Status Mask
• a start() member function which creates the Condition
• a stop() member function which detaches the Condition
# Example
Each Entity owns exactly one StatusCondition in DDS. Therefore, a StatusCondition does not need to be created, but only retrieved through the Entity which it is associated with, within the model.
Continuing the com::prismtech::MyApplication Application class example from above, if this class contains a StatusCondition called MySC then the code for accessing the StatusCondtion would be:
```cpp
DDS::StatusCondition* statusCondition = myApp->getMySCWrapper()->相结合();
```
# ReadCondition
A ReadCondition wrapper class has:
• a getCondition() member function for accessing the DDS ReadCondition
• a getInstanceStateMask() member function for accessing the instance state mask
• a getSampleStateMask() member function for accessing the sample state mask
• a getViewStateMask() member function for accessing the view state mask
• a start() member function for attaching the ReadCondition to its associated DataReader
• a stop() member function for deleting the ReadCondition from its associated DataReader
# Example
Continuing the com::prismtech::MyApplication Application class example from above, if the MyApplication model has a ReadCondition called MyRC, then the code to access the ReadCondition would be:
```cpp
DDS::ReadCondition* readCondition = myApp->getMyRCWrapper()->getCondition();
```
# QueryCondition
A QueryCondition wrapper class has:
• a getCondition() member function for accessing the DDS ReadCondition
• a getInstanceStateMask() member function for accessing the instance state mask
• a getSampleStateMask() member function for accessing the sample state mask
• a getViewStateMaks() member function for accessing the view state mask
• a start() member function for attaching the ReadCondition to its associated DataReader
• a stop() member function for deleting the ReadCondition from its associated DataReader
• a setQueryParameters() member function for setting the parameters for the QueryExpression associated with the QueryCondition
# Example
Continuing the com::prismtech::MyApplication Application class example from above, if the MyApplication model contains a QueryCondition called MyQC, then the code to access the QueryCondition would be:
```cpp
DDS::QueryCondition* queryCondition = myApp->getMyQCWrapper()->condition();
```
The setQueryParameters() member function must be called with the appropriate argument before the Condition() member function is called or an exception will be raised.
# GuardCondition
A GuardCondition wrapper class contains:
• a getCondition() member function that returns the DDS GuardCondition
• a start() member function for creating the GuardCondition
• a stop() member function that sets the value of the GuardCondition to 0
# Example
Continuing the com::prismtech::MyApplication Application class example, if the MyApplication model contains a GuardCondition called MyGC, then the code to access the GuardCondition would be:
```cpp
DDS::GuardCondition* guardCondition = myApp->getMyGCWrapper()-> Batman();
```
# 6.4.10 Partitions
The C++ code for the Modeler Partition component (in the model) is generated in the Wrapper.h, WrapperImplementation.h and WrapperImplementation.cpp class files.
The generated code can be used to get and set the names of connected Publishers and Subscribers in the Partition QoS.
The generated Partition class is assigned the same name as the name of the Partition in the model.
This class defines the following methods:
• a getName() member function which retrieves the partition name
• a setName() member function which sets the partition name
• an addPublisher()/Subscriber() member function that adds a publisher/subscriber to the list of publishers/subscribers connected to the partition
• a removePublisher()/Subscriber() member function that removes a publisher/subscriber from the list of publishers/subscribers connected to the partition
# 7
# Creating Launch Configurations
This section describes how to set up ‘launch configurations’ for the Vortex OpenSplice Modeler which provide additional convenient ways to run and control the Modeler.
A Vortex OpenSplice daemon must be running on the host where your code will be run and for the domain within which your code will operate.
Starting a Vortex OpenSplice daemon is only required when running a Shared Memory Deployment. For more details about starting Vortex OpenSplice, please see the Vortex OpenSplice Deployment Guide.
The Modeler includes an HDE icon (located in the Eclipse Icon Bar) which can start and stop the Vortex OpenSplice daemon. However, configurations can be manually created to start and stop the daemon if desired or if the daemon does not start when using the HDE tool from the icon bar.
The instructions provided in this section describe how to manually create, start, and stop configurations for the Vortex OpenSplice (OSPL) daemon.
It is recommended that Vortex OpenSplice launch configurations are created which can start and stop the Vortex OpenSplice daemon: this will enable Vortex OpenSplice code to be run from within Eclipse. These instructions assume that the environment is configured for the version of Vortex OpenSplice that will be used. Refer to the Vortex OpenSplice Getting Started Guide for configuration information. Environment variables can be set for specific launch configurations by selecting the launch configuration and clicking on the Environment tab.
# 7.1 Creating and Running an OSPL start Launch Configuration
# 7.1.1 Creating the start Configuration
# Step 1
Choose Run > External Tools > External Tools from the Eclipse Menu Bar. This will open the External Tools dialog.
# Step 2
Right-click on the Program item located in tree view (located on the left-hand side of the External Tools dialog) and choose New. This will create a new item under the Program item.
# Step 3
Enter OSPL start in the Name text field (located near the top of the dialog); this is for the launch configuration.
# Step 4
In the Location text box, use the Browse File System button to locate the OSPL executable (ospl.exe on Windows platforms). The full pathname for the OSPL executable should appear in the Location text box.
For example, on Windows this could be "C:\Program Files
(x86)\ADLINK\Vortex\_v2\Device\VortexOpenSplice\6.6.0p1\HDE\x86.win32\bin\ospl.exe".
# Step 5
Enter the word start in the Arguments text box. This will instruct the OSPL executable to start the daemon.
# Step 6
Click the Apply button to apply the changes.
# Step 7
Click the Close button to close the dialog.
# 7.1.2 Running the start Configuration
Running the start launch configuration executes the ospl start command and starts the daemon.
# Step 1
Choose Run > External Tools > External Tools from the Eclipse Menu Bar. This will open the External Tools dialog.
# Step 2
Select the OSPL start item (located under the Program item) in tree view (located on the left-hand side of the External Tools dialog).
# Step 3
Click the Run button (located at the bottom of the dialog). This will start the daemon.
# Step 4
Click the Close button to close the dialog.
# 7.2 Creating and Running an OSPL stop Launch Configuration
# 7.2.1 Creating the stop Configuration
# Either:
Repeat all of the steps shown under Section 3.8.1.1, Creating the start Configuration, above, but use OSPL stop for the launch configuration’s name, and enter stop in the Arguments text box instead of start.
# OR:
# Step 1
Right-click on the launch configuration created under Section 3.8.1.1, Creating the start Configuration.
# Step 2
Click Duplicate.
# Step 3
Select Duplicate Launch Configuration.
# Step 4
Rename it from OSPL start (1) to OSPL stop by entering the new name in the Name field
# Step 5
Replace start with stop in the argument field.
# Step 6
Click Apply.
# 7.2.2 Running the stop Configuration
Running the stop launch configuration executes the ospl stop command and stops the daemon.
# Step 1
Choose Run > External Tools > External Tools from the Eclipse Menu Bar. This will open the External Tools dialog.
# Step 2
Select the OSPL stop item (located under the Program item) in tree view (located on the left-hand side of the External Tools dialog).
# Step 3
Click the Run button. This will stop the daemon.
# Step 4
Click the Close button to close the dialog.
# 8
# Compiling and Running
This section describes how Vortex OpenSplice Modeler and Eclipse Workbench are used to compile and run applications.
# 8.1 Compiling
The Eclipse Workbench can be used to compile the native code by either
• manually invoking the Eclipse Builder by choosing Project > Build Project, Project > Build All from the Menu Bar
OR
• enabling the Project > Build Automatically option (a tick mark is displayed)
# 8.2 Running
# 8.2.1 Java
# Java
Right-click on the Java source and choose Run As > Java Application to run the application (a Vortex OpenSplice daemon is expected to be running).
The Java application must contain a main() method for this option to be available.
This facility requires the environment to be configured for Vortex OpenSplice. If not, Vortex OpenSplice Modeler comes with a handy Java run configuration preset targeting Vortex OpenSplice deployments, according to the Vortex OpenSplice preferences (see Section on Setting Vortex OpenSplice Preferences). To make use of it, choose Run As > OpenSplice Java Application.
If you need to have additional configuration settings for your run, simply create a Java run configuration for the specific Java source file containing the main() method, then edit the variables from the Environment tab (right-click on the source file, choose Run As > Run, then create new run configuration).
# 8.2.2 C++
# C++
Right-click on the C++ source and choose Run As > Local C++ Application to run the application against the selected target DDS platform. Note that if the target is Vortex OpenSplice, the Vortex OpenSplice daemon needs to be running.
Additionally, for Vortex OpenSplice targets, this facility requires that the environment be configured.
Otherwise, there is a handy C++ run configuration preset available under Run As > Vortex OpenSplice C++ Application, which utilizes the values set in the Vortex OpenSplice preferences (see Section on Setting Vortex OpenSplice Preferences).
You can also create a C++ run configuration for the specific C++ executable, then edit the variables from the Environment tab (right-click on the source file, choose Run As > Run, then create new run configuration).
To run a C++ application targeting Vortex Lite, you can choose Run As > Local C++ Application. However, you will need to manually configure the required environment variables.
There is also a handy C++ run configuration preset available under Run As > Vortex Lite C++ Application. Otherwise, You can also create a C++ run configuration for the specific C++ executable, then edit the variables from the Environment tab (right-click on the source file, choose Run $A s > R u n$ , then create new run configuration).
# 9
# Tutorial
This tutorial uses an example DDS-based chatroom system consisting of three autonomous applications (the Application Model) plus data type definitions (the Information Model) to demonstrate how to use the basic features of the Vortex OpenSplice Modeler modeling tool.
The purpose of this tutorial is not to describe DDS nor the example application’s in-depth logic and architecture, but rather to show how a project can be created, modeled and implemented using the Vortex OpenSplice Modeler.
# i
A completed Chatroom example project is included with Vortex OpenSplice Modeler. The completed example can be opened by right-clicking in the Project Explorer, choosing New > Example to open the New Example dialog, selecting Chatroom, then clicking the Finish button. The Chatroom project and three other projects, which contains the Chatroom’s generated and (example) user-written code, should open in the Project Explorer.
Java and C++ versions of the Chatroom example are covered in this tutorial. The source code, for Java and C++, is provided in Appendix A Chatroom Example Java Source Code, and Appendix B Chatroom Example C++ Source Code.
A thorough tutorial on DDS, including a detailed description of the Chatroom example, is provided in the Vortex OpenSplice C Tutorial Guide 2 .
# 9.1 Example Chatroom Overview
The tutorial example, Chatroom, is a simple system which enables people to chat with each other. The system consists of autonomous applications, distributed amongst the system’s peers, which transmit messages between the system’s users (see Basic Chatroom Architecture).
This tutorial uses the Chatroom example to demonstrate how to:
• create a Vortex OpenSplice project which can generate the source code and interfaces for a DDS-based distributed application
• add Modeler’s components, DDS entities, and resources to the project
• create a model which establishes the relationships between the application’s entities
• generate Vortex OpenSplice-compliant source code
• implement the applications business logic and associated interfaces which use the generated code
The services or functions that the Chatroom provides includes:
• enabling users to log on and off the chatroom
– the users, called chatters, have unique IDs to identify them
• controlling user load by tracking who logs on and off of the chatroom
• enabling users to see which users are logged on to the chatroom
• enabling users to post messages to other chatters
• enabling users to subscribe to the messages being published by other users
– messages are transmitted directly from the message publishers to all subscribers
The Chatroom employs the DDS-DCPS architectural approach, which is similar to a peer-to-peer architecture. Individual chatroom application nodes are distributed across hosts in a network (see Basic Chatroom Architecture).
Each chatroom application communicates directly with each of the others. This architecture is scalable and has a degree of fault tolerance (the chatroom system will continue to operate even if a node fails).
Basic Chatroom Architecture
# Network Domain
The Chatroom system consists of:
• autonomous applications which perform specific tasks (the Application Model):
– Chatter - responsible for publishing the identity of the user, followed by all chat messages he or she wishes to transmit. (This application is write-only.)
– MessageBoard - responsible for subscribing itself to all chat messages and for displaying them in the order in which they are received. (This application is read-only).
– UserLoad - This part is responsible for continuously keeping track of users that join and leave the Chatroom. (This application is read-only).
Each of these applications are modeled as separate processes. They use the standard output to print their messages (output has been kept rudimentary in order to enable the example to remain focused on the efficient utilization of the DCPS).
• data types which define the structure of the data or information which constitute the messages that users transmit between each other (the Information Model).
The Chatroom’s applications are constructed from:
• standard DDS entities, including
– DomainParticipants
– Publishers
– Subscribers
– Topics
– Content Filter Topics
– Listeners
– Partitions
– DataWriters and DataReaders
– WaitSets
– Conditions
• interfaces, implemented by the developer, which provide the Chatroom’s business logic
The DDS-specific parts of the applications are generated by Vortex OpenSplice Modeler and do not need to be implemented by the developer.
# 9.2 Creating the Chatroom
The pathnames shown here use Unix forward slash ( / ) delimiters: Windows users should replace theforward slashes ( / ) in the pathnames with back slashes ( \ ) as well as adding the drive letter (for example, c:\).
Here is an outline of the steps to follow to create the Chatroom in the Modeler:
Step 1
Create a Project to contain the Chatroom application and information models.
Step 2
Import an IDL specification which defines the structure and Topic types (the Information Model) into the Tutorial project.
Step 3
Create a Chat module to hold the Chatroom components.
Step 4
Create the ChatMessage\_topic, NamedMessage\_topic and the NameService\_topic (part of the Information Model) that the Chatroom requires.
Step 5
Set QoS policy values for the DDS entities.
Step 6
Create a partition which application’s subscribers and publishers will be associated with.
Step 7
Use the Diagram Editor to model the Chatroom’s applications.
Step 8
Generate the DDS-related source code from the application and information models.
Step 9
Implement the Chatter, MessageBoard and UserLoad applications’ business logic.
Step 10
Compile the code.
Step 11
Run and test the application.
These steps are described in detail below.
# 9.2.1 Step 1: Create a Project
Create a Project which will contain the information model and the applications (Chatter, MessageBoard and UserLoad) that will be modeled for the Chatroom.
# 9.2. Creating the Chatroom
1. If the Vortex OpenSplice Design Perspective is not open, then open it by clicking on the Window menu icon (located in the upper right-hand corner of the Workbench, above the Outline Section), then choosing Other > Open Perspective > Vortex OpenSplice Design.
2. Create a new project by choosing File $> N e w >$ Vortex OpenSplice Project from the Menu Bar.
3. Enter the name Tutorial into the Project Name text box: this will be the project’s name.
If you clear the Use Default Location check box, then you can save to your project to any directory by entering its location into the Location text box.
4. Click the Finish button to create the Tutorial project. The Tutorial project should now appear in the Project Explorer window (located on the left-hand side of the Eclipse Workbench).
Clicking the tree expansion icon will reveal the project’s model and default module components.
Eclipse only auto-saves the project when the project is created. Eclipse does not auto-save any subsequent changes to a project. Remember to save any changes or additions to your project using File > Save from the menu or the $[ C t r l ] { + } [ S ]$ short-cut key combination.
New Project in Vortex OpenSplice Design Perspective
# 9.2.2 Step 2: Provide an Information Model
Import an Interface Definition Language (IDL) specification which defines the data types and Topic types for the messages and other data the Chatroom needs (the Information Model).
Vortex OpenSplice distributes data using structured data types. The data types are transported using Topics. The OMG’s Interface Definition Language (IDL), which is platform- and implementation language-independent, is used by Vortex OpenSplice Modeler to define the data types. The IDL definitions imported into the project provide the data type definitions which constitute the project’s information model.
To import the IDL definitions for the Tutorial project:
# 9.2. Creating the Chatroom
1. Choose File > Import > Vortex OpenSplice > Vortex OpenSplice IDL Import Wizard, then click the Next button.
2. In the Vortex OpenSplice IDL Import Wizard:
a) Enter Tutorial into the Destination Folder entry box by using the Browse button (located adjacent to the box) to navigate to the Tutorial folder.
b) Enter <ospl>/examples/dcps/tutorial/idl/chat.idl into the IDL Source text box (or use the adjacent Browse button to navigate to the file), where:
<ospl> is your Vortex OpenSplice installation’s home directory
<lang> is the target language (Java or C++)
Windows users should replace the forward slashes ( / ) in the pathname with back slashes ( \ ).
c) Click Finish when done.
A new model, called Chat, should appear (provided Eclipse is set to automatically build projects: this is the default behaviour). The Chat model will contain the Chat module and its data types (ChatMessage, NamedMessage and NameService).
The Chatroom’s NameService data type should not be confused with the OMG’s CORBA Naming Service of the same name; they are not related in any way.
ChatMessage - Contains the message to be published, a message index and the ID of the user publishing the message.
NamedMessage - Contains the user name, user ID, message and message index, information that the Message-Board application requires.
NameService - Contains the details of a single user, their userID and name.
The IDL definitions for these data types are shown in the following code extract.
```c
/******************************************************************************************
*
* Copyright (c) 2006 to 2017
* ADLINK Technology Limited
* All rights Reserved.
*
* LOGICAL_NAME: Chat.idl
* FUNCTION: Vortex OpenSplice Tutorial example code.
* MODULE: Tutorial for the Java programming language.
* DATE june 2006.
******************************************************************************************
*
* This file contains the data definitions for the tutorial examples.
*
***/
module Chat {
const long MAX_NAME = 32;
typedef string<MAX_NAME> nameType;
struct ChatMessage {
long userID; // owner of message
long index; // message number
string content; // message body
};
#pragma keylist ChatMessage userID
struct NameService {
```
```txt
long userID; // unique user identification
nameType name; // name of the user
};
#pragma keylist NameService userID
struct NamedMessage {
long userID; // unique user identification
nameType userName; // user name
long index; // message number
string content; // message body
};
#pragma keylist NamedMessage userID
};
```
# 9.2.3 Step 3: Create a Chat module
Create a Chat module for containing the Chatroom components.
1. Expand the model called model in the Project Explorer to show the default module. Right-click on the default module to display the context menu. Choose the New Module option from the context menu.
2. In the New Module wizard:
a) Enter Chat into the Name field.
b) Click Finish when done.
The Chat module should now appear as a child node of the default module.
# 9.2.4 Step 4: Create the Topics
Create the ChatMessage\_topic, NamedMessage\_topic and NameService\_topic (part of the Information Model) that the Chatroom requires.
To create the ChatMessage\_topic:
1. Expand the model called model in the Project Explorer to display the Chat module. Right-click the Chat module to display the context menu. Choose the New Topic option from the context menu.
2. In the New Topic wizard:
a) Enter ChatMessage\_topic into the Name field.
b) Click the Browse button adjacent to the Data Type text box; this opens the Data Type Selection dialog. Navigate to the ChatMessage struct in the Chat module within the Chat model, then select the Chat struct, then click the OK button to confirm.
c) Click Finish when done.
The ChatMessage\_topic should now appear as a child of the module under the default model.
Repeat these steps for the NamedMessage\_topic and NameService\_topic, but selecting the NamedMessage struct or the NameService struct, respectively, in the Data Type Selection dialog.
The Tutorial project should now contain the Chat Model, Chat Module, structs and topics as shown in the illustration below.
# Tutorial’s Data Types and Associated Topics
# 9.2.5 Step 5: Set the QoS policy values
Each DDS entity instance is automatically assigned a set of QoS policies, appropriately named the QoS Set. A QoS Set contains only the policies which are appropriate for the particular entity instance’s type. A QoS Set’s policy values are given pre-defined default values. These values can be changed using the QoS Set Editor.
A QoS policy consists of one or more properties, each property has a value. Strictly speaking, the value should be referred to as a policy’s property value. However, for brevity, the term policy value is used here to mean the policy’s property value.
The Topics associated with the NameService and ChatMessage information models will be used to demonstrate how to set QoS policy values. The policies and their property values are:
Policy Values for the Chatroom Topics