You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@edgent.apache.org by cd...@apache.org on 2017/11/21 11:50:59 UTC
[19/50] incubator-edgent-samples git commit:
APPLICATION_DEVELOPMENT.md tweaks
APPLICATION_DEVELOPMENT.md tweaks
Project: http://git-wip-us.apache.org/repos/asf/incubator-edgent-samples/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-edgent-samples/commit/0b4b3130
Tree: http://git-wip-us.apache.org/repos/asf/incubator-edgent-samples/tree/0b4b3130
Diff: http://git-wip-us.apache.org/repos/asf/incubator-edgent-samples/diff/0b4b3130
Branch: refs/heads/develop
Commit: 0b4b31305f69a8bed92fb054095ddb69e63b64f6
Parents: d6d7285
Author: Dale LaBossiere <dl...@us.ibm.com>
Authored: Tue Sep 26 17:16:04 2017 -0400
Committer: Dale LaBossiere <dl...@us.ibm.com>
Committed: Tue Sep 26 17:16:04 2017 -0400
----------------------------------------------------------------------
APPLICATION_DEVELOPMENT.md | 142 ++++++++++++++++++++++------------------
1 file changed, 78 insertions(+), 64 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-edgent-samples/blob/0b4b3130/APPLICATION_DEVELOPMENT.md
----------------------------------------------------------------------
diff --git a/APPLICATION_DEVELOPMENT.md b/APPLICATION_DEVELOPMENT.md
index 9199c94..44e3230 100644
--- a/APPLICATION_DEVELOPMENT.md
+++ b/APPLICATION_DEVELOPMENT.md
@@ -15,12 +15,12 @@
limitations under the License.
-->
-#Edgent Application Development, Packaging and Execution.
+# Edgent Application Development, Packaging and Execution.
This file is a work-in-progress.
To develop Edgent applications you will utilize the
-Edgent SDK/runtime jars, package your application
+Edgent SDK/runtime jars and package your application
artifacts for deploying to an edge device for execution.
The Edgent SDK/runtime jars are published to maven-central.
@@ -28,13 +28,19 @@ Alternatively, you can build the Edgent SDK yourself from a source release
and the resulting jars will be added to your local maven repository.
There are a set of Edgent jars for each supported platform: java8, java7, and android.
-The artifact groupId prefix is: org.apache.edgent (for java8),
-org.apache.edgent.java7 and org.apache.edgent.android. e.g.
- org.apache.edgent.api org.apache.edgent.api.java7
+The maven artifact groupId prefixes are:
-See `JAVA_SUPPORT.md` for more information on coordinates, etc.
+- `org.apache.edgent` - for java8,
+- `org.apache.edgent.java7`
+- `org.apache.edgent.android`
-The Edgent API is most easily used by using java8 lambda expressions.
+e.g., the groupIds for the Edgent API artifacts are
+`org.apache.edgent.api` and `org.apache.edgent.api.java7` for
+Java 8 and Java 7 respectively.
+
+See `JAVA_SUPPORT.md` for more information on artifact coordinates, etc.
+
+The Edgent API is most easily used by using Java8 lambda expressions.
If you only want to deploy your Edgent application to a java8 environment
then your application may use any java8 features it chooses. You compile
and run against the Edgent java8 jars.
@@ -45,23 +51,26 @@ with java8 lambda expressions. You compile with java8 but constrain
your application to using java7 features plus java8 lambda expressions.
The Retrolambda tool is used to convert your application's generated
class files to java7.
-(the java7 and android Edgent jars were created in that manner too)
+The Edgent java7 and android platform jars were created in that manner too.
Your application would then be run against the appropriate
-Edgent platform jars. Alternatively you can forgo the use of lambda
+Edgent platform jars.
+
+Alternatively you can forgo the use of lambda
expressions and write your application in java7 and compile
and run against the appropriate Edgent platform jars.
-For convenience it's easiest to build your Edgent applcation using
+For convenience it's easiest to build your Edgent application using
maven-repository-enabled build tooling (e.g., maven, maven-enabled
Eclipse or IntelliJ). The tooling transparently downloads the
-required Edgent jars from the maven repository.
+required Edgent jars from the maven repository if they aren't
+already present in your local maven repository.
The supplied Edgent samples poms include support for building for
-a java8, java7 or android execution environent. The poms are
+a java8, java7 or android execution environment. The poms are
configured for the generation of a standard jar as well as an
uber jar for a sample application.
-You can clone the samples/template project as a starting point
+You can clone the `samples/template` project as a starting point
for your Edgent application. See `samples/template/README.md`.
TODO: we would like to provide a maven Edgent Application archetype
@@ -70,14 +79,14 @@ that users can use to create an application project template.
If you can't or don't want to use maven-repository-enabled tooling
you will need to get a local copy of the Edgent jars and their
dependencies and add them to your compile classpath.
-The Edgent supplied get-edgent-jars.sh tool can be used to
+The Edgent supplied `get-edgent-jars.sh` tool can be used to
get copies of the jars from a maven repository.
-##Packaging and Execution
+## Packaging and Execution
Edgent doesn't provide any "deployment" mechanisms other than its primitive
-"register jar" feature (see the IotProvider javadoc). Generally, managing
+"register jar" feature (see the `IotProvider` javadoc). Generally, managing
the deployment of application and Edgent jars to edge devices is left to
others (as an example, the IBM Watson IoT Platform has device APIs to
support "firmware" download/update).
@@ -89,50 +98,56 @@ be on the device. It's unlikely the device will be able to retrieve
the dependencies directly from a remote maven repository such as
maven central.
-Here are three options for dealing with this:
-
-a) construct an uber-jar for your application.
- The uber jar contains the application's classes and
- the application's dependent Edgent classes and their
- transitive dependencies.
-
- The uber jar is a standalone entity containing
- everything that's needed to run your application.
-
- The Edgent samples poms contain configuration information
- that generates an uber jar in addition to the standard
- application jar. Eclipse can also export an uber jar.
-
-b) create an application package bundle.
- The bundle contains the application's jar
- and the application's dependent Edgent jars and their
- transitive dependencies.
- The bundle is copied to the device and unpacked.
- A run script forms the appropriate CLASSPATH
- to the package's jars and starts the application.
-
- The Edgent supplied package-app.sh tool supports this mode.
- Eclipse can also export a similar collection
- of information.
-
-c) separately manage the application's jars and the
- Edgent jars and their dependencies.
- Copy the application's jars to the device.
- Get a copy of the Edgent jars and their dependencies
- onto the device to be shared by any Edgent applications
- that want to use them.
-
- The Apache Edgent project does not release a
- binary bundle containing all of the Edgent jars
- and their dependencies. The binary artifacts
- are only released to maven central.
-
- The Edgent supplied get-edgent-jars.sh tool supports this mode.
+Here are three options for dealing with this.
+
+### Create an uber-jar for your application
+
+The uber jar is a standalone entity containing
+everything that's needed to run your application.
+
+The uber jar contains the application's classes and
+the application's dependent Edgent classes and their
+transitive dependencies.
+
+The Edgent samples poms contain configuration information
+that generates an uber jar in addition to the standard
+application jar. Eclipse can also export an uber jar.
+
+### Create an application package bundle
+
+The bundle is a standalone entity containing
+everything that's needed to run your application.
+
+The bundle contains the application's jar
+and the application's dependent Edgent jars and their
+transitive dependencies.
+
+The bundle is copied to the device and unpacked.
+A run script forms the appropriate `CLASSPATH`
+to the package's jars and starts the application.
+
+The Edgent supplied `package-app.sh` tool supports this mode.
+Eclipse can also export a similar collection
+of information.
+
+### Separately manage the application and Edgent jars
+
+Copy the application's jars to the device.
+Get a copy of the Edgent jars and their dependencies
+onto the device to be shared by any Edgent applications
+that want to use them.
+
+The Apache Edgent project does not release a
+binary bundle containing all of the Edgent jars
+and their dependencies. The binary artifacts
+are only released to maven central.
+
+The Edgent supplied get-edgent-jars.sh tool supports this mode.
-##get-edgent-jars.sh
+## get-edgent-jars.sh
The `get-edgent-jars.sh` script copies the Edgent runtime jars and their
-dependencies from a local or remote maven repository.
+dependencies from a local or remote maven repository into a local folder.
The user may then directly use the jars in CLASSPATH specifications
for Edgent application compilation or execution.
@@ -144,7 +159,7 @@ script's default Edgent version.
The script creates and builds a small maven project as
part of its execution.
-```sh
+``` sh
get-edgent-jars.sh --version 1.2.0-SNAPSHOT # retrieve the Edgent 1.2.0-SNAPSHOT java8 jars
This command downloads the Apache Edgent jars and their transitive external dependencies.
The external dependencies have their own licensing term that you should review.
@@ -164,12 +179,11 @@ Continue? [y/n] y
```
For more usage information:
-
-```sh
+``` sh
get-edgent-jars.sh -h
```
-##package-app.sh
+## package-app.sh
The `package-app.sh` script creates an application bundle.
The application bundle can be copied to an edge-device,
@@ -195,8 +209,8 @@ the application.
E.g.,
-```sh
-cd MyApp # the project directory
+``` sh
+cd MyApp # the application's project directory
package-app.sh --mainClass com.mycompany.app.MyApp --appjar target/my-app-1.0-SNAPSHOT.jar
##### get the app specific dependencies...
...
@@ -211,6 +225,6 @@ package-app.sh --mainClass com.mycompany.app.MyApp --appjar target/my-app-1.0-SN
For more usage information:
-```sh
+``` sh
package-app.sh -h
```