JavaScript docs, including docs for globals. (#3454)

docs/content/configuration/indexing-service.md

@@ -230,12 +230,12 @@ Example: a function that sends batch_index_task to workers 10.0.0.1 and 10.0.0.2
 "type":"javascript",
 "function":"function (config, zkWorkers, task) {\nvar batch_workers = new java.util.ArrayList();\nbatch_workers.add(\"10.0.0.1\");\nbatch_workers.add(\"10.0.0.2\");\nworkers = zkWorkers.keySet().toArray();\nvar sortedWorkers = new Array()\n;for(var i = 0; i < workers.length; i++){\n sortedWorkers[i] = workers[i];\n}\nArray.prototype.sort.call(sortedWorkers,function(a, b){return zkWorkers.get(b).getCurrCapacityUsed() - zkWorkers.get(a).getCurrCapacityUsed();});\nvar minWorkerVer = config.getMinWorkerVersion();\nfor (var i = 0; i < sortedWorkers.length; i++) {\n var worker = sortedWorkers[i];\n  var zkWorker = zkWorkers.get(worker);\n  if(zkWorker.canRunTask(task) && zkWorker.isValidVersion(minWorkerVer)){\n    if(task.getType() == 'index_hadoop' && batch_workers.contains(worker)){\n      return worker;\n    } else {\n      if(task.getType() != 'index_hadoop' && !batch_workers.contains(worker)){\n        return worker;\n      }\n    }\n  }\n}\nreturn null;\n}"
 }
-
-
 ```
 
-
-
+<div class="note info">
+Please refer to the Druid [JavaScript programming guide](../development/javascript.html) for guidelines about using
+Druid's JavaScript functionality.
+</div>
 
 #### Autoscaler
 

docs/content/development/javascript.md

@@ -0,0 +1,52 @@
+---
+layout: doc_page
+---
+# JavaScript Programming Guide
+
+This page discusses how to use JavaScript to extend Druid.
+
+## Examples
+
+JavaScript can be used to extend Druid in a variety of ways:
+
+- [Aggregators](../querying/aggregations.html#javascript-aggregator)
+- [Extraction functions](../querying/aggregations.html#javascript-extraction-function)
+- [Filters](../querying/aggregations.html#javascript-filter)
+- [Post-aggregators](../querying/aggregations.html#javascript-post-aggregator)
+- [Input parsers](../ingestion/data-formats.html#javascript)
+- [Query routing](../development/router.html#javascript)
+
+JavaScript can be injected dynamically at runtime, making it convenient to rapidly prototype new functionality
+without needing to write and deploy Druid extensions.
+
+Druid uses the Mozilla Rhino engine at optimization level 9 to compile and execute JavaScript.
+
+## Global variables
+
+Avoid using global variables. Druid may share the global scope between multiple threads, which can lead to
+unpredictable results if global variables are used.
+
+## Performance
+
+Simple JavaScript functions typically perform a slight performance penalty to native speed. More complex JavaScript
+functions can have steeper performance penalties. Druid compiles JavaScript functions once per node per query.
+
+You may need to pay special attention to garbage collection when making heavy use of JavaScript functions, especially
+garbage collection of the compiled classes themselves. Be sure to use a garbage collector configuration that supports
+timely collection of unused classes (this is generally easier on JDK8 with the Metaspace than it is on JDK7).
+
+## Security
+
+Druid does not execute JavaScript functions in a sandbox, so they have full access to the machine. If you are running
+a cluster where users that can submit queries should not be allowed to execute arbitrary code, we recommend disabling
+JavaScript functionality by setting the [configuration property](../configuration/index.html)
+`druid.javascript.disabled = true`.
+
+## JavaScript vs. Native Extensions
+
+Generally we recommend using JavaScript when security is not an issue, and when speed of development is more important
+than performance or memory use. If security is an issue, or if performance and memory use are of the utmost importance,
+we recommend developing a native Druid extension.
+
+In addition, native Druid extensions are more flexible than JavaScript functions. There are some kinds of extensions
+(like sketches) that must be written as native Druid extensions due to their need for custom data formats.

docs/content/development/router.md

@@ -116,6 +116,11 @@ Allows defining arbitrary routing rules using a JavaScript function. The functio
 }
 ```
 
