Skip to main content
Jump to: navigation, search

Difference between revisions of "Lyo/Adaptor Project Setup"

< Lyo
m (remove extra sentence)
m (demote headings)
Line 1: Line 1:
= Adaptor project setup from scratch =
 
 
 
This page describes how to create the projects to be ready to take the [https://wiki.eclipse.org/Lyo/ToolchainModellingAndCodeGenerationWorkshop Toolchain Modelling and Code Generation Workshop].
 
This page describes how to create the projects to be ready to take the [https://wiki.eclipse.org/Lyo/ToolchainModellingAndCodeGenerationWorkshop Toolchain Modelling and Code Generation Workshop].
  
== Project layout ==
+
= Project layout =
  
 
The recommended project layout is the following:
 
The recommended project layout is the following:
Line 12: Line 10:
 
Where top <code>adaptor-project</code> directory may be a git repository root, <code>adaptor-project-model</code> is the Lyo Toolchain Modelling project and <code>adaptor-project-webapp</code> contains the adaptor generated from the definitions in <code>adaptor-project-model</code>.
 
Where top <code>adaptor-project</code> directory may be a git repository root, <code>adaptor-project-model</code> is the Lyo Toolchain Modelling project and <code>adaptor-project-webapp</code> contains the adaptor generated from the definitions in <code>adaptor-project-model</code>.
  
== Modelling project ==
+
= 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 &gt; New &gt; 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):
 
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 &gt; New &gt; 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):
Line 19: Line 17:
 
[[File:Screen_Shot_2017-04-13_at_19.57.37.png|center|800px]]
 
[[File:Screen_Shot_2017-04-13_at_19.57.37.png|center|800px]]
  
== Adaptor code skeleton ==
+
= 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:
 
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:
Line 26: Line 24:
 
* customising the generated project with the Lyo-specific configuration
 
* customising the generated project with the Lyo-specific configuration
  
== Creating a Maven project from an archetype ==
+
= Creating a Maven project from an archetype =
  
 
To create a Maven project from an archetype via Eclipse, select ''File &gt; New &gt; 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:
 
To create a Maven project from an archetype via Eclipse, select ''File &gt; New &gt; 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:
Line 48: Line 46:
 
[[File:Screen_Shot_2017-04-13_at_20.15.33.png|center|800px]]
 
[[File:Screen_Shot_2017-04-13_at_20.15.33.png|center|800px]]
  
== Customising the project ==
+
= Customising the project =
  
=== General POM changes ===
+
== 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:
 
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:
Line 75: Line 73:
 
   <version>1.2</version>
 
   <version>1.2</version>
 
</dependency></source>
 
</dependency></source>
=== Lyo package dependencies ===
+
 
 +
== 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:
 
The generated code will use Lyo dependencies that we need to declare. Before we can do that, we need to add the Lyo repository:
Line 96: Line 95:
 
   <scope>runtime</scope>
 
   <scope>runtime</scope>
 
</dependency></source>
 
</dependency></source>
 +
 
Lyo dependencies need by the generated code:
 
Lyo dependencies need by the generated code:
  
Line 130: Line 130:
 
   <version>${version.lyo.core}</version>
 
   <version>${version.lyo.core}</version>
 
</dependency></source>
 
</dependency></source>
 +
 
<blockquote>Exclusions are due to the [https://bugs.eclipse.org/bugs/show_bug.cgi?id=513477 Bug 513477]
 
<blockquote>Exclusions are due to the [https://bugs.eclipse.org/bugs/show_bug.cgi?id=513477 Bug 513477]
 
</blockquote>
 
</blockquote>
 +
 
Finally, generator includes the experimental support for OAuth:
 
Finally, generator includes the experimental support for OAuth:
  
Line 156: Line 158:
 
   <type>war</type>
 
   <type>war</type>
 
</dependency></source>
 
</dependency></source>
 +
 
<blockquote>OAuth is enabled by default. If you want to disable it, open the generated <code>Application</code> class and do the following changes:
 
<blockquote>OAuth is enabled by default. If you want to disable it, open the generated <code>Application</code> class and do the following changes:
  
Line 175: Line 178:
 
   </exclusions>
 
   </exclusions>
 
</dependency></source>
 
</dependency></source>
=== web.xml configuration ===
+
 
 +
== web.xml configuration ==
  
 
Parameters in <code>/src/main/webapp/WEB-INF/web.xml</code> should be prefixes with the '''Package Base''' you used in the project skeleton initialisation (<code>test.sample.webapp</code> on this page).
 
Parameters in <code>/src/main/webapp/WEB-INF/web.xml</code> should be prefixes with the '''Package Base''' you used in the project skeleton initialisation (<code>test.sample.webapp</code> on this page).

Revision as of 19:16, 13 April 2017

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):

Screen Shot 2017-04-13 at 19.57.37.png

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:

Screen Shot 2017-04-13 at 20.11.06.png

Select the maven-archetype-webapp archetype:

Screen Shot 2017-04-13 at 20.06.39.png

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

Screen Shot 2017-04-13 at 20.12.28.png

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

Screen Shot 2017-04-13 at 20.15.33.png

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.

Back to the top