diff --git a/docs-new/eclipse_lyo/setup-an-oslc-provider-consumer-application.md b/docs-new/eclipse_lyo/setup-an-oslc-provider-consumer-application.md index 6e65257..a273f23 100644 --- a/docs-new/eclipse_lyo/setup-an-oslc-provider-consumer-application.md +++ b/docs-new/eclipse_lyo/setup-an-oslc-provider-consumer-application.md @@ -1,26 +1,26 @@ # Create an Eclipse Lyo project -This document provides step-by-step instructions for creating a Java project with the necessary configurations to develop any OSLC server/client using Lyo. The instructions assume you are using the Eclipse IDE, but should be equally valid for any other development environment. +This document provides step-by-step instructions for creating a Java project with the necessary configurations to develop OSLC server/client applications using Lyo. The instructions assume Eclipse IDE is being used, but are equally valid for other development environments. ## An alternative to the manual steps below An alternative to the instructions on this page is to use [Lyo Designer](./lyo-designer.md) to quickly generate the project, including a very basic code skeleton. The generated project will also include the necessary setup for OpenApi/Swagger support, TRS, etc. -1. Make sure your environment is set up for Lyo development as instructed on [Eclipse Setup for Lyo-based Development](./eclipse-setup-for-lyo-based-development.md). +1. Set up the environment for Lyo development as instructed on [Eclipse Setup for Lyo-based Development](./eclipse-setup-for-lyo-based-development.md). 1. Install [Lyo Designer](./install-lyo-designer.md). 1. Follow the [Create a Modelling Project](./toolchain-modelling-workshop.md#create-modelling-project) instructions (*Only this particular section*) to create the Eclipse project. -1. Follow the [Adapter Interface](./toolchain-modelling-workshop.md#adaptor-interface-view) instructions (*Only this particular section*) to create a single Adaptor Interface in the model. You do not need to create any additional elements, such as a Service Provider Catalog, Service Provider, etc. Just make sure you set the generation settings as expected. -1. Follow the [Generate Lyo Java code](./toolchain-modelling-workshop.md#generate-oslc4j-java-code) instructions (*Only this particular section*) to generate your basic project setup. -1. You are done! But of course, you can proceed with Lyo Designer to model your complete OSLC Server/Client and generate even more of your project code. +1. Follow the [Adaptor Interface](./toolchain-modelling-workshop.md#adaptor-interface-view) instructions (*Only this particular section*) to create a single Adaptor Interface in the model. Do not create additional elements, such as a Service Provider Catalog, Service Provider, etc. Set the generation settings as expected. +1. Follow the [Generate Lyo Java code](./toolchain-modelling-workshop.md#generate-oslc4j-java-code) instructions (*Only this particular section*) to generate the basic project setup. +1. The process is complete! Lyo Designer can be used to model the complete OSLC Server/Client and generate additional project code. ## Introduction -In the instructions below, we assume the following parameters, which you will need to adjust for your particular project: +In the instructions below, the following parameters are assumed, which need to be adjusted for the particular project: -* Eclipse Project Name: *adaptor-sample-webapp* -* Base Package Name for Java Classes: *com.sample.adaptor* +* Eclipse Project Name: `adaptor-sample-webapp` +* Base Package Name for Java Classes: `com.sample.adaptor` -We will here only create the code skeleton. The [Toolchain Modelling Workshop](./toolchain-modelling-workshop.md) can then be used to generate the necessary code to become a fully functional server. +These instructions create only the code skeleton. The [Toolchain Modelling Workshop](./toolchain-modelling-workshop.md) can then be used to generate the necessary code to become a fully functional server. As a complement when following the instructions below, you can find sample projects under the [Lyo Adaptor Sample Modelling](https://github.com/OSLC/lyo-adaptor-sample-modelling) git repository. @@ -41,17 +41,17 @@ Creating the project consists of these steps: ## Set up Eclipse -Make sure your environment is set up for Lyo development as instructed on [Eclipse Setup for Lyo-based Development](./eclipse-setup-for-lyo-based-development.md). +Set up the environment for Lyo development as instructed on [Eclipse Setup for Lyo-based Development](./eclipse-setup-for-lyo-based-development.md). ## Create a Maven project To create a Maven project from an archetype via Eclipse: -1. Select *File -> New -> Other*. -1. Then select *Maven Project* under *Maven* group. -1. Leave the *Create a simple project* checkbox unchecked. -1. Uncheck the *Use default Workspace location* option and point it to the project root. -1. Press *Next*. +1. Select **File -> New -> Other**. +1. Then select **Maven Project** under **Maven** group. +1. Leave the **Create a simple project** checkbox unchecked. +1. Uncheck the **Use default Workspace location** option and point it to the project root. +1. Press **Next**. ![](./images/CreateMavenAdaptorProject_Step1.png) @@ -59,23 +59,23 @@ Next, select the `maven-archetype-webapp` archetype: ![](./images/CreateMavenAdaptorProject_Step2.png) -Next, fill in the **Group Id**, **Artefact Id**, and the **Package Base**. +Next, fill in the **Group Id**, **Artifact Id**, and the **Package Base**. -* The **Package Base** value (`com.sample.adaptor` on this page) will be used as a base package for your server code. +* The **Package Base** value (`com.sample.adaptor` on this page) will be used as a base package for the server code. ![](./images/CreateMavenAdaptorProject_Step3.png) -You should now have the project in Eclipse and the following folder structure: +The project is now available in Eclipse with the following folder structure: ![](./images/CreateMavenAdaptorProject_CodeStructure.png) ## Customise the project POM file -We now need to modify the project *pom.xml* file. +Modify the project `pom.xml` file. ### Set up general POM properties -We will also use properties to define a common version for Lyo packages: +Use properties to define a common version for Lyo packages: ```xml @@ -89,9 +89,9 @@ We will also use properties to define a common version for Lyo packages: ### (Optional) Add Lyo repositories -Lyo release artefacts are on Maven central since 4.0.0 - no action needed from your side. +Lyo release artefacts are on Maven central since 4.0.0 - no action needed. -If you wish to use the latest development snapshots, you will need the following entry: +If using the latest development snapshots is required, the following entry is needed: ```xml @@ -111,7 +111,7 @@ If you wish to use the latest development snapshots, you will need the following ### SLF4J package dependencies -Lyo uses SLF4J for logging, leaving the choice of the actual logging library to use. We will use the simplest option: +Lyo uses SLF4J for logging, leaving the choice of the actual logging library to use. The simplest option: ```xml @@ -124,7 +124,7 @@ Lyo uses SLF4J for logging, leaving the choice of the actual logging library to ### Servlet dependencies -We require Java EE 6 or higher and JSTL: +Java EE 6 or higher and JSTL are required: ```xml @@ -146,7 +146,10 @@ Lyo depends on JAX-RS APIs and your application needs to add implementations of #### For Lyo 5.x -For Lyo release 5.0.0 and above, you will need to choose a JAX-RS 2.0 implementation. If you are using Jersey, you should use version 2.35. *Note that starting with Jersey 2.26, HK2 is not bundled with the core artefacts (see the [Jersey migration guide](https://eclipse-ee4j.github.io/jersey.github.io/documentation/2.35/user-guide.html#mig-2.26)).* +For Lyo release 5.0.0 and above, choose a JAX-RS 2.0 implementation. If using Jersey, use version 2.35. + +!!! note + Starting with Jersey 2.26, HK2 is not bundled with the core artefacts (see the [Jersey migration guide](https://eclipse-ee4j.github.io/jersey.github.io/documentation/2.35/user-guide.html#mig-2.26)). ```xml @@ -211,7 +214,7 @@ If your server needs to support OAuth, include the following: ``` -To support OAuth, you will need to add the following JAX-RS Providers to your Application (the `javax.ws.rs.core.Application` subclass): +To support OAuth, add the following JAX-RS Providers to the Application (the `javax.ws.rs.core.Application` subclass): ```java RESOURCE_CLASSES.add(Class.forName("org.eclipse.lyo.server.oauth.webapp.services.ConsumersService")); @@ -233,14 +236,14 @@ If your OSLC server also needs to consume resources from another server, a depen ### Configure the Embedded Jetty server for quick debugging -Finally, you should use an embedded servlet container during the debugging to simplify the development process. +Finally, use an embedded servlet container during the debugging to simplify the development process. Replace the existing `` entry with the Jetty configuration below, using the following customisations: -* *adaptor-sample* is the context path that can be the same as your eclipse project name (or something more appropriate) -* *8080* is the port number you want to run the services on. +* `adaptor-sample` is the context path that can be the same as the eclipse project name (or something more appropriate) +* `8080` is the port number to run the services on. -This will make your server available under the path http://localhost:8080/adaptor-sample. +This will make the server available under the path http://localhost:8080/adaptor-sample. ```xml @@ -273,9 +276,9 @@ This will make your server available under the path http://localhost:8080/adapto Modify the parameters in `/src/main/webapp/WEB-INF/web.xml` according to the template below. -* *Adaptor Sample* could be the same as your eclipse project name (or something more appropriate). -* *com.sample.adaptor* should be the same as the base package name for your project. -* *8080* should match the port number specified in the POM file for Jetty configuration. +* `Adaptor Sample` could be the same as the eclipse project name (or something more appropriate). +* `com.sample.adaptor` should be the same as the base package name for the project. +* `8080` should match the port number specified in the POM file for Jetty configuration. ```xml @@ -317,11 +320,11 @@ The instructions below are based on [Swagger Core JAX RS Project Setup 1.5.X](ht ### Add OpenApi/Swagger Maven dependencies -Add the following Swagger dependency to your maven pom.xml file. +Add the following Swagger dependency to the maven pom.xml file. #### For Lyo 5.0.0 -Assuming you are adopting the Jersey implementation with the version specified above. +Assuming the Jersey implementation is adopted with the version specified above. ```xml @@ -343,11 +346,11 @@ Assuming you are adopting the Jersey implementation with the version specified a ``` -### Co-host Swagger UI with your server +### Co-host Swagger UI with the server -The following steps provide the end-user with an interactive console to the OSLC services, by integrating [Swagger UI](https://swagger.io/swagger-ui/) with your OSLC server. +The following steps provide the end-user with an interactive console to the OSLC services, by integrating [Swagger UI](https://swagger.io/swagger-ui/) with the OSLC server. -Add the following plugins to the existing `` entry of your `pom.xml` file. These plugins download and extract the necessary `Swagger UI` files from [Swagger UI GitHub project](https://github.com/swagger-api/swagger-ui) onto your project: +Add the following plugins to the existing `` entry of the `pom.xml` file. These plugins download and extract the necessary `Swagger UI` files from [Swagger UI GitHub project](https://github.com/swagger-api/swagger-ui) onto the project: ```xml @@ -419,9 +422,9 @@ public class Application extends javax.ws.rs.core.Application { ### Configure Swagger's Servlet in the web.xml -Add the following to your web.xml: +Add the following to the `web.xml`: -* *swagger.api.basepath* depends on your particular settings, as instructed above. +* `swagger.api.basepath` depends on the particular settings, as instructed above. ```xml @@ -446,7 +449,7 @@ The OpenApi documentation can be achieved with as little as adding `@Api` to eac #### `@Api` 1. For each REST service (i.e. OSLC Service), simply add the `@Api` annotation. -1. (*OPTIONAL*) add the *value* and *description* details. The *value* is used to group the REST methods into common categories, helping in the structuring of the methods in the documentation. You can give it the same value as that of the @Path annotation, collecting all REST methods for the same service together. +1. (*OPTIONAL*) add the `value` and `description` details. The `value` is used to group the REST methods into common categories, helping in the structuring of the methods in the documentation. You can give it the same value as that of the @Path annotation, collecting all REST methods for the same service together. ```java @Api(value = "requirements", description = "OSLC service for resources of type" + "Requirement") @@ -464,7 +467,7 @@ For each REST method, add the `@ApiOperation` Swagger annotation. !!! example If your OSLC Service defines separate Java methods to handle HTML and RDF/XML content types for the same path and HTTP method, OpenApi will only recognise one of these methods and ignore the other. - **Workaround:** Annotate ALL methods that are identified as unique with the complete list of media types in the *produces* property of the `@ApiOperation` annotation. This way, the generated documentation correctly indicates the existence of all methods. + **Workaround:** Annotate ALL methods that are identified as unique with the complete list of media types in the `produces` property of the `@ApiOperation` annotation. This way, the generated documentation correctly indicates the existence of all methods. ```java @GET @@ -490,7 +493,7 @@ public class Requirement ### Access the Swagger UI interactive console -Before you can access the [Swagger UI](https://swagger.io/swagger-ui/) interactive console for the first time, edit the `swagger-ui/index.html` file, replacing the url `http://petstore.swagger.io/v2/swagger.json` with the url of your own yaml file `http://localhost:8080/adaptor-sample/services/swagger.yaml`. +Before accessing the [Swagger UI](https://swagger.io/swagger-ui/) interactive console for the first time, edit the `swagger-ui/index.html` file, replacing the url `http://petstore.swagger.io/v2/swagger.json` with the URL of the YAML file `http://localhost:8080/adaptor-sample/services/swagger.yaml`. The generated interactive API console can be accessed via: @@ -562,7 +565,7 @@ public class Application extends javax.ws.rs.core.Application { } ``` -Define the `InmemPagedTrsSingleton` singleton class. You will need to complete the code example below, with: +Define the `InmemPagedTrsSingleton` singleton class. Complete the code example below, with: * the code that populates `uris` with the initial set of resources to be managed by `InmemPagedTrs`; * the desired `basePageLimit` and `changelogPageLimit` parameters. @@ -618,7 +621,7 @@ The application is now ready to respond to REST requests from a TRS Client. Once ### Update the TRS data set -To update the set of OSLC resources that form the TRS Base and ChangeLog, simply call the following methods in your code: +To update the set of OSLC resources that form the TRS Base and ChangeLog, call the following methods in the code: * `InmemPagedTrsSingleton.getInmemPagedTrs().onCreated(aResource);` * `InmemPagedTrsSingleton.getInmemPagedTrs().onModified(aResource);` @@ -626,10 +629,8 @@ To update the set of OSLC resources that form the TRS Base and ChangeLog, simply ## Run the server -Once the server is developed, you can run it by selecting *Run As ➞ Maven build ...* from the project's context menu, and setting the goal to `clean jetty:run-war`. - -You can now access your server from http://localhost:8080/adaptor-sample. +Once the server is developed, run it by selecting **Run As ➞ Maven build ...** from the project's context menu, and setting the goal to `clean jetty:run-war`. -* *adaptor-sample* and *8080* will depend on your particular settings, as instructed above. +Access the server from [http://localhost:8080/adaptor-sample](http://localhost:8080/adaptor-sample) (`adaptor-sample` and `8080` will depend on the particular settings, as instructed above). -> **Pro Tip:** If you get the error *Project configuration is not up-to-date with pom.xml*, simply right click on the eclipse project and select *Maven ➞ Update Project* ... +> **Pro Tip:** If the error `Project configuration is not up-to-date with pom.xml` occurs, right click on the eclipse project and select **Maven ➞ Update Project** ...