Fixed error in max number of properties.

[[capabilities]]
Capabilities
============

/////////
Details, originally contained in the capabilities document.
/////////

[[capabilities-data-security]]
== Data Security ==

Some data may need to be protected from unauthorized access (e.g., theft, modification).
Neo4j does not deal with data encryption explicitly, but supports all means built into the Java programming language and the JVM to protect data by encrypting it before storing.

Furthermore, data can be easily secured by running on an encrypted datastore at the file system level.
Finally, data protection should be considered in the upper layers of the surrounding system in order to prevent problems with scraping, malicious data insertion, and other threats.

[[capabilities-data-integrity]]
== Data Integrity ==

In order to keep data consistent, there needs to be mechanisms and structures that guarantee the integrity of all stored data.
In Neo4j, data integrity is maintained for the core graph engine together with other data sources - see below.

[[capabilities-core-graph-engine]]
=== Core Graph Engine ===

In Neo4j, the whole data model is stored as a graph on disk and persisted as
part of every committed transaction.
In the storage layer, Relationships, Nodes, and Properties have direct pointers to each other.
This maintains integrity without the need for data duplication between the different backend store files.

[[capabilities-different-data-sources]]
=== Different Data Sources ===

In a number of scenarios, the core graph engine is combined with other systems
in order to achieve optimal performance for non-graph lookups.
For example, Apache Lucene is frequently used as an additional index system for text queries that would otherwise be very processing-intensive in the graph layer.

To keep these external systems in synchronization with each other, Neo4j provides
full Two Phase Commit transaction management, with rollback support over all data
sources.
Thus, failed index insertions into Lucene can be transparently rolled back in all data sources and thus keep data up-to-date.

[[capabilities-data-integration]]
== Data Integration ==

Most enterprises rely primarily on relational databases to store their data, but
this may cause performance limitations.
In some of these cases, Neo4j can be used as an extension to supplement search/lookup for faster decision making.
However, in any situation where multiple data repositories contain the same data, synchronization can be an issue.

In some applications, it is acceptable for the search platform to be slightly out
of sync with the relational database.
In others, tight data integrity (eg., between Neo4j and RDBMS) is necessary.
Typically, this has to be addressed for data changing in real-time and for bulk data changes happening in the RDBMS.

A few strategies for synchronizing integrated data follows.

[[capabilities-event-based-synchronization]]
=== Event-based Synchronization ===

In this scenario, all data stores, both RDBMS and Neo4j, are fed with domain-specific
events via an event bus.
Thus, the data held in the different backends is not actually synchronized but rather replicated.

[[capabilities-periodic-synchronization]]
=== Periodic Synchronization ===

Another viable scenario is the periodic export of the latest changes in the RDBMS to
Neo4j via some form of SQL query.
This allows a small amount of latency in the synchronization, but has the advantage of using the RDBMS as the master for all data purposes.
The same process can be applied with Neo4j as the master data source.

[[capabilities-full-export]]
=== Periodic Full Export/Import of Data ===

Using the Batch Inserter tools for Neo4j, even large amounts of data can be imported
into the database in very short times.
Thus, a full export from the RDBMS and import into Neo4j becomes possible.
If the propagation lag between the RDBMS and Neo4j is not a big issue, this is a very viable solution.

[[capabilities-availability]]
== Availability and Reliability ==

Most mission-critical systems require the database subsystem to be accessible at all
times.
Neo4j ensures availability and reliability through a few different strategies.

[[capabilities-op-availability]]
=== Operational Availability ===

In order not to create a single point of failure, Neo4j supports different
approaches which provide transparent fallback and/or recovery from failures.

==== Online backup (Cold spare) ====

In this approach, a single instance of the master database is used, with Online
Backup enabled.
In case of a failure, the backup files can be mounted onto a new
Neo4j instance and reintegrated into the application.

==== Online Backup High Availability (Hot spare) ====

Here, a Neo4j "backup" instance listens to online transfers of changes from the
master.
In the event of a failure of the master, the backup is already running
and can directly take over the load.

==== High Availability cluster ====

This approach uses a cluster of database instances, with one (read/write) master
and a number of (read-only) slaves.
Failing slaves can simply be restarted and brought back online.
Alternatively, a new slave may be added by cloning an existing one.
Should the master instance fail, a new master will be elected by the remaining
cluster nodes.

[[capabilities-disaster]]
=== Disaster Recovery/ Resiliency ===

In cases of a breakdown of major part of the IT infrastructure, there need to be
mechanisms in place that enable the fast recovery and regrouping of the remaining
services and servers.
In Neo4j, there are different components that are suitable to be part of a disaster recovery strategy.

==== Prevention ====

* Online Backup High Availability to other locations outside the current data center.
* Online Backup to different file system locations: this is a simpler form of backup,
applying changes directly to backup files; it is thus more suited for local backup scenarios.
* Neo4j High Availability cluster: a cluster of one write-master Neo4j server and a number of read-slaves, getting transaction logs from the master.
  Write-master failover is handled by quorum election among the read-slaves for a new master.

==== Detection ====

* SNMP and JMX monitoring can be used for the Neo4j database.

==== Correction ====

* Online Backup: A new Neo4j server can be started directly on the backed-up files
and take over new requests.
* Neo4j High Availability cluster: A broken Neo4j read slave can be reinserted into the cluster, getting the latest updates from the master.
  Alternatively, a new server can be inserted by copying an existing server and applying the latest updates to it.

[[capabilities-capacity]]
== Capacity ==

[[capabilities-file-sizes]]
=== File Sizes ===

Neo4j relies on Java's Non-blocking I/O subsystem for all file handling.
Furthermore, while the storage file layout is optimized for interconnected data, Neo4j does not require raw devices.
Thus, filesizes are only limited by the underlying operating system's capacity to handle large files.
Physically, there is no built-in limit of the file handling capacity in Neo4j.

Neo4j tries to memory-map as much of the underlying store files as possible.
If the available RAM is not sufficient to keep all data in RAM, Neo4j will use buffers in some cases, reallocating the memory-mapped high-performance I/O windows to the regions with the most I/O activity dynamically.
Thus, ACID speed degrades gracefully as RAM becomes the limiting factor.

[[capabilities-read-speed]]
=== Read speed ===

Enterprises want to optimize the use of hardware to deliver the maximum business value
from available resources.
Neo4j's approach to reading data provides the best possible usage of all available hardware resources.
Neo4j does not block or lock any read operations; thus, there is no danger for deadlocks in read operations and no need for read transactions.
With a threaded read access to the database, queries can be run simultaneously on as many processors as may be available.
This provides very good scale-up scenarios with bigger servers.

[[capabilities-write-speed]]
=== Write speed ===

Write speed is a consideration for many enterprise applications.
However, there are two different scenarios:

. sustained continuous operation and
. bulk access (e.g., backup, initial or batch loading).

To support the disparate requirements of these scenarios, Neo4j supports two modes of writing to the storage layer.

In transactional, ACID-compliant normal operation, isolation level is maintained and
read operations can occur at the same time as the writing process.
At every commit, the data is persisted to disk and can be recovered to a consistent state upon system failures.
This requires disk write access and a real flushing of data.
Thus, the write speed of Neo4j on a single server in continuous mode is limited by the I/O capacity of the hardware.
Consequently, the use of fast SSDs is highly recommended for production scenarios.

Neo4j has a Batch Inserter that operates directly on the store files.
This mode does not provide transactional security, so it can only be used when there is a single write thread.
Because data is written sequentially, and never flushed to the logical logs, huge performance boosts are achieved.
The Batch Inserter is optimized for non-transactional bulk import of large amounts of data.

[[capabilities-data-size]]
=== Data size ===

In Neo4j, data size is mainly limited by the address space of the primary keys for Nodes, Relationships, Properties and RelationshipTypes.
Currently, the address space is as follows:

