Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

Difference between revisions of "Lyo/creating OSLC4J project"

< Lyo
(Replaced content with "This page has moved to [http://oslc.github.io/developing-oslc-applications/eclipse_lyo/setup-an-oslc-provider-consumer-application.html Lyo's new documentation].")
 
(4 intermediate revisions by the same user not shown)
Line 1: Line 1:
= Eclipse Setup =
+
This page has moved to [http://oslc.github.io/developing-oslc-applications/eclipse_lyo/setup-an-oslc-provider-consumer-application.html Lyo's new documentation].
 
+
Make sure your environment is setup for OSLC4J development as instructed on [https://wiki.eclipse.org/Lyo/General_Setup_for_OSLC4J_Development General Setup for OSLC4J development]
+
 
+
= Create an OSLC4J project =
+
 
+
The steps below guide you through the necessary steps of creating an Eclipse project with the necessary configurations to develop any OSLC4J adaptor.
+
 
+
In the instructions below, we assume the following parameters, which you will need to adjust for your particular project:
+
 
+
* Eclipse Project Name: ''adaptor-sample-webapp''
+
* Base Package Name for Java Classes: ''com.sample.adaptor''
+
 
+
We will here only create the code skeleton. The [https://wiki.eclipse.org/Lyo/ToolchainModellingAndCodeGenerationWorkshop Toolchain Modelling and Code Generation Workshop] can then be used to generate the necessary code to 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 -&gt; New -&gt; Other''
+
# then select ''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
+
# Press ''Next''
+
 
+
<!-- ![](https://wiki.eclipse.org/images/d/d5/CreateMavenAdaptorProject_Step1.png) -->
+
[[File:CreateMavenAdaptorProject_Step1.png|frame|none|800px]]
+
 
+
Next, select the <code>maven-archetype-webapp</code> archetype:
+
 
+
<!-- ![](https://wiki.eclipse.org/images/2/26/CreateMavenAdaptorProject_Step2.png) -->
+
[[File:CreateMavenAdaptorProject_Step2.png|frame|none|800px]]
+
 
+
Next, Fill in the '''Group Id''', '''Artefact Id''', and the '''Package Base'''.
+
 
+
* The '''Package Base''' value (<code>com.sample.adaptor</code> on this page) will be used as a base package for your adaptor code.
+
 
+
<!-- ![](https://wiki.eclipse.org/images/d/d9/CreateMavenAdaptorProject_Step3.png) -->
+
[[File:CreateMavenAdaptorProject_Step3.png|frame|none|800px]]
+
 
+
You should now have the project in Eclipse and the following folder structure:
+
 
+
<!-- ![](https://wiki.eclipse.org/images/c/cd/CreateMavenAdaptorProject_CodeStructure.png) -->
+
[[File:CreateMavenAdaptorProject_CodeStructure.png|frame|none|800px]]
+
 
+
== Customise the project POM file ==
+
 
+
We now need to modify the project ''pom.xml'' file.
+
 
+
=== 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:
+
 
+
<source lang="xml"><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></source>
+
We require Java EE 6 or higher and JSTL:
+
 
+
<source lang="xml"><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></source>
+
=== Lyo package dependencies ===
+
 
+
an OSLC4J project will use Lyo dependencies that we need to declare. Before we can do that, we need to add the Lyo repository:
+
 
+
<source lang="xml">  <repositories>
+
    <repository>
+
      <id>lyo-releases</id>
+
      <name>lyo-releases repository</name>
+
      <url>https://repo.eclipse.org/content/repositories/lyo-releases/</url>
+
    </repository>
+
  </repositories></source>
+
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:
+
 
+
<source lang="xml"><dependency>
+
  <groupId>org.slf4j</groupId>
+
  <artifactId>slf4j-simple</artifactId>
+
  <version>1.7.21</version>
+
  <scope>runtime</scope>
+
</dependency></source>
+
Lyo dependencies need:
+
 
+
<source lang="xml"><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></source>
+
<blockquote>Exclusions are due to the [https://bugs.eclipse.org/bugs/show_bug.cgi?id=513477 Bug 513477]
+
</blockquote>
+
Finally, your adaptor might need to includes the experimental support for OAuth:
+
 
+
<source lang="xml"><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></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:
+
 
+
* comment out line <code>RESOURCE_CLASSES.add(Class.forName(&quot;org.eclipse.lyo.server.oauth.webapp.services.ConsumersService&quot;));</code>
+
* comment out line <code>RESOURCE_CLASSES.add(Class.forName(&quot;org.eclipse.lyo.server.oauth.webapp.services.OAuthService&quot;));</code>
+
* change <code>catch (ClassNotFoundException e)</code> to <code>catch (Exception e)</code>
+
</blockquote>
+
If you use OAuth or consume any resources in your Adaptor Interface, an OSLC client dependency is needed:
+
 
+
<source lang="xml"><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></source>
+
=== Embedded Jetty server for quick debugging ===
+
 
+
Finally, you should use an embedded servlet container during the debugging to simplify the development process.
+
 
+
Replace the existing <code>&lt;build&gt;</code> 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.
+
 
+
This will make your adaptor available under the path http://localhost:8080/adaptor-sample
+
 
+
<source lang="xml"><build>
+
  <plugins>
+
    <plugin>
+
      <groupId>org.eclipse.jetty</groupId>
+
      <artifactId>jetty-maven-plugin</artifactId>
+
      <version>9.3.9.v20160517</version>
+
      <configuration>
+
        <webAppConfig>
+
          <contextPath>/adaptor-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></source>
+
== Customise the web configuration ==
+
 
+
Modify the parameters in <code>/src/main/webapp/WEB-INF/web.xml</code> 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.
+
 
+
<source lang="xml"><?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>Adaptor Sample</display-name>
+
  <context-param>
+
    <description>Base URI for the adaptor.</description>
+
    <param-name>com.sample.adaptor.servlet.baseurl</param-name>
+
    <param-value>http://localhost:8080</param-value>
+
  </context-param>
+
  <listener>
+
    <description>Listener for ServletContext lifecycle changes</description>
+
    <listener-class>com.sample.adaptor.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>com.sample.adaptor.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></source>
+
== Final tips ==
+
 
+
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--&gt;Update Project...
+
 
+
== Run the adaptor ==
+
 
+
Once the adaptor is developed, you can run it by selecting ''Run As -&gt; Maven build ...'' from the project's context menu, and setting the goal to <code>clean jetty:run-exploded</code>.
+

Latest revision as of 00:48, 25 April 2019

This page has moved to Lyo's new documentation.

Back to the top