Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

Difference between revisions of "Lyo/ToolchainModellingAndCodeGenerationWorkshop"

< Lyo
(Setup OSLC4J projects)
Line 1: Line 1:
 
= Introduction =
 
= 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 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):
 
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 [http://open-services.net/bin/view/Main/OslcCoreSpecification OSLC Core Specification] and the [http://open-services.net/bin/view/Main/OSLCCoreSpecAppendixA#oslc_ResourceShape_Resource Resource Shape constraint language].
 
* '''Domain Specification View''' – To define the types of resources, their properties and relationships, according the [http://open-services.net/bin/view/Main/OslcCoreSpecification OSLC Core Specification] and the [http://open-services.net/bin/view/Main/OSLCCoreSpecAppendixA#oslc_ResourceShape_Resource 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.
 
* '''Toolchain View''' – To allocate resources to tools. For each tool, the set of resources being exposes and/or consumed are defined.
Line 9: Line 11:
 
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: [http://open-services.net/linked-data-and-oslc-tutorial-2015-update/ Linked Data and OSLC Tutorial (2015 Update)]
 
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: [http://open-services.net/linked-data-and-oslc-tutorial-2015-update/ 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.  
+
This tutorial takes you through the steps from creating the initial modelling project to the code generation and final execution of the tool adaptors.
# In [[Lyo/ToolchainModellingAndCodeGenerationWorkshop#Eclipse_Setup | Eclipse Setup]], you will perform the necessary installation and configuration of your Eclipse environment.
+
 
# In [[Lyo/ToolchainModellingAndCodeGenerationWorkshop#Create_a_Toolchain_Modelling_Project | Create a Toolchain Modelling Project]], you will create an empty modelling project, configured to start modelling your toolchain.
+
# In [[Lyo/ToolchainModellingAndCodeGenerationWorkshop#Eclipse_Setup|Eclipse Setup]], you will perform the necessary installation and configuration of your Eclipse environment.
# In [[Lyo/ToolchainModellingAndCodeGenerationWorkshop#Model_the_Toolchain | Model the Toolchain]] , you will graphically specify your toolchain and adaptor functionality, from which almost complete code will be generated.
+
# In [[Lyo/ToolchainModellingAndCodeGenerationWorkshop#Create_a_Toolchain_Modelling_Project|Create a Toolchain Modelling Project]], you will create an empty modelling project, configured to start modelling your toolchain.
# In [[Lyo/ToolchainModellingAndCodeGenerationWorkshop#Generate_OSLC4J_Java_code | Generate OSLC4J Java code]], you will perform the steps to generate the necessary OSLC4J code.
+
# In [[Lyo/ToolchainModellingAndCodeGenerationWorkshop#Model_the_Toolchain|Model the Toolchain]] , you will graphically specify your toolchain and adaptor functionality, from which almost complete code will be generated.
# In [[Lyo/ToolchainModellingAndCodeGenerationWorkshop#Finalize_Development_of_each_Adaptor | Finalize Development of each Adaptor]], you perform the final implementation steps to make the adaptors ready to run.
+
# In [[Lyo/ToolchainModellingAndCodeGenerationWorkshop#Generate_OSLC4J_Java_code|Generate OSLC4J Java code]], you will perform the steps to generate the necessary OSLC4J code.
 +
# In [[Lyo/ToolchainModellingAndCodeGenerationWorkshop#Finalize_Development_of_each_Adaptor|Finalize Development of each Adaptor]], you perform the final implementation steps to make the adaptors ready to run.
 +
 
 +
'''''Note:'''
  
'''''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 [https://bugs.eclipse.org/bugs/enter_bug.cgi?product=Lyo Bugzilla]''
 
* 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 [https://bugs.eclipse.org/bugs/enter_bug.cgi?product=Lyo Bugzilla]''
 
* If you wish to cite this modelling prototype in scientific papers and communications, please reference:
 
* 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, [https://www.thinkmind.org/index.php?view=article&articleid=alldata_2016_3_10_90030 "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
+
** Jad El-khoury, Didem Gurdur, Frederic Loiret, Martin Törngren, Da Zhang, Mattias Nyberg, [https://www.thinkmind.org/index.php?view=article&articleid=alldata_2016_3_10_90030 &quot;Modelling Support for a Linked Data Approach to Tool Interoperability&quot;], 2nd International Conference on Big Data, Small Data, Linked Data and Open Data - ALLDATA, Portugal, 2016
** El-Khoury, Jad. [http://www.sciencedirect.com/science/article/pii/S2352711016300267 "Lyo Code Generator: A Model-based Code Generator for the Development of OSLC-compliant Tool Interfaces."] SoftwareX, 2016.
+
** El-Khoury, Jad. [http://www.sciencedirect.com/science/article/pii/S2352711016300267 &quot;Lyo Code Generator: A Model-based Code Generator for the Development of OSLC-compliant Tool Interfaces.&quot;] SoftwareX, 2016.
  
= Sample Modelling Project =
+
= Eclipse Setup =
  
As a complement when following the instructions below, this [[Media:Lyo-SampleToolChainModel.zip| sample Toolchain modelling project]] contains a basic but complete model that can be used as a starting point and/or a reference.
+
First, make sure your Eclipse environment is setup as expected for general OSLC4J development, as instructed in [[Lyo/General_Setup_for_OSLC4J_Development|General Setup for OSLC4J development]]
  
= Eclipse Setup =
+
Then, make sure your environment is setup for OSLC4J modelling and code generation as instructed on [[Lyo/modelling_and_generation/installation|Modelling and Generation Installation]]
Make sure your environment is setup for OSLC4J modelling and code generation as instructed on [[Lyo/modelling_and_generation/installation | Modelling and Generation Installation]]
+
  
 
= Create a Toolchain Modelling Project =
 
= 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.
 
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.
 +
 +
== Sample Modelling Project ==
 +
 +
As a complement when following the instructions below, this [Media:Lyo-SampleToolChainModel.zip sample Toolchain modelling project] contains a basic but complete model that can be used as a starting point and/or a reference.
 +
 +
== Projects layout ==
 +
 +
You will be modelling a toolchain that can potentially consist of a number of OSLC adaptors, each of which is itself an Eclipse project. A recommended structure of your projects is the following:
 +
 +
<pre>toolchain-project/
 +
    toolchain-project-model/
 +
    adaptor1-project-webapp/
 +
    adaptor2-project-webapp/</pre>
 +
Where
 +
 +
* The top <code>toolchain-project</code> directory may be a git repository root
 +
* <code>toolchain-project-model</code> is the Lyo Toolchain Modelling project
 +
* each <code>adaptor-project-webapp</code> contains each of the adaptors generated from the definitions in <code>toolchain-project-model</code>.
 +
 +
== Create modelling project ==
  
 
# In your Eclipse workspace, switch to the '''Sirius''' perspective
 
# In your Eclipse workspace, switch to the '''Sirius''' perspective
 
# Create a new modelling project
 
# Create a new modelling project
## Select '''New > Modelling Project'''
+
## Select '''New &gt; Modelling Project'''
 
## Choose a project name
 
## Choose a project name
 
# Create a toolchain model
 
# Create a toolchain model
## Right click the newly created project, and select '''New > other…'''
+
## Right click the newly created project, and select '''New &gt; other…'''
 
## In the Wizards window, search and select ''Toolchain Model'', then press '''Next'''
 
## In the Wizards window, search and select ''Toolchain Model'', then press '''Next'''
 
## choose a suitable file name (say ''My.toolchain'') for the toolchain model, then press '''Next'''
 
## choose a suitable file name (say ''My.toolchain'') for the toolchain model, then press '''Next'''
Line 46: Line 70:
 
## Press '''OK'''
 
## Press '''OK'''
 
# Navigate to the modelling diagrams
 
# Navigate to the modelling diagrams
## Expand the ''My.toolchain'' file in the Model Explorer until the ''SpecificationDiagram'' & ''ToolchainDiagram'' entries are visible.
+
## Expand the ''My.toolchain'' file in the Model Explorer until the ''SpecificationDiagram'' &amp; ''ToolchainDiagram'' entries are visible.
 
## Do not double-click on the file. Instead, press the triangle/arrow to the left of the file entry.
 
## Do not double-click on the file. Instead, press the triangle/arrow to the left of the file entry.
 
## You can now open and edit any of these views, by double-clicking on the desired diagram.
 
## You can now open and edit any of these views, by double-clicking on the desired diagram.
# Navigate the toolchain model  
+
# Navigate the toolchain model
## 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.  
+
## 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.
 
## It is recommended that you place the window on the left, along with the '''Model Explorer'''.
 
## It is recommended that you place the window on the left, along with the '''Model Explorer'''.
  
 
= Model the Toolchain =
 
= 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.  
+
 
 +
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.
 
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.
  
 
== Modelling Overview ==
 
== Modelling Overview ==
 +
 
The figure below presents the overall meta-model underlying a toolchain model (and its corresponding three viewpoints). The model consists of 3 main parts:
 
The figure below presents the overall meta-model underlying a toolchain model (and its corresponding three viewpoints). The model consists of 3 main parts:
 +
 
* '''Domain Specification''' - Modelling the OSLC domain specification(s) to be exposed and/or consumed by the adaptor, as defined in [http://open-services.net/bin/view/Main/OslcCoreSpecification?sortcol=table;up=#Service_Provider_Resources the OSLC Core Specification].
 
* '''Domain Specification''' - Modelling the OSLC domain specification(s) to be exposed and/or consumed by the adaptor, as defined in [http://open-services.net/bin/view/Main/OslcCoreSpecification?sortcol=table;up=#Service_Provider_Resources the OSLC Core Specification].
 
* '''Server''' - modelling the OSLC resources - and their corresponding services - to be exposed by the adaptor.
 
* '''Server''' - modelling the OSLC resources - and their corresponding services - to be exposed by the adaptor.
 
* '''Client''' - modelling the interactions - as a client - that the adaptor might have with other OSLC servers.
 
* '''Client''' - modelling the interactions - as a client - that the adaptor might have with other OSLC servers.
  
[[File:OSLCToolAdaptorMetalModel.png | 900px]]
+
[ 900px](OSLCToolAdaptorMetalModel.png &quot; 900px&quot;)
  
 
== General Modelling Instructions ==
 
== General Modelling Instructions ==
 +
 
The toolchain modelling prototype is based on Sirius. The reader is referred to the [http://www.eclipse.org/sirius/doc/user/Sirius%20User%20Manual.html Sirius User Manual] for detailed instructions on how to use Sirius-based modellers. Below is a very short extract (Refer to diagram below):
 
The toolchain modelling prototype is based on Sirius. The reader is referred to the [http://www.eclipse.org/sirius/doc/user/Sirius%20User%20Manual.html 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:
 
* A diagram editor is divided in three areas:
** The '''main graphical area''', which shows the elements and supports direct interaction with them;  
+
** 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 '''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.  
+
** 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  
+
* One interacts with the diagram and its elements through
** The '''Properties''' window (Select the menu '''Windows > ShowView > Properties''' to load the window)
+
** The '''Properties''' window (Select the menu '''Windows &gt; ShowView &gt; Properties''' to load the window)
 
** Contextual menus available on the graphical elements.
 
** 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.
 
* 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.
 
** 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 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 –  
+
** To '''create an Edge''' between Elements –
 
*** Select the edge operation from the tools pallet
 
*** Select the edge operation from the tools pallet
 
*** Select the desired source element in the diagram.
 
*** Select the desired source element in the diagram.
Line 86: Line 115:
  
 
== Domain Specification View ==
 
== 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''.
 
  
[[File:LyoToolchainModel-SpecificationDiagram.png|800px|An example domain specification diagram]]
+
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''.
  
# Using the '''tools pallet''' (located on the right), create any number of '''Domain Specifications'''.  
+
[[File:LyoToolchainModel-SpecificationDiagram.png|frame|none|800px|alt=An example domain specification diagram|caption An example domain specification diagram]]
 +
 
 +
# 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'' – as desired.
 
# For each such '''Domain Specification''', set the domain properties - ''Name'', ''Namespace Prefix'' and ''Namespace URI'' – as desired.
 
## 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''.
 
## 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''.
Line 108: Line 138:
  
 
== Toolchain View ==
 
== 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.
 
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.
  
[[File:LyoToolchainModel-ToolchainDiagram.png|800px|An example toolchain diagram]]
+
[[File:LyoToolchainModel-ToolchainDiagram.png|frame|none|800px|alt=An example toolchain diagram|caption An example toolchain diagram]]
  
# 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:
+
<ol style="list-style-type: decimal;">
## ''name'': the name of your adaptor
+
<li>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:
## ''java Class Base Namespace'': the name of the base Java root package from which the code of your adaptor will be generated.
+
<ol style="list-style-type: decimal;">
## ''Java Files Base Path'': The path where java files will be generated. (for example, ''/src/'')
+
<li>''name'': the name of your adaptor</li>
## ''Javascript Files Base Path'': The path where javascript files will be generated. (for example, ''/WebContent'')
+
<li>''java Class Base Namespace'': the name of the base Java root package from which the code of your adaptor will be generated.</li>
## ''Jsp Files Base Path'': The path where the Jsp files will be generated. (for example, ''/WebContent'')
+
<li>''Java Files Base Path'': The path where java files will be generated. (for example, ''/src/'')</li>
#* '''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/''
+
<li>''Javascript Files Base Path'': The path where javascript files will be generated. (for example, ''/WebContent'')</li>
# For each '''Adaptor Interface''', use the '''AddManagedResource''' & '''AddConsumedResource''' tools to define the resources that the interface manages or consumes respectively.
+
<li>''Jsp Files Base Path'': The path where the Jsp files will be generated. (for example, ''/WebContent'')</li></ol>
 +
 
 +
<ul>
 +
<li>'''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/''</li></ul>
 +
</li>
 +
<li>For each '''Adaptor Interface''', use the '''AddManagedResource''' &amp; '''AddConsumedResource''' tools to define the resources that the interface manages or consumes respectively.</li></ol>
  
 
== Adapter Interface View ==
 
== 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.
 
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.
  
[[File:LyoToolchainModel-AdaptorInterfaceDiagram.png|800px|An example adaptor interface diagram]]
+
[[File:LyoToolchainModel-AdaptorInterfaceDiagram.png|frame|none|800px|alt=An example adaptor interface diagram|caption An example adaptor interface diagram]]
  
 
# In the Toolchain view, double-click on the '''Adaptor Interface''' to open its internal design view.
 
# In the Toolchain view, double-click on the '''Adaptor Interface''' to open its internal design view.
Line 131: Line 168:
 
## Set the properties for each of these elements as desired.
 
## Set the properties for each of these elements as desired.
 
## Note that the model currently supports the definition of one (and only one) ServiceProviderCatalog per adaptor.
 
## Note that the model currently supports the definition of one (and only one) ServiceProviderCatalog per adaptor.
# Use the tools pallet to create any additional '''ServiceProviders'''. Such elements need to be directly associated with an existing '''ServiceProviderCatalog''' element in the diagram.  
+
# Use the tools pallet to create any additional '''ServiceProviders'''. Such elements need to be directly associated with an existing '''ServiceProviderCatalog''' element in the diagram.
## From the Pallet, select the '''CreateServiceProvider''' tool  
+
## From the Pallet, select the '''CreateServiceProvider''' tool
 
## In the diagram, select the '''ServiceProviderCatalog''' to which this '''ServiceProvider''' belongs.
 
## In the diagram, select the '''ServiceProviderCatalog''' to which this '''ServiceProvider''' belongs.
 
## For the newly created '''ServiceProvider''', fill-in the '''ServiceProvider''' properties (''title'', ''description'') as defined according to OSLC.
 
## For the newly created '''ServiceProvider''', fill-in the '''ServiceProvider''' properties (''title'', ''description'') as defined according to OSLC.
## (optional) To control the relative URLs used in the ServiceProvider web service, specify the following optional properties:  
+
## (optional) To control the relative URLs used in the ServiceProvider web service, specify the following optional properties:
 
### ''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'').
 
### ''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'').
 
### ''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}''.
 
### ''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}''.
# 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''':  
+
# 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''':
## From the Pallet, select the '''CreateService''' tool  
+
## From the Pallet, select the '''CreateService''' tool
 
## In the diagram, select the '''ServiceProvider''' to which this Service element belongs.
 
## In the diagram, select the '''ServiceProvider''' to which this Service element belongs.
 
# For each of the '''Dialogs/CreationFactories/QueryCapabilities''', define the '''Resources''' being managed
 
# For each of the '''Dialogs/CreationFactories/QueryCapabilities''', define the '''Resources''' being managed
## From the Pallet, select the '''AddManagedResource''' tool  
+
## From the Pallet, select the '''AddManagedResource''' tool
 
## In the diagram, select the '''Dialog/CreationFactory/QueryCapability''' that manages the Resource.
 
## In the diagram, select the '''Dialog/CreationFactory/QueryCapability''' that manages the Resource.
# (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:  
+
# (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:
 
## ''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'').
 
## ''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'').
 
## ''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.
 
## ''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.
 
# Define the '''Resources''' that the adaptor consumes
 
# Define the '''Resources''' that the adaptor consumes
## From the Pallet, select the '''AddComsumedResource''' tool  
+
## From the Pallet, select the '''AddComsumedResource''' tool
 
## In the diagram, select the '''RequiredAdaptor''' element.
 
## In the diagram, select the '''RequiredAdaptor''' element.
 
# View the Toolchain view and note that any added Provided/Consumed resources are now also represented as ports in the toolchain view.
 
# 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 =
 
= 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:
 
  
[[File:Lyo-ToolchainModelValidation.png|800px| Toolchain Model Validation]]
+
Once the tool model is defined, validate it to ensure all required properties are defined as expected before code can be generated:
 +
 
 +
[ Toolchain Model Validation](Lyo-ToolchainModelValidation.png &quot; Toolchain Model Validation&quot;){width=&quot;800&quot;}
  
 
# In the '''ModelExplorer''', double-click on the toolchain model (''My.toolchain'') entry, in order to open the toolchain model.
 
# In the '''ModelExplorer''', double-click on the toolchain model (''My.toolchain'') entry, in order to open the toolchain model.
# Select the menu item '''Toolchain Editor > Validate'''
+
# Select the menu item '''Toolchain Editor &gt; Validate'''
 
# If you receive ''Valiation Problems'', press '''Details''' to read the error details, and correct your model accordingly.
 
# If you receive ''Valiation Problems'', press '''Details''' to read the error details, and correct your model accordingly.
 
# 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.
 
# 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.
Line 164: Line 202:
  
 
= Setup OSLC4J projects =
 
= Setup OSLC4J projects =
 +
 
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.
 
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.
  
For each of the Adaptor Interfaces in the model, create and setup an Eclipse OSLC4J project as instructed under [[Lyo/creating_OSLC4J_project#Setup_an_OSLC4J_project | Setup an OSLC4J project]].
+
For each of the Adaptor Interfaces in the model, create and setup an Eclipse OSLC4J project as instructed under [[Lyo/creating_OSLC4J_project|Setup an OSLC4J project]].
Alternatively, simply download and modify the [[Lyo/creating_OSLC4J_project#Sample_Project | Sample Project]].
+
  
 
These projects will then be populated with the generated code needed.
 
These projects will then be populated with the generated code needed.
  
'''Note:''' Make sure each project is configured to match the Adaptor Interface project properties defined under [[Lyo/ToolchainModellingAndCodeGenerationWorkshop#Toolchain_View | Toolchain View]]
+
'''Note:''' Make sure each project is configured to match the Adaptor Interface project properties defined under [[Lyo/ToolchainModellingAndCodeGenerationWorkshop#Toolchain_View|Toolchain View]]
  
 
= Generate OSLC4J Java code =
 
= 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'''
+
Once the toolchain model is defined and validated, you can generate the corresponding code for each adaptor through the following simple step:
  
'''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.
+
<code>Right-click on the toolchain model (</code>''<code>My.toolchain</code>''<code>), and select </code>'''<code>Acceleo</code> <code>Model</code> <code>to</code> <code>Text</code> <code>&gt;</code> <code>Generate</code> <code>CodeGenerator</code>'''
  
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.  
+
'''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.
  
 
= Browsing the generated code =
 
= Browsing the generated code =
 +
 
Besides the '''AdaptorManager''' class (see next section), 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.
 
Besides the '''AdaptorManager''' class (see next section), 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.
* To illustrate, open a class file in the package ''your.basepackage.name''.resources, and note the following placeholder:  
+
 
// Start of user code imports
+
* To illustrate, open a class file in the package ''your.basepackage.name''.resources, and note the following placeholder:
// End of user code
+
 
 +
<code>// Start of user code imports</code><br />
 +
<code>// End of user code</code>
 +
 
 
* Any code entered between these two lines of code is maintained across subsequent generations. In this example, the placeholder is intended for developer-specific imports, but any Java code can be inserted.
 
* Any code entered between these two lines of code is maintained across subsequent generations. In this example, the placeholder is intended for developer-specific imports, but any Java code can be inserted.
  
Line 195: Line 238:
 
#* Which resource classes are generated? Each resource for which an OSLC-service is defined; as well as - recursively - the resource extending such a resource, and the resources defined for any of its attributes. that is, all resources needed.
 
#* Which resource classes are generated? Each resource for which an OSLC-service is defined; as well as - recursively - the resource extending such a resource, and the resources defined for any of its attributes. that is, all resources needed.
 
# Package: '''''your.basepackage.name''.services'''
 
# Package: '''''your.basepackage.name''.services'''
#* this package contains the JAX-RS classes corresponding to the resource services defined in the model, as well as those for the ServiceProvider and ServiceProviderCatalog.  
+
#* this package contains the JAX-RS classes corresponding to the resource services defined in the model, as well as those for the ServiceProvider and ServiceProviderCatalog.
#* 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 adaptor 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 adaptor model.
 
#* Each JAX-RS class contains methods to respond to both HTML and RDF/XML requests.
 
#* Each JAX-RS class contains methods to respond to both HTML and RDF/XML requests.
 
# Package: '''''your.basepackage.name''.servlet'''
 
# Package: '''''your.basepackage.name''.servlet'''
 
#* Contains necessary classes for the project such as ServiceProviderFactory, ServletListener, etc.
 
#* Contains necessary classes for the project such as ServiceProviderFactory, ServletListener, etc.
 
# Package: '''''your.basepackage.name''.clients'''
 
# Package: '''''your.basepackage.name''.clients'''
#* for each required adaptor, a corresponding Java class is defined.  
+
#* for each required adaptor, a corresponding Java class is defined.
 
#* Currently, the class simply provides a GET method for each resource provided by the required server. This class is a starting point to explore the remaining functionality provided by the OslcClient class, and its methods will be expanded in the future.
 
#* Currently, the class simply provides a GET method for each resource provided by the required server. This class is a starting point to explore the remaining functionality provided by the OslcClient class, and its methods will be expanded in the future.
#Package: '''''your.basepackage.name'''''
+
# Package: '''''your.basepackage.name'''''
 
#* The '''AdaptorManager''' class contains the set of methods that will ultimately communicate with the source tool to access its internal data, and eventually expose information as OSLC resources.
 
#* The '''AdaptorManager''' class contains the set of methods that will ultimately communicate with the source tool to access its internal data, and eventually expose information as OSLC resources.
 
#* Only skeletons of the methods are generated. it remains the task of the developer to manual code these methods, as detailed in the next section.
 
#* Only skeletons of the methods are generated. it remains the task of the developer to manual code these methods, as detailed in the next section.
Line 215: Line 258:
  
 
= Fill in the internal implementation of each adaptor =
 
= Fill in the internal implementation of each adaptor =
 +
 
The manual code the developer needs to implement is concentrated in a single class - the '''AdaptorManager''' class (in the ''your.basepackage.name'' package). The methods that need to be provided are:
 
The manual code the developer needs to implement is concentrated in a single class - the '''AdaptorManager''' class (in the ''your.basepackage.name'' package). The methods that need to be provided are:
* '''contextInitializeServletListener''' & '''contextDestroyServletListener''' - to implement any application initialisation and termination activities such as establishing a connection to a database.
+
 
 +
* '''contextInitializeServletListener''' &amp; '''contextDestroyServletListener''' - to implement any application initialisation and termination activities such as establishing a connection to a database.
 
* '''getServiceProviderInfos''' - returns the set of ServiceProviders
 
* '''getServiceProviderInfos''' - returns the set of ServiceProviders
 
* for each serviced resource, methods to get, create, search and query such resources.
 
* for each serviced resource, methods to get, create, search and query such resources.
  
 
= Run the adaptor =
 
= Run the adaptor =
 +
 
Once the manual code is completed, You are now ready to run an adaptor.
 
Once the manual code is completed, You are now ready to run an adaptor.
# Select the menu '''Run-->Run Configurations ...'''
+
 
 +
# Select the menu '''Run--&gt;Run Configurations ...'''
 
# Select the newly created configuration
 
# Select the newly created configuration
 
# Click '''Run'''
 
# Click '''Run'''
 
# You can now browse and debug your adaptor through the generated HTML pages starting with http://localhost:8080/YourAdaptor/services/catalog/singleton
 
# You can now browse and debug your adaptor through the generated HTML pages starting with http://localhost:8080/YourAdaptor/services/catalog/singleton
 
#* You need to at least implement the getServiceProviderInfos method and some of resource C.R.U.D. methods first.
 
#* You need to at least implement the getServiceProviderInfos method and some of resource C.R.U.D. methods first.

Revision as of 04:44, 26 April 2017

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:

Eclipse Setup

First, make sure your Eclipse environment is setup as expected for general OSLC4J development, as instructed in General Setup for OSLC4J development

Then, make sure your environment is setup for OSLC4J modelling and code generation as instructed on Modelling and Generation Installation

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.

Sample Modelling Project

As a complement when following the instructions below, this [Media:Lyo-SampleToolChainModel.zip sample Toolchain modelling project] contains a basic but complete model that can be used as a starting point and/or a reference.

Projects layout

You will be modelling a toolchain that can potentially consist of a number of OSLC adaptors, each of which is itself an Eclipse project. A recommended structure of your projects is the following:

toolchain-project/
    toolchain-project-model/
    adaptor1-project-webapp/
    adaptor2-project-webapp/

Where

  • The top toolchain-project directory may be a git repository root
  • toolchain-project-model is the Lyo Toolchain Modelling project
  • each adaptor-project-webapp contains each of the adaptors generated from the definitions in toolchain-project-model.

Create modelling project

  1. In your Eclipse workspace, switch to the Sirius perspective
  2. Create a new modelling project
    1. Select New > Modelling Project
    2. Choose a project name
  3. 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
  4. Right-click the project again, and select Viewpoints selection
    1. select ToolChainViewpoint
    2. Press OK
  5. 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.
  6. 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.

Modelling Overview

The figure below presents the overall meta-model underlying a toolchain model (and its corresponding three viewpoints). The model consists of 3 main parts:

  • Domain Specification - Modelling the OSLC domain specification(s) to be exposed and/or consumed by the adaptor, as defined in the OSLC Core Specification.
  • Server - modelling the OSLC resources - and their corresponding services - to be exposed by the adaptor.
  • Client - modelling the interactions - as a client - that the adaptor might have with other OSLC servers.

[ 900px](OSLCToolAdaptorMetalModel.png " 900px")

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
caption 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 Resource elements.
    1. Select the operation CreateResource from the tools pallet, and then select the containing Domain Specification in the diagram.
    2. Set the required attributes for each Resource (such as its name) in the Properties window.
    3. Once created, a Resource can be moved to another Domain by a simple drag-and-drop action.
  4. Inside each Domain Specification, use the tools pallet to create any number of (a) LiteralProperty, (b) ReferenceProperty, and (c) LocalReferenceProperty elements.
    1. Select the desired operation from the tools pallet, and then select the Properties list 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.
    3. 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.
  5. To relate a Property to a Resource, drag-and-drop the property from the Properties list 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 Resource and the Resource the ReferenceProperty refers to.
    • Note: A Resource can refer to Properties (Literal or Reference) from any other Domain Specification.

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
caption 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
caption 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:

[ Toolchain Model Validation](Lyo-ToolchainModelValidation.png " Toolchain Model Validation"){width="800"}

  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 you receive Valiation Problems, press Details to read the error details, and correct your model accordingly.
  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.
    • Note: The context menu contains two Validate menu items. The first is specific to the Toochain Editor, while the second is for general EMF modelling. You are to select to first entry.

Setup OSLC4J projects

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.

For each of the Adaptor Interfaces in the model, create and setup an Eclipse OSLC4J project as instructed under Setup an OSLC4J project.

These projects will then be populated with the generated code needed.

Note: Make sure each project is configured to match the Adaptor Interface project properties defined under Toolchain View

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.

Browsing the generated code

Besides the AdaptorManager class (see next section), 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.

  • To illustrate, open a class file in the package your.basepackage.name.resources, and note the following placeholder:

// Start of user code imports
// End of user code

  • Any code entered between these two lines of code is maintained across subsequent generations. In this example, the placeholder is intended for developer-specific imports, but any Java code can be inserted.

The following Java classes are generated based on the adaptor specification model:

  1. Package: your.basepackage.name.resources
    • for each OSLC-resource of relevance to your project, a corresponding Java class is defined. The class includes the appropriate OSLC annotations, instance attributes, getters, setters, etc.
    • Which resource classes are generated? Each resource for which an OSLC-service is defined; as well as - recursively - the resource extending such a resource, and the resources defined for any of its attributes. that is, all resources needed.
  2. Package: your.basepackage.name.services
    • this package contains the JAX-RS classes corresponding to the resource services defined in the model, as well as those for the ServiceProvider and ServiceProviderCatalog.
    • 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 adaptor model.
    • Each JAX-RS class contains methods to respond to both HTML and RDF/XML requests.
  3. Package: your.basepackage.name.servlet
    • Contains necessary classes for the project such as ServiceProviderFactory, ServletListener, etc.
  4. Package: your.basepackage.name.clients
    • for each required adaptor, a corresponding Java class is defined.
    • Currently, the class simply provides a GET method for each resource provided by the required server. This class is a starting point to explore the remaining functionality provided by the OslcClient class, and its methods will be expanded in the future.
  5. Package: your.basepackage.name
    • The AdaptorManager class contains the set of methods that will ultimately communicate with the source tool to access its internal data, and eventually expose information as OSLC resources.
    • Only skeletons of the methods are generated. it remains the task of the developer to manual code these methods, as detailed in the next section.
  6. Jsp pages are also generated to handle HTML requests, in the folder webcontent/your/base/package/name. These pages are very useful for debugging purposes:
    • resource presentations
    • query results
    • creation dialogs
    • selection Dialogs
    • ServiceProvider presentations
    • ServiceProviderCatalog presentations

Fill in the internal implementation of each adaptor

The manual code the developer needs to implement is concentrated in a single class - the AdaptorManager class (in the your.basepackage.name package). The methods that need to be provided are:

  • contextInitializeServletListener & contextDestroyServletListener - to implement any application initialisation and termination activities such as establishing a connection to a database.
  • getServiceProviderInfos - returns the set of ServiceProviders
  • for each serviced resource, methods to get, create, search and query such resources.

Run the adaptor

Once the manual code is completed, You are now ready to run an adaptor.

  1. Select the menu Run-->Run Configurations ...
  2. Select the newly created configuration
  3. Click Run
  4. You can now browse and debug your adaptor through the generated HTML pages starting with http://localhost:8080/YourAdaptor/services/catalog/singleton
    • You need to at least implement the getServiceProviderInfos method and some of resource C.R.U.D. methods first.

Back to the top