Lyo/Adaptor Project Setup

Adaptor project setup from scratch

This page describes how to create the projects to be ready to take the Toolchain Modelling and Code Generation Workshop.

Project layout

The recommended project layout is the following:

adaptor-project/
    adaptor-project-model/
    adaptor-project-webapp/

Where top adaptor-project directory may be a git repository root, adaptor-project-model is the Lyo Toolchain Modelling project and adaptor-project-webapp contains the adaptor generated from the definitions in adaptor-project-model.

Modelling project

Start by creating a modelling project that will contain the definitions for the generated web application of the OSLC adaptor. For that, make sure that the latest version of the modelling tools was installed from the Eclipse Lyo Update Site and then open the project creation dialog by selecting File > New > Other and then Modeling Project under Sirius group. Uncheck the option to use the default workspace location. The location should point to the the modelling project directory (disregard the warning):

Adaptor code skeleton

Now we will create the adaptor code skeleton. Once combined with the generated code, it will become a fully functional adaptor. Creation of the skeleton consists of 2 steps:

• creating a Maven project from an archetype
• customising the generated project with the Lyo-specific configuration

Creating a Maven project from an archetype

To create a Maven project from an archetype via Eclipse, select File > New > Other and then Maven Project under Maven group. Leave the Create a simple project checkbox unchecked. Uncheck the Use default Workspace location option and point it to the project root:

Select the maven-archetype-webapp archetype:

Fill in the Group Id, Artefact Id, and the Package Base. You will need to enter them once again during the workshop:

You should now have 2 projects in Eclipse and the following folder structure:

Customising the project

General POM changes

We need to make sure our project uses UTF-8 and JDK 1.8. We will also use properties to define a common version for Lyo Core and Lyo Server packages:

<properties>
  <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
  <project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
  <maven.compiler.source>1.8</maven.compiler.source>
  <maven.compiler.target>1.8</maven.compiler.target>
  <version.lyo.core>2.1.2</version.lyo.core>
  <version.lyo.server>2.1.0</version.lyo.server>
</properties>

Generated code requires Java EE 6 or higher and JSTL:

<dependency>
  <groupId>javax.servlet</groupId>
  <artifactId>javax.servlet-api</artifactId>
  <version>3.1.0</version>
  <scope>provided</scope>
</dependency>
<dependency>
  <groupId>javax.servlet</groupId>
  <artifactId>jstl</artifactId>
  <version>1.2</version>
</dependency>

Lyo package dependencies

The generated code will use Lyo dependencies that we need to declare. Before we can do that, we need to add the Lyo repository:

  <repositories>
    <repository>
      <id>lyo-releases</id>
      <name>lyo-releases repository</name>
      <url>https://repo.eclipse.org/content/repositories/lyo-releases/</url>
    </repository>
  </repositories>

Now were are ready to add the dependencies.

Lyo uses SLF4J for logging, leaving the choice of the actual logging library to use. We will use the simplest option:

<dependency>
  <groupId>org.slf4j</groupId>
  <artifactId>slf4j-simple</artifactId>
  <version>1.7.21</version>
  <scope>runtime</scope>
</dependency>

Lyo dependencies need by the generated code:

<dependency>
  <groupId>org.eclipse.lyo.oslc4j.core</groupId>
  <artifactId>oslc4j-core</artifactId>
  <version>${version.lyo.core}</version>
  <exclusions>
    <exclusion>
      <groupId>org.slf4j</groupId>
      <artifactId>slf4j-log4j12</artifactId>
    </exclusion>
  </exclusions>
</dependency>
<dependency>
  <groupId>org.eclipse.lyo.oslc4j.core</groupId>
  <artifactId>oslc4j-jena-provider</artifactId>
  <version>${version.lyo.core}</version>
  <exclusions>
    <exclusion>
      <groupId>org.slf4j</groupId>
      <artifactId>slf4j-log4j12</artifactId>
    </exclusion>
  </exclusions>
</dependency>
<dependency>
  <groupId>org.eclipse.lyo.oslc4j.core</groupId>
  <artifactId>oslc4j-wink</artifactId>
  <version>${version.lyo.core}</version>