|=========
| nodes | 2^35^ (∼ 34 billion)
| relationships | 2^35^ (∼ 34 billion)
| properties | 2^36^ to 2^38^ depending on property types (maximum ∼ 274 billion, always at least ∼ 68 billion)
| relationship types | 2^15^ (∼ 32 000)
|=========

[[capabilities]]
Capabilities
============

/////////
Details, originally contained in the capabilities document.
/////////

[[capabilities-data-security]]
== Data Security ==

Some data may need to be protected from unauthorized access (e.g., theft, modification).
Neo4j does not deal with data encryption explicitly, but supports all means built into the Java programming language and the JVM to protect data by encrypting it before storing.

Furthermore, data can be easily secured by running on an encrypted datastore at the file system level.
Finally, data protection should be considered in the upper layers of the surrounding system in order to prevent problems with scraping, malicious data insertion, and other threats.

[[capabilities-data-integrity]]
== Data Integrity ==

In order to keep data consistent, there needs to be mechanisms and structures that guarantee the integrity of all stored data.
In Neo4j, data integrity is maintained for the core graph engine together with other data sources - see below.

[[capabilities-core-graph-engine]]
=== Core Graph Engine ===

In Neo4j, the whole data model is stored as a graph on disk and persisted as
part of every committed transaction.
In the storage layer, Relationships, Nodes, and Properties have direct pointers to each other.
This maintains integrity without the need for data duplication between the different backend store files.

[[capabilities-different-data-sources]]
=== Different Data Sources ===

In a number of scenarios, the core graph engine is combined with other systems
in order to achieve optimal performance for non-graph lookups.
For example, Apache Lucene is frequently used as an additional index system for text queries that would otherwise be very processing-intensive in the graph layer.

To keep these external systems in synchronization with each other, Neo4j provides
full Two Phase Commit transaction management, with rollback support over all data
sources.
Thus, failed index insertions into Lucene can be transparently rolled back in all data sources and thus keep data up-to-date.

[[capabilities-data-integration]]
== Data Integration ==

Most enterprises rely primarily on relational databases to store their data, but
this may cause performance limitations.
In some of these cases, Neo4j can be used as an extension to supplement search/lookup for faster decision making.
However, in any situation where multiple data repositories contain the same data, synchronization can be an issue.

In some applications, it is acceptable for the search platform to be slightly out
of sync with the relational database.
In others, tight data integrity (eg., between Neo4j and RDBMS) is necessary.
Typically, this has to be addressed for data changing in real-time and for bulk data changes happening in the RDBMS.

A few strategies for synchronizing integrated data follows.

[[capabilities-event-based-synchronization]]
=== Event-based Synchronization ===

In this scenario, all data stores, both RDBMS and Neo4j, are fed with domain-specific
events via an event bus.
Thus, the data held in the different backends is not actually synchronized but rather replicated.

[[capabilities-periodic-synchronization]]
=== Periodic Synchronization ===

Another viable scenario is the periodic export of the latest changes in the RDBMS to
Neo4j via some form of SQL query.
This allows a small amount of latency in the synchronization, but has the advantage of using the RDBMS as the master for all data purposes.
The same process can be applied with Neo4j as the master data source.

[[capabilities-full-export]]
=== Periodic Full Export/Import of Data ===

Using the Batch Inserter tools for Neo4j, even large amounts of data can be imported
into the database in very short times.
Thus, a full export from the RDBMS and import into Neo4j becomes possible.
If the propagation lag between the RDBMS and Neo4j is not a big issue, this is a very viable solution.

[[capabilities-availability]]
== Availability and Reliability ==

Most mission-critical systems require the database subsystem to be accessible at all
times.
Neo4j ensures availability and reliability through a few different strategies.

[[capabilities-op-availability]]
=== Operational Availability ===

In order not to create a single point of failure, Neo4j supports different
approaches which provide transparent fallback and/or recovery from failures.

==== Online backup (Cold spare) ====

In this approach, a single instance of the master database is used, with Online
Backup enabled.
In case of a failure, the backup files can be mounted onto a new
Neo4j instance and reintegrated into the application.

==== Online Backup High Availability (Hot spare) ====

Here, a Neo4j "backup" instance listens to online transfers of changes from the
master.
In the event of a failure of the master, the backup is already running
and can directly take over the load.

==== High Availability cluster ====

This approach uses a cluster of database instances, with one (read/write) master
and a number of (read-only) slaves.
Failing slaves can simply be restarted and brought back online.
Alternatively, a new slave may be added by cloning an existing one.
Should the master instance fail, a new master will be elected by the remaining
cluster nodes.

[[capabilities-disaster]]
=== Disaster Recovery/ Resiliency ===

In cases of a breakdown of major part of the IT infrastructure, there need to be
mechanisms in place that enable the fast recovery and regrouping of the remaining
services and servers.
In Neo4j, there are different components that are suitable to be part of a disaster recovery strategy.

==== Prevention ====

* Online Backup High Availability to other locations outside the current data center.
* Online Backup to different file system locations: this is a simpler form of backup,
applying changes directly to backup files; it is thus more suited for local backup scenarios.
* Neo4j High Availability cluster: a cluster of one write-master Neo4j server and a number of read-slaves, getting transaction logs from the master.
  Write-master failover is handled by quorum election among the read-slaves for a new master.

==== Detection ====

* SNMP and JMX monitoring can be used for the Neo4j database.

==== Correction ====

* Online Backup: A new Neo4j server can be started directly on the backed-up files
and take over new requests.
* Neo4j High Availability cluster: A broken Neo4j read slave can be reinserted into the cluster, getting the latest updates from the master.
  Alternatively, a new server can be inserted by copying an existing server and applying the latest updates to it.

[[capabilities-capacity]]
== Capacity ==

[[capabilities-file-sizes]]
=== File Sizes ===

Neo4j relies on Java's Non-blocking I/O subsystem for all file handling.
Furthermore, while the storage file layout is optimized for interconnected data, Neo4j does not require raw devices.
Thus, filesizes are only limited by the underlying operating system's capacity to handle large files.
Physically, there is no built-in limit of the file handling capacity in Neo4j.

Neo4j tries to memory-map as much of the underlying store files as possible.
If the available RAM is not sufficient to keep all data in RAM, Neo4j will use buffers in some cases, reallocating the memory-mapped high-performance I/O windows to the regions with the most I/O activity dynamically.
Thus, ACID speed degrades gracefully as RAM becomes the limiting factor.

[[capabilities-read-speed]]
=== Read speed ===

Enterprises want to optimize the use of hardware to deliver the maximum business value
from available resources.
Neo4j's approach to reading data provides the best possible usage of all available hardware resources.
Neo4j does not block or lock any read operations; thus, there is no danger for deadlocks in read operations and no need for read transactions.
With a threaded read access to the database, queries can be run simultaneously on as many processors as may be available.
This provides very good scale-up scenarios with bigger servers.

[[capabilities-write-speed]]
=== Write speed ===

Write speed is a consideration for many enterprise applications.
However, there are two different scenarios:

. sustained continuous operation and
. bulk access (e.g., backup, initial or batch loading).

To support the disparate requirements of these scenarios, Neo4j supports two modes of writing to the storage layer.

In transactional, ACID-compliant normal operation, isolation level is maintained and
read operations can occur at the same time as the writing process.
At every commit, the data is persisted to disk and can be recovered to a consistent state upon system failures.
This requires disk write access and a real flushing of data.
Thus, the write speed of Neo4j on a single server in continuous mode is limited by the I/O capacity of the hardware.
Consequently, the use of fast SSDs is highly recommended for production scenarios.

Neo4j has a Batch Inserter that operates directly on the store files.
This mode does not provide transactional security, so it can only be used when there is a single write thread.
Because data is written sequentially, and never flushed to the logical logs, huge performance boosts are achieved.
The Batch Inserter is optimized for non-transactional bulk import of large amounts of data.

[[capabilities-data-size]]
=== Data size ===

