A Java Runtime Environment (JRE), version 11 is required. f you also plan to use LynxDesigner for java development, a Java Development Kit (JDK) is needed instead. Install either the JRE or JDK, version 11 from Eclipse Temurin, version 11.

To install LynxDesigner:

Download LynxDesigner from the Lynxwork download site
Unzip your download to any desired location.
Run the LynxDesigner.exe executable.
- If you don’t have a Java Runtime Environment (JRE) or Java Development Kit (JDK) installed, you will get an error message. Make sure you first install a JRE/JDK, before you try again.
When prompted for a workspace location, choose a location where the data files can be saved.

1-2 LynxDesigner Mac Installation

LynxDesigner runs as a desktop Mac application that can be installed and run locally.
For Mac users, it can also be recommended to install LynxDesigner as Plugins (1-4 – LynxDesigner installation as Plugins) in case there are issues with installing unsigned applications.

1-3 LynxDesigner Linux Installation

LynxDesigner runs as a desktop Linux application that can be installed and run locally

1-4 LynxDesigner installation as Plugins

A user can also choose to install LynxDesigner through a set of plugins on an existing Eclipse installation.
LynxDesigner is known to work in the following setup. It may well work with other versions/distributions of Eclipse.

Download and install Eclipse
1. LynxDesigner is tested to work with Release 2022-03 “Eclipse IDE for Enterprise Java and Web Developers” https://www.eclipse.org/downloads/packages/release/2022-03/r/eclipse-ide-enterprise-java-and-web-developers
2. It may well work with other versions
Start Eclipse
Install the LyoDesigner plugins
1. Select the menu Help > Install New Software.
2. Enter the update site http://download.eclipse.org/lyo/p2/edge
3. Select the listed LyoDesigner plugins
4. You will prompted “Do you trust these signers?”, press Select All and then “Trust Selected”.
5. Press “Restart Now” when prompted
Install the Lynxdesigner plugins
1. Select the menu Help > Install New Software.
2. Enter the update sitehttps://download.sandbox.lynxwork.com/lynxdesigner/plugins/p2/edge/
3. Select the listed LynxDesigner plugins
4. You will prompted “Do you trust these signers?”, press Select All and then “Trust Selected”.
5. Press “Restart Now” when prompted.

1-5 Software Update

By default, LynxDesigner is setup to automatically check for new updates, which you can then manually install.
To control the update preferences

select the menu Windows > Preferences
select install/update > Automatic Updates from the left menu.
If you choose to avoid automatic updates, you can always check for any updates through the menu Help > Check for Updates

1-6 LynxDesigner – An Environment for Java Development

LynxDesigner produces Java code as a Maven artifact (See LD-1496 – Development & Deployment Support ). Such code can then be further developed using any Integrated Development Environment (IDE) that supports Java development (for example IntelliJ IDEA or Eclipse).
LynxDesigner itself can also be configured to act as such a java IDE.
To setup LynxDesigner as an IDE, follow the instructions under 1-7 – Eclipse JEE – An Environment for Java Development, applying the same steps on a LynxDesigner installation, instead of an Eclipse IDE (that is, skip step 1 in the instructions).

1-7 Eclipse JEE – An Environment for Java Development

LynxDesigner produces Java code as a Maven artifact, which can then be further developed using any Integrated Development Environment (IDE) that supports Java development (for example IntelliJ IDEA or Eclipse).
The instructions below help you setup an Eclipse IDE for such development:

Install the Eclipse IDE for Java EE Developers distribution
Install a JDK, version 11. Eclipse Temurin, version 11 is recommended as your default JDK
Install Maven version 3.9.3 or higher
Start Eclipse
In Eclipse, change the Installed JRE to the newly installed JDK (instead of the default JRE).
- Select Window > Preferences.
- Select Java > Installed JREs.
- Click Add…
- In the new window that appears,
  - Choose Standard VM as JRE Type.
  - Click Next.
  - As JRE home choose the installation dir of your JDK.
  - Click Finish.
- Back to the preferences screen:
  - Select the old JRE.
  - Click Remove.
  - Check the newly added JDK
  - Click OK.
In Eclipse, change the Installed Maven to the newly installed Maven (instead of the default embedded version).
- Select Window > Preferences.
- Select Maven > Installions.
- Click Add…
- In the new window that appears,
  - Choose Installation Type as External.
  - Click Directory.
  - Choose the installation directory of your Maven installation.
  - Click Finish.
- Back to the preferences screen:
  - Check the newly added Maven configuration
  - Click OK.

2 General Modelling Functionality

2-1 Model Editor

LynxDesigner is based on the Eclipse Sirius modelling framework. The reader is referred to the Sirius User Manual for full details of the available modelling capabilities. This section provides a concise summary.
The editor is divided into the following Views:

The main Diagram area shows the modelling elements, which the user can directly interact with.
The Palette gives access to additional tools, such as creation tools.
The Properties window shows detailed properties of the selected modelling element.
The Model Explorer – shows the hierarchy of available Projects, the contained models within each project, and the contained model elements within each model.
The Tabbar – provides additional, more global operations such as filtering, printing, zooming, etc.

The LynxDesigner Editor

2-2 Editor Perspectives and Windows

The Modelling Editor is structured as set of Views. These Views can be laid out across the screen as desired by the user. They can also be shown/hidden as desired.
A Perspective is a predefined layout of a set of Views, which can then be modified by the user.
The most relevant Perspectives for LynxDesigner are:

