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/DomainSpecificationModelling"

< Lyo
(Replaced content with "This page has moved to Lyo Designer's new home under the [https://github.com/eclipse/lyo.designer/wiki/User-Manual-for-Domain-Specification-Modelling Eclipse Foundation's...")
Line 1: Line 1:
= Introduction =
+
This page has moved to Lyo Designer's new home under the [https://github.com/eclipse/lyo.designer/wiki/User-Manual-for-Domain-Specification-Modelling Eclipse Foundation's Github]
 
+
With Lyo Designer, you can graphically model your domain specifications according to the OSLC Core specification. A '''Domain Specification''' defines 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].
+
 
+
From such a model, you can produce a library of Java classes, with the appropriate Lyo OSLC4J annotations to reflect the defined OSLC Resources, and their properties. These classes can then be further used in the development of OSLC applications using the Lyo OSLC4J SDK.
+
 
+
A domains model can also be imported into a toolchain model, to model a complete toolchain, as well as a single server and/or client. (see [[Lyo/ToolchainModellingAndCodeGenerationWorkshop|Lyo's Toolchain Modelling Instructions]] for details).
+
 
+
== Bug Reporting ==
+
 
+
Please send any bug reports, 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]
+
 
+
= Eclipse Setup =
+
 
+
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]]
+
 
+
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]]
+
 
+
= Create a Modelling Project =
+
 
+
== Projects layout ==
+
 
+
You will need to create an Eclipse (modelling) project within which you will create the specification model. In this model, you will potentially define a number of domain specifications.
+
 
+
You may also choose to distribute the domain specifications into a number of different Java libraries, each of which is itself an Eclipse project.
+
 
+
So, a recommended structure of your projects is the following:
+
 
+
<pre>oslc-project/
+
    oslc-model-project/
+
    domain1-project/
+
    domain2-project/</pre>
+
Where
+
 
+
* The top <code>oslc-project</code> directory may be a git repository root
+
* <code>oslc-model-project</code> is the Lyo Designer modelling project, where your model is managed.
+
* each <code>domain-project</code> contains the java classes corresponding to one or more domain specifications, generated from the definitions in <code>oslc-model-project</code>.
+
 
+
== Create a Domain Specification Modelling Project ==
+
 
+
# In your Eclipse workspace, switch to the '''Modeling''' perspective
+
# Create a new modelling project
+
## Select '''New &gt; Modelling Project'''
+
## Choose a project name
+
# Create a Specification model
+
## Right click the newly created project, and select '''New &gt; other…'''
+
## In the Wizards window, navigate and select ''Lyo Designer &gt; OSLC Domain Model'', then press '''Next'''
+
## choose a suitable file name (say ''domain.xml'') for the model, then press '''Next'''
+
## Set '''Model Object''' to ''Specification''
+
## Press '''Finish'''
+
## Right-click the project again, and select '''Viewpoints selection'''
+
## select '''ToolChainViewpoint'''
+
## Press '''OK'''
+
# View the initial diagrams
+
## In the Model Explorer, by pressing the triangle/arrow to the left of the ''domain.xml'' file , expand the file structure until the ''SpecificationDiagram'' entry is visible.
+
##* ''Note:'' Do not double-click on the file. This will instead open the file in an xml editor.
+
## You can now open and edit any of these views, by double-clicking on the desired entry.
+
 
+
= Model OSLC Domain Specifications =
+
 
+
You are now ready to graphically specify the OSLC domain specifications.
+
 