In Neo4j, data size is mainly limited by the address space of the primary keys for Nodes, Relationships, Properties and RelationshipTypes.
Currently, the address space is as follows:

* 2ˆ35 (~ 34 billion) nodes
* 2ˆ35 (~ 34 billion) relationships
* 2ˆ36 (~ 68 billion) properties
* 2ˆ15 (~ 32 000) relationship types


PLANNER-825: Mention OptaPlanner REST API changes in 7.0 release notes

[[_kieserver.releasenoteskie.7.0.0]]
= Breaking changes in Kie Server 7.0 from 6.x

== ServiceResponse XStream marshalling changes

NOTE: This release note applies only when directly interfacing with the Kie Server (kie-server) API, not when using the Kie Server Java Client (kie-server-client) API.

In an effort to be more consistent with JAXB marshalling, XStream marshalling has undergone the following changes:

- The XML ServiceResponse element's `response` object no longer renders with the canonical name.
- XStream now uses `type` and `msg` as attributes, not child elements.

For more details, see https://issues.jboss.org/browse/DROOLS-1509[DROOLS-1509].

== Simplified Planner REST API

=== ServiceResponse wrapper removal
`ServiceResponse` wrapper has been removed from Planner service responses returned by KIE Server.
This allows an easier processing of the responses on the client side.

[source,xml,options="nowrap"]
----
<solver-instance>
    ...
    <status>SOLVING</status>
    <score scoreClass="org.optaplanner.core.api.score.buildin.hardsoft.HardSoftScore">0hard/-10soft</score>
    <best-solution class="curriculumcourse.curriculumcourse.CourseSchedule">
        ...
    </best-solution>
</solver-instance>
----

=== New Planner API overview

Register a solver:

- PUT http://${kie-server}/services/rest/server/containers/${container_id}/solvers/${solver_id}

Submit a solution:

- POST http://${kie-server}/services/rest/server/containers/${container_id}/solvers/${solver_id}/state/solving

Get the best solution:

- GET http://${kie-server}/services/rest/server/containers/${container_id}/solvers/${solver_id}/bestsolution

Terminate a solver:

- POST http://${kie-server}/services/rest/server/containers/${container_id}/solvers/${solver_id}/state/terminating-early

Dispose a solver:

- DELETE http://${kie-server}/services/rest/server/containers/${container_id}/solvers/${solver_id}


Update 2019-01-31-java-language.adoc

Update 2019-01-31-java-language.adoc

= Java 语言
:hp-image: /covers/cover.png
:published_at: 2019-01-31
:hp-tags: Java,
:hp-alt-title: java language

== 基础
=== 面向对象编程概念
核心概念：

* 对象
* 消息（messages）
* 类
* 继承

* 与现实的关联
* 语法

==== 对象
对象是面向对象技术的关键，常用于对现实事物建模，是其相关的状态与行为的软件封装。

. 理解现实世界
现实事物都能被分割为两个特征：状态(state)、行为(behavior)，学习面向对象编程的好方法便是辨识你能想到的每个事物的状态与行为。或许你会发现一些复杂性，有的事物能够囊括其他事物的状态与行为。

. 进入代码世界
现实世界的状态与行为对应代码世界的方法(Methods)与字段(Fields)

* 状态与行为如何用对象表示
* 数据封装
* 使用对象的益处

= Java 语言
:hp-image: /covers/cover.png
:published_at: 2019-01-31
:hp-tags: Java,
:hp-alt-title: java language

== 基础
=== 面向对象编程概念
核心概念：

* 对象
* 消息（messages）
* 类
* 继承

* 与现实的关联
* 语法

==== 对象
对象常用于对现实存在建模，是其相关的状态与行为的软件封装。


Remove link to deleted section in docs

Remove link to deleted section in docs

[[viewing-debugging-dependencies]]
[[sec:debugging-build-scans]]
= View and Debug Dependencies

Gradle provides tooling to navigate dependency graphs and mitigate link:https://en.wikipedia.org/wiki/Dependency_hell[dependency hell].
Users can render the full graph of dependencies as well as identify the selection reason and origin for a dependency.
Dependencies can originate through build script declared dependencies or transitive dependencies.
You can visualize dependencies with:

- the built-in Gradle CLI `dependencies` task
- the built-in Gradle CLI `dependencyInsight` task
- link:https://scans.gradle.com/[build scans]

[[sec:listing_dependencies]]
== List Project Dependencies

Gradle provides the built-in `dependencies` task to render a dependency tree from the command line.
By default, the dependency tree renders dependencies for all <<declaring_dependencies.adoc#sec:what-are-dependency-configurations,configurations>> within a <<command_line_interface#executing_tasks_in_multi_project_builds,single project>>.
The dependency tree indicates the selected version of each dependency.
It also displays information about dependency conflict resolution.

The `dependencies` task can be especially helpful for issues related to transitive dependencies.
Your build file lists direct dependencies, but the `dependencies` task can help you understand which transitive dependencies resolve during your build.

=== Output Annotations

The `dependencies` task marks dependency trees with the following annotations:

- `(*)`: Indicates repeated occurrences of a transitive dependency subtree. Gradle expands transitive dependency subtrees only once per project; repeat occurrences only display the root of the subtree, followed by this annotation.
- `(c)`: This element is a <<dependency_constraints.adoc#sec:direct-vs-transitive-deps,dependency constraint>>, not a dependency. Look for the matching dependency elsewhere in the tree.
- `(n)`: A dependency or dependency configuration that <<declaring_dependencies.adoc#sec:resolvable-consumable-configs,cannot be resolved>>.

=== Specify a Dependency Configuration

To focus on the information about one dependency configuration, provide the optional parameter `--configuration`.
Just like <<command_line_interface#sec:name_abbreviation, project and task names>>, Gradle accepts abbreviated names to select a dependency configuration.
For example, you can specify `tRC` instead of `testRuntimeClasspath` if the pattern matches to a single dependency configuration.
Both of the following examples show dependencies in the `testRuntimeClasspath` dependency configuration of a Java project:

----
> gradle -q dependencies --configuration testRuntimeClasspath
----

----
> gradle -q dependencies --configuration tRC
----

To see a list of all the configurations available in a project, including those added by any plugins, you can run a `resolvableConfigurations` report.

For more info, see that plugin's documentation (for instance, the Java Plugin is documented <<java_plugin.adoc#sec:java_plugin_and_dependency_management,here>>).

=== Example

Consider a project that uses the link:https://www.eclipse.org/jgit/[JGit library] to execute Source Control Management (SCM) operations for a release process.
You can declare dependencies for external tooling with the help of a <<declaring_dependencies.adoc#sec:what-are-dependency-configurations,custom dependency configuration>>.
This avoids polluting other contexts, such as the compilation classpath for your production source code.

The following example declares a custom dependency configuration named "scm" that contains the JGit dependency:

====
include::sample[dir="snippets/dependencyManagement/inspectingDependencies-dependenciesReport/groovy",files="build.gradle[tags=dependency-declaration]"]
include::sample[dir="snippets/dependencyManagement/inspectingDependencies-dependenciesReport/kotlin",files="build.gradle.kts[tags=dependency-declaration]"]
====

Use the following command to view a dependency tree for the `scm` dependency configuration:

----
> gradle -q dependencies --configuration scm
include::{snippetsPath}/dependencyManagement/inspectingDependencies-dependenciesReport/tests/dependencyReport.out[]
----

[[sec:identifying_reason_dependency_selection]]
== Identify the Dependency Version Selected

A project may request two different versions of the same dependency either directly or transitively.
Gradle applies <<dependency_resolution.adoc#sec:version-conflict,version conflict resolution>> to ensure that only one version of the dependency exists in the dependency graph.
The following example introduces a conflict with `commons-codec:commons-codec`, added both as a direct dependency and a transitive dependency of JGit:

