|
|
| (30 intermediate revisions by 2 users not shown) |
| Line 1: |
Line 1: |
| − | = Introduction =
| + | #REDIRECT [[Lyo/ToolchainModellingAndCodeGenerationWorkshop | Graphical Toolchain Modelling and Code Generation Workshop]] |
| − | | + | '''''News''''': This workshop is now integrated into the [[Lyo/ToolchainModellingAndCodeGenerationWorkshop | Graphical Toolchain Modelling and Code Generation Workshop]]. The new modelling approach 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 process of developing an OSLC4J provider using a code generator. The generator is based on an EMF model of OSLC domain specifications.
| + | |
| − | | + | |
| − | The steps take you from creating an initial Eclipse project to code generate and run your adaptor.
| + | |
| − | | + | |
| − | # In [[Lyo/AdaptorCodeGeneratorWorkshop#Create_an_OSLC4J_project | Create an OSLC4J project]], you will create an empty project that is configured to start developing an OSLC4J adaptor. The instructions target our code generator. Yet, after these steps, you may also be able to proceed with manually developing your adaptor. | + | |
| − | # In [[Lyo/AdaptorCodeGeneratorWorkshop#Instantiate_an_adaptor_model | Instantiate an adaptor model]], you will do the very basic step of creating an empty adaptor EMF model.
| + | |
| − | # In [[Lyo/AdaptorCodeGeneratorWorkshop#Define_your_adaptor_model | Define your adaptor model]], you will model your adaptor.
| + | |
| − | # In [[Lyo/AdaptorCodeGeneratorWorkshop#Configure_.26_run_the_adaptor_generator | Configure & run the adaptor generator]], you will configure the code generator in order to generate source code for your project - based on the model you have defined.
| + | |
| − | # In [[Lyo/AdaptorCodeGeneratorWorkshop#Fill_in_the_internal_implementation_of_the_adaptor | Fill in the internal implementation of the adaptor]], you will perform the manual coding of the remaining parts of the adaptor
| + | |
| − | # In [[Lyo/AdaptorCodeGeneratorWorkshop#Run_the_adaptor | Run the adaptor]], you are ready to run.
| + | |
| − | | + | |
| − | '''Are you interested in initiating an OSLC4J Provider without the use of the code generator?''' You will find the instructions under [[Lyo/AdaptorCodeGeneratorWorkshop#Create_an_OSLC4J_project | Create an OSLC4J project]] very usuful anyway.
| + | |
| − | | + | |
| − | = Eclipse Setup =
| + | |
| − | | + | |
| − | Make sure your environment is setup appropriately as instructed on [[Lyo/AdaptorCodeGeneratorWorkshop/EclipseSetup | Eclipse Setup]]
| + | |
| − | | + | |
| − | = OSLC4J Project Setup for code generation =
| + | |
| − | | + | |
| − | == Introduction ==
| + | |
| − | First of all, decide on the following 2 values for your particular project. In these instructions we will use the following generic values.
| + | |
| − | * '''ProjectName''': ''YourProviderProjectName''
| + | |
| − | * '''PackageName''': ''your.base.package.name''
| + | |
| − | | + | |
| − | == Create an OSLC4J project ==
| + | |
| − | This information is based on the tutorial from [https://www.mbat-artemis.eu/home/index.php/dissemination/education-and-training?download=37:mbat-tutorial-implementing-oslc-consumers-and-providers-in-java-oslc4j-eclipse the MBAT Tutorial on Implementing OSLC Consumers and Providers with OSLC4J]
| + | |
| − | | + | |
| − | # Create a JAVA EE Web Application
| + | |
| − | ## '''File-->New-->Project…'''
| + | |
| − | ## Select ''Web/Dynamic Web Project''
| + | |
| − | ## As project name, specify ''YourProviderProjectName''
| + | |
| − | ## On the final step of the wizard, check the “Generate web.xml …“ option
| + | |
| − | ## Select '''Finish'''
| + | |
| − | # Convert project to Maven
| + | |
| − | ## Right click on the project, and select '''Configure --> Convert to Maven Project'''
| + | |
| − | ## In the window that appears, select ''“war”'' under '''Packaging'''
| + | |
| − | # Configure the project
| + | |
| − | ## Create a folder '''test''' at the root of the project
| + | |
| − | ## Create the sub-folders '''launches''' & '''resources''' under the new folder '''test'''
| + | |
| − | ## Copy the 3 configuration files from the [[Media:OSLC4JCodeGeneratorconfigurationFileTemplates.zip | Configuration File Templates]] into the corresponding folders:
| + | |
| − | ### /YourProviderProjectName/pom.xml
| + | |
| − | ### /YourProviderProjectName/WebContent/WEB-INF/web.xml
| + | |
| − | ### /YourProviderProjectName/test/resources/jetty.xml
| + | |
| − | ### If necessary, refresh your Eclipse workspace by right clicking on /YourProviderProjectName -> Refresh
| + | |
| − | ## Search and replace each of the following keywords with the specific values for your project
| + | |
| − | ### '''ProjectName:''' ''YourProviderProjectName''
| + | |
| − | ### '''PackageName:''' ''your.base.package.name''
| + | |
| − | ## If you get the error “Project configuration is not up-to-date with pom.xml”, simply right click on the YourProviderProjectName project and select '''Maven-->Update Project…'''.
| + | |
| − | # Activate Project Facet JAX-RS
| + | |
| − | ## Right click the project & Select '''properties'''
| + | |
| − | ## Open '''Project Facets'''
| + | |
| − | ## Select '''JAX-RS (REST Web Services)'''
| + | |
| − | ## Click '''Further Configuration required…'''
| + | |
| − | ## In the new window that appears
| + | |
| − | ### Set '''Type:''' Disable Library Configuration
| + | |
| − | ### Enter '''JAX-RS servlet class name''': org.apache.wink.server.internal.servlet.RestServlet
| + | |
| − | ### Under '''URL mapping pattern''':
| + | |
| − | #### Remove the existing one
| + | |
| − | #### Add a new one /services/*
| + | |
| − | # Further project configuration
| + | |
| − | ## right click the project & select '''Properties'''
| + | |
| − | ## select '''Deployment Assembly'''
| + | |
| − | ## '''Add…'''
| + | |
| − | ## In the new window that appears
| + | |
| − | ### select '''Java Build Path Entries'''
| + | |
| − | ### click '''Next >'''
| + | |
| − | ### select '''Maven Dependencies'''
| + | |
| − | ### click '''Finish'''
| + | |
| − | ### click '''Apply'''
| + | |
| − | ### click '''OK'''
| + | |
| − | # Create a new Run configuration
| + | |
| − | ## Select the menu '''Run-->Run Configurations …'''
| + | |
| − | ## Select Maven Build
| + | |
| − | ## Create a new Configuration (Right click on "Maven Build" -> "New")
| + | |
| − | ## Enter a '''name''' for the new configuration (such as Launch YourProviderProjectName)
| + | |
| − | ## Set the '''Base directory''' to ${workspace_loc:/ YourProviderProjectName}
| + | |
| − | ## Set '''Goal''' as jetty:run-exploded
| + | |
| − | ## Switch to tab '''JRE'''
| + | |
| − | ### Set '''Runtime JRE''' to Workspace default JRE…
| + | |
| − | ## Switch to tab '''Source'''
| + | |
| − | ### Click Add…
| + | |
| − | ### In the new window, select Project and click OK
| + | |
| − | #### Check the YourProviderProjectName project
| + | |
| − | #### Check the “add required projects of selected projects” option
| + | |
| − | #### Click OK
| + | |
| − | ## Switch to Tab '''Common'''
| + | |
| − | ### Select Shared Files
| + | |
| − | ### Click Browse…
| + | |
| − | ### In the window that appears, select the recently created folder “test/launches” under the YourProviderProjectName project
| + | |
| − | ### click '''OK'''
| + | |
| − | ## Click '''Apply'''
| + | |
| − | ## Clock '''Close'''
| + | |
| − | | + | |
| − | == Instantiate an adaptor model ==
| + | |
| − | # Create a new folder ''adaptorModel'' in the ''YourProviderProjectName'' Project. (This is where the adaptorModel will be created.)
| + | |
| − | # Open the ''adaptor_interface.ecore'' model in the org.eclipse.lyo.oslc4j.adaptormodel project (folder ''model'')
| + | |
| − | # Expand the ecore model until the ''AdaptorInterface'' EClass
| + | |
| − | # Right-click on the AdaptorInterface EClass & select '''Create Dynamic Instance …'''
| + | |
| − | # In the dialog that appears
| + | |
| − | ## select the folder ''adaptorModel'' under the ''YourProviderProjectName'' project as the “parent folder”
| + | |
| − | ## choose a suitable File name for the adaptor model - ''AdaptorInterface.xmi'' is fine.
| + | |
| − | # Right-click on the newly created ''AdaptorInterface.xmi'' file, and select '''open with --> Other … --> EMF Facet Model Browser'''.
| + | |
| − | | + | |
| − | '''Eclipse Note:''' There are 2 ways to open/view/edit the adaptor model, which will be used below:
| + | |
| − | * EMF Facet Model Browser: A better interface when creating new EMF instances in the model, as well as being able to jump to specific types of instances within the model.
| + | |
| − | * Sample Reflective Ecore Model Editor: A good interface when composing EMF models of other EMF models (See below).
| + | |
| − | | + | |
| − | == Define your adaptor model ==
| + | |
| − | The adaptor metal-model being instantiated is illustrated below. It consists of 2 main branches:
| + | |
| − | | + | |
| − | * The left side of the meta-model is a model of the OSLC core resources as defined in [http://open-services.net/bin/view/Main/OslcCoreSpecification?sortcol=table;up=#Service_Provider_Resources the OSLC Core Specification].
| + | |
| − | * The right side of the meta-model is a model of a typical OSLC domain specification.
| + | |
| − | | + | |
| − | [[File:OSLCToolAdaptorMetalModel.png]]
| + | |
| − | | + | |
| − | We will refer to this meta-model to explain how to define your adaptor model instance.
| + | |
| − | | + | |
| − | === Load existing domain specifications ===
| + | |
| − | '''Note:''' These steps are optional, but recommended
| + | |
| − | | + | |
| − | While an adaptor model can be completely defined from en empty instance, it is recommended to reuse some pre-defined domain specification models. (that is, this step can be skipped if your model uses no standard domain specifications)
| + | |
| − | # In the Project Explorer window, right-click on the newly created ''AdaptorInterface.xmi'' file, and select '''open with --> Other … --> Sample Reflective Ecore Model Editor'''.
| + | |
| − | # In the newly opened window, right-click and select the context menu '''Load Resource …'''
| + | |
| − | # Select '''Browse Workspace …'''
| + | |
| − | # Expand the ''model'' folder of the ''org.eclipse.lyo.oslc4j.adaptormodel'' project.
| + | |
| − | # Select the desired domain specification(s) that you intend to use. (Note that these domain specification models are composed of each other. That is, including one – say ChangeManagement – may indirectly include another – in this case CoreSpecifications.)
| + | |
| − | # Press OK.
| + | |
| − | # Elements of the loaded domain specification models can now be referenced in the ''AdaptorInterface'' model you are creating.
| + | |
| − | | + | |
| − | '''Note:''' At any point when modelling your adaptor, you can repeat the above steps in order to load and use other domain specifications.
| + | |
| − | | + | |
| − | === Define right-side of adaptor model ===
| + | |
| − | | + | |
| − | # Right-click on '''AdaptorInterface(1)''' instance and select '''New Child -->''' '''Specification(5)'''
| + | |
| − | ## This instance is a simple container of domain specifications and namespaces. No properties defined.
| + | |
| − | # '''Recall''': as detailed in section [[Lyo/AdaptorCodeGeneratorWorkshop#Load_existing_domain_specifications | Load existing domain specifications]], you can always reuse any pre-defined domain specification models. The following steps are only necessary for user-specific domain specifications, that you prefer to embed into your own adaptor model.
| + | |
| − | # Define any number of additional domain specifications. For each such domain specification:
| + | |
| − | ## Right-click on the '''Specification(5)''' instance and select '''New Child -->''' '''NamespacePrefix(6)'''
| + | |
| − | ### For the newly-created NamespacePrefix, simply provide the prefix for the new domain specification (Note: To view and change properties of a model element, you can (a) right-click on the EMF instance, and select "Show Properties View")
| + | |
| − | ## Right-click on the '''Specification(5)''' instance and select '''New Child -->''' '''DomainSpecification(7)'''
| + | |
| − | ### For the newly created DomainSpecification instance, fill-in its properties. (Note that the namespacePrefix property refers to an instance of NamespacePrefix(6))
| + | |
| − | ### Define '''Resource(9)''' and/or '''ResourceProperty(8)''' instances as desired.
| + | |
| − | ### Note that a Resource instance can refer to ResourceProperties from any other domainSpecification in the model.
| + | |
| − | | + | |
| − | === Define left-side of adaptor model ===
| + | |
| − | # In the Project Explorer window, right-click on AdaptorInterface.xmi file, and select '''open with --> Other … --> EMF Facet Model Browser'''
| + | |
| − | # In the newly opened window, double-click on the '''AdaptorInterface(1)''' EMF instance to open its Properties window, and configure it.
| + | |
| − | ## ''Note:'' To view and change properties of a model element, you can (a) right-click on the EMF instance within the ''Instances'' frame, and select '''Show Properties View''' or (b) double-click on the instance.
| + | |
| − | ## The properties’ meaning is as follows:
| + | |
| − | ### ''name'': the name of your adaptor (for example, use the same name as your project name)
| + | |
| − | ### ''javaClassBaseNamespace'': the name of the base Java root package from which the code of your adaptor will be generated.
| + | |
| − | #### Make sure that this value matches “your.base.package.name” selected above.
| + | |
| − | ### ''Java Files Base Path'': The path of where java files will be generated. (for example, '''/src/'')
| + | |
| − | ### ''Javascript Files Base Path'': The path of where javascript files will be generated. (for example, ''/WebContent'')
| + | |
| − | ### ''Jsp Files Base Path'': The path of where the Jsp files will be generated. (for example, “/WebContent”)
| + | |
| − | # Right-click on AdaptorInterface instance and select “New Child --> '''ServiceProviderCatalog(2)'''
| + | |
| − | ## For the newly created catalog, fill-in all its properties as defined according to OSLC.
| + | |
| − | ## Note that you can only define 1 catalogue in an adaptor.
| + | |
| − | # Right-click on the ServiceProviderCatalog instance and select “New Child --> '''Publisher(4)'''
| + | |
| − | ## For the newly created Publisher, fill-in all the Publisher properties as defined according to OSLC.
| + | |
| − | ## Note that you can only define 1 Publisher for a catalog.
| + | |
| − | # Right-click on the ServiceProviderCatalogue instance and select “New Child --> '''ServiceProvider(3)'''
| + | |
| − | ## 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:
| + | |
| − | ### 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}".
| + | |
| − | ## Note that you can define one-or-many ServiceProviders for a ServiceProviderCatalogue.
| + | |
| − | # From each of the defined ServiceProviders, proceed down to create and define '''Services(10)''' & '''Capabilities(11,12,13)'''.
| + | |
| − | ## Make sure you fill-in all properties of each EMF instance you create.
| + | |
| − | ## Make sure you satisfy the cardinality of each of the containment relationships as illustrated in the figure above.
| + | |
| − | ## When defining the properties of '''Capabilities(11,12,13)''', make sure you define each of their Resource Types property. (Which are defined either under the '''Specifiation(5)''' EMF instance (see section [[Lyo/AdaptorCodeGeneratorWorkshop#Define_right-side_of_adaptor_model | Define right-side of adaptor model]]), or exist as part of a loaded domain specification (see section [[Lyo/AdaptorCodeGeneratorWorkshop#Load_existing_domain_specifications | Load existing domain specifications]]).)
| + | |
| − | ## (optional) To control the relative URLs used in the web service handling 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).
| + | |
| − | ### 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.
| + | |
| − | | + | |
| − | == Configure & run the adaptor generator ==
| + | |
| − | | + | |
| − | # Define a "run configuration" for adaptor code generation
| + | |
| − | ## Select '''Run --> Run Configurations …'''
| + | |
| − | ## Select ''Acceleo Application''
| + | |
| − | ## Press the '''New launch configuration''' button
| + | |
| − | ### '''Name''': something practical such as ''Generate YourProviderProjectName''
| + | |
| − | ### '''Project''': select the ''org.eclipse.lyo.oslc4j.codegenerator'' project
| + | |
| − | ### '''Main class''': ''codegenerator.main.Generate''
| + | |
| − | ### '''Model''': the newly created ''adaptormodel'' in the ''YourProviderProjectName'' project
| + | |
| − | ### '''Target''': The YourProviderProjectName project
| + | |
| − | ## Press '''Apply'''
| + | |
| − | ## Press '''Close'''.
| + | |
| − | # '''''Bug fix''''' – Did you compose your model from other models (section [[Lyo/AdaptorCodeGeneratorWorkshop#Load_existing_domain_specifications | Load existing domain specifications]]) and reference some of its elements in your adaptor model? Currently, the way EMF models reference each other in the xmi files causes problems with the code generator. Before you trigger the code generator, perform the following steps: (These steps need to be repeated if the adaptor model is later changed to include further references).
| + | |
| − | ## Copy the workspace location of any loaded resources (EMF models)
| + | |
| − | ### In the ''Project Explorer'' window, right-click on the ''AdaptorInterface.xmi'' file, and select '''open with --> Other … --> Sample Reflective Ecore Model Editor'''.
| + | |
| − | ### In the newly opened window, right-click and select the context menu '''Load Resource …'''
| + | |
| − | ### Select '''Browse Workspace …'''
| + | |
| − | ### Select the domain specification EMF model that you have earlier loaded.
| + | |
| − | ### Copy the path to the xmi file selected into the clipboard (it will be something like ''platform:/resource/org.eclipse.lyo.oslc4j.adaptormodel/model/someSpecification.xmi'')
| + | |
| − | ### Press '''Cancel'''.
| + | |
| − | ## In the Project Explorer window, right-click on the ''AdaptorInterface.xmi'' file, and select '''open with --> XML Editor'''
| + | |
| − | ## Search and replace each ''href'' entry that refers to your domain specification.
| + | |
| − | ### Replace href values that look like ''href="../../org.eclipse.lyo.oslc4j.adaptormodel/model/someSpecification.xmi#//...'' with the copied value (which ought to look more like ''href="platform:/resource/org.eclipse.lyo.oslc4j.adaptormodel/model/someSpecification.xmi#//..."'').
| + | |
| − | ## Repeat these steps for each domain specification model you have loaded and referenced.
| + | |
| − | # Once you are satisfied with your model, code generate the adaptor
| + | |
| − | ## Select '''Run > Run Configurations …'''
| + | |
| − | ## Select the ''Generate YourProviderProjectName'' configuration
| + | |
| − | ## Press '''Run'''.
| + | |
| − | | + | |
| − | == Fill in the internal implementation of the adaptor ==
| + | |
| − | At a minimum, manual code is needed to connect the adaptor to the backend tool with which it communicate, as well as access its internal data that are eventually exposed as OSLC resources. This minimal code needs to be implemented in the AdaptorManager class (in the “your.base.package.name” package).
| + | |
| − | | + | |
| − | '''''TODO:''''' <Explain the methods in AdaptorManager that must be implemented>
| + | |
| − | | + | |
| − | '''''TODO:''''' <Explain the methods in the generated code that can be extended>
| + | |
| − | | + | |
| − | == Run the adaptor ==
| + | |
| − | | + | |
| − | You are now ready to run the adaptor
| + | |
