Skip to content

docs: style updates for Lyo 101 setup #41

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
berezovskyi merged 3 commits into from
Jul 19, 2025
Merged

docs: style updates for Lyo 101 setup #41

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
c2d7dd6
docs: style updates for Lyo 101 setup
berezovskyi Jul 10, 2025
0319eef
Update docs-new/eclipse_lyo/setup-an-oslc-provider-consumer-applicati…
berezovskyi Jul 10, 2025
b199876
Update docs-new/eclipse_lyo/setup-an-oslc-provider-consumer-applicati…
berezovskyi Jul 10, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
101 changes: 51 additions & 50 deletions docs-new/eclipse_lyo/setup-an-oslc-provider-consumer-application.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.

Expand All @@ -41,41 +41,41 @@ 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)

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
<properties>
Expand All @@ -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
<repositories>
Expand All @@ -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
<dependency>
Expand All @@ -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
<dependency>
Expand All @@ -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
<dependency>
Expand Down Expand Up @@ -211,7 +214,7 @@ If your server needs to support OAuth, include the following:
</dependency>
```

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"));
Expand All @@ -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 `<build>` 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
<build>
Expand Down Expand Up @@ -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
<?xml version="1.0" encoding="UTF-8"?>
Expand Down Expand Up @@ -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
<dependency>
Expand All @@ -343,11 +346,11 @@ Assuming you are adopting the Jersey implementation with the version specified a
</dependency>
```

### 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 `<plugins>` 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 `<plugins>` 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
<build>
Expand Down Expand Up @@ -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
<servlet>
Expand All @@ -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")
Expand All @@ -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
Expand All @@ -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:

Expand Down Expand Up @@ -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.

Expand Down Expand Up @@ -618,18 +621,16 @@ 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);`
* `InmemPagedTrsSingleton.getInmemPagedTrs().onDeleted(aResource.getAbout());`

## 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** ...