====
include::sample[dir="snippets/dependencyManagement/inspectingDependencies-dependencyInsightReport/groovy",files="build.gradle[tags=dependency-declaration]"]
include::sample[dir="snippets/dependencyManagement/inspectingDependencies-dependencyInsightReport/kotlin",files="build.gradle.kts[tags=dependency-declaration]"]
====

The dependency tree in a link:https://scans.gradle.com/[build scan] shows information about conflicts.
Click on a dependency and select the "Required By" tab to see the selection reason and origin of the dependency.

image::dependency-management-dependency-insight-report-build-scan.png[]

=== Dependency Insights

Gradle provides the built-in `dependencyInsight` task to render a  _dependency insight report_ from the command line.
Dependency insights provide information about a single dependency within a single <<declaring_dependencies.adoc#sec:what-are-dependency-configurations,configuration>>.
Given a dependency, you can identify the selection reason and origin.

`dependencyInsight` accepts the following parameters:

`--dependency <dependency>` (mandatory)::
The dependency to investigate.
You can supply a complete `group:name`, or part of it.
If multiple dependencies match, Gradle generates a report covering all matching dependencies.
`--configuration <name>` (mandatory)::
The dependency configuration which resolves the given dependency.
This parameter is optional for projects that use the <<java_plugin#java_plugin, Java plugin>>, since the plugin provides a default value of `compileClasspath`.
`--single-path` (optional)::
Render only a single path to the dependency.

The following code snippet demonstrates how to run a dependency insight report for all paths to a dependency named "commons-codec" within the "scm" configuration:

----
> gradle -q dependencyInsight --dependency commons-codec --configuration scm
include::{snippetsPath}/dependencyManagement/inspectingDependencies-dependencyInsightReport/tests/dependencyInsightReport.out[]
----

For more information about configurations, see the <<declaring_dependencies.adoc#sec:what-are-dependency-configurations,dependency configuration documentation>>.

==== Selection Reasons

The "Selection reasons" section of the dependency insight report lists the reasons why a dependency was selected.
Have a look at the table below to understand the meaning of the different terms used:

.Terminology
[%header%autowidth,compact]
|===
| Reason    | Meaning

| (Absent)
| No reason other than a reference, direct or transitive, was present.

| Was requested : <text>
| The dependency appears in the graph, and the inclusion came with a <<declaring_dependencies#sec:documenting-dependencies, `because` text>>.

| Was requested : didn't match versions <versions>
| The dependency appears with a <<dynamic_versions#sub:declaring_dependency_with_dynamic_version, dynamic version>> which did not include the listed versions.
May be followed by a `because` text.

| Was requested : reject version <versions>
| The dependency appears with a <<rich_versions#rich-version-constraints, rich version>> containing one or more `reject`.
May be followed by a `because` text.

| By conflict resolution : between versions <version>
| The dependency appeared multiple times, with different version requests.
This resulted in <<dependency_resolution#sec:version-conflict, conflict resolution>> to select the most appropriate version.

| By constraint
| A <<dependency_constraints#sec:adding-constraints-transitive-deps, dependency constraint>> participated in the version selection.
May be followed by a `because` text.

| By ancestor
| There is a <<rich_versions#rich-version-constraints, rich version>> with a `strictly` which enforces the version of this dependency.

| Selected by rule
| A <<resolution_rules#resolution_rules, dependency resolution rule>> overruled the default selection process.
May be followed by a `because` text.

| Rejection : <version> by rule because <text>
| A `ComponentSelection.reject` link:{groovyDslPath}/org.gradle.api.artifacts.ComponentSelection.html#org.gradle.api.artifacts.ComponentSelection:reject(java.lang.String)[rejected the given version] of the dependency.

| Rejection: version <version>: <attributes information>
| The dependency has a dynamic version and some versions did not match the <<variant_model#sec:variant-aware-matching, requested attributes>>.

| Forced
| The build enforces the version of the dependency through an enforced platform or resolution strategy.
|===

If multiple selection reasons exist, the insight report lists all of them.

== Troubleshooting

[[sec:resolving-version-conflict]]
=== Version Conflicts

If the selected version does not match your expectation, Gradle offers a series of tools to help you <<dependency_constraints.adoc#dependency-constraints,control transitive dependencies>>.

[[sec:resolving-variant-aware-errors]]
=== Variant Selection Errors

Sometimes a selection error happens at the <<variant_model.adoc#understanding-variant-selection,variant selection level>>.
Have a look at the <<variant_model.adoc#sec:variant-select-errors,dedicated section>> to understand these errors and how to resolve them.

[[sub:resolving-unsafe-configuration-resolution-errors]]
=== Unsafe Configuration Resolution Errors

Resolving a configuration can have side effects on Gradle's project model.
As a result, Gradle must manage access to each project's configurations.
There are a number of ways a configuration might be resolved unsafely.
For example:

* A task from one project directly resolves a configuration in another project in the task's action.
* A task specifies a configuration from another project as an input file collection.
* A build script for one project resolves a configuration in another project during evaluation.
* Project configurations are resolved in the settings file.

Gradle produces a deprecation warning for each unsafe access.
Unsafe access can cause indeterminate errors.
You should <<command_line_interface.adoc#sec:command_line_warnings,fix unsafe access warnings>> in your build.

In most cases, you can resolve unsafe accesses by creating a cross-project dependency on the other project.
See the documentation for <<cross_project_publications.adoc#cross_project_publications, sharing outputs between projects>> for more information.

If you find a use case that can't be resolved using these techniques, please let us know by filing a https://github.com/gradle/gradle/issues[GitHub Issue].

[[viewing-debugging-dependencies]]
[[sec:debugging-build-scans]]
= View and Debug Dependencies

Gradle provides tooling to navigate dependency graphs and mitigate link:https://en.wikipedia.org/wiki/Dependency_hell[dependency hell].
Users can render the full graph of dependencies as well as identify the selection reason and origin for a dependency.
Dependencies can originate through build script declared dependencies or transitive dependencies.
You can visualize dependencies with:

- the built-in Gradle CLI `dependencies` task
- the built-in Gradle CLI `dependencyInsight` task
- link:https://scans.gradle.com/[build scans]

[[sec:listing_dependencies]]
== List Project Dependencies

Gradle provides the built-in `dependencies` task to render a dependency tree from the command line.
By default, the dependency tree renders dependencies for all <<declaring_dependencies.adoc#sec:what-are-dependency-configurations,configurations>> within a <<command_line_interface#executing_tasks_in_multi_project_builds,single project>>.
The dependency tree indicates the selected version of each dependency.
It also displays information about dependency conflict resolution.

The `dependencies` task can be especially helpful for issues related to transitive dependencies.
Your build file lists direct dependencies, but the `dependencies` task can help you understand which transitive dependencies resolve during your build.

=== Output Annotations

The `dependencies` task marks dependency trees with the following annotations:

- `(*)`: Indicates repeated occurrences of a transitive dependency subtree. Gradle expands transitive dependency subtrees only once per project; repeat occurrences only display the root of the subtree, followed by this annotation.
- `(c)`: This element is a <<dependency_constraints.adoc#sec:direct-vs-transitive-deps,dependency constraint>>, not a dependency. Look for the matching dependency elsewhere in the tree.
- `(n)`: A dependency or dependency configuration that <<declaring_dependencies.adoc#sec:resolvable-consumable-configs,cannot be resolved>>.

=== Specify a Dependency Configuration

To focus on the information about one dependency configuration, provide the optional parameter `--configuration`.
Just like <<command_line_interface#sec:name_abbreviation, project and task names>>, Gradle accepts abbreviated names to select a dependency configuration.
For example, you can specify `tRC` instead of `testRuntimeClasspath` if the pattern matches to a single dependency configuration.
Both of the following examples show dependencies in the `testRuntimeClasspath` dependency configuration of a Java project:

----
> gradle -q dependencies --configuration testRuntimeClasspath
----

----
> gradle -q dependencies --configuration tRC
----

