anchor.diff:  
   ShieldClient shieldClient = new ShieldClient(client);
   ClearRealmCacheResponse response = shieldClient.authc().prepareClearRealmCache()
  -    .realms("ldap1", "ad1")
  +    .realms("ldap1", "ad1") (1)
       .usernames("rdeniro")
       .get();
   ------------------------------------------------------------------------------------------------------
   
  -In the example above, we clear the caches of two realms - `ldap1` and `ad1` - for the `rdeniro` user.
  +(1) Clears the `ldap1` and `ad1` realm caches for the `rdeniro` user.
  +
  +
  
positive.code: TransportClient client = new TransportClient(ImmutableSettings.builder()
      .put("cluster.name", "myClusterName")
      .put("shield.user", "test_user:changeme")
      .put("shield.ssl.truststore.path", "/path/to/truststore.jks")
      .put("shield.ssl.truststore.password", "password")
      .put("shield.transport.ssl", "true"))
      .addTransportAddress(new InetSocketTransportAddress("localhost", 9300))
      .addTransportAddress(new InetSocketTransportAddress("localhost", 9301));
  ------------------------------------------------------------------------------------------------------
  NOTE: The `truststore.jks` truststore needs to contain the certificate of the CA that has signed the Elasticsearch nodes'
  certificates. If you are using a public CA that is already trusted by the Java runtime, then you can omit
  `shield.ssl.truststore.path` and `shield.ssl.truststore.password`.
  
  In the above code snippets, we set up a _Transport Client_ and configured the authentication token globally. Meaning,
  that every request executed with this client will include this token in its headers.
  
  The global configuration of the token *must be* set to some user with the privileges in the default `transport_client`
  role, as described earlier. The global authentication token may also be overridden by adding a `Authorization` header on
  each request. This is useful when an application uses multiple users to access Elasticsearch via the same client. When
  operating in this mode, it is best to set the global token to a user that only has the `transport_client` role. The
  following example directly sets the authentication token on the request when executing a search.
  
  [source,java]
  ------------------------------------------------------------------------------------------------------
  import org.elasticsearch.shield.authc.support.SecuredString;
  import org.elasticsearch.client.transport.TransportClient;
  
  import static org.elasticsearch.shield.authc.support.UsernamePasswordToken.basicAuthHeaderValue;
  ...
  
  String token = basicAuthHeaderValue("test_user", new SecuredString("changeme".toCharArray()));
  TransportClient client = new TransportClient(ImmutableSettings.builder()
      .put("shield.user", "transport_client_user:changeme")
      ...
      .addTransportAddress(new InetSocketTransportAddress("localhost", 9300))
      .addTransportAddress(new InetSocketTransportAddress("localhost", 9301));
  
  client.prepareSearch().putHeader("Authorization", token).get();
  ------------------------------------------------------------------------------------------------------
  
  [float]
  ===== Anonymous Access
  
  added[1.1.0]
  
  If Shield enables <<anonymous-access,anonymous access>>, the `shield.user` setting may be dropped and all requests will
  be executed under the anonymous user (with the exception of the requests on which the `Authorization` header is explicitly
  set, as shown above). For this to work, please make sure the anonymous user is configured with sufficient roles that have
  the same privileges as described <<java-transport-client-role,above>>.
  
  
  [float]
  [[shield-client]]
  ==== Shield Client
  
  Shield exposes its own API to the user which is accessible by the `ShieldClient` class. The purpose of this API
   is to manage all Shield related aspects. While at the moment it only exposes an operation for clearing up the
   realm caches, the plan is to extend this API in the future.
  
  `ShieldClient` is a wrapper around the existing clients (any client class implementing `org.elasticsearch.client.Client`.
  
   The following example shows how one can clear up Shield's realm caches using the `ShieldClient`:
  
  [source,java]
  ------------------------------------------------------------------------------------------------------
  
negative.code: dependencies {
    // Provide the Shield jar on the classpath for compilation and at runtime
    // Note: Many projects can use the Shield jar as a runtime dependency
    compile "org.elasticsearch:elasticsearch-shield:2.0.0"
  
    /* ... */
  }
  --------------------------------------------------------------
  
  . Set up the transport client. At a minimum, you must configure `shield.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.client.transport.TransportClient;
  ...
  
  TransportClient client = new TransportClient(ImmutableSettings.builder()
      .put("cluster.name", "myClusterName")
      .put("shield.user", "transport_client_user:changeme")
      .addTransportAddress(new InetSocketTransportAddress("localhost", 9300))
      .addTransportAddress(new InetSocketTransportAddress("localhost", 9301));
  -------------------------------------------------------------------------------------------------
  +
  WARNING: If you configure a transport client without SSL, passwords are sent in plaintext.
  +
  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.shield.authc.support.SecuredString;
  import org.elasticsearch.client.transport.TransportClient;
  
  import static org.elasticsearch.shield.authc.support.UsernamePasswordToken.basicAuthHeaderValue;
  ...
  
  TransportClient client = new TransportClient(ImmutableSettings.builder()
      .put("shield.user", "transport_client_user:changeme")
      ...
      .addTransportAddress(new InetSocketTransportAddress("localhost", 9300))
      .addTransportAddress(new InetSocketTransportAddress("localhost", 9301));
  
  String token = basicAuthHeaderValue("test_user", new SecuredString("changeme".toCharArray()));
  
  client.prepareSearch().putHeader("Authorization", token).get();
  --------------------------------------------------------------------------------------------------
  
  . Enable SSL to authenticate clients and encrypt communications. To enable SSL, you need to:
  
  .. Configure the client's keystore path and password. 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.client.transport.TransportClient;
  ...
  
  TransportClient client = new TransportClient(ImmutableSettings.builder()
      .put("cluster.name", "myClusterName")
      .put("shield.user", "transport_client_user:changeme")
      .put("shield.ssl.keystore.path", "/path/to/client.jks") (1)
      .put("shield.ssl.keystore.password", "password")
      ...
  --------------------------------------------------------------------------------------------------
  +
  (1) The `client.jks` keystore must contain the client's signed CA certificate and the CA certificate.
  +
  .. Enable the SSL transport by setting `shield.transport.ssl` to `true` in the client configuration.
  +
  [source,java]
  --------------------------------------------------------------------------------------------------
  import org.elasticsearch.client.transport.TransportClient;
  ...
  
  TransportClient client = new TransportClient(ImmutableSettings.builder()
      .put("cluster.name", "myClusterName")
      .put("shield.user", "transport_client_user:changeme")
      .put("shield.ssl.keystore.path", "/path/to/client.jks") (1)
      .put("shield.ssl.keystore.password", "password")
      .put("shield.transport.ssl", "true"))
      .addTransportAddress(new InetSocketTransportAddress("localhost", 9300))
      .addTransportAddress(new InetSocketTransportAddress("localhost", 9301));
  --------------------------------------------------------------------------------------------------
  
  [float]
  [[disabling-client-auth]]
  ===== Disabling Client Authentication
  
  If you want to disable client authentication, you can use a client-specific transport protocol. For more information, <<separating-node-client-traffic, Separating Node to Node and Client Traffic>>.
  
  If you are not using client authentication and sign the Elasticsearch node certificates with your own CA, you need to set the truststore path and password in the client configuration:
  
  [source,java]
  ------------------------------------------------------------------------------------------------------
  import org.elasticsearch.client.transport.TransportClient;
  