Modelling
Java

Besides the modelling Views listed above, other relevant Views are:

Error Log
Problems
Console

To show a particular View (for example Properties):

Select the menu Windows > ShowView > …

To show a particular Perspective (for example Modelling):

Select the menu Windows > Perspective > Open Perspective> .

2-3 Model Interactions

The user can interact with a model to create, edit or reposition elements in a number of intuitive ways:

Interaction through Contextual Menus – the user Interacts with the modelling elements through Contextual Menus available by right-clicking on a graphical element.
Element Creation – the user creates elements in the Diagram area through one of the tools in the Tool Palette.
- To create an Element, the basic pattern is to left-click on the tool in the palette, and then apply it once on the diagram. (Do not drag-drop from the Palette to the Diagram)
Connection Creation – the user creates connections in the Diagram area through one of the tools in the Tool Palette. To create a connection between 2 Element
1. Select the edge operation from the tools Pallet
2. Select the desired source element in the diagram.
3. Select the desired destination element in the diagram.
4. An edge is now created between the source and destination
Direct actions on Elements – When the user moves the mouse curser over an element, the cursor’s shape lists the set of actions allowed on that element.

2-4 Modelling Aspects

For better separation of concerns, LynxDesigner organizes a model around three aspects

Information Modelling – (3 – Information Modelling) Defines the types of resources (together with their properties and relationships) that are to be exchanged between applications. The model is based on the OSLC Core Specification and the Resource Shape Constraints Language.
Toolchain Modelling – (4 – Toolchain Modelling) Models an overview of the applications, and their interactions – in terms of the Resources being shared through application services.
Application Interface Modelling – (5 – Application Interface Modelling) Models the detailed services of an application, including the corresponding Resources shared through these services. Sufficient details are captured in this view, so that an almost complete API code can be generated.

The information captured in these three aspects can be defined concurrently, and in any order.
Working with these models allows you to work at a higher level of abstraction, without needing to deal with the underlying technical details (Standards and technologies such as OSLC, Linked Data, RDF, etc.).

2-5 Model organisation in modelling files and projects

In LynxDesigner, Models are persisted in a modelling file, which is then managed under a Modelling project. Each project may contain any number of modelling files. Naturally, models can cross-reference each other across files, and projects.
A modelling file can be used to persist information from any (or all) of the three perspectives. For example, you can choose to handle all three perspectives with a single file. Alternatively, you can use a different modelling file for each of the perspectives.

To create a modelling project:

In LynxDesigner, switch to the Modeling perspective
Select New > Modelling Project
Choose a project name, and if desired a specific location.
You are now ready to create modelling files inside this project.
1. To create an Information Model, see 3-2 – Create an Information Model
2. To create a Toolchain Model see 4-2 – Create an Toolchain Model

Note: A Modelling Project is different from a Java Project. The latter is used to manage the Java code generated from Information Models (6-1 – Information Model Code Generation) and Adaptor Interface models (6-4 – Application Interface Code Generation).

2-6 Model composition by importing between projects

To manage large models, LynxDesigner allows you to compose a model by importing and referencing elements from other models in external modelling projects.
You can import and use a previously defined model, through the addition of Project Dependencies:

In the Model Explorer view, right-click on the Project Dependencies entry within the modelling project, and select Add Model.
select Browse Workspace
Navigate and select the desired model.
Press OK.
In your own model, you can now create references to elements from the imported model. See for example 3-8 – Information Model composition by importing between projects

2-7 Model Validation

At any time, you can validate the model to ensure that all required properties are completely defined as expected.
It is recommended that a model is validated frequently to identify any missing properties.
At the least, model validation should be performed before any code is generated to ensure correct code is produced.

Any part of the complete model can be validated:

Navigate down and open any particular diagram within the model tree
Right-click on the diagram canvas to open the context menu
Select the context menu item Validate
If you receive Validation Problems, press Details to read the error details, and correct your model accordingly. Alternatively, you can open the Problems view to see the list of errors

3 Information Modelling

3-1 Information Modelling

In an Information Model, you can define the set the Resource types (together with their properties and relationships) that are to be communicated between applications. The models reflect the exact digital representation of the artefacts that are actually communicated between applications. The model is based on the Resource Shape Constraints Language.
An information model is created in a Specification Diagram, where one or more Domain specifications can be defined (3-3 – Organize information models into Domain specifications).

An example specification diagram containing 1+ Domain specifications

3-2 Create an Information Model

An information model can be defined either (a) in a stand-alone Information Model file, or (b) within a Toolchain model (4-2 – Create an Toolchain Model). In both alternatives, the information model is managed within a modelling project (2-5 – Model organisation in modelling files and projects).

To create a stand-alone Information model:

In LynxDesigner, switch to the Modeling perspective
Open the desired modelling project, or create a new modelling project as instructed in 2-5 – Model organisation in modelling files and projects
Create an Information Model
1. Right-click on the modelling project, and select New > other…
2. In the Wizards window, navigate and select Lyo Designer > OSLC Domain Specification Model, then press Next
3. choose a suitable file name (or keep the suggested default) for the model, then press Next
4. Set Model Object to Specification
5. Press Finish
6. Right-click the project again, and select Viewpoints selection
7. select LynxworkDesigner
8. Press OK
Open the diagram
1. In the Model Explorer, expand the file structure (by pressing the triangle/arrow to the left of the newly created model file) until the Specification entry is visible. (Note: Do not double-click on the file. This will instead open the file in an xml editor.)
2. If you don’t find a Specification Diagram entry below the Specification entry, Right-click and select New Representation > Specification Diagram.
3. Double-click on the Specification Diagram entry below the Specification.

