APPLICATION_DEVELOPMENT.md tweaks
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 @@
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 @@
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 @@
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 @@
the dependencies directly from a remote maven repository such as
maven central.
-Here are three options for dealing with this:
+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.
+### 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 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.
+The uber jar contains the application's classes and
+the application's dependent Edgent classes and their
+transitive dependencies.
-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 samples poms contain configuration information
+that generates an uber jar in addition to the standard
+application jar. Eclipse can also export an uber jar.
- The Edgent supplied package-app.sh tool supports this mode.
- Eclipse can also export a similar collection
- of information.
+### Create an application package bundle
-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 bundle is a standalone entity containing
+everything that's needed to run your application.
- 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.
+The bundle contains the application's jar
+and the application's dependent Edgent jars and their
+transitive dependencies.
-##get-edgent-jars.sh
+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
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 @@
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 @@
```
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 @@
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 @@
For more usage information:
-```sh
+``` sh
package-app.sh -h
```
