Skip to main content
Jump to: navigation, search

Difference between revisions of "Lyo/ToolchainModellingAndCodeGenerationWorkshop"

< Lyo
(Add Acceleo dependency)
m (clarify Sirius dependency)
Line 33: Line 33:
 
# Install the following additional Eclipse packages
 
# Install the following additional Eclipse packages
 
## Acceleo
 
## Acceleo
## Sirius
+
## Sirius Specifier Environment
 
# Clone the OSLC Tools repository ''git://git.eclipse.org/gitroot/lyo/org.eclipse.lyo.tools.git ''
 
# Clone the OSLC Tools repository ''git://git.eclipse.org/gitroot/lyo/org.eclipse.lyo.tools.git ''
 
## Open the '''Git Repositories''' perspective in Eclipse  
 
## Open the '''Git Repositories''' perspective in Eclipse  

Revision as of 03:59, 17 May 2016

Introduction

The instructions below guide you through the steps of graphically modelling and automatically generating OSLC4J-compliant Java code. This supports the modelling of a complete toolchain (including interactions between OSLC servers and clients), as well as a single server and/or client.

The toolchain model is structured around the following three viewpoints (Illustrations and details can be found later in this workshop):

  • Domain Specification View – To define the types of resources, their properties and relationships, according the OSLC Core Specification and the Resource Shape constraint language.
  • Toolchain View – To allocate resources to tools. For each tool, the set of resources being exposes and/or consumed are defined.
  • Adapter Interface View – To design the internal details of the tool interface. Sufficient information is captured in this view, so that an almost complete interface code, which is compliant with the OSLC4J software development kit (SDK) can be generated.

Working with the model allows you to work at a higher level of abstraction, without needing to deal with all the technical details of the OSLC standard (such as Linked Data, RDF, etc.). However, a basic understanding of the Linked Data and OSLC concepts remains necessary in order to build a valid model. For an introduction to Linked Data and OSLC, the following resources on open-services.net can be recommended: Linked Data and OSLC Tutorial (2015 Update)

This tutorial takes you through the steps from creating the initial modelling project to the code generation and final execution of the tool adaptors.

  1. In Eclipse Setup, you will perform the necessary installation and configuration of your Eclipse environment.
  2. In Create a Toolchain Modelling Project, you will create an empty modelling project, configured to start modelling your toolchain.
  3. In Model the Toolchain , you will graphically specify your toolchain and adaptor functionality, from which almost complete code will be generated.
  4. In Generate OSLC4J Java code, you will perform the steps to generate the necessary OSLC4J code.
  5. In Finalize Development of each Adaptor, you perform the final implementation steps to make the adaptors ready to run.

Note:

  • The prototype presented here is under development and its features may change over time. Your feedback, suggestions for improvements and bug reports are appreciated. In particular, the graphical notation being used is experimental and certainly needs further improvements. Please send any questions or suggestions to the project mailinglist lyo-dev@eclipse.org, or report Bugs/features through Bugzilla
  • If you wish to cite this modelling prototype in scientific papers and communications, please reference
Jad El-khoury, Didem Gurdur, Frederic Loiret, Martin Törngren, Da Zhang, Mattias Nyberg, 
"Modelling Support for a Linked Data Approach to Tool Interoperability", 
2nd International Conference on Big Data, Small Data, Linked Data and Open Data - ALLDATA, Portugal, 2016

Sample Modelling Project

As a complement when following the instructions below, this sample Toolchain modelling project contains a basic but complete model that can be used as a starting point and/or a reference.

Eclipse Setup