To create an information model inside a Toolchain model:

In LynxDesigner, switch to the Modeling perspective
Open the desired modelling project that contains the Toolchain model
In the Project Explorer, Expand the tree of the Toolchain model until you reach the Specification element.
Right-click and select New Representation > Specification Diagram

3-3 Organize information models into Domain specifications

Resource Types in an Information Model are organized into a number of Domain Specifications. A Domain Specification is used to package resources that belong together – as found appropriate by the modeler. For example, in the OSLC standard, Domain Specifications are defined for Requirements Management, Quality Management, Architecture Management, etc.

To create and populate an Information model with Domains Specifications:

Open or create the Specification Diagram (3-2 – Create an Information Model )
Using the tools pallet (located on the right), create any number of Domain Specifications.
For each such Domain Specification, set the domain properties – Name, Namespace Prefix and Namespace URI.
1. For example, when modelling the Requirements Management domain, the namespace URI may be http://your.company.net/ns/rm# with a preferred namespace prefix of cmp_rm.
Inside each Domain Specification, use the tools pallet to model your Resource types & their properties and relationships (See 3-4 – Modelling Resource Types, Relationships and Properties ).

Instead of dealing with all Domain Specifications at once, you can also choose to focus on a single domain, by creating a Domain Specification diagram for the desired Domain Specification:

In the Specification diagram, double-click on an Domain Specification to open its internal view – if it exists.
If the view is being opened for the first time, a prompt for entering the diagram name is shown.

An example Domain Specification diagram

3-4 Modelling Resource Types, Relationships and Properties

Once an Information Model – and its corresponding Specification Diagram – are created, you can define a set of Domain Specifications (3-3 – Organize information models into Domain specifications ), within which you define Resources and Resource Properties.
Using the Tool Palette:

Open the Specification Diagram, or any specific Domain Specification Diagram
Use the tools pallet to create any number of Resource elements.
1. Select the operation Resource Type from the tools pallet, and then place your cursor on the desired Domain Specification in the diagram.
2. Set the required attributes for each Resource (such as its name) in the Propertieswindow.
Use the tools pallet to create any number of (a) Literal Property, and (b) Reference Property elements.
1. Select the desired operation from the tools pallet, and then select the Propertieslist within the desired Domain Specification in the diagram.
2. Set the required attributes for each Property (such as Occurs, description, range, …) in the Properties window.
To assign a Property to a Resource, drag-and-drop the property from the Propertieslist to the desired resource.
- A relation to a LiteralProperty is listed inside the Resource element it is allocated to.
- A relation to a ReferenceProperty is shown as an arrow between the Resourceand the Resource the ReferenceProperty refers to – if such a resource is visible in the diagram. (otherwise, the property is listed inside the Resource element it is allocated to.)
- Note: A Resource can refer to Properties (Literal or Reference) from any other Domain Specification.

Resources and Resource Properties can also be defined through direct actions on the diagram:

Place the mouse curser over an empty area on (a) the Specification Diagram, or (b) any specific Domain Specification Diagram – 3 icons will appear that provides you with actions to create a Resource, Literal Property and Reference Property.
Place the mouse curser over a Resource element – 2 icons will appear that provides you with actions to create a Literal Property and Reference Property directly on that Resource.

3-5 Reorganising your Resource Types, Relationships and Properties

Besides changes to the attributes of Resources and Properties, it is quite common that some reorganisation of the Information Model is necessary over the lifecycle of the model.

To move a Resource from one Domain to another – in the Specification diagram, drag-and-drop the desired Resource from one Domain Specification to another.
To change a LiteralProperty to a ReferenceProperty (or vice versa) – simply change (a) the Range and (b) value type values of the property in the Properties window.
To change the Range of a ReferenceProperty to point to another Resouce – Select the target end of the arrow and move it from its current destination Resource to another.

3-6 Configure the overall generation settings of an Information Model

If you plan to generate java code from your information model, you will need to configure the generation settings of the Information Model. This is particularly relevant if you manage the information model independently from the various Application Interfaces that might be using it.

Open the Specification Diagram
Use the tools pallet to create a Specification Configuration, placing it in the Specification Diagram (an empty area in the Diagram, and not inside any specific Domain Specification). This element lets you configure the Specification model’s generation settings. The element consists of two sets of configurations as follows:
1. General: Contains the general generation settings:
  1. Files Base Path: The path where the generated files will be generated. Set the path relative to your current location, which is the modelling project.
  2. Java Base Package Name: the name of the base Java root package from which the code of your adaptor will be generated.
2. Project Configuration: This relates to the configuration of the Java project
  1. Do Not Generate Project Configuration Files: Set this property if you don’t want the automatic generation of these files. This is typically used once you have initially generated such files, and then wanted to manually control changes to the files.
  2. Group Id, Artifact Id &Version: define the maven project settings.
  3. Lyo Version: Define the version of Lyo libraries to use.

