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.
Difference between revisions of "Lyo/TRSSDK"
(26 intermediate revisions by 3 users not shown) | |||
Line 1: | Line 1: | ||
− | The Tracked Resource Set (TRS) Software Development Kit (SDK) consists of two primary pieces; a toolkit and reference applications. | + | The [http://open-services.net/wiki/core/TrackedResourceSet-2.0/ Tracked Resource Set (TRS)] Software Development Kit (SDK) consists of two primary pieces; a toolkit and reference applications. |
− | + | <br> | |
− | + | = TRS SDK Prerequisites = | |
+ | |||
+ | *[http://eclipse.org/downloads Eclipse 3.6 or higher IDE] | ||
+ | *[http://eclipse.org/egit/download/ EGit] team provider for git (recommended) or [http://git-scm.com/download git command line package]. | ||
+ | *[http://www.eclipse.org/m2e/download/ m2eclipse] for Maven support in the Eclipse IDE | ||
+ | *The Lyo projects requires a Java 1.6 compiler and Java 1.6 runtime. The Eclipse project settings have been set appropriately. If you are building outside of Eclipse, please use Java 1.6. | ||
<br> | <br> | ||
− | = | + | = TRS Toolkit = |
− | + | The goal of the TRS toolkit is to provide a simple set of java beans that represent the entities within the TRS specification. Also, a convenient set of string constants that represent the TRS properties is provided. In addition to these code components which can be used to create TRS implementations, a test suite component exists. The test suite consists of a series of JUnit compliance tests which validate a TRS endpoint conforms to the TRS specification. | |
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
<br> | <br> | ||
+ | |||
+ | == Loading the TRS Toolkit == | ||
=== Clone the Lyo Core git repository === | === Clone the Lyo Core git repository === | ||
Line 24: | Line 26: | ||
*Open the Git Repositories view in Eclipse and click the Clone Git Repository icon | *Open the Git Repositories view in Eclipse and click the Clone Git Repository icon | ||
*Use git://git.eclipse.org/gitroot/lyo/org.eclipse.lyo.core.git as the URI (browse it also on line). User/Password are not required. | *Use git://git.eclipse.org/gitroot/lyo/org.eclipse.lyo.core.git as the URI (browse it also on line). User/Password are not required. | ||
− | *On the Branch Selection page, select the master branch | + | *On the Branch Selection page, select [http://wiki.eclipse.org/index.php?title=Lyo/TRSSDKPreview trs-0.5] for the 0.5 release or the master branch for the latest release. Master is recommended unless there is a specific need for the 0.5 release.<br> |
*On the Local Destination page, specify a location or accept the default and click Finish | *On the Local Destination page, specify a location or accept the default and click Finish | ||
Line 31: | Line 33: | ||
<br> | <br> | ||
− | === Import Eclipse projects from the git repository === | + | === Clone the Lyo Testsuite git repository === |
+ | |||
+ | *Repeat the above steps using git://git.eclipse.org/gitroot/lyo/org.eclipse.lyo.testsuite.git as the repository URL. | ||
+ | |||
+ | This should load a second org.eclipse.lyo.testsuite repository into your Git Repositories view. | ||
+ | |||
+ | <br> | ||
+ | |||
+ | === Import Eclipse projects from the Lyo Core git repository === | ||
*In the Git Repositories view, right click org.eclipse.lyo.core and select Import Projects | *In the Git Repositories view, right click org.eclipse.lyo.core and select Import Projects | ||
Line 37: | Line 47: | ||
*Import the following projects: | *Import the following projects: | ||
− | | + | org.eclipse.lyo.oslc4j.core |
− | | + | org.eclipse.lyo.oslc4j.provider.jena |
− | | + | org.eclipse.lyo.oslc4j.provider.json4j |
− | | + | org.eclipse.lyo.oslc4j.wink |
org.eclipse.lyo.core.utils | org.eclipse.lyo.core.utils | ||
Line 53: | Line 63: | ||
[Optional] Add the projects to a new working set. | [Optional] Add the projects to a new working set. | ||
− | + | <br> | |
− | *Expand the | + | === Import the TRS compliance test suite from the Lyo Testsuite git repository === |
+ | |||
+ | *In the Git Repositories view, right click org.eclipse.lyo.testsuite and select Import Projects | ||
+ | *Select the Import Existing Projects wizard and click Next | ||
+ | *Import the org.eclipse.lyo.testsuite.trs projects. | ||
+ | |||
+ | <br> | ||
+ | |||
+ | === Build all projects === | ||
+ | |||
+ | *Expand the org.eclipse.lyo.oslc4j.core project | ||
*Right click pom.xml -> Run As -> Maven clean | *Right click pom.xml -> Run As -> Maven clean | ||
*Right click pom.xml -> Run As -> Maven install | *Right click pom.xml -> Run As -> Maven install | ||
*Repeat these steps for the following projects in the listed order: | *Repeat these steps for the following projects in the listed order: | ||
− | + | org.eclipse.lyo.oslc4j.provider.jena | |
− | <br> | + | org.eclipse.lyo.oslc4j.provider.json4j |
+ | |||
+ | org.eclipse.lyo.oslc4j.wink | ||
+ | |||
+ | org.eclipse.lyo.core.utils | ||
+ | |||
+ | org.eclipse.lyo.core.trs | ||
+ | |||
+ | org.eclipse.lyo.testsuite.trs | ||
+ | |||
+ | <br> | ||
+ | |||
+ | '''Mac Users''': If build fails with "Unable to find javadoc command", you can get around that by adding the below to your pom.xml files. See [http://mgorski.net/2013/dev/fail-to-execute-javadoc-plugin-on-mac-osx-java_home-issue this page]. | ||
+ | <pre> <properties> | ||
+ | <javadocExecutable>${java.home}/../bin/javadoc</javadocExecutable> | ||
+ | </properties></pre> | ||
== Exploring the TRS Toolkit == | == Exploring the TRS Toolkit == | ||
− | + | Under most circumstances the best way to learn how to use the TRS Toolkit is through exploring the TRS reference application (continue on to next section). However, some additional details concerning the TRS Toolkit may be found on the [[Lyo/TRSToolkit|Exploring the TRS Toolkit]] page. | |
− | + | <br> | |
− | + | ||
− | In | + | = TRS Reference Application = |
+ | |||
+ | The reference application is written in Java and demonstrates the implementation of a TRS Provider using change requests as the resources that are being created, modified and deleted. There are two implementations. In one implementation, JAX-RS, an annotation based Java RESTful specification, and Apache Wink, a JAX-RS server side component, are used to define and serve up the TRS provider endpoints. In the other implementation, a generic web sevlet approach is used. Both are described in detail in the guided tour section.<br> | ||
+ | |||
+ | While this reference application depends on certain technlogoies, the core TRS concepts demonstrated within may be applied to other languages, frameworks, and resource domains. | ||
+ | |||
+ | In addition to this reference application, consider exploring the [http://wiki.eclipse.org/Lyo/BuildTRS4JBugzilla Bugzilla TRS Reference Application] which also makes use of the TRS SDK described previously. | ||
<br> | <br> | ||
− | + | == Learning Objectives == | |
− | + | <span style="line-height: 1.5em;">By working through the material for the TRS Reference Application, you will learn how to perform the following tasks:</span> | |
− | * | + | |
− | * | + | *Use the TRS toolkit to create a TRS provider using JAX-RS or servlets<br> |
− | * | + | *Configure and use the TRS compliance test suite to verify the validity of a TRS provider<br> |
− | * | + | |
− | * | + | <br> |
− | * | + | |
− | * | + | == <span style="line-height: 1.5em;">TRS Reference Application Prerequisites</span> == |
− | * | + | |
+ | *The TRS Reference Application saves change requests to c:\temp\ChangeRequests.xml in the 0.5 release. In the 2.0 release the file, as well as a ChangeEvents.xml file containing persisited change events, is saved to the current working directory. This is often <local Rio Git repository>\org.eclipse.lyo.rio\org.eclipse.lyo.rio.trs . Ensure that you have write access to this file(s). In the 0.5 release if you want to change the default location, you can open up the org.eclipse.lyo.rio.trs.Constants.java file and change the PATH_FLAT_FILE location to point to a location of your choosing. (Don't forget to do a manual Maven build afterward!). In the 2.0 release, alter the ChangeRequestsFile and ChangeEventsFile entries in '''org.eclipse.lyo.rio.trs/src/main/resources'''/'''congfig.properties''' to controll where the files are generated. A new maven build is not required for the 2.0 release.<br> | ||
+ | *Before following the steps in the following sections please make sure the TRS Toolkit from section 2.1 has been loaded into your workspace. | ||
+ | |||
+ | <br> | ||
+ | |||
+ | == Loading the TRS Reference Application == | ||
+ | |||
+ | === Clone the Lyo Rio git repository === | ||
+ | |||
+ | This example assumes EGit is being used. | ||
+ | |||
+ | *Open the Git Repositories view in Eclipse and click the Clone Git Repository icon | ||
+ | *Usegit://git.eclipse.org/gitroot/lyo/org.eclipse.lyo.rio.git as the URI (browse it also on line). User/Password are not required. | ||
+ | *On the Branch Selection page, select [http://wiki.eclipse.org/index.php?title=Lyo/TRSSDKPreview trs-0.5] for the 0.5 release or the master branch for the latest release. Master is recommended unless there is a specific need for the 0.5 release. | ||
+ | *On the Local Destination page, specify a location or accept the default and click Finish | ||
+ | |||
+ | The repository should now show up in your Git Repositories view. | ||
<br> | <br> | ||
− | = TRS Reference Application = | + | === Import Eclipse projects from the git repository === |
+ | |||
+ | *In the Git Repositories view, right click org.eclipse.lyo.rio and select Import Projects | ||
+ | *Select the Import Existing Projects wizard and click Next | ||
+ | *Import the org.eclipse.lyo.rio.trs project<br><br> | ||
+ | |||
+ | == Building and Running the TRS Reference Application == | ||
+ | |||
+ | *Expand the org.eclipse.lyo.rio.trs project | ||
+ | *Right click pom.xml -> Run As -> Maven clean | ||
+ | *Right click pom.xml -> Run As -> Maven install | ||
+ | |||
+ | Once the build completes, right-click Launch TRS Reference App.launch and click Run As -> Launch TRS Reference App. | ||
+ | |||
+ | The reference application is launched within an embedded Jetty server and the message "TRS Reference Application launched at http://localhost:8082/org.eclipse.lyo.rio.trs/index.html" is displayed in the Console view. The link in the message opens a web page that describes the various links that are available in the reference application. | ||
+ | |||
+ | <br> | ||
+ | |||
+ | == TRS Reference Application Guided Tour == | ||
− | + | For a walkthrough of the TRS reference application and its capabilities please see the [[Lyo/TRSReferenceApplication|TRS reference application guided tour]]. | |
− | + | = Bugzilla TRS Reference Application = | |
+ | In addition to the reference application described on this page consider exploring the [http://wiki.eclipse.org/Lyo/BuildTRS4JBugzilla Bugzilla TRS Reference Application] which also makes use of the TRS SDK. |
Revision as of 12:39, 25 November 2013
The Tracked Resource Set (TRS) Software Development Kit (SDK) consists of two primary pieces; a toolkit and reference applications.
Contents
TRS SDK Prerequisites
- Eclipse 3.6 or higher IDE
- EGit team provider for git (recommended) or git command line package.
- m2eclipse for Maven support in the Eclipse IDE
- The Lyo projects requires a Java 1.6 compiler and Java 1.6 runtime. The Eclipse project settings have been set appropriately. If you are building outside of Eclipse, please use Java 1.6.
TRS Toolkit
The goal of the TRS toolkit is to provide a simple set of java beans that represent the entities within the TRS specification. Also, a convenient set of string constants that represent the TRS properties is provided. In addition to these code components which can be used to create TRS implementations, a test suite component exists. The test suite consists of a series of JUnit compliance tests which validate a TRS endpoint conforms to the TRS specification.
Loading the TRS Toolkit
Clone the Lyo Core git repository
This example assumes EGit is being used.
- Open the Git Repositories view in Eclipse and click the Clone Git Repository icon
- Use git://git.eclipse.org/gitroot/lyo/org.eclipse.lyo.core.git as the URI (browse it also on line). User/Password are not required.
- On the Branch Selection page, select trs-0.5 for the 0.5 release or the master branch for the latest release. Master is recommended unless there is a specific need for the 0.5 release.
- On the Local Destination page, specify a location or accept the default and click Finish
The repository should now show up in your Git Repositories view.
Clone the Lyo Testsuite git repository
- Repeat the above steps using git://git.eclipse.org/gitroot/lyo/org.eclipse.lyo.testsuite.git as the repository URL.
This should load a second org.eclipse.lyo.testsuite repository into your Git Repositories view.
Import Eclipse projects from the Lyo Core git repository
- In the Git Repositories view, right click org.eclipse.lyo.core and select Import Projects
- Select the Import Existing Projects wizard and click Next
- Import the following projects:
org.eclipse.lyo.oslc4j.core
org.eclipse.lyo.oslc4j.provider.jena
org.eclipse.lyo.oslc4j.provider.json4j
org.eclipse.lyo.oslc4j.wink
org.eclipse.lyo.core.utils
org.eclipse.lyo.core.trs
You may import the other projects if you like, but they are not required for building the TRS Toolkit.
[Optional] Add the projects to a new working set.
Import the TRS compliance test suite from the Lyo Testsuite git repository
- In the Git Repositories view, right click org.eclipse.lyo.testsuite and select Import Projects
- Select the Import Existing Projects wizard and click Next
- Import the org.eclipse.lyo.testsuite.trs projects.
Build all projects
- Expand the org.eclipse.lyo.oslc4j.core project
- Right click pom.xml -> Run As -> Maven clean
- Right click pom.xml -> Run As -> Maven install
- Repeat these steps for the following projects in the listed order:
org.eclipse.lyo.oslc4j.provider.jena
org.eclipse.lyo.oslc4j.provider.json4j
org.eclipse.lyo.oslc4j.wink
org.eclipse.lyo.core.utils
org.eclipse.lyo.core.trs
org.eclipse.lyo.testsuite.trs
Mac Users: If build fails with "Unable to find javadoc command", you can get around that by adding the below to your pom.xml files. See this page.
<properties> <javadocExecutable>${java.home}/../bin/javadoc</javadocExecutable> </properties>
Exploring the TRS Toolkit
Under most circumstances the best way to learn how to use the TRS Toolkit is through exploring the TRS reference application (continue on to next section). However, some additional details concerning the TRS Toolkit may be found on the Exploring the TRS Toolkit page.
TRS Reference Application
The reference application is written in Java and demonstrates the implementation of a TRS Provider using change requests as the resources that are being created, modified and deleted. There are two implementations. In one implementation, JAX-RS, an annotation based Java RESTful specification, and Apache Wink, a JAX-RS server side component, are used to define and serve up the TRS provider endpoints. In the other implementation, a generic web sevlet approach is used. Both are described in detail in the guided tour section.
While this reference application depends on certain technlogoies, the core TRS concepts demonstrated within may be applied to other languages, frameworks, and resource domains.
In addition to this reference application, consider exploring the Bugzilla TRS Reference Application which also makes use of the TRS SDK described previously.
Learning Objectives
By working through the material for the TRS Reference Application, you will learn how to perform the following tasks:
- Use the TRS toolkit to create a TRS provider using JAX-RS or servlets
- Configure and use the TRS compliance test suite to verify the validity of a TRS provider
TRS Reference Application Prerequisites
- The TRS Reference Application saves change requests to c:\temp\ChangeRequests.xml in the 0.5 release. In the 2.0 release the file, as well as a ChangeEvents.xml file containing persisited change events, is saved to the current working directory. This is often <local Rio Git repository>\org.eclipse.lyo.rio\org.eclipse.lyo.rio.trs . Ensure that you have write access to this file(s). In the 0.5 release if you want to change the default location, you can open up the org.eclipse.lyo.rio.trs.Constants.java file and change the PATH_FLAT_FILE location to point to a location of your choosing. (Don't forget to do a manual Maven build afterward!). In the 2.0 release, alter the ChangeRequestsFile and ChangeEventsFile entries in org.eclipse.lyo.rio.trs/src/main/resources/congfig.properties to controll where the files are generated. A new maven build is not required for the 2.0 release.
- Before following the steps in the following sections please make sure the TRS Toolkit from section 2.1 has been loaded into your workspace.
Loading the TRS Reference Application
Clone the Lyo Rio git repository
This example assumes EGit is being used.
- Open the Git Repositories view in Eclipse and click the Clone Git Repository icon
- Usegit://git.eclipse.org/gitroot/lyo/org.eclipse.lyo.rio.git as the URI (browse it also on line). User/Password are not required.
- On the Branch Selection page, select trs-0.5 for the 0.5 release or the master branch for the latest release. Master is recommended unless there is a specific need for the 0.5 release.
- On the Local Destination page, specify a location or accept the default and click Finish
The repository should now show up in your Git Repositories view.
Import Eclipse projects from the git repository
- In the Git Repositories view, right click org.eclipse.lyo.rio and select Import Projects
- Select the Import Existing Projects wizard and click Next
- Import the org.eclipse.lyo.rio.trs project
Building and Running the TRS Reference Application
- Expand the org.eclipse.lyo.rio.trs project
- Right click pom.xml -> Run As -> Maven clean
- Right click pom.xml -> Run As -> Maven install
Once the build completes, right-click Launch TRS Reference App.launch and click Run As -> Launch TRS Reference App.
The reference application is launched within an embedded Jetty server and the message "TRS Reference Application launched at http://localhost:8082/org.eclipse.lyo.rio.trs/index.html" is displayed in the Console view. The link in the message opens a web page that describes the various links that are available in the reference application.
TRS Reference Application Guided Tour
For a walkthrough of the TRS reference application and its capabilities please see the TRS reference application guided tour.
Bugzilla TRS Reference Application
In addition to the reference application described on this page consider exploring the Bugzilla TRS Reference Application which also makes use of the TRS SDK.