This is a once-only installation and configuration of your Eclipse environment.

  1. Make sure your environment is setup appropriately for OSLC4J code generation as instructed on Eclipse Setup
  2. Install the following additional Eclipse packages
    1. Acceleo
    2. Sirius Specifier Environment
  3. Clone the OSLC Tools repository git://git.eclipse.org/gitroot/lyo/org.eclipse.lyo.tools.git
    1. Open the Git Repositories perspective in Eclipse
    2. Click the "Clone a Git Repository and add the clone to this view" icon.
    3. Set the URI to git://git.eclipse.org/gitroot/lyo/org.eclipse.lyo.tools.git
    4. The repository should now appear in your Git Repositories view
  4. Import the necessary Eclipse projects from the Git repository
    1. In the Git Repositories view, right click the org.eclipse.lyo.tools repository and select Import Projects
    2. Select the Import Existing Projects wizard and click next
    3. Select and import all identified 9 projects.
  5. Create a new "Eclipse Application" configuration called Tool Chain Design
    1. Select Run > Run Configurations …
    2. Select Eclipse Application
    3. Press New button to create a new configuration
    4. In the new dialog,
      1. Set name to Tool Chain Design
      2. In Arguments tab, change VM argument value to -Xms256m -Xmx768m -XX:MaxPermSize=256m (last option became obsolete in Java 8)

Create a Toolchain Modelling Project

We will here create an Eclipse project within which we create the actual model. The java code that will be ultimately generated will be produced in another set of projects.

  1. Run the Tool Chain Design configuration in order to run a new Eclipse workspace with the required plugins
    1. Select Run > Run Configurations …
    2. Select the Tool Chain Design configuration
    3. Press Run
  2. In the new Tool Chain Design Eclipse workspace, switch to the Sirius perspective
  3. Create a new modelling project for your toolchain
    1. Select New > Modelling Project
    2. Choose a project name
  4. Create a toolchain model
    1. Right click the newly created project, and select New > other…
    2. In the Wizards window, search and select Toolchain Model, then press Next
    3. choose a suitable file name (say My.toolchain) for the toolchain model, then press Next
    4. Set Model Object to Toolchain
    5. Press Finish
  5. Right-click the project again, and select Viewpoints selection
    1. select ToolChainViewpoint
    2. Press OK
  6. Navigate to the modelling diagrams
    1. Expand the My.toolchain file in the Model Explorer until the SpecificationDiagram & ToolchainDiagram entries are visible.
    2. Do not double-click on the file. Instead, press the triangle/arrow to the left of the file entry.
    3. You can now open and edit any of these views, by double-clicking on the desired diagram.
  7. Navigate the toolchain model
    1. To explore a tree structure of the toolchain model, double-click on the My.toolchain entry in the Model Explorer, to open the model in a new tree-structured diagram window.
    2. It is recommended that you place the window on the left, along with the Model Explorer.

Model the Toolchain

You are now ready to graphically specify the desired functionality of your toolchain and/or adaptor(s). From such a model, the Lyo code generator can then produce the bulk of the code necessary to realize the modelled functionality.

The instructions to define the three views that form the complete model are presented sequentially below. However, the views can be defined in any other order.

General Modelling Instructions

The toolchain modelling prototype is based on Sirius. The reader is referred to the Sirius User Manual for detailed instructions on how to use Sirius-based modellers. Below is a very short extract (Refer to diagram below):

  • A diagram editor is divided in three areas:
    • The main graphical area, which shows the elements and supports direct interaction with them;
    • The tool palette, which gives access to additional tools (for example creation tools to add new elements to the diagram);
    • The tab-bar at the top of the graphical area, which provides additional, more global operations.
  • One interacts with the diagram and its elements through
    • The Properties window (Select the menu Windows > ShowView > Properties to load the window)
    • Contextual menus available on the graphical elements.
  • One creates elements and edges in the main graphical area through one of the tools in the tool palette.
    • When a tool is selected and you move the mouse on the diagram, you will notice that the mouse cursor’s shape changes to indicate whether the action is allowed or not, at this particular location. For example some elements can only be created at the top-level of the diagram (in the diagram’s background itself), and not inside other elements.
    • 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. (No drag-drop)
    • To create an Edge between Elements –
      • Select the edge operation from the tools pallet
      • Select the desired source element in the diagram.
      • Select the desired destination element in the diagram.
      • An edge is now created between the source and destination.
  • The tab-bar contains the Filters Selection button, than provide alternatives to hide (or show) diagram elements.

Domain Specification View

In this view, you can define the set of domain specifications of relevance to the tool-chain, including the definition of Resources and Resource Properties that form each Domain Specification.