A configuration setup at the Specification level produces a single Java project containing all resources from all contained Domain Specifications. You can also specify settings at the Domain Specification level, to override the general Specification settings. This can be used to define different Java project for any Domain Specification. To create a Specification Configuration for a specific Domain Specification see 3-7 – Configure the generation settings of a specific Domain Specification

3-7 Configure the generation settings of a specific Domain Specification

3-6 – Configure the overall generation settings of an Information Model explains how to configure the generation settings for the whole information model (that is, for all the Resource Types within all of its Domain Specifications).
It may sometimes be desired to generate OSLC-resource Java classes into a set of separate java libraries, which are then included in multiple OSLC projects. For example, you might want to generate the classes from each Domain Specification into a separate Java (maven) projects.
LynxDesigner allows you to control the generation settings of each individual Domain Specification and/or all Domain Specifications.
LynxDesigner allows you even to model Domain Specification(s) without necessarily generating them. This can be useful if:

You want to model existing implemented Domain Specifications so that they can be used in the model. That is, you can define OSLC services on such Java classes, but you don’t necessarily want to generate these classes.
You have previously generated domain specificaitons, and have done manual modifications that you don’t want to overrride.

To configure the generation settings for a single Domain Specification:

Select Generation Setting from the tools pallet, and then select a Domain Specification in the diagram.
Set the generation properties as desired.
1. Java Files Path – The relative file path to be used to save the generated Java classes.
2. Java class Package Name – The package name of the generated Java classes.
3. Do Not Generate – whether the Java classes should be generated at all.

The following rules applies when generation settings are set at different levels in the model:

The generation settings of a specific Domain Specification (if defined) override those set for the overall Specification model.
The generation settings of the overall Specification model (if defined) override those set for a specific Tool Adaptor.

Important to note that when related Java classes are distributed into different Java projects, it is necessary to set dependencies between these Java projects, in order for the code to compile. For example Resource oslc:Requirement contains a reference property dcterms:creator, whose range is Resource foaf:Person. If the OSLC and FOAF Domain Specifications are generated into different maven projects, the OSLC maven project should include a maven dependency to the FOAF maven project.

3-8 Information Model composition by importing between projects

To manage large information models, LynxDesigner allows you to compose a model from multiple model files, by importing and reusing existing information models.

See 2-6 – Model composition by importing between projects to import and use a previously defined model.
In your own Specification Diagram, you can now view the Resources and Resource Properties from the imported Domain Specifications.
1. Expand the imported Specification model (under the the Project Dependenciesentry) until the Domain Specification entries are visible.
2. Drag-drop any Domain Specification into an existing Specification Diagram to visualize its content.
In your own Specification Diagram, you can also create references to Resources and Resource Properties from the imported Domain Specifications. For example, when defining the Resource Properties of a Resource, you can choose from a list of all available Resource properties (both imported and those defined within your own model).

3-9 Information Model composition through multiple diagrams

To manage large models, LynxDesigner allows you create multiple diagrams for the same model file, where each diagram can have a subset of the information in the complete model.
Within a single model, you can create any number of diagrams, each of which can contain any number of (overlapping) Domain Specifications.

Open the Model Explorer view.
Expand the Information Model file until the Specification entry is visible. (Do not double-click on the file. Instead, press the triangle/arrow to the left of the file entry.)
right-click the Specification entry, and select New Representation > New SpecificationDiagram.

You can define new Domain Specifications or visualize existing ones in any of these Specification diagrams.

You can drag-drop any existing Domain Specification into any existing Specification Diagram to visualize its content.
You can create a new Domain Specification through the tools palette. 3-3 – Organize information models into Domain specifications

Note the following:

A Specification Diagram can contain any number of Domain Specifications.
A Domain Specification can be viewed from within any number of Specification Diagrams.
- Once defined in a diagram, you can drag-drop a Domain Specification from the Model Explorer view into any other diagram to represent that domain in additional diagrams.
A change to a model entity (a Domain Specification, Resource, Resource Property) is reflected in all diagrams.

4 Toolchain Modelling

4-1 Toolchain Modelling

From a Toolchain viewpoint, you can define the set of Applications that form your development environment, as well as a high-level representation of the services each Application produces and/or consumes. These services are then further designed in the detailed Application Interface design as defined in5-1 – Application Interface Modelling.

An example toolchain diagram

4-2 Create an Toolchain Model

A Toolchain model is created inside a modelling project. To create a toolchain model:

In LynxDesigner, switch to the Modeling perspective.
Open the desired modelling project, or create a new modelling project as intructed in 2-5 – Model organisation in modelling files and projects
Create a Toolchain model
1. Right click on the modelling project, and select New > other…
2. In the Wizards window, navigate and select Lyo Designer > OSLC Toolchain Model, then press Next
3. choose a suitable file name (or keep the suggested default) for the model, then press Next
4. Set Model Object to Toolchain
5. Press Finish
6. Right-click the project again, and select Viewpoints selection
7. select LynxworkDesigner
8. Press OK
Open the diagram
1. In the Model Explorer, expand the file structure (by pressing the triangle/arrow to the left of the newly created model file) until the Toolchain entry is visible. (Note: Do not double-click on the file. This will instead open the file in an xml editor.)
2. If you don’t find a Toolchain Diagram entry below the Toolchain entry, right-click and select New Representation > Toolchain Diagram
3. Double-click on the Toolchain Diagram entry to open the diagram.

