generate both shaded and non-shaded JARs opentripplanner#1986

also updated documentation and scripts that reference JAR file

docs/Basic-Usage.md

@@ -6,9 +6,9 @@ This page will get you up and running with your own OTP server. If all goes well
 
 OpenTripPlanner is written in Java and distributed as a single runnable JAR file. These JARs are published
 [here](http://dev.opentripplanner.org/jars/). Grab one of these JARs for the
-[latest released version](http://dev.opentripplanner.org/jars/otp-0.18.0.jar)
+[latest released version](http://dev.opentripplanner.org/jars/otp-0.18.0-shaded.jar)
 or if you're feeling adventurous try the
-[bleeding edge development code](http://dev.opentripplanner.org/jars/otp-0.19.0-SNAPSHOT.jar).
+[bleeding edge development code](http://dev.opentripplanner.org/jars/otp-0.19.0-SNAPSHOT-shaded.jar).
 You may also want to get your own copy of the OTP source code and [build the JAR from scratch](Getting-OTP),
 especially if you plan to do some development yourself.
 
@@ -59,15 +59,15 @@ If you do not you will need to install a recent OpenJDK or Oracle Java package f
 
 GTFS and OSM data sets are often very large, and OTP is relatively memory-hungry. You will need at least 1GB of memory
 when working with the Portland TriMet data set, and several gigabytes for larger inputs. A typical command to start OTP
-looks like `java -Xmx1G -jar otp-0.18.0.jar <options>`. The `-Xmx` parameter sets
+looks like `java -Xmx1G -jar otp-0.18.0-shaded.jar <options>`. The `-Xmx` parameter sets
 the limit on how much memory OTP is allowed to consume. If you have sufficient memory in your computer,
 set this to a couple of gigabytes; when OTP doesn't have enough "breathing room" it can grind to a halt.
 
 It's possible to analyze the GTFS, OSM and any other input data and save the resulting representation of the transit
 network (what we call a ['graph'](http://en.wikipedia.org/wiki/Graph_%28mathematics%29)) to disk.
 For simplicity we'll skip saving this file and start up an OTP server immediately after the graph is built. The command to do so is:
 
-    java -Xmx2G -jar otp-0.18.0.jar --build /home/username/otp --inMemory
+    java -Xmx2G -jar otp-0.18.0-shaded.jar --build /home/username/otp --inMemory
 
 where `/home/username/otp` should be the directory where you put your input files. The graph build operation should
 take about one minute to complete, and then you'll see a `Grizzly server running` message. At this point you can open

docs/Developers-Guide.md

@@ -271,7 +271,7 @@ Release checklist:
 - cp -R target/site/enunciate /usr/share/nginx/html/apidoc/x.y.0
 - check that all docs in /usr/share/nginx/html/javadoc/ have o+r permissions (they should be by default)
 - mvn release:perform
-- cp target/checkout/target/otp-x.y.0.jar /usr/share/nginx/html/jars/
+- cp target/checkout/target/otp-x.y.0-shaded.jar /usr/share/nginx/html/jars/
 - rm /usr/share/nginx/html/jars/otp-x.y.0-SNAPSHOT*
 - check http://dev.opentripplanner.org/jars/ and http://dev.opentripplanner.org/javadoc/ in a browser
 - update the version numbers that appear in Basic-Usage, Developers-Guide, Getting-OTP, and index.md and check them in

docs/Getting-OTP.md

@@ -3,10 +3,7 @@
 ## Pre-built JARs
 
 OpenTripPlanner is now distributed as a single stand-alone runnable JAR file. The JAR file for each release is
-published [here](http://dev.opentripplanner.org/jars/). In addition, whenever new changes are made to the master branch 
-of the main OTP repository on Github, the resulting JAR is published to the
- [same location](http://dev.opentripplanner.org/jars/otp-latest-master.jar).
-
+published [here](http://dev.opentripplanner.org/jars/).
 
 ## Building from Source
 
@@ -53,14 +50,16 @@ If all goes well you should see a success message like the following:
 [INFO] ------------------------------------------------------------------------
 ```
 
-This build process should produce a JAR file called `otp.jar` in the `target/` directory which contains all the 
-compiled OTP classes and their dependencies. The shell script called 'otp' in the root of the cloned repository will 
+This build process should produce a JAR file called `otp-x.y.z-shaded.jar` in the `target/` directory which contains
+all the compiled OTP classes and their dependencies (the external libraries they use). The shell script called 'otp'
+in the root of the cloned repository will
 start the main class of that JAR file under a Java virtual machine, so after the Maven build completes you should be 
-able to run `./otp --help` and see an OTP help message including command line options.
+able to run `./otp --help` and see an OTP help message including command line options. Due to the way Maven works, this
+script is not executable by default, so you will need to do `chmod u+x ./otp` before you run it to mark it as executable.
 
 The words "clean package" are the build steps you want to run. You're telling maven to clean up any extraneous junk in
- the directory, then perform all the build steps including compilation up to "package", which bundles the compiled program
- into a single JAR file for distribution. 
+ the directory, then perform all the build steps, including compilation, up to and including "package",
+ which bundles the compiled program into a single JAR file for distribution.
 
 If you have just cloned OTP you will be working with the default "master" branch, where most active development occurs.
  This is not the most stable or deployment-ready code available. To avoid newly minted bugs or undocumented behavior,
@@ -77,6 +76,13 @@ git clean -df
 mvn clean package -DskipTests
 ```
 
+Please note that the build process creates two distinct versions of the OTP JAR file. The one ending in `-shaded.jar`
+is much bigger because it contains copies of all the external libraries that OTP uses.
+It serves as a stand-alone runnable distribution of OTP. The one with a version number but without the word `shaded`
+contains only OTP itself, without any external dependencies. This JAR is useful when OTP is included as a component in
+some other project, where we want the dependency management system to gather all the external libraries automatically.
+
+
 ## Maven Repository
 
 OpenTripPlanner is a Maven project. Maven is a combined build and dependency management system: it fetches
@@ -86,7 +92,7 @@ can be automatically included in other Java projects.
 
 This repository is machine-readable (by Maven or other build systems) and for the moment does not include any human readable indexes. 
 You can nonetheless fetch an OTP JAR from this repository by constructing the proper URL for the release
-you want. For example, release 0.13.0 will be found at `http://maven.conveyal.com/org/opentripplanner/otp/0.13.0/otp-0.13.0.jar`
+you want. For example, release 0.13.0 will be found at `http://maven.conveyal.com/org/opentripplanner/otp/0.13.0/otp-0.13.0-shaded.jar`.
 
 To make use of OTP in another project, you must first specify our Maven repository in the Project Object Model (POM):
 

docs/Scripting.md

@@ -14,20 +14,20 @@ There are currently 3 different modes for using scripting:
 
 - Launching OTP with the `--script` command-line parameter, providing the script filename as an option.
 - Starting an OTP server with the `--enableScriptingWebService` command-line parameter, and posting a script to execute to the `/ws/scripting/run` API end-point.
-- Launching a Jython script with `otp.jar` in the classpath and creating the scripting entry-point bean in the script itself.
+- Launching a Jython script with `otp-x.y.z-shaded.jar` in the classpath and creating the scripting entry-point bean in the script itself.
 
 ### Launching a script from OTP
 
 The main advantage of this method is its simplicity. The drawback is that you need to start OTP everytime you run a script, which can be slow to startup for large graphs. The second drawback is that you can't import custom packages from within the script, you are limited to the "plain basic" Jython.
 
-__Note__: The Jython (or Groovy) JAR are *not* included in the OTP.jar. You thus have to add one of them (depending on your script) to the java classpath (see command below). Jython jar can be [downloaded here](http://www.jython.org/downloads.html). Make sure you select the "standalone" version of jython, otherwise some classes will be missing.
+__Note__: The Jython (or Groovy) JAR are *not* included in the OTP shaded JAR. You thus have to add one of them (depending on your script) to the java classpath (see command below). Jython jar can be [downloaded here](http://www.jython.org/downloads.html). Make sure you select the "standalone" version of jython, otherwise some classes will be missing.
 
 __Note__: Due a guava bug, there is an incompatibility between Jython 2.3 / 2.5 and OTP. To solve it, make sure otp.jar is added *before* jython-standalone.jar in the classpath. This bug should be solved in jython starting 2.7.
 
 Start OTP specifying the classpath and adding the `--script` option:
 
 ```Bash
-$ java -cp otp.jar:jython-standalone.jar org.opentripplanner.standalone.OTPMain --graphs . --script myscript.py
+$ java -cp otp-x.y.z-shaded.jar:jython-standalone.jar org.opentripplanner.standalone.OTPMain --graphs . --script myscript.py
 ```
 
 This will start OTP with a default graph in the current directory and execute the script `myscript.py`.
@@ -40,7 +40,7 @@ The main advantage of this method is that you do not need to start a new OTP ser
 
 Start an OTP server as usual, adding the `--enableScriptingWebService` option:
 ``` Bash
-$ java -cp otp.jar:jython-standalone.jar org.opentripplanner.standalone.OTPMain --graphs . --server --enableScriptingWebService
+$ java -cp otp-x.y.z-shaded.jar:jython-standalone.jar org.opentripplanner.standalone.OTPMain --graphs . --server --enableScriptingWebService
 ```
 The API end-point `/ws/scripting/run` now accepts script content to be run, posted as multi-part form data.
 
@@ -76,7 +76,7 @@ otp = OtpsEntryPoint.fromArgs([ "--graphs", "." ])
 ```
 
 ```Bash
-$ java -cp otp.jar:jython-standalone.jar org.python.util.jython myscript.py
+$ java -cp otp-x.y.z-shaded.jar:jython-standalone.jar org.python.util.jython myscript.py
 ```
 
 Note that contrary to java custom the jython "main" class is all lowercase, this is not a typo.

docs/Version-Notes.md

@@ -1,7 +1,7 @@
 ## The *master* branch (Version 0.x.0-SNAPSHOT)
 This is the most up-to-date branch where all new development occurs and is the basis for an upcoming x.y release of OTP.
 It does not support WAR deployment as it has a built-in HTTP layer, the same one used in the Glassfish application server.
-If you run `target/otp-VERSION.jar` with the `--server` option (use `--help` for a list of available options),
+If you run `target/otp-x.y.z-shaded.jar` with the `--server` option (use `--help` for a list of available options),
 resources will be available at the following URLs:
 - The JavaScript map-based trip planner is at [[http://localhost:8080/]]
 - The OTP API base path is [[http://localhost:8080/otp/]]

pom.xml

@@ -232,8 +232,10 @@
                                     </excludes>
                                 </filter>
                             </filters>
-                            <!-- The shaded JAR will be the main artifact for the project -->
-                            <shadedArtifactAttached>false</shadedArtifactAttached>
+                            <!-- The shaded JAR will not be the main artifact for the project, it will be attached
+                              for deployment in the way source and docs are. -->
+                            <shadedArtifactAttached>true</shadedArtifactAttached>
+                            <shadedClassifierName>shaded</shadedClassifierName>
                             <!-- MinimizeJar removes unused classes, (classes not imported explicitly by name).
                               We have eliminated most Jersey auto-scanning, but there is still some need for include
                               filters to force-include classes that are dynamically loaded by name/auto-scanned. -->

src/scripts/otp

@@ -2,4 +2,4 @@
 # Run OTP in standalone mode with the supplied arguments.
 # Standalone OTP can build a graph, visualize a graph, run an OTP API server,
 # or any combination of these.
-java -Xmx6G -Xverify:none -jar `dirname $0`/target/${project.build.finalName}.jar "$@"
+java -Xmx6G -Xverify:none -jar `dirname $0`/target/${project.build.finalName}-shaded.jar "$@"

src/scripts/otp-batch-analyst

@@ -15,4 +15,4 @@
 # You should have received a copy of the GNU General Public License
 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
-java -Xmx6G -cp `dirname $0`/otp-core/target/otp.jar org.opentripplanner.analyst.batch.BatchProcessor $1
+java -Xmx6G -Xverify:none -cp `dirname $0`/target/${project.build.finalName}-shaded.jar org.opentripplanner.analyst.batch.BatchProcessor $1