To see a list of all the configurations available in a project, including those added by any plugins, you can run a `resolvableConfigurations` report.

For more info, see that plugin's documentation (for instance, the Java Plugin is documented <<java_plugin.adoc#sec:java_plugin_and_dependency_management,here>>).

=== Example

Consider a project that uses the link:https://www.eclipse.org/jgit/[JGit library] to execute Source Control Management (SCM) operations for a release process.
You can declare dependencies for external tooling with the help of a <<declaring_dependencies.adoc#sec:what-are-dependency-configurations,custom dependency configuration>>.
This avoids polluting other contexts, such as the compilation classpath for your production source code.

The following example declares a custom dependency configuration named "scm" that contains the JGit dependency:

====
include::sample[dir="snippets/dependencyManagement/inspectingDependencies-dependenciesReport/groovy",files="build.gradle[tags=dependency-declaration]"]
include::sample[dir="snippets/dependencyManagement/inspectingDependencies-dependenciesReport/kotlin",files="build.gradle.kts[tags=dependency-declaration]"]
====

Use the following command to view a dependency tree for the `scm` dependency configuration:

----
> gradle -q dependencies --configuration scm
include::{snippetsPath}/dependencyManagement/inspectingDependencies-dependenciesReport/tests/dependencyReport.out[]
----

[[sec:identifying_reason_dependency_selection]]
== Identify the Dependency Version Selected

A project may request two different versions of the same dependency either directly or transitively.
Gradle applies <<dependency_resolution.adoc#sec:version-conflict,version conflict resolution>> to ensure that only one version of the dependency exists in the dependency graph.
The following example introduces a conflict with `commons-codec:commons-codec`, added both as a direct dependency and a transitive dependency of JGit:

====
include::sample[dir="snippets/dependencyManagement/inspectingDependencies-dependencyInsightReport/groovy",files="build.gradle[tags=dependency-declaration]"]
include::sample[dir="snippets/dependencyManagement/inspectingDependencies-dependencyInsightReport/kotlin",files="build.gradle.kts[tags=dependency-declaration]"]
====

The dependency tree in a link:https://scans.gradle.com/[build scan] shows information about conflicts.
Click on a dependency and select the "Required By" tab to see the selection reason and origin of the dependency.

image::dependency-management-dependency-insight-report-build-scan.png[]

=== Dependency Insights

Gradle provides the built-in `dependencyInsight` task to render a  _dependency insight report_ from the command line.
Dependency insights provide information about a single dependency within a single <<declaring_dependencies.adoc#sec:what-are-dependency-configurations,configuration>>.
Given a dependency, you can identify the selection reason and origin.

`dependencyInsight` accepts the following parameters:

`--dependency <dependency>` (mandatory)::
The dependency to investigate.
You can supply a complete `group:name`, or part of it.
If multiple dependencies match, Gradle generates a report covering all matching dependencies.
`--configuration <name>` (mandatory)::
The dependency configuration which resolves the given dependency.
This parameter is optional for projects that use the <<java_plugin#java_plugin, Java plugin>>, since the plugin provides a default value of `compileClasspath`.
`--single-path` (optional)::
Render only a single path to the dependency.

The following code snippet demonstrates how to run a dependency insight report for all paths to a dependency named "commons-codec" within the "scm" configuration:

----
> gradle -q dependencyInsight --dependency commons-codec --configuration scm
include::{snippetsPath}/dependencyManagement/inspectingDependencies-dependencyInsightReport/tests/dependencyInsightReport.out[]
----

For more information about configurations, see the <<declaring_dependencies.adoc#sec:what-are-dependency-configurations,dependency configuration documentation>>.

==== Selection Reasons

The "Selection reasons" section of the dependency insight report lists the reasons why a dependency was selected.
Have a look at the table below to understand the meaning of the different terms used:

.Terminology
[%header%autowidth,compact]
|===
| Reason    | Meaning

| (Absent)
| No reason other than a reference, direct or transitive, was present.

| Was requested : <text>
| The dependency appears in the graph, and the inclusion came with a <<declaring_dependencies#sec:documenting-dependencies, `because` text>>.

| Was requested : didn't match versions <versions>
| The dependency appears with a <<dynamic_versions#sub:declaring_dependency_with_dynamic_version, dynamic version>> which did not include the listed versions.
May be followed by a `because` text.

| Was requested : reject version <versions>
| The dependency appears with a <<rich_versions#rich-version-constraints, rich version>> containing one or more `reject`.
May be followed by a `because` text.

| By conflict resolution : between versions <version>
| The dependency appeared multiple times, with different version requests.
This resulted in <<dependency_resolution#sec:version-conflict, conflict resolution>> to select the most appropriate version.

| By constraint
| A <<dependency_constraints#sec:adding-constraints-transitive-deps, dependency constraint>> participated in the version selection.
May be followed by a `because` text.

| By ancestor
| There is a <<rich_versions#rich-version-constraints, rich version>> with a `strictly` which enforces the version of this dependency.

| Selected by rule
| A <<resolution_rules#resolution_rules, dependency resolution rule>> overruled the default selection process.
May be followed by a `because` text.

| Rejection : <version> by rule because <text>
| A `ComponentSelection.reject` link:{groovyDslPath}/org.gradle.api.artifacts.ComponentSelection.html#org.gradle.api.artifacts.ComponentSelection:reject(java.lang.String)[rejected the given version] of the dependency.

| Rejection: version <version>: <attributes information>
| The dependency has a dynamic version and some versions did not match the <<variant_model#sec:variant-aware-matching, requested attributes>>.

| Forced
| The build <<dependency_downgrade_and_exclude#forced_dependencies_vs_strict_dependencies, enforces>> the version of the dependency.
|===

If multiple selection reasons exist, the insight report lists all of them.

== Troubleshooting

[[sec:resolving-version-conflict]]
=== Version Conflicts

If the selected version does not match your expectation, Gradle offers a series of tools to help you <<dependency_constraints.adoc#dependency-constraints,control transitive dependencies>>.

[[sec:resolving-variant-aware-errors]]
=== Variant Selection Errors

Sometimes a selection error happens at the <<variant_model.adoc#understanding-variant-selection,variant selection level>>.
Have a look at the <<variant_model.adoc#sec:variant-select-errors,dedicated section>> to understand these errors and how to resolve them.

[[sub:resolving-unsafe-configuration-resolution-errors]]
=== Unsafe Configuration Resolution Errors

Resolving a configuration can have side effects on Gradle's project model.
As a result, Gradle must manage access to each project's configurations.
There are a number of ways a configuration might be resolved unsafely.
For example:

* A task from one project directly resolves a configuration in another project in the task's action.
* A task specifies a configuration from another project as an input file collection.
* A build script for one project resolves a configuration in another project during evaluation.
* Project configurations are resolved in the settings file.

Gradle produces a deprecation warning for each unsafe access.
Unsafe access can cause indeterminate errors.
You should <<command_line_interface.adoc#sec:command_line_warnings,fix unsafe access warnings>> in your build.

In most cases, you can resolve unsafe accesses by creating a cross-project dependency on the other project.
See the documentation for <<cross_project_publications.adoc#cross_project_publications, sharing outputs between projects>> for more information.

If you find a use case that can't be resolved using these techniques, please let us know by filing a https://github.com/gradle/gradle/issues[GitHub Issue].


HBASE-17730 Add license header to design doc.