4-3 Model Applications in the Toolchain Model

Once a toolchain model – and its corresponding Diagram – is created, you can define the set of Applications that form this toolchain:

Using the tools pallet, create any number of Adaptor Interface elements.
For each Adaptor Interface, you only need to set its name property.
For each Adaptor Interface, use the AddManagedResource tool to directly define default web operations for a particular resource type. A more detailed design of such operations can be done in the Application Interface model (5-1 – Application Interface Modelling).
For each Adaptor Interface, use the AddConsumedResource tool to directly define the resource types that the application may need to consume.

5 Application Interface Modelling

5-1 Application Interface Modelling

Each Application in the Toolchain is further detailed in an Application Interface model. The model details the interface’s internal design by defining the provided services, and the corresponding Resources shared through these services. This information is then used to generate the interface implementation (6-4 – Application Interface Code Generation ).

An example adaptor interface diagram

5-2 Create an Application Interface Model

An Application Interface model is created as part of a Toolchain model.

In the Toolchain view, double-click on an Application to open its internal design view
1. If such an internal model already exists, it will be opened.
2. If such an internal model does not already exists, you are first prompted for a diagram name, before the newly created diagram is opened.
You are now ready to define the desired services as detailed in LD-1658 – Define Discovery services & LD-1659 – Define Operations on Resource Types .

5-3 Importing Information Model from other modelling projects

Interface services apply to Resource types defined in information models. These models can be either defined within the same toolchain model (as described in 3-2 – Create an Information Model), or imported from other projects (as described in 2-6 – Model composition by importing between projects).

When defining services, you can then refer to Resources types from both the current toolchain model, as well as those from any imported model.

5-4 Define Discovery services

An Application Interface can publish its API services so that a client can discover and use them. This is based on OSLC Core Discovery , through the definition of ServiceProviderCatalog, ServiceProviders and OSLC Services.
When created, an Application Interface is initiated with one ServiceProviderCatalog, and one ServiceProvider. The default model is sufficient as a starting point to build services.

To create additional ServiceProviders:

From the Tool Pallet, select the CreateServiceProvider tool
In the diagram, select the ServiceProviderCatalog to which this ServiceProviderbelongs.
For the newly created ServiceProvider, fill-in the ServiceProvider properties (title, description).

Notes:

LynxDesigner currently supports the definition of one (and only one) ServiceProviderCatalog per Application.
For each ServiceProviderCatalog and ServiceProvider in the model, there will be a corresponding web service that responds to requests on a specific relative URL. If you want to control the relative URLs of these web services, specify some of the provided optional properties, as instructed in 5-6 – Configuring the URLs of Services and Operations .

5-5 Define Operations on Resource Types

For an Application Interface, you can define any of the following operations for any one (or more) Resource Type:

Selection Dialog – A user interface that can be embedded by any client, which allows the end-user to search, select and establish a traceability link to any chosen resource instance. Further details can be found in OSLC Core – Delegated Dialogsspecification.
Creation Dialog – A user interface that can be embedded by any client, which allows the end-user to create a new resource instance, and establish a traceability link to this new resource instance. Further details can be found in OSLC Core – Delegated Dialogs specification.
Query – a web services that provides a mechanism for a client to query or search for resources based on a simple query language. Further details can be found in OSLC Core- Query specification.
Creation Factory – a web services that provides a mechanism for a client to create a resource. Further details can be found in OSLC Core – Creation Factory
Read/Update/Delete Resource – Web services that provides a mechanism for a client to read, update or delete a given resource.

To define the operations:

From the Pallet, select the Services tool.
In the diagram, select a position on the canvas to create the Service element.
A dialog appears, prompting you for the Resource Type upon which the operations apply. Select the desired Resource Type.
A new dialog appears, prompting you for the set of operations to define. Select the desired set.
Once selected, elements appear in the diagram to represented the modelled operations, as exemplified in the diagram below. The operations will be represented in two different ways in the diagram.
1. A list of all defined operations are listed under the Resource Type.
2. The OSLC operations (Dialogs, Query, Creation Factory) are represented within an OSLC Service, which in turn is defined within its containing Service Provider. This structure reflects the OSLC model where a ServiceProvider consists of set of OSLC Services, which in turn contain the operations: Selection Dialogs, Creation Dialogs, and Creation Factories.
3. The CRUD operations (Read, Update, Delete) are represented – together with the OSLC structure – under the Server Structure container.
The newly created operations are defined with default values, which can then be further configured through the Properties view of each element. In particular, if you want to control the URLs that handle these operations, see Configuring the URLs of the OSLC Services.

Figure # example model of Operations on ChangeRequest resource

5-6 Configuring the URLs of Services and Operations

For each ServiceProviderCatalog, ServiceProvider and OSLC Service in the model, there will be a corresponding JAX-RS web service, that responds to web requests on a specific URL. You can control the URLs of these web services.

For a ServiceProvider, modify the following properties:

serviceNamespace – specifies the relative URL for the ServiceProvider JAX-RS Service. For example, a value of “projects” will lead to the URL http://base_url/context_path/projects. The default is serviceProviders (leading to the default http://base_url/context_path/serviceProviders).
instanceID – specifies the relative URL of a single service provider, including the parameter variables necessary to identify a specific service provider. For example, {projectId} leads to the url http://base_url/context_path/projects/1 mapping the value 1 to the projectId parameter in the java code. Other IDs can be collectionName/{collectionName}/project/{projectName}. The default is {serviceProviderId}.

