Merge branch 'cgfrost-76619826-document-expert-mode'

[resolves #98]

Author: nebhale

README.md

@@ -64,6 +64,7 @@ To learn how to configure various properties of the buildpack, follow the "Confi
 	* [Repositories](docs/extending-repositories.md) ([Configuration](docs/extending-repositories.md#configuration))
 	* [Utiltities](docs/extending-utiltities.md)
 * [Debugging the Buildpack](docs/debugging-the-buildpack.md)
+* [Buildpack Modes](docs/buildpack-modes.md)
 * Related Projects
 	* [Java Buildpack Dependency Builder](https://github.com/cloudfoundry/java-buildpack-dependency-builder)
 	* [Java Test Applications](https://github.com/cloudfoundry/java-test-applications)

docs/buildpack-modes.md

@@ -0,0 +1,56 @@
+# Buildpack Modes
+The Java Buildpack has three execution modes as described in the blog post, ['Packaged and Offline Buildpacks'][l].
+
+* **Easy Mode:** Uses the repository at `https://download.run.pivotal.io`. This does not require any cloning or downloading unless you want to modify the Cloud Foundry provided buildpack. This is the default, and what we recommend to anyone who asks.
+* **Expert Mode:**   Refers to a repository hosted at a different location, possibly on an internal network.  The [structure of the repository[r] is defined as an HTTP-accessible collection of files. The repository root must contain an `index.yml` file that is a mapping of concrete versions to absolute URIs.  This repository can be created manually or [creating a replica](#replicating-the-repository-optional) for the repository at `https://download.run.pivotal.io`.  This is what we would recommend to any customer that didn’t want to access the Internet. It’s easy to keep applications secure and up-to-date, but requires the expertise to run a web-server and keep it up to date.
+* **Offline Mode:** Uses only the packaged internal cache. This is what we recommend if you wanted a single, self-contained artifact. The downside is having to package and keep all your dependencies up to date.
+
+
+## Easy Mode
+The "Easy Mode" buildpack is included in all Cloud Foundry distributions and used by default.  To configure the buildpack, refer to [Configuration and Extension][c].
+
+You can also download specific versions of the buildpack to use with the `create-buildpack`, and `update-buildpack` Cloud Foundry CLI commands.  To find these, navigate to the [Java Buildpack Releases page][v] and download one of the following:
+
+  * `java-buildpack-v<VERSION>.zip`
+  * Source Code (zip)
+
+To add the buildpack to an instance of Cloud Foundry, use the `cf create-buildpack java-buildpack java-buildpack-v<VERSION>.zip` command.  For more details refer to the [Cloud Foundry buildpack documentation][b].
+
+
+## Expert Mode
+The "Expert Mode" buildpack is a minor fork of the default Java Buildpack.  For details on configuring the buildpack, refer to [Configuration and Extension][c].  To configure the buildpack to point at an alternate repository, modify the [`config/repository.yml`][y] file to use a different `default_repository_root`.
+
+```yaml
+# Repository configuration
+---
+default_repository_root: https://<ALTERNATE_HOST>
+```
+
+Once the buildpack has been modified, it needs to be packaged and uploaded to the Cloud Foundry instance.  In order to package the modified buildpack, refer to [Building Packages][p].  To add the buildpack to an instance of Cloud Foundry, use the `cf create-buildpack java-buildpack java-buildpack-v<VERSION>.zip` command.  For more details refer to the [Cloud Foundry buildpack documentation][b].
+
+### Replicating the Repository _(Optional)_
+The easiest way to create a fully populated internal repository is to replicate the one found at `https://download.run.pivotal.io`.  The [Java Buildpack Dependency Builder][d] contains a `replicate` script that automates this process.  To use the script, issue the following commands from the root directory of a clone of this repository:
+
+```bash
+$ bundle install
+$ bundle exec bin/replicate [--base-uri <BASE-URI> | --host-name <HOST-NAME>] --output <OUTPUT>
+```
+
+For details on using the `replicate script` refer to [Replicating Repository][e].
+
+
+## Offline Mode
+The "Offline Mode" buildpack is a self-contained packaging of either the "Easy Mode" or "Expert Mode" buildpacks.
+
+You can download specific versions of the "Offline Mode" buildpack to use with the `create-buildpack` and `update-buildpack` Cloud Foundry CLI commands.  To find these, navigate to the [Java Buildpack Releases page][v] and download one of the `java-buildpack-offline-v<VERSION>.zip` file.   In order to package a modified "Offline Mode" buildpack, refer to [Building Packages][p].  To add the buildpack to an instance of Cloud Foundry, use the `cf create-buildpack java-buildpack java-buildpack-offline-v<VERSION>.zip` command.  For more details refer to the [Cloud Foundry buildpack documentation][b].
+
+
+[b]: http://docs.pivotal.io/pivotalcf/adminguide/buildpacks.html
+[c]: ../README.md#configuration-and-extension
+[d]: https://github.com/cloudfoundry/java-buildpack-dependency-builder
+[e]: https://github.com/cloudfoundry/java-buildpack-dependency-builder#replicating-repository
+[l]: http://blog.cloudfoundry.org/2014/04/03/packaged-and-offline-buildpacks/
+[p]: ../README.md#building-packages
+[r]: https://github.com/cloudfoundry/java-buildpack/blob/master/docs/extending-repositories.md#repository-structure
+[v]: https://github.com/cloudfoundry/java-buildpack/releases
+[y]: ../config/repository.yml

java-buildpack.iml

@@ -273,26 +273,24 @@
     <orderEntry type="sourceFolder" forTests="false" />
     <orderEntry type="library" scope="PROVIDED" name="addressable (v2.3.6, rbenv: 1.9.3-p547) [gem]" level="application" />
     <orderEntry type="library" scope="PROVIDED" name="ast (v2.0.0, rbenv: 1.9.3-p547) [gem]" level="application" />
-    <orderEntry type="library" scope="PROVIDED" name="bundler (v1.7.0, rbenv: 1.9.3-p547) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="bundler (v1.7.3, rbenv: 1.9.3-p547) [gem]" level="application" />
     <orderEntry type="library" scope="PROVIDED" name="codeclimate-test-reporter (v0.4.0, rbenv: 1.9.3-p547) [gem]" level="application" />
     <orderEntry type="library" scope="PROVIDED" name="crack (v0.4.2, rbenv: 1.9.3-p547) [gem]" level="application" />
-    <orderEntry type="library" scope="PROVIDED" name="debase (v0.0.9, rbenv: 1.9.3-p547) [gem]" level="application" />
     <orderEntry type="library" scope="PROVIDED" name="debugger-ruby_core_source (v1.3.5, rbenv: 1.9.3-p547) [gem]" level="application" />
     <orderEntry type="library" scope="PROVIDED" name="diff-lcs (v1.2.5, rbenv: 1.9.3-p547) [gem]" level="application" />
     <orderEntry type="library" scope="PROVIDED" name="docile (v1.1.5, rbenv: 1.9.3-p547) [gem]" level="application" />
-    <orderEntry type="library" scope="PROVIDED" name="json (v1.8.1, rbenv: 1.9.3-p547) [gem]" level="application" />
     <orderEntry type="library" scope="PROVIDED" name="multi_json (v1.10.1, rbenv: 1.9.3-p547) [gem]" level="application" />
-    <orderEntry type="library" scope="PROVIDED" name="parser (v2.2.0.pre.3, rbenv: 1.9.3-p547) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="parser (v2.2.0.pre.4, rbenv: 1.9.3-p547) [gem]" level="application" />
     <orderEntry type="library" scope="PROVIDED" name="powerpack (v0.0.9, rbenv: 1.9.3-p547) [gem]" level="application" />
     <orderEntry type="library" scope="PROVIDED" name="rainbow (v2.0.0, rbenv: 1.9.3-p547) [gem]" level="application" />
     <orderEntry type="library" scope="PROVIDED" name="rake (v10.3.2, rbenv: 1.9.3-p547) [gem]" level="application" />
     <orderEntry type="library" scope="PROVIDED" name="redcarpet (v3.1.2, rbenv: 1.9.3-p547) [gem]" level="application" />
     <orderEntry type="library" scope="PROVIDED" name="rspec (v3.0.0, rbenv: 1.9.3-p547) [gem]" level="application" />
-    <orderEntry type="library" scope="PROVIDED" name="rspec-core (v3.0.3, rbenv: 1.9.3-p547) [gem]" level="application" />
-    <orderEntry type="library" scope="PROVIDED" name="rspec-expectations (v3.0.3, rbenv: 1.9.3-p547) [gem]" level="application" />
-    <orderEntry type="library" scope="PROVIDED" name="rspec-mocks (v3.0.3, rbenv: 1.9.3-p547) [gem]" level="application" />
-    <orderEntry type="library" scope="PROVIDED" name="rspec-support (v3.0.3, rbenv: 1.9.3-p547) [gem]" level="application" />
-    <orderEntry type="library" scope="PROVIDED" name="rubocop (v0.24.1, rbenv: 1.9.3-p547) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="rspec-core (v3.0.4, rbenv: 1.9.3-p547) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="rspec-expectations (v3.0.4, rbenv: 1.9.3-p547) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="rspec-mocks (v3.0.4, rbenv: 1.9.3-p547) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="rspec-support (v3.0.4, rbenv: 1.9.3-p547) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="rubocop (v0.25.0, rbenv: 1.9.3-p547) [gem]" level="application" />
     <orderEntry type="library" scope="PROVIDED" name="ruby-debug-base19x (v0.11.30.pre15, rbenv: 1.9.3-p547) [gem]" level="application" />
     <orderEntry type="library" scope="PROVIDED" name="ruby-debug-ide (v0.4.22, rbenv: 1.9.3-p547) [gem]" level="application" />
     <orderEntry type="library" scope="PROVIDED" name="ruby-progressbar (v1.5.1, rbenv: 1.9.3-p547) [gem]" level="application" />