An example domain specification diagram

  1. Using the tools pallet (located on the right), create any number of Domain Specifications.
  2. For each such Domain Specification, set the domain properties - Name, Namespace Prefix and Namespace URI – as desired.
    1. For example, the OSLC RM domain specification defines the namespace URI of http://open-services.net/ns/rm# with a preferred namespace prefix of oslc_rm.
    2. Note: The Namespace Prefix property cannot be changed directly. Instead, you need to select the Namespace Prefix entry in the Model Explorer tree first.
  3. Inside each Domain Specification, use the tools pallet to create any number of (a) Resource, (b) LiteralProperty, (c) ReferenceProperty elements.
    1. Select the desired operation from the tools pallet, and then select the containing Domain Specification in the diagram.
    2. Set the required attributes for each Resource and/or Property (such as Occurs, description, range, …) in the Properties window.
    3. In particular, the default name of an element needs to be changed to something suitable.
    4. Once created, a LiteralProperty can be changed to a ReferenceProperty (or vice versa), by simply changing the Range and value type values of the property in the Properties window.
  4. To relate a LiteralProperty to a Resource, use the CreateResourceToProperty operation from the tools pallet to create an edge from a Resource to the desired LiteralProperty.
    1. An arrow is now created between the Resource and its properties, showing the Property name, as well as the end cardinality.
    2. The LiteralProperty is now also graphically listed inside the Resource element it is allocated to.
  5. To relate a ReferenceProperty to a Resource, use the CreateResourceToProperty operation from the tools pallet to create an edge from a Resource to the desired ReferenceProperty.
    1. An arrow is now created between the Resource and the Resource the ReferenceProperty refers to (and NOT the resource property itself).
  • Notes
    • A Resource can refer to Properties (Literal or Reference) from any other Domain Specification.
    • The user can choose between two alternative graphical notations to represent the relationship between a Resource and a LiteralProperty (The best alternative is still under development.) Use the Filters Selection button in the tab-bar to experiment with the following alternatives
      • Showing LiteralProperties embedded within the Resource (analogous to how attributes are defined within a Class in UML)
      • Showing an edge line between the two entities (similar to the notation used for ReferenceProperties)

Toolchain View

In this view, you define the set of tools (at least their OSLC interfaces) that form your toolchain. You can also model the interactions between the tool interfaces, by defining the resources each interface produces and/or consumes.

An example toolchain diagram

  1. Using the tools pallet, create any number of Adaptor Interface elements. For each such Adaptor Interface, it is important to set its properties appropriately, to ensure the code generation works as expected. The properties’ meaning is as follows:
    1. name: the name of your adaptor
    2. java Class Base Namespace: the name of the base Java root package from which the code of your adaptor will be generated.
    3. Java Files Base Path: The path where java files will be generated. (for example, /src/)
    4. Javascript Files Base Path: The path where javascript files will be generated. (for example, /WebContent)
    5. Jsp Files Base Path: The path where the Jsp files will be generated. (for example, /WebContent)
    • Note: the paths above are relative to your current location, which is the toolchain modelling project. You will most likely want to generate the code for each adaptor into a different and separate project. Indicate your target path for each adaptor relative to the modelling project location. For example, ../adaptor1Project/src/
  2. For each Adaptor Interface, use the AddManagedResource & AddConsumedResource tools to define the resources that the interface manages or consumes respectively.

Adapter Interface View

For each Adaptor Interface in the Toolchain view, you can now detail the internal design of the adaptor by defining its OSLC Service Providers, Services, etc. This information forms the basis for the code being generated.