////
/**
 *
 * Licensed to the Apache Software Foundation (ASF) under one
 * or more contributor license agreements.  See the NOTICE file
 * distributed with this work for additional information
 * regarding copyright ownership.  The ASF licenses this file
 * to you under the Apache License, Version 2.0 (the
 * "License"); you may not use this file except in compliance
 * with the License.  You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
////

= Coprocessor Design Improvements (link:https://issues.apache.org/jira/browse/HBASE-17732[HBASE-17732])

Author: Apekshit Sharma

== Introduction

This doc explains current design of Coprocessor feature in brief, few issues I noticed, and
suggestions on how to fix them & further improve overall design.

*TL;DR* +
We are moving from

* Observer *is* Coprocessor
* FooService *is* CoprocessorService

To

* Coprocessor *has* Observer
* Coprocessor *has* Service

See code example in <<main.design.change.suggestions>>.

== Terminology

hooks = functions in observers. Named because third-party use these functions to “hook up” custom
logic to internal code paths.

[[background]]
== Background

Coprocessors are well link:http://hbase.apache.org/book.html#cp[documented in the refguide].

Here we give a little background information on involved classes, their responsibilities, and
relationship to each other.

* Main classes
** Coprocessor (interface)
*** All *Observer* interfaces derive from Coprocessor interface.
**** Coprocessor Interface is a _Marker _Interface. It just has start/stop methods and enums for
stages in the Coprocessor Lifecycle.
** http://hbase.apache.org/book.html#_observer_coprocessors[Observers] (interface)
*** Contain hooks which third-party programs can override to inject functionality in various
internal code paths. For e.g preCreateTable(...) will be called just before any table is created.
*** Current set of observers: _MasterObserver, RegionObserver, RegionServerObserver, WALObserver,
EndpointObserver, BulkLoadObserver._
** CoprocessorEnvironment (interface)
*** Encapsulates a coprocessor instance and other information like versions, priority, etc.
*** Coprocessor implementations use it to get access to tables.
*** Four main implementations: _MasterEnvironment, RegionEnvironment, RegionServerEnvironment,
WALEnvironment._
** CoprocessorHost (abstract class)
*** Responsible for loading coprocessors
*** Four concrete sub-classes: MasterCoprocessorHost, RegionCoprocessorHost,
RegionServerCoprocessorHost, WALCoprocessorHost
*** Each host is tied to corresponding environment type using template argument ‘E’.

== Problems

* CoprocessorEnvironment has `Coprocessor getInstance()`. Since Observer types which can be
handled by an environment are not statically tied to it, coprocessor hosts (which are statically
tied to Environment) don’t know which kind of coprocessors are relevant to them, i.e.
MasterCoprocessorHost is tied to MasterEnvironment, but it doesn’t know that it can only handle
MasterObserver(s). As a result:
** Problem 1: All hosts load all observers i.e. MasterCoprocessorHost will also load RegionObserver
and other observers.
** Problem 2: Hosts use runtime checks likes `observer instanceOf ExpectedObserver` in
execOperation and other functions to filter out incompatible observers.
** Problem 3: Many redundant functions in every implementation of coprocessor host.
* Observer *extends* Coprocessor (inheritance)
** Problem 4: Any third-party coprocessor which wants to use many observers will have to extend all
of them in same class. For eg.
class AccessController implements MasterObserver,
    RegionObserver, RegionServerObserver, EndpointObserver,
    BulkLoadObserver, AccessControlService.Interface,
    CoprocessorService
That results in big classes with 100+ functions.

== Proposed Solutions

* There are 6 types of observers (listed in <<background>> section above), but just 4 types of
CoprocessorEnvironment. So some XEnvironment has to be handling multiple Observers
(RegionEnvironment serves RegionObserver, EndpointObserver and BulkLoadObservers). Our aim is to
statically tie environment to types of observers it can serve. There are two alternative choices
here:
** Option 1: Limit to 4 types of Observers. That fits nicely in our pattern-of-4
(4 hosts, 4 environments, 4 observers) and will make the overall design simpler. Although it may
look simple at surface, it’ll actually lead to a single large observer interface which will only
grow and may contain 100s of hooks in future (master already has 100+)
** Option 2: Use multiple observers to group together similar kinds of hooks.
Like we have RegionObserver, EndpointObserver and BulkLoadObserver; we can have ScannerObserver,
AMObserver, etc instead of single MasterObserver. Benefits being
*** Proper encapsulation of related hooks and separation from unrelated hooks
*** We can give different Stability guarantees for different set of hooks. Something which’ll make
our CP compat management much easier.

I believe Option 2 to be better than Option 1, and the design changes suggested later are based on
Option 2.

* For problem 4, we should replace inheritance with composition, so developers have choice to
break out observer implementations into separate classes.

[[main.design.change.suggestions]]
== Main Design Change suggestions

* Extend pattern-of-4 up to coprocessor.
+
CoprocessorHost →  Env → Coprocessor
* Tie each CoprocessorEnvironment to corresponding Coprocessor
* Use composition instead of inheritance between Coprocessor and Observers.

=== Current design

Only changing parts are mentioned here. Anything not changing is represented by “...”

[source,java]
----
interface Coprocessor {
  ...
}

interface CoprocessorEnvironment {
  Coprocessor getInstance();
  ...
}

interface CoprocessorService {
  Service getService();
}

abstract class CoprocessorHost<E extends CoprocessorEnvironment> {
  ...
}

interface RegionObserver extends Coprocessor {
  ...
}

interface BulkLoadObserver extends Coprocessor {
  ...
}

interface EndpointObserver extends Coprocessor {
  ...
}
----

=== New design

[source,java]
----
interface Coprocessor {
  ...
}

// Extend pattern-of-4 to coprocessors.
interface RegionCoprocessor extends Coprocessor {
  RegionObserver getRegionObserver();
  BulkLoadObserver getBulkLoadObserver();
  EndpointObserver getEndpointObserver();
  Service getService();
}

// Tie coprocessor to environment
interface CoprocessorEnvironment<C extends Coprocessor> {
  C getInstance();
  ...
}

abstract class CoprocessorHost<C extends Coprocessor, E extends CoprocessorEnvironment<C>> {
  ...
}

// Doesn’t extend coprocessor
interface RegionObserver extends Coprocessor {
  …
}

// Doesn’t extend coprocessor
interface BulkLoadObserver extends Coprocessor {
  …
}
----

== How does it fix our issues?

* Fix #1:  CoprocessorHost is now tied to types of coprocessors it can serve by template argument C.
During load time, it can ignore any coprocessors which don’t match.
* Fix #2 and #3: Pull the duplicate functions into CoprocessorHost class. Individual host subclasses
can use these directly. One interesting part here is ObserverGetter<C, O>. For any specific hook,
say in observer O, subclasses specify ObserverGetter<C, O> so that the shared methods can extract
observer O from coprocessor C.
* Fix #4: Choosing composition over inheritance, by adding getter functions in coprocessors (e.g.
getRegionObserver()), implementations can now break up observer implementations into separate
classes. For e.g. our AccessController will now just be:
`class AccessController implements AccessControlService.Interface, CoprocessorService`

[[migrating.existing.cps.to.new.design]]
== Migrating existing CPs to new design

There’s a simple and small fix that can migrate existing coprocessors to the new design. +
If  we had the following observer in the old design: +
----
class FooObserver implements RegionObserver {
...
...
}
----

It can be “made to work” with the new design like this: +
----
class FooObserver implements RegionCoprocessor, RegionObserver {
  public RegionObserver getRegionObserver() { return this; }
  ...
  ...
}
----

However, note that this is only a workaround to quickly migrate ~100 CPs in our code base to new
design without creating new classes and files. *New CPs should NOT follow this pattern.*

== Additional Benefit

* Cleaner solution to https://issues.apache.org/jira/browse/HBASE-17106[HBASE-17106].
* We can have multiple observer interfaces for each environment now. For e.g We can break our single
 monolithic MasterObsever (~150 functions) to multiple observer interfaces - ScannerObserver,
 AMObserver, etc.
* These observers can be assigned different compatibility guarantees. For instances, new hooks by
Backup feature could have been put into separate Observer and marked IS.Unstable, while features
which have hardened over years can be marked IS.Stable.
* Only the coprocessors corresponding to hosts which support endpoint service will have
“getService()” method. So WALCoprocessor which cannot support service doesn’t have one. That may
look minor thing. But if our design can cleanly convey what is and isn’t supported, that’s beautiful
and powerful and helpful for downstream developers.


Update 2016-08-15-Play-Framework-Beginner-Tutorial-How-to-handle-a-big-json-file-in-play-more-than-22-root-variables.adoc

# Play Framework - Beginner Tutorial : How to handle a big json file in play ( more than 22 root variables)

:published_at: 2016-08-15
:hp-tags: play

It is not a good practice to have such a big json with many root variables. Nevertheless, we might need to call a rest api that will give a json like this

```
{  "a1": ...,  "a2" : ...,  "a3" : ...,  "a4" : ...,  "a5" : ...,  "a6" : ...,  "a7" : ...,  "a8" : ...,  "a9" : ...,  "a10" : ...,  "a11" : ...,  "a12" : ...,  "a13" : ...,  "a14" : ...,  "a15" : ...,  "a16" : ...,  "a17" : ...,  "a18" : ...,  "a19" : ...,  "a20" : ...,  "a21": ...,  "a22" : ...,  "a23" : ...,  "a24" : ...,  ....}

# Play Framework - Beginner Tutorial : How to handle a big json file in play ( more than 22 root variables)

:published_at: 2016-08-15
:hp-tags: play

It is not a good practice to have such a big json with many root variables. Nevertheless, we might need to call a rest api that will give a json like this

'''
{  "a1": ...,  "a2" : ...,  "a3" : ...,  "a4" : ...,  "a5" : ...,  "a6" : ...,  "a7" : ...,  "a8" : ...,  "a9" : ...,  "a10" : ...,  "a11" : ...,  "a12" : ...,  "a13" : ...,  "a14" : ...,  "a15" : ...,  "a16" : ...,  "a17" : ...,  "a18" : ...,  "a19" : ...,  "a20" : ...,  "a21": ...,  "a22" : ...,  "a23" : ...,  "a24" : ...,  ....}

'''


Add documentation for cloning in setup

Add documentation for cloning in setup

= How to build your own project upon Edge

Edge is designed to be built upon.
You are free to make whatever changes you like (additions and deletions), in accordance with the <<_license>> (MIT).

== Create a repository

If you don't have a remote repository already (e.g. on GitHub), here's how to create a new local one:

[source,shell]
----
src$ mkdir acme
src$ cd acme
acme$ git init
----

If you already have a repository, you can clone it like so:

[source,shell]
----
src$ git clone git@github.com:acme/acme.git
src$ cd acme
----

== Add Edge to your project

Once you have your repository, you can add Edge as a remote, and incorporate it in:

[source,shell]
----
acme$ git remote add edge https://github.com/juxt/edge.git
acme$ git pull edge master
----

== Add a remote later (optional)

It's a good idea to have somewhere to back up your commits.

For example, if you create a new repository on GitHub called `acme` under the organisation `acme`, you could add the repository to your project like this:

.Create a git remote
[source,shell]
----
acme$ git remote add origin git@github.com:acme/acme.git
acme$ git push -u origin master
----

== Create a new app

With your new project created, you're ready to create an app.
Apps are deps.edn projects within Edge which are intended to be run as a server.

From the root of the repo, run the `./bin/app` script.
It can be run with an optional flags which add support for Sass or Clojurescript, these are `--sass` and `--cljs` respectively.

[NOTE]
====
Your project name should be namespaced to match your application.
If your company was named "Acme" you might use "acme/api" or "com.acme/api".

If you're unsure, use your company name at work, or your github username for hobby projects.
There's a low chance of conflicts in an application.

The project namespace will determine the Clojure namespaces within your application.
====

[source,shell]
----
edge$ ./bin/app acme/api
edge$ ./bin/app acme/blog --sass
edge$ ./bin/app acme/dashboard --cljs
edge$ ./bin/app acme/radar --sass --cljs
----

== Next steps

<<dev-guide.adoc#,Learn Edge's development environment>>.

== License

----
The MIT License (MIT)

Copyright © 2016-2019 JUXT LTD.

Permission is hereby granted, free of charge, to any person obtaining a copy of
this software and associated documentation files (the "Software"), to deal in
the Software without restriction, including without limitation the rights to
use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
the Software, and to permit persons to whom the Software is furnished to do so,
subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
----

= How to build your own project upon Edge

Edge is designed to be built upon.
You are free to make whatever changes you like (additions and deletions), in accordance with the <<_license>> (MIT).

== Create a new project

.Create new project
[source,shell]
----
src$ mkdir acme
src$ cd acme
acme$ git init
acme$ git remote add edge https://github.com/juxt/edge.git
acme$ git pull edge master
----

== Create a remote (optional)

It's a good idea at this point to have somewhere to back up your commits.

For example, if you create a new repository on GitHub called `acme` under the organisation `acme`, you could add the repository to your project like this:

.Create a git remote
[source,shell]
----
acme$ git remote add origin git@github.com:acme/acme.git
acme$ git push -u origin master
----

== Create a new app

With your new project created, you're ready to create an app.
Apps are deps.edn projects within Edge which are intended to be run as a server.

From the root of the repo, run the `./bin/app` script.
It can be run with an optional flags which add support for Sass or Clojurescript, these are `--sass` and `--cljs` respectively.

[NOTE]
====
Your project name should be namespaced to match your application.
If your company was named "Acme" you might use "acme/api" or "com.acme/api".

If you're unsure, use your company name at work, or your github username for hobby projects.
There's a low chance of conflicts in an application.

The project namespace will determine the Clojure namespaces within your application.
====

[source,shell]
----
edge$ ./bin/app acme/api
edge$ ./bin/app acme/blog --sass
edge$ ./bin/app acme/dashboard --cljs
edge$ ./bin/app acme/radar --sass --cljs
----

== Next steps

<<dev-guide.adoc#,Learn Edge's development environment>>.

== License

----
The MIT License (MIT)

Copyright © 2016-2019 JUXT LTD.

Permission is hereby granted, free of charge, to any person obtaining a copy of
this software and associated documentation files (the "Software"), to deal in
the Software without restriction, including without limitation the rights to
use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
the Software, and to permit persons to whom the Software is furnished to do so,
subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
----


[guide] Remove ref to Swing/SwtScheduler in addons appendix (#2959)

See https://github.com/reactor/reactor-addons/issues/273

[[reactor-extra]]
= Reactor-Extra

The `reactor-extra` artifact contains additional operators and utilities that are for
users of `reactor-core` with advanced needs, or incubating operators.

As this is a separate artifact, you need to explicitly add it to your build. The following
example shows how to do so in Gradle:

====
[source,groovy]
----
dependencies {
     compile 'io.projectreactor:reactor-core'
     compile 'io.projectreactor.addons:reactor-extra' <1>
}
----
<1> Add the reactor extra artifact in addition to core. See <<getting>> for details
about why you do not need to specify a version if you use the BOM, usage in Maven, and other details.
====

[[extra-tuples]]
== `TupleUtils` and Functional Interfaces

The `reactor.function` package contains functional interfaces that complement the Java 8
`Function`, `Predicate`, and `Consumer` interfaces, for three to eight values.

`TupleUtils` offers static methods that act as a bridge between lambdas of these functional
interfaces to a similar interface on the corresponding `Tuple`.

This lets you easily work with independent parts of any `Tuple`, as the following example shows:

====
[source,java]
----
.map(tuple -> {
  String firstName = tuple.getT1();
  String lastName = tuple.getT2();
  String address = tuple.getT3();

  return new Customer(firstName, lastName, address);
});
----
====

You can rewrite the preceding example as follows:

====
[source,java]
----
.map(TupleUtils.function(Customer::new)); // <1>
----
<1> (as `Customer` constructor conforms to `Function3` functional interface signature)
====

[[extra-math]]
== Math Operators With `MathFlux`

The `reactor.math` package contains a `MathFlux` specialized version of `Flux` that offers
mathematical operators, including `max`, `min`, `sumInt`, `averageDouble`, and others.

[[extra-schedulers]]
== Schedulers

Reactor-extra comes with the `ForkJoinPoolScheduler` (in the `reactor.scheduler.forkjoin` package): it uses the Java `ForkJoinPool` to execute tasks.

[[reactor-extra]]
= Reactor-Extra

The `reactor-extra` artifact contains additional operators and utilities that are for
users of `reactor-core` with advanced needs.

As this is a separate artifact, you need to explicitly add it to your build. The following
example shows how to do so in Gradle:

====
[source,groovy]
----
dependencies {
     compile 'io.projectreactor:reactor-core'
     compile 'io.projectreactor.addons:reactor-extra' <1>
}
----
<1> Add the reactor extra artifact in addition to core. See <<getting>> for details
about why you do not need to specify a version if you use the BOM, usage in Maven, and other details.
====

[[extra-tuples]]
== `TupleUtils` and Functional Interfaces

The `reactor.function` package contains functional interfaces that complement the Java 8
`Function`, `Predicate`, and `Consumer` interfaces, for three to eight values.

`TupleUtils` offers static methods that act as a bridge between lambdas of these functional
interfaces to a similar interface on the corresponding `Tuple`.

This lets you easily work with independent parts of any `Tuple`, as the following example shows:

====
[source,java]
----
.map(tuple -> {
  String firstName = tuple.getT1();
  String lastName = tuple.getT2();
  String address = tuple.getT3();

  return new Customer(firstName, lastName, address);
});
----
====

You can rewrite the preceding example as follows:

====
[source,java]
----
.map(TupleUtils.function(Customer::new)); // <1>
----
<1> (as `Customer` constructor conforms to `Function3` functional interface signature)
====

[[extra-math]]
== Math Operators With `MathFlux`

The `reactor.math` package contains a `MathFlux` specialized version of `Flux` that offers
mathematical operators, including `max`, `min`, `sumInt`, `averageDouble`, and others.

[[extra-schedulers]]
== Schedulers

Reactor-extra comes with several specialized schedulers:

* `ForkJoinPoolScheduler` (in the `reactor.scheduler.forkjoin` package): Uses the Java `ForkJoinPool` to execute tasks.
* `SwingScheduler` (in the `reactor.swing` package): Runs tasks in the Swing UI event loop thread, the `EDT`.
* `SwtScheduler` (in the `reactor.swing` package): Runs tasks in the SWT UI event loop thread.


add reference for ember-data-elasticsearch-kit to integrations page

[[integrations]]
== Integrations

* http://grails.org/plugin/elasticsearch[Grails]:
  ElasticSearch Grails plugin.

* https://github.com/carrot2/elasticsearch-carrot2[carrot2]:
  Results clustering with carrot2

* https://github.com/angelf/escargot[escargot]:
  ElasticSearch connector for Rails (WIP).

* https://metacpan.org/module/Catalyst::Model::Search::ElasticSearch[Catalyst]:
  ElasticSearch and Catalyst integration.

* http://github.com/aparo/django-elasticsearch[django-elasticsearch]:
  Django ElasticSearch Backend.

* http://github.com/Aconex/elasticflume[elasticflume]:
  http://github.com/cloudera/flume[Flume] sink implementation.

* http://code.google.com/p/terrastore/wiki/Search_Integration[Terrastore Search]:
  http://code.google.com/p/terrastore/[Terrastore] integration module with elasticsearch.

* https://github.com/infochimps/wonderdog[Wonderdog]:
  Hadoop bulk loader into elasticsearch.

* http://geeks.aretotally.in/play-framework-module-elastic-search-distributed-searching-with-json-http-rest-or-java[Play!Framework]:
  Integrate with Play! Framework Application.

* https://github.com/Exercise/FOQElasticaBundle[ElasticaBundle]:
  Symfony2 Bundle wrapping Elastica.

* http://drupal.org/project/elasticsearch[Drupal]:
  Drupal ElasticSearch integration.

* https://github.com/refuge/couch_es[couch_es]:
  elasticsearch helper for couchdb based products (apache couchdb, bigcouch & refuge)

* https://github.com/sonian/elasticsearch-jetty[Jetty]:
  Jetty HTTP Transport

* https://github.com/dadoonet/spring-elasticsearch[Spring Elasticsearch]:
  Spring Factory for Elasticsearch

* https://camel.apache.org/elasticsearch.html[Apache Camel Integration]:
  An Apache camel component to integrate elasticsearch

* https://github.com/tlrx/elasticsearch-test[elasticsearch-test]:
  Elasticsearch Java annotations for unit testing with
  http://www.junit.org/[JUnit]

* http://searchbox-io.github.com/wp-elasticsearch/[Wp-ElasticSearch]:
  ElasticSearch WordPress Plugin

* https://github.com/OlegKunitsyn/eslogd[eslogd]:
  Linux daemon that replicates events to a central ElasticSearch server in real-time

* https://github.com/drewr/elasticsearch-clojure-repl[elasticsearch-clojure-repl]:
  Plugin that embeds nREPL for run-time introspective adventure! Also
  serves as an nREPL transport.

* http://haystacksearch.org/[Haystack]:
  Modular search for Django

* https://github.com/cleverage/play2-elasticsearch[play2-elasticsearch]:
  ElasticSearch module for Play Framework 2.x

* https://github.com/fullscale/dangle[dangle]:
  A set of AngularJS directives that provide common visualizations for elasticsearch based on
  D3.

* https://github.com/roundscope/ember-data-elasticsearch-kit[ember-data-elasticsearch-kit]:
  An ember-data kit for both pushing and querying objects to ElasticSearch cluster


[DOCS] Drafted 6.2.1 security release notes (elastic/x-pack-elasticsearch#3873)

Original commit: elastic/x-pack-elasticsearch@61e3f0cd993f78529f673e3d425dc92d0e99b60a

[role="xpack"]
[[xes-6.2.1]]
== {es} {xpack} 6.2.1 Release Notes
++++
<titleabbrev>6.2.1 Release Notes</titleabbrev>
++++

[[xes-bug-6.2.1]]
[float]
=== Bug fixes

Security::
* Fixed missing dependencies for x-pack-transport.
//Repo: x-pack-elasticsearch
//Pull: 3860
* Fixed `saml-metadata` env file such that it sources the appropriate
environment file.
//Repo: x-pack-elasticsearch
//Pull: 3848
* If the realm uses native role mappings and the security index health changes,
the realm caches are cleared. For example, they are cleared when the index
recovers from a red state, when the index is deleted, when the index becomes
outdated, or when the index becomes up-to-date.
//Repo: x-pack-elasticsearch
//Pull: 3782

[role="xpack"]
[[xes-6.2.1]]
== {es} {xpack} 6.2.1 Release Notes
++++
<titleabbrev>6.2.1 Release Notes</titleabbrev>
++++

To be determined...

////
[[xes-bug-6.2.1]]
[float]
=== Bug fixes

Security::
* Remove transport client dependency on security
//Repo: x-pack-elasticsearch
//Pull: 3860
* [Security] Fix saml-metadata env files
//Repo: x-pack-elasticsearch
//Pull: 3848
* [Security] Clear Realm Caches on role mapping health change
//Repo: x-pack-elasticsearch
//Pull: 3782
* [Security] Reset IndexAuditTrail to INITIALISED before start
//Repo: x-pack-elasticsearch
//Pull: 3807
////


Observability metadata docs conditionally available

we will enable the metadata documentation only if we're NOT in the release train documentation

[[appendix]]
= Appendices

include::appendix-task-repository-schema.adoc[]

include::appendix-building-the-documentation.adoc[]

ifndef::train-docs[]
include::_observability.adoc[]
endif::[]

[[appendix]]
= Appendices

include::appendix-task-repository-schema.adoc[]

include::appendix-building-the-documentation.adoc[]

include::_observability.adoc[]