Environment Setup

iotp-adaptor was developed using eclipse/Lyo Designer which is an eclipse plug-in. So you'll need to use eclipse to follow along in this Developer Guide, as well as create your own adpaters using a similar technique.

This section summarizes how to install and configure eclipse so it is ready to be used for adapter development. It doesn't go into a lot of detail, and assumes some familiarity with eclipse, JEE and git. If you need help on any of these, the Web is full of great tutorials, references and samples that are a quick Google/Bing search away.

If you run into trouble, you can ask questions on stackoverflow or the jazz.net/forum.

Installing Eclipse

Go to the eclipse.org/downloads page and download Eclipse Eclipse 2020-03 (or later) to access the Eclipse Installer for your platform. Run the Eclipse Installer and install Eclipse IDE for Java EE Developers. The Web app generated by Lyo Designer is a JEE WAR file, so you'll need the plug-ins that are already installed in the Eclipse IDE for Java EE Developers. This includes additional components you'll need:

• Data Tools Platform
• Git integration for Eclipse
• Eclipse Java Development Tools
• Eclipse Java EE Developer Tools
• JavaScript Development Tools
• Maven Integration for Eclipse
• Mylyn Task List
• Eclipse Plug-in Development Environment
• Code Recommenders Tools for Java Developers
• Eclipse XML Editors and Tools

Once eclipse is installed, start it up and open the Eclipse Marketplace and add the following additional solutions Added the following:

• Install the Eclipse Jetty 5.0.0 or later

Install eclipse/Lyo Designer

Eclipse/Lyo designer comes in two parts, the Lyo Toolchain editor (which is built on Sirius), and the Lyo Code Generator. These two components are installed using and eclipse install and update site.

1. Start eclipse and invoke Help/Install New Software...
2. Configure an install and update site called Lyo Designer with one of the following update site URLs:

• https://download.eclipse.org/lyo/product/binaries/stable/ - these are the most recent released versions
• https://download.eclipse.org/lyo/product/binaries/edge/ - these are the latest builds from eclipse.org

3. Install the following features:

• Lyo Toolchain
• Lyo Code Generator

You'll need to restart eclipse to complete the installation.

Note: If the About Eclipse menu item, and clicking on the Installation Details button show no installed software, restart with eclipse with the -clean option.

Install Jetty

You can deploy the WAR file created in the iotp-adaptor/iotp-adaptor eclipse Maven project to any JEE container. However, Jetty is a very convenient container to use for rapid development. Install Jetty from https://www.eclipse.org/jetty/download.html.

1. Start eclipse

After installing, edit your .bash_profile or whatever is appropriate for your platform and set the JETTY_HOME environment variable. For example:

export JETTY_HOME=~/Applications/jetty-distribution-9.4.5.v20170502

Next use the Eclipse Marketplace to install Eclipse Jetty if you want to be able to lanuch iotp-adaptor as a Jetty Webapp. Use src/main/webapp as the WebApp Folder so that changes made during debugging will be immediately available. Typically use /iotp as the Context Path.

Add the following VM arguments:

-Diot.platform.base=internetofthings.ibmcloud.com
-Diot.platform.api.version=v0002
-Dlog4j.debug=true

Install git and GitHub Desktop

iotp-adaptor is a GitHub project, so you'll need to use git to access the source code. If you're here, you are likely already quite familiar with git. But just in case, here's a few notes to get you started.

You can use EGit in eclipse, git command line interface, and/or GitHub Desktop. These are all efficient, effective ways to use git and each has characteristics that make it useful in different contexts. The git reference manual is also a very useful resource if you forget the specifics of a particular git command. There more at the git documentation site.

Getting the iotp-adaptor Code

Now that your eclipse platform is all setup, you're ready to clone the iotp-adaptor repository and install the eclipse Maven projects. The following is a brief summary of how to do this:

1. Start eclipse
2. Open the Git perspective
3. paste the following URI in the Git Repositories view: https://github.com/OSLC/iotp-adaptor.git
4. Select the iotp-adaptor repository, right click, and invoke Import Maven Projects... to import the iotp-adaptor maven project. Note: if this menu item isn't available, you will need to install the m2e egit connector from the eclipse marketplace. Follow these instructions.
5. Select the iotp-awaptor repository again, right click and invoke Import Projects... to import the iotp-adaptor-model project.
6. Switch to the Java EE perspective
7. Expand eclipse maven project iotp-adaptor
8. Select the pom.xml file, right click and invoke Run As > Maven install

If all goes well, you should have completed the build of iotp-adaptor, and the deployable WAR file will be in target/iotp-0.0.1-SNAPSHOT (or something similar, the version might be different).

Note, when you load a Maven project (instead of an eclipse project), Maven automatically updates the eclipse project settings from information in the Maven pom.xml file. If you make significant changes to the pom.xml file, you may need to update the eclipse project settings again. To do this, select the iotp-adaptor project, right click, and invoke Maven > Update Project.... This will ensure the eclipse automatic build will use the same settings and dependencies as the Maven commands (e.g., mvn install from the command line or Run As > Maven install from the Project Explorer). This way compilation errors will show up in the Project Explorer and Markers view as you are editing.