For a Service (and its corresponding operations), modify the following properties:

serviceNamespace – specifies whether the Service’s URL should build upon the URL of its containing service provider (relativeToServiceProvider), or it should be standalone (independantOfServiceProvider).
For each of its operations (Selection Dialog, Creation Dialog, Creation Factories), the URI property specifies the URL of the method – relative to the URL of the Service.

For the Read/Update/Delete operations, modify the following properties:

Service URL Pattern – The URL pattern for the whole web service.
Resource Url Pattern – The URL pattern for the each of the CRUD methods – relative to the web service.
1. Use [ResourceType] to denote the type of the resource.
2. Use the parameter variables necessary to identify a specific resource. For example, changeRequests{changeRequestId} leads to the urlhttp://localhost:8080/YourAdaptor/services/changeRequests/1 mapping the value 1 to the changeRequestId parameter in the java code.

5-7 Configure the overall settings of an Application Interface Model

In order to support 6-4 – Application Interface Code Generation, you first need to configure the Application’s generation settings. All settings can be found under the Configuration element in the diagram. The element consists of three sets of configurations as follows:

General: Contains the general generation settings:
1. Do Not Generate: Enable this option if you simply want to model an application but do not desired to produce code.
2. Do Not Generate from Imported Models: Enable this option to instruct the generator to not generate code from any imported models. For example, an imported information model may already be generated into another Java project. In such a case, there is no need to generate code from that model, since the already generated code can be included into the application code instead.
3. Files Base Path: The base folder path where the generated files will be generated. Set a path relative to current location, which is the modelling project.
  1. a path of ‘.’ will produce the Java code in the modelling project. That is, your project becomes both a modelling and a development project. This may work for a simple scenario. It is recommended that the Java project is separated from the modelling project however.
  2. If you model multiple applications in the same project, you will need to generate each application into separate projects. In this case, set the path to be, for example, ../application1-interface-project/
4. Java Base Package Name: the name of the base Java root package from which the code of your adaptor will be generated.
Server Configuration: relating to the settings of your OSLC server.
1. Root Server Base Url, Application Context path &Servlet Url Pattern: Configure the complete URL of your server, which becomes a combination of these settings <Root Server Base Url>/<Application Context path>/<Servlet Url Pattern>.
2. Do not Regenerate Jsp Files: Set this property to disable automatic re-generation of the JSP files. Missings files will be generated, but any existing files will be left untouched.
3. Generate Jsp Files for Oslc-UI – not releavant.
4. Jetty Port: Set the server port to be used when running your application as an embedded Jetty server (during development) using the maven goals jetty:run or jetty:run-war.
Project Configuration: relating to the generation of the development project-specific files, such as the Pom.xml and web.xml files
1. Do Not Generate Project Configuration Files: Set this property to disable automatic generation of Project Configuration Files.
2. Group Id, Artifact Id &Version: define the maven project settings.
3. Lyo Version: Define the version of Lyo libraries to use.

6 Development & Deployment Support

6-1 Information Model Code Generation

Once an Information Model is complete and validated, you can generate a library of Java classes with the appropriate OSLC4J annotations to reflect the defined OSLC Resource types, and their properties. These classes can then be further used in the development of Application Interfaces. The generation process creates a complete fully-configured Java Project.

For the generation to be enabled, you first need to make sure that the generation settings are configured as desired as detailed in 3-6 – Configure the overall generation settings of an Information Model and/or 3-7 – Configure the generation settings of a specific Domain Specification .
Right-click inside the Specification Diagram (without selecting any Domain Specification) and select the context menu item OSLC Lyo Designer > Generate Specification Java Code
You will now be prompted to enter the base path to which the java classes are to be generated.
- NOTE: To avoid such prompt, create a a generator.properties file (in the same location as the model file). Enter a single line with the value generationPath=your_generation_path.
Press OK
Once successful, a new dialog appears that confirms generation completion.

Upon a successful code generation, all the necessary Java classes that reflect the information model are produced.
For each OSLC-resource in each of the Domain Specifications, a corresponding Java class is produced. The class includes the appropriate OSLC annotations, instance attributes, getters, setters, etc.

6-2 Information model – distributable binaries

The Java code from an Information Model is structured into a library (a Maven artefact) with all the necessary dependencies defined. For a developer, this simplifies the access to the information model as binary objects (without necessrily need to access and compile the source code). This allows better control over the release process of approved information model versions.

To obtain a distributable binary from your Information model:

Construct your Information Model independently of the Application Interface models to simply the configuration of its configuration separately. That is, when creating an Information Model, define it as a stand-alone Information Model file, and not within a Toolchain model.
Make sure you 3-6 – Configure the overall generation settings of an Information Model to define the necessary package names.
Consider if you also need to 3-7 – Configure the generation settings of a specific Domain Specification.
Once generated, the resulting code consists of an independent library (a Maven artefact). You can view the resulting pom.xml file to view the resulting Group Id, Artifact Id & Version – as defined through your configuration.

6-3 Information Modelling – Simplified deployment