An example adaptor interface diagram

  1. In the Toolchain view, double-click on the Adaptor Interface to open its internal design view.
    1. If the view is being opened for the first time, you will be prompted for a diagram name.
  2. By default, each Adaptor Interface is defined with one ServiceProviderCatalog, ServiceProvider, Service and BasicCapability.
    1. Set the properties for each of these elements as desired.
    2. Note that the model currently supports the definition of one (and only one) ServiceProviderCatalog per adaptor.
  3. Use the tools pallet to create any additional ServiceProviders. Such elements need to be directly associated with an existing ServiceProviderCatalog element in the diagram.
    1. From the Pallet, select the CreateServiceProvider tool
    2. In the diagram, select the ServiceProviderCatalog to which this ServiceProvider belongs.
    3. For the newly created ServiceProvider, fill-in the ServiceProvider properties (title, description) as defined according to OSLC.
    4. (optional) To control the relative URLs used in the ServiceProvider web service, specify the following optional properties:
      1. serviceNamespace - specifies the relative URL for the ServiceProvider JAX-RS Service. For example, 'projects will lead to the url http://localhost:8080/YourAdaptor/services/projects. The default is serviceProviders (leading to the default http://localhost:8080/YourAdaptor/services/serviceProviders).
      2. 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://localhost:8080/YourAdaptor/services/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}.
  4. For each ServiceProvider, create any structure of Services and their Dialogs/CreationFactories/QueryCapabilities. Such elements need to be directly associated with existing ServiceProvider element in the diagram. For example, to create a new Service:
    1. From the Pallet, select the CreateService tool
    2. In the diagram, select the ServiceProvider to which this Service element belongs.
  5. For each of the Dialogs/CreationFactories/QueryCapabilities, define the Resources being managed
    1. From the Pallet, select the AddManagedResource tool
    2. In the diagram, select the Dialog/CreationFactory/QueryCapability that manages the Resource.
  6. (optional) To control the relative URLs used in the web service for the C.R.U.D methods of a particular resource, create a BasicCapability with the following properties:
    1. serviceNamespace - specifies whether the relative URL of the resource web service should include the URL of its managing service provider (relativeToServiceProvider), or it should be standalone (independantOfServiceProvider).
    2. instanceID - specifies the relative URL of a single resource, including the parameter variables necessary to identify a specific resource. For example, {changeRequestId} leads to the url http://localhost:8080/YourAdaptor/services/changeRequests/1 mapping the value 1 to the changeRequestId parameter in the java code.
  7. Define the Resources that the adaptor consumes
    1. From the Pallet, select the AddComsumedResource tool
    2. In the diagram, select the RequiredAdaptor element.
  8. View the Toolchain view and note that any added Provided/Consumed resources are now also represented as ports in the toolchain view.

Validate the model

Once the tool model is defined, validate it to ensure all required properties are defined as expected before code can be generated.

  1. In the ModelExplorer, double-click on the toolchain model (My.toolchain) entry, in order to open the toolchain model.
  2. Select the menu item Toolchain Editor > Validate
  3. If any, deal with any error messages that appear.
  4. You can also validate any part of the complete model, but navigating down to the particular element in the model tree diagram, before selecting the validate menu.

Generate OSLC4J Java code

Once your model is complete and validated, you are ready to generate the Java code. But it is first necessary to setup the Eclipse projects for each of the adaptors.

Setup OSLC4J projects

For each of the Adaptor Interfaces in the model, follow the instructions from the Adaptor Code Generator Workshop to create and setup an Eclipse OSLC4J project with the necessary configurations to develop any OSLC4J adaptor. These projects will then be populated with the generated code needed.

Generate OSLC4J Java code

Once the toolchain model is defined and validated, you can generate the corresponding code for each adaptor through the following simple step:

Right-click on the toolchain model (My.toolchain), and select Acceleo Model to Text > Generate CodeGenerator

Note: The code generator supports an incremental development of the adaptor model. Any manual changes to the generated code (within designated placeholders) are maintained upon a subsequent change in the adaptor model, and resulting code re-generation.

Upon a successful code generation, all the necessary Java classes for complete ready-to-run OSLC4J projects are produced. The next section gives an overview of the generated code, before proceeding with an explanation of the necessary manual code to be provided.

Finalize Development of each Adaptor

For each adaptor, follow the remaining instructions from the Adaptor Code Generator Workshop to

  1. Get an overview of the generated code,
  2. Fill in the internal implementation of the adaptor, and
  3. finally, run the adaptor.

Back to the top