[WIP] changes for Edgent PR-309 (maven)
- rework downloads page for changes is distributing samples/binaries
- rework Getting Started Guide, preserve old as old-edgent-getting-started and link to it
- Add Quickstart with Edgent Samples, rename samples page to old-samples and link to it from old getting started only
- Add Edgent Application Development
- update FAQ
- update LHS Navigation sidebar (adjust for above)
- update Top navigation bar (adjust for above)
diff --git a/site/_data/downloads.yml b/site/_data/downloads.yml
index 8ca5010..4a58c75 100644
--- a/site/_data/downloads.yml
+++ b/site/_data/downloads.yml
@@ -33,7 +33,7 @@
edgent_1-0-0_bin_asc_location: 'https://archive.apache.org/dist/incubator/edgent/1.0.0-incubating/binaries/apache-edgent-1.0.0-incubating-bin.tgz.asc'
edgent_1-0-0_bin_md5_location: 'https://archive.apache.org/dist/incubator/edgent/1.0.0-incubating/binaries/apache-edgent-1.0.0-incubating-bin.tgz.md5'
edgent_1-0-0_bin_sha_location: 'https://archive.apache.org/dist/incubator/edgent/1.0.0-incubating/binaries/apache-edgent-1.0.0-incubating-bin.tgz.sha'
-
+
edgent_1-1-0_release_note: 'https://www.apache.org/dist/incubator/edgent/1.1.0-incubating/RELEASE_NOTES'
edgent_1-1-0_doc_location: 'https://edgent.incubator.apache.org/javadoc/r1.1.0/index.html'
edgent_1-1-0_dist_location: 'https://www.apache.org/dyn/closer.cgi/incubator/edgent/1.1.0-incubating'
@@ -44,3 +44,22 @@
edgent_1-1-0_bin_asc_location: 'https://www.apache.org/dist/incubator/edgent/1.1.0-incubating/binaries/apache-edgent-1.1.0-incubating-bin.tgz.asc'
edgent_1-1-0_bin_md5_location: 'https://www.apache.org/dist/incubator/edgent/1.1.0-incubating/binaries/apache-edgent-1.1.0-incubating-bin.tgz.md5'
edgent_1-1-0_bin_sha_location: 'https://www.apache.org/dist/incubator/edgent/1.1.0-incubating/binaries/apache-edgent-1.1.0-incubating-bin.tgz.sha'
+
+edgent_1-2-0_doc_location: 'https://edgent.incubator.apache.org/javadoc/r1.2.0/index.html'
+edgent_1-2-0_java_support_doc_location: 'https://github.com/apache/incubator-edgent/blob/master/JAVA_SUPPORT.md'
+edgent_1-2-0_release_note: 'https://www.apache.org/dist/incubator/edgent/1.2.0-incubating/RELEASE_NOTES'
+edgent_1-2-0_dist_location: 'https://www.apache.org/dyn/closer.cgi/incubator/edgent/1.2.0-incubating'
+edgent_1-2-0_asc_location: 'https://www.apache.org/dist/incubator/edgent/1.2.0-incubating/apache-edgent-1.2.0-incubating-source-release.tar.gz.asc'
+edgent_1-2-0_md5_location: 'https://www.apache.org/dist/incubator/edgent/1.2.0-incubating/apache-edgent-1.2.0-incubating-source-release.tar.gz.md5'
+edgent_1-2-0_sha_location: 'https://www.apache.org/dist/incubator/edgent/1.2.0-incubating/apache-edgent-1.2.0-incubating-source-release.tar.gz.sha'
+edgent_1-2-0_zip_asc_location: 'https://www.apache.org/dist/incubator/edgent/1.2.0-incubating/apache-edgent-1.2.0-incubating-source-release.zip.asc'
+edgent_1-2-0_zip_md5_location: 'https://www.apache.org/dist/incubator/edgent/1.2.0-incubating/apache-edgent-1.2.0-incubating-source-release.zip.md5'
+edgent_1-2-0_zip_sha_location: 'https://www.apache.org/dist/incubator/edgent/1.2.0-incubating/apache-edgent-1.2.0-incubating-source-release.zip.sha'
+edgent_1-2-0_samples_release_note: 'https://www.apache.org/dist/incubator/edgent/1.2.0-incubating/RELEASE_NOTES'
+edgent_1-2-0_samples_dist_location: 'https://www.apache.org/dyn/closer.cgi/incubator/edgent/1.2.0-incubating'
+edgent_1-2-0_samples_asc_location: 'https://www.apache.org/dist/incubator/edgent/1.2.0-incubating/apache-edgent-1.2.0-incubating-samples-source-release.tar.gz.asc'
+edgent_1-2-0_samples_md5_location: 'https://www.apache.org/dist/incubator/edgent/1.2.0-incubating/apache-edgent-1.2.0-incubating-samples-source-release.tar.gz.md5'
+edgent_1-2-0_samples_sha_location: 'https://www.apache.org/dist/incubator/edgent/1.2.0-incubating/apache-edgent-1.2.0-incubating-samples-source-release.tar.gz.sha'
+edgent_1-2-0_samples_zip_asc_location: 'https://www.apache.org/dist/incubator/edgent/1.2.0-incubating/apache-edgent-1.2.0-incubating-samples-source-release.zip.asc'
+edgent_1-2-0_samples_zip_md5_location: 'https://www.apache.org/dist/incubator/edgent/1.2.0-incubating/apache-edgent-1.2.0-incubating-samples-source-release.zip.md5'
+edgent_1-2-0_samples_zip_sha_location: 'https://www.apache.org/dist/incubator/edgent/1.2.0-incubating/apache-edgent-1.2.0-incubating-samples-source-release.zip.sha'
diff --git a/site/_data/mydoc/mydoc_sidebar.yml b/site/_data/mydoc/mydoc_sidebar.yml
index 3772d02..5b307c6 100644
--- a/site/_data/mydoc/mydoc_sidebar.yml
+++ b/site/_data/mydoc/mydoc_sidebar.yml
@@ -81,7 +81,7 @@
version: all
output: web, pdf
- - title: Getting started guide
+ - title: Getting Started Guide
url: /docs/edgent-getting-started.html
audience: writers, designers
platform: all
@@ -89,6 +89,30 @@
version: all
output: web, pdf
+ - title: Quickstart with Edgent Samples
+ url: /docs/edgent-getting-started-samples.html
+ audience: writers, designers
+ platform: all
+ product: all
+ version: all
+ output: web, pdf
+
+ - title: Understanding App Development
+ url: /docs/application-development.html
+ audience: writers, designers
+ platform: all
+ product: all
+ version: all
+ output: web, pdf
+
+ - title: Quickstart IBM Watson IoT Platform
+ url: /docs/quickstart.html
+ audience: writers, designers
+ platform: all
+ product: all
+ version: all
+ output: web, pdf
+
- title: Streaming concepts
url: /docs/streaming-concepts.html
audience: writers, designers
@@ -217,29 +241,6 @@
version: all
output: web, pdf
- - title: Sample Programs
- audience: writers, designers
- platform: all
- product: all
- version: all
- output: web, pdf
- items:
- - title: Samples
- url: /docs/samples.html
- audience: writers, designers
- platform: all
- product: all
- version: all
- output: web, pdf
-
- - title: Quickstart IBM Watson IoT Platform
- url: /docs/quickstart.html
- audience: writers, designers
- platform: all
- product: all
- version: all
- output: web, pdf
-
- title: Using the Console
audience: writers, designers
platform: all
diff --git a/site/_data/mydoc/mydoc_topnav.yml b/site/_data/mydoc/mydoc_topnav.yml
index 5c47f51..0653915 100644
--- a/site/_data/mydoc/mydoc_topnav.yml
+++ b/site/_data/mydoc/mydoc_topnav.yml
@@ -111,14 +111,6 @@
version: all
output: web
- - title: Samples
- url: samples
- audience: writers, designers
- platform: all
- product: all
- version: all
- output: web
-
- title: FAQ
url: faq
audience: writers, designers
diff --git a/site/_includes/header.html b/site/_includes/header.html
index 73a2290..4bec711 100755
--- a/site/_includes/header.html
+++ b/site/_includes/header.html
@@ -86,7 +86,6 @@
<ul class="dropdown-menu">
<li><a href="docs/edgent-getting-started">Getting Started Guide</a></li>
<li><a href="docs/downloads">Downloads</a></li>
- <li><a href="docs/samples">Sample Programs</a></li>
<li><a href="docs/faq">FAQ</a></li>
</ul>
diff --git a/site/docs/application-development.md b/site/docs/application-development.md
new file mode 100644
index 0000000..4ccf482
--- /dev/null
+++ b/site/docs/application-development.md
@@ -0,0 +1,174 @@
+---
+title: Edgent Application Development, Packaging and Execution.
+---
+
+To develop Edgent applications you will utilize the
+Edgent SDK/runtime jars and package your application
+artifacts for deploying to an edge device or gateway for execution.
+
+The Edgent SDK/runtime jars are published to the
+[ASF Nexus Releases Repository](https://repository.apache.org/content/repositories/releases/)
+and the Maven Central Repository.
+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 maven artifact groupIds for the Edgent jars are:
+
+- `org.apache.edgent` - for java8,
+- `org.apache.edgent.java7`
+- `org.apache.edgent.android`
+
+Note, the Java package names for Edgent components do not incorporate
+the platform kind; the package names are the same regardless of the platform.
+
+See the release's `JAVA_SUPPORT` information in [downloads](downloads)
+for more information on artifact coordinates, etc.
+
+## Writing Your Application
+
+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.
+
+If you want to deploy your Edgent application to a java7 or android
+environment, it's still easiest to write your application using the Edgent APIs
+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 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
+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 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 if they aren't
+already present in your local maven repository.
+
+### Edgent Application Template
+
+You can clone the `template` project as a starting point for your
+Edgent application. See [Quickstart with Edgent Samples](edgent-getting-started-samples)
+for information about the template sample.
+
+TODO: we would like to provide a maven Edgent Application archetype
+that users can use to create an application project template.
+
+### Using Non-maven-integrated Tooling
+
+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. This case
+is covered in subsequent sections.
+
+## Packaging and Execution
+
+Edgent doesn't provide any "deployment" mechanisms other than its primitive
+"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).
+
+To deploy an Edgent application to a device like a Raspberry Pi,
+you could just FTP the application to the device and modify the
+device to start the application upon startup or on command.
+Also see the `cron` folder in the Edgent samples.
+
+To run your Edgent application on an edge device, your application
+jar(s) need to be on the device. Additionally, the application's
+dependent Edgent jars (and their transitive dependencies) need to
+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.
+
+### Option 1: 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 template project's pom and
+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.
+
+You run your application like:
+ `java -cp <path-to-uber-jar> <full-classname-of-main-class>`
+
+### Option 2: 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. It's possible for multiple Edgent
+applications to share the Edgent jars.
+
+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.
+
+See `get-edgent-jars-project/README.md` in the Edgent samples
+for a tool to get a copy of the Edgent jars.
+
+### Option 3: Create an application package bundle
+
+The bundle is a standalone entity containing
+everything that's needed to run your application.
+
+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 `package-app.sh` script included with the
+Edgent samples creates an application bundle.
+
+The application bundle contains the application's jar,
+the application's dependent Edgent jars (as specified in
+the application's pom) and the Edgent jars' dependencies,
+and a run-app.sh script.
+
+The application's dependent Edgent runtime jars and
+their dependencies are retrieved from a local or remote
+maven repository.
+
+If the application's execution environment is
+java7 or android, use the appropriate script options
+to retrieve the appropriate Edgent platform jars for
+execution.
+
+The generated run-app.sh script configures the CLASSPATH
+and runs the application.
+
+E.g.,
+
+``` 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...
+...
+##### create target/app-run.sh...
+##### create target/app-pkg.tar...
+##### Copy target/app-pkg.tar to the destination system"
+##### To run the app:"
+##### mkdir app-pkg"
+##### tar xf app-pkg.tar -C app-pkg"
+##### (cd app-pkg; ./app-run.sh)"
+```
+
+For more usage information:
+
+``` sh
+./package-app.sh -h
+```
diff --git a/site/docs/downloads.md b/site/docs/downloads.md
index a2c3d37..0f01a97 100644
--- a/site/docs/downloads.md
+++ b/site/docs/downloads.md
@@ -2,9 +2,11 @@
title: Downloads
---
-Official Apache Edgent releases are available for download from the ASF distribution site. A release consists of a source code bundle and a convenience binary bundle. See the table below for a release's download links.
+Offical ASF Apache Edgent releases consist of source bundles and convenience binaries. There are two source bundles, one for the Edgent samples and one for the Edgent SDK/runtime. Convenience binary jars for the Edgent SDK/runtime are available at the [ASF Nexus Releases Repository](https://repository.apache.org/content/repositories/releases/) and Maven Central.
-If you just want to use Edgent, it is easiest to download and unpack a binary bundle. The bundle includes the release's Javadoc. The Javadoc is also accessible online. For more information, please refer to the [Getting started guide](edgent-getting-started).
+If you just want to use Edgent, simply download the Samples source bundle and use it to jump-start your application development, leveraging the distributed Edgent SDK/runtime jars. The samples source bundle includes additional information regarding application development and deployment, and tools. For more information, see [Quickstart with Edgent Samples](edgent-getting-started-samples).
+
+Note, a separate binary bundle consisting of all of the Edgent jars is not released. A tool is available in the samples source bundle that can create one.
A source bundle contains a README describing how to build the sources.
@@ -14,6 +16,31 @@
## Apache Edgent Releases
+| Version | Docs |
+|:-----------------:|:----:|
+| 1.2.0-incubating | [JAVA_SUPPORT]({{ site.data.downloads.edgent_1-2-0_java_support_doc_location }}), [Javadoc]({{ site.data.downloads.edgent_1-2-0_doc_location }}) |
+
+It is essential that you verify the integrity of a downloaded bundle. See [how to verify]({{ site.data.downloads.generic_how_to_verify_location }}) for details on verifying using downloaded KEYS, PGP signature, MD5, or SHA information.
+
+Download the [KEYS]({{ site.data.downloads.edgent_keys_file_location }}) file for verifying a bundle's PGP signature.
+
+| Version | Date | Bundles | Release Notes | PGP | MD5 | SHA |
+|:-----------------:|:--------------:|:-------:|:-------------:|:---:|:---:|:-----:|
+| 1.2.0-incubating | 2017-??-?? | [Samples]({{ site.data.downloads.edgent_1-2-0_samples_dist_location }}) | [1.2.0 Release]({{ site.data.downloads.edgent_1-2-0_samples_release_note }}) | [tar-ASC]({{ site.data.downloads.edgent_1-2-0_samples_asc_location }}) | [tar-MD5]({{ site.data.downloads.edgent_1-2-0_samples_md5_location }}) | [tar-SHA]({{ site.data.downloads.edgent_1-2-0_samples_sha_location }}) |
+| | | | | [zip-ASC]({{ site.data.downloads.edgent_1-2-0_samples_zip_asc_location }}) | [zip-MD5]({{ site.data.downloads.edgent_1-2-0_samples_zip_md5_location }}) | [zip-SHA]({{ site.data.downloads.edgent_1-2-0_samples_zip_sha_location }}) |
+| | | [Source]({{ site.data.downloads.edgent_1-2-0_dist_location }}) | [1.2.0 Release]({{ site.data.downloads.edgent_1-2-0_release_note }}) | [tar-ASC]({{ site.data.downloads.edgent_1-2-0_asc_location }}) | [tar-MD5]({{ site.data.downloads.edgent_1-2-0_md5_location }}) | [tar-SHA]({{ site.data.downloads.edgent_1-2-0_sha_location }}) |
+| | | | | [zip-ASC]({{ site.data.downloads.edgent_1-2-0_zip_asc_location }}) | [zip-MD5]({{ site.data.downloads.edgent_1-2-0_zip_md5_location }}) | [zip-SHA]({{ site.data.downloads.edgent_1-2-0_zip_sha_location }}) |
+
+## Releases Prior to 1.2.0
+
+Official Apache Edgent releases are available for download from the ASF distribution site. A release consists of a source code bundle and a convenience binary bundle. See the table below for a release's download links.
+
+There is not a separate samples source bundle and convenience binary jars are not distributed to the ASF Nexus Repository or Maven Central.
+
+If you just want to use Edgent, it is easiest to download and unpack a binary bundle. The bundle includes the release's Javadoc. The Javadoc is also accessible online. For more information, please refer to the [Getting started guide](edgent-getting-started).
+
+A source bundle contains a README describing how to build the sources.
+
It is essential that you verify the integrity of a downloaded bundle. See [how to verify]({{ site.data.downloads.generic_how_to_verify_location }}) for details on verifying using downloaded KEYS, PGP signature, MD5, or SHA information.
Download the [KEYS]({{ site.data.downloads.edgent_keys_file_location }}) file for verifying a bundle's PGP signature.
diff --git a/site/docs/edgent-getting-started-samples.md b/site/docs/edgent-getting-started-samples.md
new file mode 100644
index 0000000..bb5c337
--- /dev/null
+++ b/site/docs/edgent-getting-started-samples.md
@@ -0,0 +1,171 @@
+---
+title: Getting started with Apache Edgent Samples
+---
+
+Getting started with the Edgent samples is a great way to start using Edgent and
+jump-start your application development.
+
+Essentially, you download the samples source release, then easily build and
+run them from either the command line or from an IDE.
+
+Then, see the Additional Resources section at the end of this page!
+
+If you want more of an introduction to Edgent and tutorial first, see the [Getting Started Guide](edgent-getting-started).
+
+
+Convenience binaries (jars) for the Edgent runtime releases are distributed to the ASF Nexus Repository and the Maven Central Repository. There is no need to download the Edgent runtime sources and build them unless you want to. You don't have to manually download the Edgent jars either.
+
+By default the samples depend on Java8. Download and install Java8 if you need to.
+
+## Download the Edgent Samples
+
+1. Locate the Edgent samples release you would like to use at [downloads]({{ site.data.project.download }})
+2. In the Bundles column for the desired release:
+ * Click on the _Samples_ link
+3. Download the .tar.gz or zip file from one of the mirror sites
+4. Unpack the downloaded file using the appropriate one of:
+ * `tar zxvf apache-edgent-X.X.X-incubating-samples-source-release.tar.gz`
+ * `unzip apache-edgent-X.X.X-incubating-samples-source-release.zip`
+
+## Quickstart: Build and run samples from the command line
+
+You must have Java 8 installed on your system. Maven will be automatically
+downloaded and installed by the maven wrapper `mvnw`.
+
+In the unpacked samples folder...
+
+Build the samples for Java 8
+
+```sh
+./mvnw clean package
+```
+
+Run the HelloEdgent sample
+
+```sh
+cd topology
+./run-sample.sh HelloEdgent # prints a hello message and terminates
+ Hello
+ Edgent!
+ ...
+```
+
+### Cloning the template
+
+For your application project, you can clone the template project.
+In the unpacked samples folder
+
+```sh
+cp -R template ~/myApp
+```
+
+Verify the setup
+
+```sh
+cd ~/myApp
+./mvnw clean package
+./app-run.sh # prints a hello message
+```
+See `README.md` in the new project folder for more information.
+
+
+## Quickstart: Build and run samples from an IDE
+
+Here we'll use Eclipse for the development environment. Another popular choice is the maven-integrated IntelliJ IDE.
+
+See [eclipse.org](https://www.eclipse.org) if you need to download Eclipse.
+It's easiest if you choose a package that includes the Maven integration.
+Otherwise, update your Eclipse installation with the
+[Eclipse Maven Integration](https://projects.eclipse.org/projects/technology.m2e).
+
+This remainder of this getting started information assumes a basic understanding of Eclipse.
+
+Note: Specifics may change depending on your version of Eclipse or the
+Eclipse Maven plugin.
+
+Import the samples into your Eclipse workspace:
+
+ 1. From the Eclipse *File* menu, select *Import...*
+ 2. From the *Maven* folder, select *Existing Maven Projects* and click *Next*
+ + browse to the unpacked samples folder
+ and select it. A hierarchy of samples projects / pom.xml files will be
+ listed and all selected.
+ + verify the *Add project(s) to working set* checkbox is checked
+ + click *Finish*. Eclipse starts the import process and builds the workspace.
+
+Top-level artifacts such as the `README.md` file are available under the
+`edgent-samples` project.
+
+Once the samples have been imported you can run them from
+Eclipse in the usual manner. E.g.,
+
+1. From the Eclipse *Navigate* menu, select *Open Type*
+ + enter type type name `HelloEdgent` and click *OK*
+2. right click on the `HelloEdgent` class name and from the context menu
+ + click on *Run As*, then *Java application*.
+ `HelloEdgent` runs and prints to the Console view.
+
+
+### Cloning the template
+
+To clone the template project for your application project:
+
+1. Recursively copy the template folder into a new folder from the command line, e.g.,
+ from the unpacked samples folder
+ + cp -R template ~/myApp
+2. Import the new project into your Eclipse workspace
+ 1. from the Eclipse *File* menu, select *Import...*
+ 2. from the *Maven* folder, select *Existing Maven Projects* and click *Next*
+ + browse to the new folder and select it. The project's pom.xml file will be
+ listed and selected.
+ + click *Finish*. Eclipse starts the import process and builds the workspace.
+ Note, the new imported project's name will be `my-app`.
+ This can be renamed later.
+
+Verify you can run the imported template app:
+
+1. From the Eclipse *Navigate* menu, select *Open Type*
+ + enter type type name `TemplateApp` and click *OK*
+2. right click on the `TemplateApp` class name and from the context menu
+ + click on *Run As*, then *Java application*.
+ `TemplateApp` runs and prints to the Console view.
+
+You can then start adding your application's java code.
+
+Review the `README.md` file in the newly imported project's folder.
+
+The project's `pom.xml` file is heavily commented to ease
+specifying dependencies to various Edgent jars.
+Open it and select the `pom.xml` tab in the Maven POM Editor to view
+the comments. If needed, change the `edgent.runtime.version`
+property to the desired Edgent version. When needed, adjust
+the Edgent jar dependencies.
+
+Optionally, rename the Java class, Java package,
+project's folder, and change maven project information.
+
+1. In the Eclipse Project Explorer, open the `my-app` project,
+ then the `src/main/java` folder, then the `com.mycompany.app` package.
+ Right click on `TemplateApp.java` and select *Refactor* and *Rename...*
+ + enter the new name for the Java file
+2. Right click on the `com.mycompany.app` package and select *Refactor* and *Rename...*
+ + enter the new name for the package
+3. Right click on the `my-app` project select *Refactor* and *Rename...*
+ + enter the new project name
+4. Right click on the renamed project and and select *Refactor* and *Rename Maven Artifact*
+ + enter the new maven artifact coordinates information
+
+## Additional Resources
+
+You can continue to explore the samples. The README.md in the unpacked samples
+folder summarize what is available, as well as more information about
+building and running them.
+
+As noted above, the samples include a template project that
+you can clone for your application.
+
+Some additional development tools are provided with the samples, in particular,
+`get-edgent-jars.sh` and `package-app.sh`.
+See [Edgent Application Development](application-development).
+
+The [Getting Started Guide](edgent-getting-started) identifies other resources.
diff --git a/site/docs/edgent-getting-started.md b/site/docs/edgent-getting-started.md
index 0e6e9d9..614f0f9 100644
--- a/site/docs/edgent-getting-started.md
+++ b/site/docs/edgent-getting-started.md
@@ -9,9 +9,22 @@
* Reduce the amount of data that you transmit to your analytics server
* Reduce the amount of data that you store
-For more information, see the [Edgent overview](home).
+Edgent accellerates your development of applications to push data analytics and machine learning to *edge devices*. (Edge devices include things like routers, gateways, machines, equipment, sensors, appliances, or vehicles that are connected to a network.) Edgent applications process data locally—such as, in a car, on an Android phone, or on a Raspberry Pi—before it sends data over a network.
-### Apache Edgent and streaming analytics
+For example, if your device takes temperature readings from a sensor 1,000 times per second, it is more efficient to process the data locally and send only interesting or unexpected results over the network.
+
+Releases of Edgent prior to 1.2.0 distributed Edgent and the samples differently than today. See [Old Getting Started](old-edgent-getting-started) if you are trying to use an older version.
+
+There's a lot of information available to get started with Edgent and no "best order" for navigating it. See the navigation sidebar on the left hand side of this page. In particular it is recommended that you review and visit the various items under _Get Started_.
+
+If you want to get a developent environment setup quickly see the [Quickstart with Edgent Samples](edgent-getting-started-samples) item.
+
+The _Edgent Cookbook_ topic includes many well documented recipies that are good for learning and jump-starting the development of your application.
+
+The rest of this page is an introduction to Edgent using a simple simulated Temperature Sensor application.
+
+
+## Apache Edgent and streaming analytics
The fundamental building block of an Edgent application is a **stream**: a continuous sequence of tuples (messages, events, sensor readings, and so on).
@@ -19,69 +32,35 @@
Source streams are streams that originate data for analysis, such as readings from a device's temperature sensor.
-Streams are terminated using sink functions that can perform local device control or send information to centralized analytic systems through a message hub.
+Streams are terminated using sink functions that can perform local device control or send information to external services such as centralized analytic systems through a message hub.
-Edgent's primary API is functional where streams are sourced, transformed, analyzed or sinked though functions, typically represented as lambda expressions, such as `reading -> reading < 50 || reading > 80` to filter temperature readings in Fahrenheit.
+Edgent's primary API is functional where streams are sourced, transformed, analyzed or sinked though functions, typically represented as Java8 lambda expressions, such as `reading -> reading < 50 || reading > 80` to filter temperature readings in Fahrenheit.
-### Downloading Apache Edgent
+A **topology** is a graph of streams and their processing transformations. A **provider** is a factory for creating and executing topologies.
-To use Edgent, you need the Edgent JAR files, which you may obtain by completing the following steps.
+Basic Edgent Applications follow a common structure:
-1. Locate the Edgent release you would like to use on the [downloads page]({{ site.data.project.download }})
-2. In the Bundles column for the desired release:
- * Click on the _Binary_ link if you simply want to use Edgent. This is the easiest method is to get up and running as it contains a pre-built version of Edgent.
- * Click on the _Source_ link if you would like access to the Edgent source files. If you choose this method, you must manually build Edgent yourself.
-3. Download the .tgz file from one of the mirror sites
-4. Unpack the downloaded file: `tar zxvf apache-edgent-X.X.X-incubating-XXX.tgz`
-5. Obtain the JARs
- * If you are using a binary bundle, then the Java 8 JARs are located in `edgent-X.X.X/java8`
- * If you are using a source bundle, build the source code:
- 1. Install [Gradle](https://gradle.org/) if it is not yet installed
- 2. Navigate to the unpacked directory: `cd edgent-X.X.X-src`
- 3. Run `gradle` to initialize the Gradle wrapper
- 4. Build the code and Javadoc: `./gradlew assemble`
- 5. The Java 8 JARs are located in `edgent-X.X.X-src/build/distributions/java8`
+ 1. Get a provider
+ 2. Create the topology and compose its processing graph
+ 3. Submit the topology for execution
-### Setting up your environment
+More sophisticated applications may consist of multiple topologies that may be dynamically created and started and stopped using commands from external applications.
-Ensure that you are running a supported environment. For more information, see the [Edgent overview](home). This guide assumes you're running Java 8. The Edgent Java 8 JAR files are located in either the `edgent-X.X.X/java8` or `edgent-X.X.X-src/build/distributions/java8` directory, depending on whether you downloaded a binary or source bundle.
-
-1. Create a new Java project in Eclipse, and specify Java 8 as the execution environment JRE:
-
- <img src="images/New_Java_Project.jpg">
-
-
-2. Include one or more Edgent JARs in your project's build path depending on what features your application uses:
- 1. Include one or more of the topology providers:
- * `java8/lib/edgent.providers.development.jar` (if using the [DevelopmentProvider]({{ site.docsurl }}/org/apache/{{ site.data.project.unix_name }}/providers/development/DevelopmentProvider.html))
- * `java8/lib/edgent.providers.direct.jar`(if using the [DirectProvider]({{ site.docsurl }}/org/apache/{{ site.data.project.unix_name }}/providers/direct/DirectProvider.html))
- * `java8/lib/edgent.providers.iot.jar` (if using the [IotProvider]({{ site.docsurl }}/org/apache/{{ site.data.project.unix_name }}/providers/iot/IotProvider.html))
- 2. Include the JARs for any Edgent connectors or analytic features you use in `java8/connectors` and `java8/analytics`, respectively
- 3. Include the JARs for any Edgent utility features you use:
- * `java8/utils/metrics/lib/edgent.utils.metrics.jar` (for the [org.apache.edgent.metrics]({{ site.docsurl }}/org/apache/{{ site.data.project.unix_name }}/metrics/package-summary.html) package)
- * `java8/utils/streamscope/lib/edgent.utils.streamscope.jar` (for the [org.apache.edgent.streamscope]({{ site.docsurl }}/org/apache/{{ site.data.project.unix_name }}/streamscope/package-summary.html) package)
- 4. Include the JAR for the [java.util.logging](https://docs.oracle.com/javase/8/docs/api/java/util/logging/package-summary.html) framework for [SLF4J](https://www.slf4j.org/): `java8/ext/slf4j-jdk14-X.X.X.jar`
-
- <img src="images/Build_Path_JARs.jpg">
-
-Your environment is set up! You can start writing your first Edgent application.
-
-## Creating a simple application
+## Temperature Sensor Application
If you're new to Edgent or to writing streaming applications, the best way to get started is to write a simple program.
-Edgent is a framework that pushes data analytics and machine learning to *edge devices*. (Edge devices include things like routers, gateways, machines, equipment, sensors, appliances, or vehicles that are connected to a network.) Edgent enables you to process data locally—such as, in a car engine, on an Android phone, or on a Raspberry Pi—before you send data over a network.
+First we'll go over the details of the application, then we'll run it.
-For example, if your device takes temperature readings from a sensor 1,000 times per second, it is more efficient to process the data locally and send only interesting or unexpected results over the network. To simulate this, let's define a (simulated) TempSensor class:
+Let's create a simple Temperature Sensor Application. The application takes temperature readings from a sensor 1,000 times per second. Instead of reporting each reading, it is more efficient to process the data locally and send only interesting or unexpected results over the network.
+
+To simulate this, let's define a (simulated) TempSensor class:
```java
import java.util.Random;
import org.apache.edgent.function.Supplier;
-/**
- * Every time get() is called, TempSensor generates a temperature reading.
- */
public class TempSensor implements Supplier<Double> {
double currentTemp = 65.0;
Random rand;
@@ -100,9 +79,9 @@
}
```
-Every time you call `TempSensor.get()`, it returns a new temperature reading. The continuous temperature readings are a stream of data that an Edgent application can process.
+Every time `TempSensor.get()` is called, it returns a new temperature reading.
-Our sample Edgent application processes this stream by filtering the data and printing the results. Let's define a TempSensorApplication class for the application:
+Our application composes a topology that creates a continuous stream of temperature readings and processes this stream by filtering the data and printing the results. Let's define a TempSensorApplication class for the application:
```java
import java.util.concurrent.TimeUnit;
@@ -116,20 +95,21 @@
TempSensor sensor = new TempSensor();
DirectProvider dp = new DirectProvider();
Topology topology = dp.newTopology();
+
TStream<Double> tempReadings = topology.poll(sensor, 1, TimeUnit.MILLISECONDS);
TStream<Double> filteredReadings = tempReadings.filter(reading -> reading < 50 || reading > 80);
-
filteredReadings.print();
+
dp.submit(topology);
}
}
```
-To understand how the application processes the stream, let's review each line.
+Let's review each line.
### Specifying a provider
-Your first step when you write an Edgent application is to create a [`DirectProvider`]({{ site.docsurl }}/index.html?org/apache/{{ site.data.project.unix_name }}/providers/direct/DirectProvider.html):
+Your first step when you write an Edgent application is to create a _Provider_. In this case we're using a [`DirectProvider`]({{ site.docsurl }}/index.html?org/apache/{{ site.data.project.unix_name }}/providers/direct/DirectProvider.html):
```java
DirectProvider dp = new DirectProvider();
@@ -137,28 +117,32 @@
A `Provider` is an object that contains information on how and where your Edgent application will run. A `DirectProvider` is a type of Provider that runs your application directly within the current virtual machine when its [`submit()`]({{ site.docsurl }}/org/apache/{{ site.data.project.unix_name }}/providers/direct/DirectProvider.html#submit-org.apache.{{ site.data.project.unix_name }}.topology.Topology-) method is called.
+The [`IotProvider`]({{ site.docsurl }}/index.html?org/apache/{{ site.data.project.unix_name }}/providers/iot/IotProvider.html) is an alternative that offers very useful and powerful capabilities.
+
### Creating a topology
-Additionally, a Provider is used to create a [`Topology`]({{ site.docsurl }}/index.html?org/apache/{{ site.data.project.unix_name }}/topology/Topology.html) instance:
+The Provider is used to create a [`Topology`]({{ site.docsurl }}/index.html?org/apache/{{ site.data.project.unix_name }}/topology/Topology.html) instance:
```java
Topology topology = dp.newTopology();
```
-In Edgent, `Topology` is a container that describes the structure of your application:
+In Edgent, `Topology` is a container that describes the structure of your processing graph:
* Where the streams in the application come from
* How the data in the stream is modified
-In the TempSensorApplication class above, we have exactly one data source: the `TempSensor` object. We define the source stream by calling [`topology.poll()`]({{ site.docsurl }}/org/apache/{{ site.data.project.unix_name }}/topology/Topology.html#poll-org.apache.{{ site.data.project.unix_name }}.function.Supplier-long-java.util.concurrent.TimeUnit-), which takes both a [`Supplier`]({{ site.docsurl }}/index.html?org/apache/{{ site.data.project.unix_name }}/function/Supplier.html) function and a time parameter to indicate how frequently readings should be taken. In our case, we read from the sensor every millisecond:
+Our application then composes the topology's progessing graph.
+
+### Creating a source `TStream`
+
+In the `TempSensorApplication` class above, we have exactly one data source: the `TempSensor` object. We define the source stream by calling [`topology.poll()`]({{ site.docsurl }}/org/apache/{{ site.data.project.unix_name }}/topology/Topology.html#poll-org.apache.{{ site.data.project.unix_name }}.function.Supplier-long-java.util.concurrent.TimeUnit-), which takes both a [`Supplier`]({{ site.docsurl }}/index.html?org/apache/{{ site.data.project.unix_name }}/function/Supplier.html) function and a time parameter to indicate how frequently readings should be taken. In our case, we read from the sensor every millisecond:
```java
TStream<Double> tempReadings = topology.poll(sensor, 1, TimeUnit.MILLISECONDS);
```
-### Defining the `TStream` object
-
-Calling `topology.poll()` to define a source stream creates a `TStream<Double>` instance, which represents the series of readings taken from the temperature sensor.
+Calling `topology.poll()` to define a source stream creates a `TStream<Double>` instance (because `TempSensor.get()` returns a `Double`), which represents the series of readings taken from the temperature sensor.
A streaming application can run indefinitely, so the [`TStream`]({{ site.docsurl }}/index.html?org/apache/{{ site.data.project.unix_name }}/topology/TStream.html) might see an arbitrarily large number of readings pass through it. Because a `TStream` represents the flow of your data, it supports a number of operations which allow you to modify your data.
@@ -170,7 +154,7 @@
TStream<Double> filteredReadings = tempReadings.filter(reading -> reading < 50 || reading > 80);
```
-As you can see, the function that is passed to `filter` operates on each tuple individually. Unlike data streaming frameworks like [Apache Spark](https://spark.apache.org/), which operate on a collection of data in batch mode, Edgent achieves low latency processing by manipulating each piece of data as soon as it becomes available. Filtering a `TStream` produces another `TStream` that contains only the filtered tuples; for example, the `filteredReadings` stream.
+As you can see, the function that is passed to `filter` operates on each tuple individually. Unlike data streaming frameworks like [Apache Spark](https://spark.apache.org/), which operate on a collection of data in batch mode, Edgent achieves low latency processing by manipulating each piece of data as soon as it becomes available. Filtering a `TStream` produces another `TStream` that contains only the filtered tuples; in this case, the `filteredReadings` stream.
### Printing to output
@@ -182,13 +166,15 @@
Unlike `TStream.filter()`, `TStream.print()` does not produce another `TStream`. This is because `TStream.print()` is a **sink**, which represents the terminus of a stream.
-In addition to `TStream.print()` there are other sink operations that send tuples to an MQTT server, JDBC connection, file, or Kafka cluster. Additionally, you can define your own sink by invoking [`TStream.sink()`]({{ site.docsurl }}/org/apache/{{ site.data.project.unix_name }}/topology/TStream.html#sink-org.apache.{{ site.data.project.unix_name }}.function.Consumer-) and passing in your own function.
+A real application typically publishes results to an MQTT server, IoT Hub, Kafka cluster, file, JDBC connection, or other external system. Edgent comes easy to use connectors for these. See the _connectors_ samples, [Edgent Javadoc]({{ site.docsurl }}), and _Edgent Cookbook_ for more information.
-### Submitting your application
+You can define your own sink by invoking [`TStream.sink()`]({{ site.docsurl }}/org/apache/{{ site.data.project.unix_name }}/topology/TStream.html#sink-org.apache.{{ site.data.project.unix_name }}.function.Consumer-) and passing in your own function.
-Now that your application has been completely declared, the final step is to run your application.
+### Submitting your topology
-`DirectProvider` contains a `submit()` method, which runs your application directly within the current virtual machine:
+Now that your topology / processing graph has been completely declared, the final step is to run it.
+
+`DirectProvider` contains a `submit()` method, which runs a topology directly within the current virtual machine:
```java
dp.submit(topology);
@@ -207,12 +193,71 @@
As you can see, all temperatures are outside the 50-80 degree range. In terms of a real-world application, this would prevent a device from sending superfluous data over a network, thereby reducing communication costs.
-## Further examples
-This example demonstrates a small piece of Edgent's functionality. Edgent supports more complicated topologies, such as topologies that require merging and splitting data streams, or perform operations which aggregate the last *N* seconds of data (for example, calculating a moving average).
+### Building and Running
-For more complex examples, see:
+Its easiest to use the Edgent Samples Source release to get started.
-* [Edgent sample programs](samples)
-* [Stream processing concepts](streaming-concepts)
-* [Common Edgent operations](common-edgent-operations)
+If you just want to see this application in action, it's one of the provided samples!
+
+Go to [Getting Started with Samples](edgent-getting-started-samples) to get and build the samples.
+
+Then you can run this application from the command line:
+
+```sh
+cd <the-unpacked-samples-root-folder>
+cd topology; ./run-sample.sh TempSensorApplication
+ 46.59272336309031
+ 46.681544551652934
+ ...
+^C to terminate it
+```
+
+If you setup an Eclipse workspace with the samples, you can run the application from Eclipse:
+
+1. From the Eclipse *Navigate* menu, select *Open Type*
+ + enter type type name `TempSensorApplication` and click *OK*
+2. right click on the `TempSensorApplication` class name and from the context menu
+ + click on *Run As*, then *Java application*.
+ `TempSensorApplication` runs and prints to the Console view.
+ Click on the `terminate` control in the Console view to stop the application.
+
+
+### Creating your own project
+
+In this flow we'll take you though creating a new project for this application.
+Its easiest to use the `template` project in the Edgent Samples to get started.
+
+Go to [Getting Started with Samples](edgent-getting-started-samples) and follow the steps to
+
+ * do the general samples setup
+ * clone the `template` project to use for this application
+
+Then create the `TempSensor.java` and `TempSensorApplication.java` files in the project, copying in the above code.
+
+To build and run from the command line, see the new project's README.md (copied in from the template).
+In the project's folder (adjust the package name below if appropriate)
+
+```sh
+./mvnw clean package
+./app-run.sh --main com.mycompany.app.TempSensorApplication
+ 46.59272336309031
+ 46.681544551652934
+ ...
+^C to terminate it
+```
+
+If you setup the cloned template in an Eclipse workspace:
+
+1. From the Eclipse *Navigate* menu, select *Open Type*
+ + enter type type name `TempSensorApplication` and click *OK*
+2. right click on the `TempSensorApplication` class name and from the context menu
+ + click on *Run As*, then *Java application*.
+ `TempSensorApplication` runs and prints to the Console view.
+ Click on the `terminate` control in the Console view to stop the application.
+
+## Next Steps
+
+This introduction demonstrates a small piece of Edgent's functionality. Edgent supports more complicated topologies, such as topologies that require merging and splitting data streams, or perform operations which aggregate the last *N* seconds of data (for example, calculating a moving average). Typically your application will want to publish to an IoT hub and be controlled by applications in a data center.
+
+There are many more useful resources under the _Get Started_ and _Edgent Cookbook_ topics in the navigation sidebar on the left hand side of this page.
diff --git a/site/docs/faq.md b/site/docs/faq.md
index 2ee33ec..b2fde5c 100644
--- a/site/docs/faq.md
+++ b/site/docs/faq.md
@@ -4,51 +4,57 @@
## What is Apache Edgent?
-Edgent provides APIs and a lightweight runtime to analyze streaming data at the edge.
+Edgent provides APIs and a lightweight runtime enabling you to easily create event-driven applications to analyze streaming data at the edge.
## What do you mean by the edge?
The edge includes devices, gateways, equipment, vehicles, systems, appliances and sensors of all kinds as part of the Internet of Things.
-## How is Apache Edgent used?
+It's easy for for Edgent applications to connect to other entities such as an enterprise IoT hub.
-Edgent can be used at the edge of the Internet of Things, for example, to analyze data on devices, engines, connected cars, etc. Edgent could be on the device itself, or a gateway device collecting data from local devices. You can write an edge application on Edgent and connect it to a Cloud service, such as the IBM Watson IoT Platform. It can also be used for enterprise data collection and analysis; for example log collectors, application data, and data center analytics.
+While Edgent's design center is executing on constrained edge devices, Edgent applications can run on any system meeting minimal requirements such as a Java runtime.
## How are applications developed?
-Applications are developed using a functional flow API to define operations on data streams that are executed as a graph of "oplets" in a lightweight embeddable runtime. The SDK provides capabilities like windowing, aggregation and connectors with an extensible model for the community to expand its capabilities.
+Applications are developed using a functional flow API to define operations on data streams that are executed as a flow graph in a lightweight embeddable runtime. Edgent provides capabilities like windowing, aggregation and connectors with an extensible model for the community to expand its capabilities.
-## What APIs does Apache Edgent support?
+You can develop Edgent applications using an IDE of your choice.
-Currently, Edgent supports APIs for Java and Android. Support for additional languages, such as Python, is likely as more developers get involved. Please consider joining the Edgent open source development community to accelerate the contributions of additional APIs.
+Generally, mechanisms for deploying an Edgent Application to a device are beyond the scope of Edgent; they are often device specific or may be defined by an enterprise IoT system. To deploy an Edgent application to a device like a Raspberry Pi, you could just FTP the application to the device and modify the device to start the application upon startup or on command. See [Edgent Application Development](application-development).
+
+## What environments does Apache Edgent support?
+
+Currently, Edgent provides APIs and runtime for Java and Android. Support for additional languages, such as Python, is likely as more developers get involved. Please consider joining the Edgent open source development community to accelerate the contributions of additional APIs.
## What type of analytics can be done with Apache Edgent?
-Edgent provides windowing, aggregation and simple filtering. It uses Apache Common Math to provide simple analytics aimed at device sensors. Edgent is also extensible, so you can call existing libraries from within your Edgent application. In the future, Edgent will include more analytics, either exposing more functionality from Apache Common Math, other libraries or hand-coded analytics.
+The core Edgent APIs makes it easy to incorporate any analytics you want into the stream processing graph. Its trivial to create windows and trigger aggregation functions you supply. It's trivial to specify whatever filtering and transformation functions you want to supply. The functions you supply can use existing libraries.
+
+Edgent comes with some initial analytics for aggregation and filtering that you may find useful. It uses Apache Common Math to provide simple analytics aimed at device sensors. In the future, Edgent will include more analytics, either exposing more functionality from Apache Common Math, other libraries or hand-coded analytics.
## What connectors does Apache Edgent support?
-Edgent supports connectors for MQTT, HTTP, JDBC, File, Apache Kafka and IBM Watson IoT Platform. Edgent is extensible; you can add the connector of your choice.
+Edgent provides easy to use connectors for MQTT, HTTP, JDBC, File, Apache Kafka and IBM Watson IoT Platform. Edgent is extensible; you can create connectors.
## What centralized streaming analytic systems does Apache Edgent support?
-Edgent supports open source technology (such as Apache Spark, Apache Storm, Flink and samza), IBM Streams (on-premises or IBM Streaming Analytics on Bluemix), or any custom application of your choice.
+Edgent applications can publish and subscribe to message systems like MQTT or Kafka, or IoT Hubs like IBM Watson IoT Platform. Centralized streaming analytic systems can do likewise to then consume Edgent application events and data, as well as control an Edgent application. The centralized streaming analytic system could be Apache Spark, Apache Storm, Flink and samza, IBM Streams (on-premises or IBM Streaming Analytics on Bluemix), or any custom application of your choice.
## Why do I need Apache Edgent on the edge, rather than my streaming analytic system?
-Edgent is designed for the edge, rather than a more centralized system. It has a small footprint, suitable for running on devices. Edgent provides simple analytics, allowing a device to analyze data locally and to only send to the centralized system if there is a need, reducing communication costs.
+Edgent is designed for the edge. It has a small footprint, suitable for running on constrained devices. Edgent applications can analyze data on the edge and to only send to the centralized system if there is a need, reducing communication costs.
## Why do I need Apache Edgent, rather than coding the complete application myself?
-Edgent is a tool for edge analytics that allows you to be more productive. Edgent provides a consistent data model (streams and windows) and provides useful functionality, such as aggregations, joins, etc. Using Edgent lets you to take advantage of this functionality, allowing you to focus on your application needs.
+Edgent is designed to accellerate your development of edge analytic applications - to make you more productive! Edgent provides a simple yet powerful consistent data model (streams and windows) and provides useful functionality, such as aggregations, joins, and numerous connectors. Using Edgent lets you to take advantage of this functionality, allowing you to focus on your application needs. For example, you can create an Edgent application that periodically samples a sensor and publishes values to an MQTT server in about 10 lines of code!
## Where can I download Apache Edgent?
-Releases include source code and convenience binary bundles. The source code is also available on GitHub. The [downloads]({{ site.data.project.download }}) page has all of the details.
+Releases include Edgent samples source code and Edgent API and runtime source code. Convenience binaries are released to Maven Central. The source code is also available on GitHub. The [downloads]({{ site.data.project.download }}) page has all of the details.
## How do I get started?
-Getting started is simple. Once you have downloaded Edgent, everything you need to know to get up and running, you will find [here](edgent-getting-started). We suggest you also run the [Edgent sample programs](samples) to familiarize yourselves with the code base.
+Getting started is simple. See [Quickstart with Edgent Samples](edgent-getting-started-samples) to jump right in or see the [Getting Started Guide](edgent-getting-started) if you prefer a bit of an introduction and tutorial first.
## How can I get involved?
diff --git a/site/docs/old-edgent-getting-started.md b/site/docs/old-edgent-getting-started.md
new file mode 100644
index 0000000..00401f6
--- /dev/null
+++ b/site/docs/old-edgent-getting-started.md
@@ -0,0 +1,224 @@
+---
+title: Getting started with Apache Edgent pre-1.2.0
+---
+
+This information applies to Edgent releases prior to 1.2.0. See [Getting Started](edgent-getting-started) for current releases.
+
+## What is Apache Edgent?
+
+Edgent is an open source programming model and runtime for edge devices that enables you to analyze streaming data on your edge devices. When you analyze on the edge, you can:
+
+* Reduce the amount of data that you transmit to your analytics server
+* Reduce the amount of data that you store
+
+For more information, see the [Edgent overview](home).
+
+### Apache Edgent and streaming analytics
+
+The fundamental building block of an Edgent application is a **stream**: a continuous sequence of tuples (messages, events, sensor readings, and so on).
+
+The Edgent API provides the ability to process or analyze each tuple as it appears on a stream, resulting in a derived stream.
+
+Source streams are streams that originate data for analysis, such as readings from a device's temperature sensor.
+
+Streams are terminated using sink functions that can perform local device control or send information to centralized analytic systems through a message hub.
+
+Edgent's primary API is functional where streams are sourced, transformed, analyzed or sinked though functions, typically represented as lambda expressions, such as `reading -> reading < 50 || reading > 80` to filter temperature readings in Fahrenheit.
+
+### Samples
+
+See [samples](old-samples) for information about samples that come with Edgent.
+
+### Downloading Apache Edgent
+
+To use Edgent, you need the Edgent JAR files, which you may obtain by completing the following steps.
+
+1. Locate the Edgent release you would like to use on the [downloads page]({{ site.data.project.download }})
+2. In the Bundles column for the desired release:
+ * Click on the _Binary_ link if you simply want to use Edgent. This is the easiest method is to get up and running as it contains a pre-built version of Edgent.
+ * Click on the _Source_ link if you would like access to the Edgent source files. If you choose this method, you must manually build Edgent yourself.
+3. Download the .tgz file from one of the mirror sites
+4. Unpack the downloaded file: `tar zxvf apache-edgent-X.X.X-incubating-XXX.tgz`
+5. Obtain the JARs
+ * If you are using a binary bundle, then the Java 8 JARs are located in `edgent-X.X.X/java8`
+ * If you are using a source bundle, build the source code:
+ 1. Install [Gradle](https://gradle.org/) if it is not yet installed
+ 2. Navigate to the unpacked directory: `cd edgent-X.X.X-src`
+ 3. Run `gradle` to initialize the Gradle wrapper
+ 4. Build the code and Javadoc: `./gradlew assemble`
+ 5. The Java 8 JARs are located in `edgent-X.X.X-src/build/distributions/java8`
+
+### Setting up your environment
+
+Ensure that you are running a supported environment. For more information, see the [Edgent overview](home). This guide assumes you're running Java 8. The Edgent Java 8 JAR files are located in either the `edgent-X.X.X/java8` or `edgent-X.X.X-src/build/distributions/java8` directory, depending on whether you downloaded a binary or source bundle.
+
+1. Create a new Java project in Eclipse, and specify Java 8 as the execution environment JRE:
+
+ <img src="images/New_Java_Project.jpg">
+
+
+2. Include one or more Edgent JARs in your project's build path depending on what features your application uses:
+ 1. Include one or more of the topology providers:
+ * `java8/lib/edgent.providers.development.jar` (if using the [DevelopmentProvider]({{ site.docsurl }}/org/apache/{{ site.data.project.unix_name }}/providers/development/DevelopmentProvider.html))
+ * `java8/lib/edgent.providers.direct.jar`(if using the [DirectProvider]({{ site.docsurl }}/org/apache/{{ site.data.project.unix_name }}/providers/direct/DirectProvider.html))
+ * `java8/lib/edgent.providers.iot.jar` (if using the [IotProvider]({{ site.docsurl }}/org/apache/{{ site.data.project.unix_name }}/providers/iot/IotProvider.html))
+ 2. Include the JARs for any Edgent connectors or analytic features you use in `java8/connectors` and `java8/analytics`, respectively
+ 3. Include the JARs for any Edgent utility features you use:
+ * `java8/utils/metrics/lib/edgent.utils.metrics.jar` (for the [org.apache.edgent.metrics]({{ site.docsurl }}/org/apache/{{ site.data.project.unix_name }}/metrics/package-summary.html) package)
+ * `java8/utils/streamscope/lib/edgent.utils.streamscope.jar` (for the [org.apache.edgent.streamscope]({{ site.docsurl }}/org/apache/{{ site.data.project.unix_name }}/streamscope/package-summary.html) package)
+ 4. Include the JAR for the [java.util.logging](https://docs.oracle.com/javase/8/docs/api/java/util/logging/package-summary.html) framework for [SLF4J](https://www.slf4j.org/): `java8/ext/slf4j-jdk14-X.X.X.jar`
+
+ <img src="images/Build_Path_JARs.jpg">
+
+Your environment is set up! You can start writing your first Edgent application.
+
+## Creating a simple application
+
+If you're new to Edgent or to writing streaming applications, the best way to get started is to write a simple program.
+
+Edgent is a framework that pushes data analytics and machine learning to *edge devices*. (Edge devices include things like routers, gateways, machines, equipment, sensors, appliances, or vehicles that are connected to a network.) Edgent enables you to process data locally—such as, in a car engine, on an Android phone, or on a Raspberry Pi—before you send data over a network.
+
+For example, if your device takes temperature readings from a sensor 1,000 times per second, it is more efficient to process the data locally and send only interesting or unexpected results over the network. To simulate this, let's define a (simulated) TempSensor class:
+
+```java
+import java.util.Random;
+
+import org.apache.edgent.function.Supplier;
+
+/**
+ * Every time get() is called, TempSensor generates a temperature reading.
+ */
+public class TempSensor implements Supplier<Double> {
+ double currentTemp = 65.0;
+ Random rand;
+
+ TempSensor(){
+ rand = new Random();
+ }
+
+ @Override
+ public Double get() {
+ // Change the current temperature some random amount
+ double newTemp = rand.nextGaussian() + currentTemp;
+ currentTemp = newTemp;
+ return currentTemp;
+ }
+}
+```
+
+Every time you call `TempSensor.get()`, it returns a new temperature reading. The continuous temperature readings are a stream of data that an Edgent application can process.
+
+Our sample Edgent application processes this stream by filtering the data and printing the results. Let's define a TempSensorApplication class for the application:
+
+```java
+import java.util.concurrent.TimeUnit;
+
+import org.apache.edgent.providers.direct.DirectProvider;
+import org.apache.edgent.topology.TStream;
+import org.apache.edgent.topology.Topology;
+
+public class TempSensorApplication {
+ public static void main(String[] args) throws Exception {
+ TempSensor sensor = new TempSensor();
+ DirectProvider dp = new DirectProvider();
+ Topology topology = dp.newTopology();
+ TStream<Double> tempReadings = topology.poll(sensor, 1, TimeUnit.MILLISECONDS);
+ TStream<Double> filteredReadings = tempReadings.filter(reading -> reading < 50 || reading > 80);
+
+ filteredReadings.print();
+ dp.submit(topology);
+ }
+}
+```
+
+To understand how the application processes the stream, let's review each line.
+
+### Specifying a provider
+
+Your first step when you write an Edgent application is to create a [`DirectProvider`]({{ site.docsurl }}/index.html?org/apache/{{ site.data.project.unix_name }}/providers/direct/DirectProvider.html):
+
+```java
+DirectProvider dp = new DirectProvider();
+```
+
+A `Provider` is an object that contains information on how and where your Edgent application will run. A `DirectProvider` is a type of Provider that runs your application directly within the current virtual machine when its [`submit()`]({{ site.docsurl }}/org/apache/{{ site.data.project.unix_name }}/providers/direct/DirectProvider.html#submit-org.apache.{{ site.data.project.unix_name }}.topology.Topology-) method is called.
+
+### Creating a topology
+
+Additionally, a Provider is used to create a [`Topology`]({{ site.docsurl }}/index.html?org/apache/{{ site.data.project.unix_name }}/topology/Topology.html) instance:
+
+```java
+Topology topology = dp.newTopology();
+```
+
+In Edgent, `Topology` is a container that describes the structure of your application:
+
+* Where the streams in the application come from
+* How the data in the stream is modified
+
+In the TempSensorApplication class above, we have exactly one data source: the `TempSensor` object. We define the source stream by calling [`topology.poll()`]({{ site.docsurl }}/org/apache/{{ site.data.project.unix_name }}/topology/Topology.html#poll-org.apache.{{ site.data.project.unix_name }}.function.Supplier-long-java.util.concurrent.TimeUnit-), which takes both a [`Supplier`]({{ site.docsurl }}/index.html?org/apache/{{ site.data.project.unix_name }}/function/Supplier.html) function and a time parameter to indicate how frequently readings should be taken. In our case, we read from the sensor every millisecond:
+
+```java
+TStream<Double> tempReadings = topology.poll(sensor, 1, TimeUnit.MILLISECONDS);
+```
+
+### Defining the `TStream` object
+
+Calling `topology.poll()` to define a source stream creates a `TStream<Double>` instance, which represents the series of readings taken from the temperature sensor.
+
+A streaming application can run indefinitely, so the [`TStream`]({{ site.docsurl }}/index.html?org/apache/{{ site.data.project.unix_name }}/topology/TStream.html) might see an arbitrarily large number of readings pass through it. Because a `TStream` represents the flow of your data, it supports a number of operations which allow you to modify your data.
+
+### Filtering a `TStream`
+
+In our example, we want to filter the stream of temperature readings, and remove any "uninteresting" or expected readings—specifically readings which are above 50 degrees and below 80 degrees. To do this, we call the `TStream`'s [`filter`]({{ site.docsurl }}/org/apache/{{ site.data.project.unix_name }}/topology/TStream.html#filter-org.apache.{{ site.data.project.unix_name }}.function.Predicate-) method and pass in a function that returns *true* if the data is interesting and *false* if the data is uninteresting:
+
+```java
+TStream<Double> filteredReadings = tempReadings.filter(reading -> reading < 50 || reading > 80);
+```
+
+As you can see, the function that is passed to `filter` operates on each tuple individually. Unlike data streaming frameworks like [Apache Spark](https://spark.apache.org/), which operate on a collection of data in batch mode, Edgent achieves low latency processing by manipulating each piece of data as soon as it becomes available. Filtering a `TStream` produces another `TStream` that contains only the filtered tuples; for example, the `filteredReadings` stream.
+
+### Printing to output
+
+When our application detects interesting data (data outside of the expected parameters), we want to print results. You can do this by calling the [`TStream.print()`]({{ site.docsurl }}/org/apache/{{ site.data.project.unix_name }}/topology/TStream.html#print--) method, which prints using `.toString()` on each tuple that passes through the stream:
+
+```java
+filteredReadings.print();
+```
+
+Unlike `TStream.filter()`, `TStream.print()` does not produce another `TStream`. This is because `TStream.print()` is a **sink**, which represents the terminus of a stream.
+
+In addition to `TStream.print()` there are other sink operations that send tuples to an MQTT server, JDBC connection, file, or Kafka cluster. Additionally, you can define your own sink by invoking [`TStream.sink()`]({{ site.docsurl }}/org/apache/{{ site.data.project.unix_name }}/topology/TStream.html#sink-org.apache.{{ site.data.project.unix_name }}.function.Consumer-) and passing in your own function.
+
+### Submitting your application
+
+Now that your application has been completely declared, the final step is to run your application.
+
+`DirectProvider` contains a `submit()` method, which runs your application directly within the current virtual machine:
+
+```java
+dp.submit(topology);
+```
+
+After you run your program, you should see output containing only "interesting" data coming from your sensor:
+
+```
+49.904032311772596
+47.97837504039084
+46.59272336309031
+46.681544551652934
+47.400819234155236
+...
+```
+
+As you can see, all temperatures are outside the 50-80 degree range. In terms of a real-world application, this would prevent a device from sending superfluous data over a network, thereby reducing communication costs.
+
+## Further examples
+
+This example demonstrates a small piece of Edgent's functionality. Edgent supports more complicated topologies, such as topologies that require merging and splitting data streams, or perform operations which aggregate the last *N* seconds of data (for example, calculating a moving average).
+
+For more complex examples, see:
+
+* [Edgent sample programs](old-samples)
+* [Stream processing concepts](streaming-concepts)
+* [Common Edgent operations](common-edgent-operations)
diff --git a/site/docs/samples.md b/site/docs/old-samples.md
similarity index 94%
rename from site/docs/samples.md
rename to site/docs/old-samples.md
index 52f3dc3..c1c1569 100644
--- a/site/docs/samples.md
+++ b/site/docs/old-samples.md
@@ -2,6 +2,8 @@
title: Sample programs
---
+This information applies to Edgent releases prior to 1.2.0. See [Getting started guide](edgent-getting-started) for current releases.
+
The [Getting started guide](edgent-getting-started) includes a step-by-step walkthrough of a simple Edgent application.
Edgent also includes a number of sample Java applications that demonstrate different ways that you can use and implement Edgent.