</dependency>
<dependency>
  <groupId>org.eclipse.lyo.oslc4j.core</groupId>
  <artifactId>oslc4j-json4j-provider</artifactId>
  <version>${version.lyo.core}</version>
</dependency>

Exclusions are due to the Bug 513477

Finally, generator includes the experimental support for OAuth:

<dependency>
  <groupId>org.eclipse.lyo.server</groupId>
  <artifactId>oauth-core</artifactId>
  <version>${version.lyo.server}</version>
</dependency>
<dependency>
  <groupId>org.eclipse.lyo.server</groupId>
  <artifactId>oauth-consumer-store</artifactId>
  <version>${version.lyo.server}</version>
  <exclusions>
    <exclusion>
      <groupId>org.slf4j</groupId>
      <artifactId>slf4j-log4j12</artifactId>
    </exclusion>
  </exclusions>
</dependency>
<dependency>
  <groupId>org.eclipse.lyo.server</groupId>
  <artifactId>oauth-webapp</artifactId>
  <version>${version.lyo.server}</version>
  <type>war</type>
</dependency>

OAuth is enabled by default. If you want to disable it, open the generated Application class and do the following changes:

• comment out line RESOURCE_CLASSES.add(Class.forName("org.eclipse.lyo.server.oauth.webapp.services.ConsumersService"));
• comment out line RESOURCE_CLASSES.add(Class.forName("org.eclipse.lyo.server.oauth.webapp.services.OAuthService"));
• change catch (ClassNotFoundException e) to catch (Exception e)

If you use OAuth or consume any resources in your Adaptor Interface, an OSLC client dependency is needed:

<dependency>
  <groupId>org.eclipse.lyo.clients</groupId>
  <artifactId>oslc-java-client</artifactId>
  <version>${version.lyo.core}</version>
  <exclusions>
    <exclusion>
      <groupId>org.slf4j</groupId>
      <artifactId>jcl-over-slf4j</artifactId>
    </exclusion>
  </exclusions>
</dependency>

web.xml configuration

Parameters in /src/main/webapp/WEB-INF/web.xml should be prefixes with the Package Base you used in the project skeleton initialisation (test.sample.webapp on this page).

<?xml version="1.0" encoding="UTF-8"?>
<web-app xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns="http://java.sun.com/xml/ns/javaee"
  xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd"
  id="WebApp_ID" version="3.0">
  <display-name>Sample Adaptor</display-name>
  <context-param>
    <description>Base URI for the adaptor.</description>
    <param-name>test.sample.webapp.servlet.baseurl</param-name>
    <param-value>http://localhost:8080</param-value>
  </context-param>
  <listener>
    <description>Listener for ServletContext lifecycle changes</description>
    <listener-class>test.sample.webapp.servlet.ServletListener</listener-class>
  </listener>
  <servlet>
    <servlet-name>JAX-RS Servlet</servlet-name>
    <servlet-class>org.apache.wink.server.internal.servlet.RestServlet</servlet-class>
    <init-param>
      <param-name>javax.ws.rs.Application</param-name>
      <param-value>test.sample.webapp.servlet.Application</param-value>
    </init-param>
    <load-on-startup>1</load-on-startup>
  </servlet>
  <servlet-mapping>
    <servlet-name>JAX-RS Servlet</servlet-name>
    <url-pattern>/services/*</url-pattern>
  </servlet-mapping>
</web-app>

Embedded Jetty server for quick debugging

Finally, you should use an embedded servlet container during the debugging to simplify the development process. Jetty configuration looks the following:

<build>
  <plugins>
    <plugin>
      <groupId>org.eclipse.jetty</groupId>
      <artifactId>jetty-maven-plugin</artifactId>
      <version>9.3.9.v20160517</version>
      <configuration>
        <webAppConfig>
          <contextPath>/test-sample</contextPath>
        </webAppConfig>
        <reload>automatic</reload>
        <scanIntervalSeconds>5</scanIntervalSeconds>
        <systemProperties>
          <systemProperty>
            <name>jetty.port</name>
            <value>8080</value>
          </systemProperty>
        </systemProperties>
        <stopKey />
        <stopPort />
      </configuration>
    </plugin>
  </plugins>
</build>

Afterwards, you can run the generated adaptor with mvn clean jetty:run-exploded command.