Standard CI/CD workflow can be setup to support the automatic flow from generating Information Model (preferably through a review process on a Git repository) to the release of the resulting Java artefacts to an Artifactory repository.
This facilities the processes of defining dependencies from the Application Interface to the appropriate information models.

6-4 Application Interface Code Generation

Once an Application Interface model is complete and validated, you can generate its Java code. The generation process creates a complete fully-configured Java Project. The developer needs only to develop the code that connects to the Application, and obtains the necessary data.

For the generation to be enabled, you need to make sure that the generation settings are configured as desired as detailed in 5-7 – Configure the overall settings of an Application Interface Model.
Right-click on the desired Application in the Toolchain view, and select OSLC Lyo Designer > Generate Java Code
Enter the base path to where the java classes are to be generated in the prompted window,
- NOTE: To avoid such prompt, create a a generator.properties file (in the same location as the model file). Enter a single line with the value generationPath=your_generation_path.
Press OK
Once successful, a new dialog appears that confirms generation completion.

Notes:

LynxDesigner supports an incremental development of the Application Interface model (& corresponding implementation). Any manual changes to the generated code (within designated placeholders) are maintained upon a subsequent change in the model, and resulting code re-generation.
LynxDesigner allows you to generate different parts of the code into different projects (or file locations). This allows for better reuse of generated code packages. Specifically, the code corresponding to the Information Model used by the Application can be packaged separately. This is achieved by a combination of 3-6 – Configure the overall generation settings of an Information Model and 3-7 – Configure the generation settings of a specific Domain Specification .

Upon a successful code generation, all the necessary Java classes needed to serve the designed services are produced. In addition to that, 6-7 – Developer Pages are produced to help further develppment and debugging of the Application Interface.
The following Java classes are generated based on the Application Interface model:

resources Package
- This package contains Java classes that correspond to the Resource Type of relevance to your project.
- Which Resource Type classes are generated? The generator only produce the classes that are needed (directly or indirectly) by the defined services. That is, an Information Model may contain much larger set of resource types, which are not necessarily generated unless needed by the application.
- Note that this package can be empty if you configured your model to produce the code from Information models into a separate package.
services Package
- This package contains the JAX-RS classes that handle the web services as defined in the Application Interface model.
- Each JAX-RS class contains the necessary methods that correspond to Query Capabilities, Creation Factories, Dialogs, as well as the CRUD methods to interact with resources – as defined in the Application Interface model.
- Each JAX-RS class contains methods to respond to both HTML and RDF/XML requests.
id.resources & id.services Packages
- This package contains classes that represent the IDs (and hence URLs) of all Resource Types and Services to be handled by the Application Interface.
servlet Package
- Contains the necessary classes to initiate and setup the web application.
webapp Folder
- The folder contains the JSP pages that delivers the HTML content for all web requests.
- The folder also contain 6-7 – Developer Pages that are useful for debugging purposes, helping the developer explore and test the APIs.

At a minimum, the developer needs to develop the code that connects to the Application, and obtains the necessary data for any given web request. This is further detailed in 6-5 – Code development to access data from the Application

6-5 Code development to access data from the Application

Code generated by LynxDesigner is almost complete. The developer needs only to develop the code that connects to the Application, and obtains the necessary data for any given web request.
For each Resource Type associated with any web service, a skeleton class is generated in the services packages. This class needs to be implemented to connect to the Application, and obtain the necessary data.

6-6 Support for embedding user code inside generated code

All generated classes have complete functionality, and need not be modified nor complemented with additional manual code. However, the classes contain placeholders that allow the developer to insert additional code and hence modify the generated default code where necessary. such manual code remains intact after subsequent generations, if modifications are placed within the designated placeholders. This allows for the incremental development of the adaptor model, and its resulting code.User code blocks are allowed inside the placeholders below. Any code entered between these two lines of code is maintained across subsequent generations.

// Start of user code imports

// End of user code

6-7 Developer Pages

Besides the generated code that serves the designed services of the Application Interface, a set of developer pages are provided to help the develop navigate and test the various DelegatedUIs as well as API calls in a convenient way.

Frontpage – A front page highlitghting two main entry points: (a) Navigation of Services through the defined ServiceProviderCatalog, ServiceProviders and ultimately the web services.
ServiceProviderCatalag – A page listing the defined Service Providers.
For each Service Provider – a page listing its OSLC Services, and the details of each such service.
1. For a Selection Dialog – a page that simply embeds the Dialog as an i-frame. The page acts as a typical OSLC consumer, interacting with the Dialog as would be expected.
2. For an OSLC Query capability – a page that consists of (a) a form that reflects the OSLC Parameters oslc.where, oslc.paging, etc and (b) query results that list the results of the query.
For each Resource Type – a page representing information about the Resource. It contains its small/large UI Previews, as well as the machine formats (RDF/XML, Json-ld, etc.)

6-8 Application Interface – distributable binaries

The Java code from an Application Interface results in a Maven artefact with all the necessary dependencies defined. This can then be built into a deployable war-file, which can then be deployed under a web application server such as Tomcat or Jetty (6-11 – Application Interface deployment as web application under Tomcat). The project is also configured to run as a Docker container (6-10 – Application Interface deployment as Docker container).
You just need to ensure the project is configured through 5-7 – Configure the overall settings of an Application Interface Model

6-9 Application Interface – Simplified deployment

