[DOCS] Added transport client info for X-Pack (elastic/x-pack-elasticsearch#2737)

* [DOCS] Added transport client info for X-Pack

* [DOCS] Relocated X-Pack java client info

* [DOCS] Added transport client deprecation info

Original commit: elastic/x-pack-elasticsearch@416aab1d76

docs/en/installing-xes.asciidoc

@@ -220,6 +220,8 @@ For more information, see
 {xpack-ref}/setting-up-authentication.html#set-built-in-user-passwords[Setting Built-in User Passwords].
 --
 
+. Optional: <<setup-xpack-client, Configure the Java Client>>.
+
 . {kibana-ref}/installing-xpack-kb.html[Install {xpack} on {kib}].
 
 . {logstash-ref}/installing-xpack-log.html[Install {xpack} on Logstash].

docs/en/security/tribe-clients-integrations/java.asciidoc

@@ -16,120 +16,21 @@ NOTE: Using the Java Node Client with secured clusters is not recommended or
 To use the transport client with a secured cluster, you need to:
 
 [[java-transport-client-role]]
+. <<xpack-javaclient, Set up the client for use with {xpack}>>.
+
 . Configure a user with the privileges required to start the transport client.
 A default `transport_client` role is built-in to {xpack} that grants the
 appropriate cluster permissions for the transport client to work with the secured
 cluster. The transport client uses the _Nodes Info API_ to fetch information about
 the nodes in the cluster.
 
-. Add the {xpack} transport JAR file to your CLASSPATH. You can download the {xpack}
-distribution and extract the JAR file manually or you can get it from the
-https://artifacts.elastic.co/maven/org/elasticsearch/client/x-pack-transport/{version}/x-pack-transport-{version}.jar[Elasticsearch Maven repository].
-+
-As with any dependency, you will also need its transitive dependencies. Refer to the
-https://artifacts.elastic.co/maven/org/elasticsearch/client/x-pack-transport/{version}/x-pack-transport-{version}.pom[X-Pack POM file
-for your version] when downloading for offline usage.
---
-
-If you are using Maven, you need to add the {xpack} JAR file as a dependency in
-your project's `pom.xml` file:
-
-[source,xml]
---------------------------------------------------------------
-<project ...>
-
-   <repositories>
-      <!-- add the elasticsearch repo -->
-      <repository>
-         <id>elasticsearch-releases</id>
-         <url>https://artifacts.elastic.co/maven</url>
-         <releases>
-            <enabled>true</enabled>
-         </releases>
-         <snapshots>
-            <enabled>false</enabled>
-         </snapshots>
-      </repository>
-      ...
-   </repositories>
-   ...
-
-   <dependencies>
-      <!-- add the x-pack jar as a dependency -->
-      <dependency>
-         <groupId>org.elasticsearch.client</groupId>
-         <artifactId>x-pack-transport</artifactId>
-         <version>{version}</version>
-      </dependency>
-      ...
-   </dependencies>
-   ...
-
- </project>
---------------------------------------------------------------
-
-If you are using Gradle, you need to add the {xpack} JAR file as a dependency in
-your `build.gradle` file:
-
-[source,groovy]
---------------------------------------------------------------
-repositories {
-  /* ... Any other repositories ... */
-
-  // Add the Elasticsearch Maven Repository
-  maven {
-    url "https://artifacts.elastic.co/maven"
-  }
-}
-
-dependencies {
-  compile "org.elasticsearch.client:x-pack-transport:{version}"
-
-  /* ... */
-}
---------------------------------------------------------------
---
-
-If you are using a repository manager such as https://www.sonatype.com/nexus-repository-oss[Nexus OSS] within your
-company, you need to add the repository as per the following screenshot:
-
-
-image::images/nexus.png["Adding the Elastic repo in Nexus",link="images/nexus.png"]
-
-
-Then in your project's `pom.xml` if using maven, add the following repositories and dependencies definitions:
-
-[source,xml]
---------------------------------------------------------------
-<dependencies>
-    <dependency>
-        <groupId>org.elasticsearch.client</groupId>
-        <artifactId>x-pack-transport</artifactId>
-        <version>{version}</version>
-    </dependency>
-</dependencies>
-
-<repositories>
-    <repository>
-        <id>local-nexus</id>
-        <name>Elastic Local Nexus</name>
-        <url>http://0.0.0.0:8081/repository/elasticsearch/</url>
-        <releases>
-            <enabled>true</enabled>
-        </releases>
-        <snapshots>
-            <enabled>false</enabled>
-        </snapshots>
-    </repository>
-</repositories>
---------------------------------------------------------------
-
 . Set up the transport client. At a minimum, you must configure `xpack.security.user` to
 include the name and password of your transport client user in your requests. The
 following snippet configures the user credentials globally--every request
 submitted with this client includes the `transport_client_user` credentials in
 its headers.
 +