+<div class="note info">
+Please refer to the Druid [JavaScript programming guide](../development/javascript.html) for guidelines about using
+Druid's JavaScript functionality.
+</div>
+
 HTTP Endpoints
 --------------
 

docs/content/ingestion/data-formats.md

@@ -143,9 +143,14 @@ columns names ("column_1", "column2", ... "column_n") will be assigned. Ensure t
   }
 ```
 
-Please note with the JavaScript parser that data must be fully parsed and returned as a `{key:value}` format in the JS logic. 
+Note with the JavaScript parser that data must be fully parsed and returned as a `{key:value}` format in the JS logic.
 This means any flattening or parsing multi-dimensional values must be done here.
 
+<div class="note info">
+Please refer to the Druid [JavaScript programming guide](../development/javascript.html) for guidelines about using
+Druid's JavaScript functionality.
+</div>
+
 ### Multi-value dimensions
 
 Dimensions can have multiple values for TSV and CSV data. To specify the delimiter for a multi-value dimension, set the `listDelimiter` in the `parseSpec`.

docs/content/querying/aggregations.md

@@ -78,12 +78,8 @@ Computes the sum of values as 64-bit floating point value. Similar to `longSum`
 
 ### JavaScript aggregator
 
-Computes an arbitrary JavaScript function over a set of columns (both metrics and dimensions).
-
-All JavaScript functions must return numerical values.
-
-JavaScript aggregators are much slower than the native aggregators and if performance is critical, you should implement 
-your functionality as a native aggregator.
+Computes an arbitrary JavaScript function over a set of columns (both metrics and dimensions are allowed). Your
+JavaScript functions are expected to return floating-point values.
 
 ```json
 { "type": "javascript",
@@ -111,8 +107,10 @@ your functionality as a native aggregator.
 }
 ```
 
-The JavaScript aggregator is recommended for rapidly prototyping features. This aggregator will be much slower in production 
-use than a native aggregator.
+<div class="note info">
+Please refer to the Druid [JavaScript programming guide](../development/javascript.html) for guidelines about using
+Druid's JavaScript functionality.
+</div>
 
 ## Approximate Aggregations
 

docs/content/querying/dimensionspecs.md

@@ -196,6 +196,11 @@ Example for the `__time` dimension:
 }
 ```
 
+<div class="note info">
+Please refer to the Druid [JavaScript programming guide](../development/javascript.html) for guidelines about using
+Druid's JavaScript functionality.
+</div>
+
 ### Lookup extraction function
 
 Lookups are a concept in Druid where dimension values are (optionally) replaced with new values. 

docs/content/querying/filters.md

@@ -88,6 +88,10 @@ The following matches any dimension values for the dimension `name` between `'ba
 
 The JavaScript filter supports the use of extraction functions, see [Filtering with Extraction Functions](#filtering-with-extraction-functions) for details.
 
+<div class="note info">
+Please refer to the Druid [JavaScript programming guide](../development/javascript.html) for guidelines about using
+Druid's JavaScript functionality.
+</div>
 
 ### Extraction filter
 

docs/content/querying/post-aggregations.md

@@ -77,6 +77,12 @@ Example JavaScript aggregator:
   "function": "function(delta, total) { return 100 * Math.abs(delta) / total; }"
 }
 ```
+
+<div class="note info">
+Please refer to the Druid [JavaScript programming guide](../development/javascript.html) for guidelines about using
+Druid's JavaScript functionality.
+</div>
+
 ### HyperUnique Cardinality post-aggregator
 
 The hyperUniqueCardinality post aggregator is used to wrap a hyperUnique object such that it can be used in post aggregations.