Standard CI/CD workflow can be setup to automate the process flow from generating Application code to the deployment of the resulting web binary under the web application server such as Tomcat or Jetty. The project is also configured to run as a Docker container.

6-10 Application Interface deployment as Docker container

LynxDesigner produces the necessary docker files (Dockerfile & docker-compose.yml) for an Application Interface. This makes it easy to run the Application Interface using Docker, using the following simple steps:

Build the binary file – mvn -B clean install
Build the docker image, and start the container – docker-compose up –build -d

6-11 Application Interface deployment as web application under Tomcat

Once build with maven, the resulting war-file can be deployed under a web application server such as Tomcat or Jetty. This is done using the typical deployment procedures for the chosen web application server.

7 Lifecycle Management

7-1 Repository Management

LynxDesigner supports the representation of three aspects of your toolchain architecture (a) the information model (b) complete toolchain (c) detailed API design of individual applications (2-4 – Modelling Aspects). While they are interdependent, these aspects are typically developed in parallel, and will have different lifecycles (They are typically developed by different roles, at different rates and phases in the process).

How to best breakdown your models into modelling files and projects depends on the model complexity, and your specific development process.
To best support the differences in lifecycles, LynxDesigner helps you organize your models into separate projects

LynxDesigner also supports the management of these projects in separate Git repositories. Through the use of Git repositories, the following capabilities can be independently handled for each part of the complete model set:

Full flexibility is possible to decide how projects are mapped to repositories (for example, one can have one repository for each project, or manage all projects under a single repository.) Specifically, it is recommended to:

Manage information models in separate repositories from the Toolchain and Application Interface models. Such models (and their resulting code) can then be developed independently, and are also reused when modelling the remaining aspects of the toolchain.
Manage the Java code from Information Models in the same repository as its corresponding model. This ensures that the models and code are handled consistently together.
Manage the Toolchain model in a single Repository
Manage the Java project for each Application Interface in its own Git repository.

7-2 Structuring Toolchain and Information Models across multiple Modelling Projects

Ideally, Information Models and Toolchain Models are best organized in separate modelling files. This makes it easier to manage the lifecycles independently, since they are typically developed by different roles, at different rates, and phases in the process.
How to best breakdown your models into modelling files and projects depends on the model complexity, and development process.
A typical organization is as follows:

information-model-project – An Information Modelling Project, which includes a number of related Domain Specifications.
toolchain-model-project – A Toolchain Modelling Project, which includes a model of a number of Application Interfaces.

It may well be motivated to break down the Information Model into a number of projects (See 7-4 – Structuring Information Models across multiple Modelling & Development Projects). Similarly, a Toolchain Model maybe broken down into a number of projects. It is however best to avoid combining Information and Toolchain models into one project.

7-3 Structuring Application Interface Models across multiple Modelling & Development Projects

A Application Interface Model ultimately results in Java code, which is organized as a Java Project (Maven projects). For very simple models, it is possible to have a single project that acts as both a Modelling and a Java Project. In most other cases, it is best to separate the content into different projects. This becomes necessary if the toolchain contains a number of Applications, each of which needs to be its own Java project. (For a simple project with a single Application Interface, it is possible to combine both the models and resulting Java code into a single project.)

A typical organization is as follows:

toolchain-model-project – A Toolchain Modelling Project, which includes a model of Application1 Interface and Application2 Interface.
application1-interface-project – A Java Project implementing the Application1 Interface model, as generated from the toolchain-model-project.
application2-interface-project – A Java Project implementing the Application2 Interface model – as generated from the toolchain-model-project.

7-4 Structuring Information Models across multiple Modelling & Development Projects

An complete information model contains a number of domain specifications. You may choose to organize these domain specifications into any number of modeling files, managed in any number of Modelling Projects.
One guiding principle is to separate domain specifications that have different lifecycles into different modelling projects, with one modelling file per project. The simplest approach (exemplified here) is to define a single modelling file, in a single modelling project for all your Domain Specifications.

In addition, an information model ultimately results in Java code, which is also organized as Java Project(s). You can arbitrarily choose to generate the different domain specifications into any set of Java Projects (See 3-7 – Configure the generation settings of a specific Domain Specification). The simplest approach (exemplified here) is to generate each Domain Specification into a separate Java Project. This provides the best flexibility to manage the lifecycles of each Domain Specification independently.

A recommended organization for your projects is as follows:

information-model-project – An Information Modelling Project, which includes a number of related Domain Specifications.
domain1-project – A Java Project, containing the Java classes corresponding to the domain1 specification, as generated from the information-model-project.
domain2-project – A Java Project, containing the Java classes corresponding to the domain1 specification, as generated from the information-model-project.

7-5 Support for version management

By managing Modelling Projects and Java Projects under a Git repository, all contained model files are version controlled using Git’s built-in versioning (& branching) capabilities

7-6 Support for access control

By managing Modelling Projects and Java Projects under a Git repository, access control can be configured using Git’s built-in access control capabilities. For example, Access Permissions on GitHub are used to control who has the ability to perform a specific action (such as a Pull Request).
User accounts of the chosen Git solution are those used to authenticate/authorise access to the LynxDesigner models.

7-7 Support for reviewing and approval of models

By managing Modelling Projects and Java Projects under a Git repository, changes to models can be reviewed, approved and released with the help of Git’s full built-in capabilities to create branches, make Pull-Requests, approve branch merging, etc.