+--
 [source,java]
 -------------------------------------------------------------------------------------------------
 import org.elasticsearch.xpack.client.PreBuiltXPackTransportClient;
@@ -143,20 +44,20 @@ TransportClient client = new PreBuiltXPackTransportClient(Settings.builder()
     .addTransportAddress(new InetSocketTransportAddress("localhost", 9300))
     .addTransportAddress(new InetSocketTransportAddress("localhost", 9301));
 -------------------------------------------------------------------------------------------------
-+
+
 WARNING:  If you configure a transport client without SSL, passwords are sent in
           clear text.
-+
+
 You can also add an `Authorization` header to each request. If you've configured
 global authorization credentials, the `Authorization` header overrides the global
 authentication credentials. This is useful when an application has multiple users
 who access Elasticsearch using the same client. You can set the global token to
 a user that only has the `transport_client` role, and add the `transport_client`
 role to the individual users.
-+
+
 For example, the following snippet adds the `Authorization` header to a search
 request:
-+
+
 [source,java]
 --------------------------------------------------------------------------------------------------
 import org.elasticsearch.common.settings.SecureString;
@@ -181,6 +82,7 @@ String token = basicAuthHeaderValue("test_user", new SecureString("x-pack-test-p
 client.filterWithHeader(Collections.singletonMap("Authorization", token))
     .prepareSearch().get();
 --------------------------------------------------------------------------------------------------
+--
 
 . Enable SSL to authenticate clients and encrypt communications. To enable SSL,
 you need to:
@@ -188,9 +90,10 @@ you need to:
 .. Configure the paths to the client's key and certificate in addition to the certificate authorities.
 Client authentication requires every client to have a certification signed by a trusted CA.
 +
+--
 NOTE: Client authentication is enabled by default. For information about
       disabling client authentication, see <<disabling-client-auth, Disabling Client Authentication>>.
-+
+
 [source,java]
 --------------------------------------------------------------------------------------------------
 import org.elasticsearch.xpack.client.PreBuiltXPackTransportClient;
@@ -205,11 +108,12 @@ TransportClient client = new PreBuiltXPackTransportClient(Settings.builder()
         ...
         .build());
 --------------------------------------------------------------------------------------------------
+--
 
-+
 .. Enable the SSL transport by setting `xpack.security.transport.ssl.enabled` to `true` in the
 client configuration.
 +
+--
 [source,java]
 --------------------------------------------------------------------------------------------------
 import org.elasticsearch.xpack.client.PreBuiltXPackTransportClient;
@@ -227,6 +131,7 @@ TransportClient client = new PreBuiltXPackTransportClient(Settings.builder()
     .addTransportAddress(new InetSocketTransportAddress(InetAddress.getByName("localhost"), 9300))
     .addTransportAddress(new InetSocketTransportAddress(InetAddress.getByName("localhost"), 9301))
 --------------------------------------------------------------------------------------------------
+--
 
 [float]
 [[disabling-client-auth]]

docs/en/setup-xclient.asciidoc

@@ -0,0 +1,116 @@
+[role="xpack"]
+[[setup-xpack-client]]
+== Configuring {xpack} Java Clients
+
+If you want to use a Java {ref}/transport-client.html[transport client] with a
+cluster where {xpack} is installed, then you must download and configure the
+{xpack} transport client.
+
+WARNING: The `TransportClient` is aimed to be replaced by the Java High Level REST
+Client, which executes HTTP requests instead of serialized Java requests. The
+`TransportClient` will be deprecated in upcoming versions of {es}. 
+
+. Add the {xpack} transport JAR file to your *CLASSPATH*. You can download the {xpack}
+distribution and extract the JAR file manually or you can get it from the
+https://artifacts.elastic.co/maven/org/elasticsearch/client/x-pack-transport/{version}/x-pack-transport-{version}.jar[Elasticsearc Maven repository].
+As with any dependency, you will also need its transitive dependencies. Refer to the
+https://artifacts.elastic.co/maven/org/elasticsearch/client/x-pack-transport/{version}/x-pack-transport-{version}.pom[X-Pack POM file
+for your version] when downloading for offline usage.
+
+. If you are using Maven, you need to add the {xpack} JAR file as a dependency in
+your project's `pom.xml` file:
++
+--
+[source,xml]
+--------------------------------------------------------------
+<project ...>
+     <repositories>
+     <!-- add the elasticsearch repo -->
+      <repository>
+         <id>elasticsearch-releases</id>
+         <url>https://artifacts.elastic.co/maven</url>
+         <releases>
+          <enabled>true</enabled>
+         </releases>
+         <snapshots>
+            <enabled>false</enabled>
+         </snapshots>
+      </repository>
+      ...
+   </repositories>
+   ...
+
+   <dependencies>
+      <!-- add the x-pack jar as a dependency -->
+      <dependency>
+         <groupId>org.elasticsearch.client</groupId>
+         <artifactId>x-pack-transport</artifactId>
+              <version>{version}</version>
+      </dependency>
+      ...
+   </dependencies>
+   ...
+
+</project>
+--------------------------------------------------------------
+--
+
+. If you are using Gradle, you need to add the {xpack} JAR file as a dependency in
+your `build.gradle` file:
++
+--
+[source,groovy]
+--------------------------------------------------------------
+repositories {
+  /* ... Any other repositories ... */
+
+  // Add the Elasticsearch Maven Repository
+  maven {
+    url "https://artifacts.elastic.co/maven"
+  }
+}
+
+dependencies {
+  compile "org.elasticsearch.client:x-pack-transport:{version}"
+
+  /* ... */
+}
+--------------------------------------------------------------
+--
+
+. If you are using a repository manager such as https://www.sonatype.com/nexus-repository-oss[Nexus OSS] within your
+company, you need to add the repository as per the following screenshot:
++
+--
+image::security/images/nexus.png["Adding the Elastic repo in Nexus",link="images/nexus.png"]
+
+Then in your project's `pom.xml` if using maven, add the following repositories and dependencies definitions:
+
+[source,xml]
+--------------------------------------------------------------
+<dependencies>
+    <dependency>
+        <groupId>org.elasticsearch.client</groupId>
+        <artifactId>x-pack-transport</artifactId>
+        <version>{version}</version>
+    </dependency>
+</dependencies>
+
+<repositories>
+    <repository>
+        <id>local-nexus</id>
+        <name>Elastic Local Nexus</name>
+        <url>http://0.0.0.0:8081/repository/elasticsearch/</url>
+        <releases>
+            <enabled>true</enabled>
+        </releases>
+        <snapshots>
+            <enabled>false</enabled>
+        </snapshots>
+    </repository>
+  </repositories>
+--------------------------------------------------------------
+--
+
+. If you are using {security}, there are more configuration steps. See
+{xpack-ref}/java-clients.html[Java Client and Security].

docs/en/setup-xes.asciidoc

@@ -12,3 +12,4 @@ easy-to-install package. To access this functionality, you must
 
 include::installing-xes.asciidoc[]
 include::settings/configuring-xes.asciidoc[]
+include::setup-xclient.asciidoc[]