+
For general instructions on Lyo Designer, the reader is referred to [[Lyo/ToolchainModellingAndCodeGenerationWorkshop#General_Modelling_Instructions|Lyo's Toolchain Modelling Instructions]].
+
 
+
In the ''SpecificationDiagram'', you can define a set of domain specifications, within which you define ''Resources'' and ''Resource Properties''.
+
 
+
[[File:LyoToolchainModel-SpecificationDiagram.png|center|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 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''.
+
## '''Note''': To set the ''Namespace Prefix'' property, right-click on the domain, and select the context menu entry '''OSLC Lyo Designer &gt; Set Domain Prefix'''.
+
# Inside each '''Domain Specification''', use the tools pallet to create any number of '''Resource''' elements.
+
## Select the operation '''CreateResource''' from the tools pallet, and then select the containing '''Domain Specification''' in the diagram.
+
## Set the required attributes for each '''Resource''' (such as its ''name'') in the '''Properties''' window.
+
## Once created, a '''Resource''' can be moved to another Domain by a simple drag-and-drop action.
+
# Inside each '''Domain Specification''', use the tools pallet to create any number of (a) '''LiteralProperty''', (b) '''ReferenceProperty''', and (c) '''LocalReferenceProperty''' elements.
+
## Select the desired operation from the tools pallet, and then select the '''Properties''' list within the desired '''Domain Specification''' in the diagram.
+
## Set the required attributes for each '''Property''' (such as ''Occurs'', ''description'', ''range'', …) in the '''Properties''' window.
+
## 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.
+
# 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'''.
+
 
+
= Handling Large Models =
+
 
+
To manage large models, Lyo Designer supports two model structuring techniques, which will be detailed in the following subsections:
+
 
+
* Creating multiple diagrams within the same model file
+
* Composing a model into multiple model files
+
 
+
== Common Domains ==
+
 
+
But first a sample model that can be used to illustrate the suggested techniques.
+
 
+
A model of the OSLC and other common domains is already available for reuse. To reuse these common specifications:
+
 
+
# Clone the https://git.eclipse.org/gitroot/lyo/org.eclipse.lyo.tools.git git repository
+
# Import the project ''org.eclipse.lyo.tools.domainmodels''.
+
#* This project models many of the OSLC domains across a number of diagrams.
+
# Navigate the model as any other Domain Specification model.
+
 
+
In the next subsections, you will learn how to import this model into other models for reuse.
+
 
+
== Creating multiple diagrams within the same model file ==
+
 
+
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 ''domainModel.xml'' 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 &gt; New SpecificationDiagram'''.
+
 
+
You can define your Domain Specifications in any of these diagrams. Note the following:
+
 
+
* A Diagram can contain any number of Domain Specifications.
+
* A Domain Specification can be viewed in 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) are reflected in all diagrams.
+
 
+
== Composing a model into multiple model files ==
+
 
+
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 SpecificationDiagram, you can now create relationships to the imported Domain Specifications (or their contained Resources and Resource Properties).
+
## Expand the imported Specification model (under the the ''Project Dependencies'' entry) until the Domain Specification entries are visible.
+
## You can drag-drop any Domain Specification into an existing SpecificationDiagram to visualize its content.
+
## Also, when selecting the Resource Properties of a Resource, you will notice that all imported Resource properties are available as well.
+
 
+
= Generate OSLC4J Java code =
+
 
+
Once the Specification model is defined, you can choose to generate the set of Java classes, with the appropriate Lyo OSLC4J annotations to reflect the defined OSLC Resources, and their properties. These classes can then be further used in the development of OSLC applications using the Lyo OSLC4J SDK.
+
 
+
You first need to create the necessary OSLC4J project(s), onto which the code will be generated. We here assume the following parameters, which you will need to adjust for your particular project:
+
 
+
* Project Name: ''domain-project''
+
* Base Package Name for Java Classes: ''com.domain.resources''
+
 
+
# Create the OSLC4J library project. For example using mvn:
+
#* '''mvn archetype:generate -DgroupId=domain-project-group -DartifactId=domain-project -DarchetypeArtifactId=maven-archetype-quickstart -DinteractiveMode=false'''
+
# Add the necessary maven dependencies by following the instructions under [[Lyo/creating_OSLC4J_project|Create an OSLC4J project]].
+
#* At the least the <code>oslc4j-core</code> dependency is necessary.
+
# Configure the Specification model's settings to generate code within the newly created OSLC4J project.
+
## Right-click inside the Specification Diagram (without selecting any Domain Specification) and select the context menu item '''OSLC Lyo Designer &gt; Set Java Generation Settings'''
+
## Enter a relative file path, to which the Java classes will be generated.
+
##* Relative to what? anything you desire. In the comming steps, you get to define the absolute path of the defined relative path.
+
##* '''Tips:''' the relative path can be the path ''within'' your OSLC4J project (such as ''domain-project/src/main/java''), while the absolute path (defined in next step) relates to the path up until the OSLC4J project.
+
## Enter the package name (''com.domain.resources'') of the Java classes to be generated.
+
# Generate the Java code.
+
## Right-click inside the Specification Diagram (without selecting any Domain Specification) and select the context menu item '''OSLC Lyo Designer &gt; Generate Specification Java Code'''
+
## You will now be prompted to enter the base path to which all relative generation paths relate.
+
##* '''NOTE:''' Alternatively, you can define this path through a &quot;generationPath&quot; property in a &quot;generator.properties&quot; file. The properties file is expected in the same location as the model file.
+
## Press '''OK'''
+
# Once successful, you will be prompted with a dialog that confirms generation completion.
+
 
+
== (Advanced) Define generation settings per Domain Specification ==
+
 
+
You can also generate OSLC Resources classes into multiple Java projects, by specifying generation settings for each Domain Specification in your model.
+
 
+
To configure a Domain Specification's generation settings:
+
 
+
# Right-click on a specific Domain Specification element and select the context menu item '''OSLC Lyo Designer &gt; Set Java Generation Settings'''
+
# Enter (a) relative file path (b) the package name of the Java classes to be generated.
+
 
+
The generation settings of a Domain Specification override those set for the overall Specification model.
+
 
+
'''Important to note''' that when related Java classes are distributed into different Java projects, it is necessary to set dependencies betweeen 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.
+
 
+
== Browsing the generated code ==
+
 
+
For each OSLC-resource in each of the Domain Specifications, a corresponding Java class is is produced. The class includes the appropriate OSLC annotations, instance attributes, getters, setters, etc.
+
 
+
The generated 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 model, and its resulting code.
+
 
+
To illustrate, open a class file, and note the following placeholder:
+
 
+
<pre>// Start of user code imports
+
// End of user code</pre>
+
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.
+

Revision as of 09:13, 9 June 2018

This page has moved to Lyo Designer's new home under the Eclipse Foundation's Github

Back to the top