JAVA-1810: Note which setters are not propagated to PreparedStatement

Author: tolbertam

changelog/README.md

@@ -18,6 +18,7 @@
 - [bug] JAVA-1935: Add null check in QueryConsistencyException.getHost.
 - [improvement] JAVA-1771: Send driver name and version in STARTUP message.
 - [improvement] JAVA-1388: Add dynamic port discovery for system.peers\_v2.
+- [documentation] JAVA-1810: Note which setters are not propagated to PreparedStatement.
 
 Merged from 3.5.x:
 

driver-core/src/main/java/com/datastax/driver/core/Session.java

@@ -249,9 +249,14 @@ public interface Session extends Closeable {
   /**
    * Prepares the provided query.
    *
-   * <p>This method behaves like {@link #prepare(String)}, but note that the resulting {@code
-   * PreparedStatement} will inherit the query properties set on {@code statement}. Concretely, this
-   * means that in the following code:
+   * <p>This method behaves like {@link #prepare(String)}, but the resulting {@code
+   * PreparedStatement} will inherit some of the properties set on {@code statement}: {@linkplain
+   * Statement#getRoutingKey(ProtocolVersion, CodecRegistry) routing key}, {@linkplain
+   * Statement#getConsistencyLevel() consistency level}, {@linkplain
+   * Statement#getSerialConsistencyLevel() serial consistency level}, {@linkplain
+   * Statement#isTracing() tracing flag}, {@linkplain Statement#getRetryPolicy() retry policy},
+   * {@linkplain Statement#getOutgoingPayload() outgoing payload}, and {@linkplain
+   * Statement#isIdempotent() idempotence}. Concretely, this means that in the following code:
    *
    * <pre>
    * RegularStatement toPrepare = new SimpleStatement("SELECT * FROM test WHERE k=?").setConsistencyLevel(ConsistencyLevel.QUORUM);

driver-core/src/main/java/com/datastax/driver/core/Statement.java

@@ -252,7 +252,10 @@ public RetryPolicy getRetryPolicy() {
    * value in practice as it will yield very poor performance. If in doubt, leaving the default is
    * probably a good idea.
    *
-   * <p>Only {@code SELECT} queries only ever make use of that setting.
+   * <p>Only {@code SELECT} queries only ever make use of this setting.
+   *
+   * <p>Note that unlike other configuration, when this statement is prepared {@link
+   * BoundStatement}s created off of {@link PreparedStatement} do not inherit this configuration.
    *
    * <p>Note: Paging is not supported with the native protocol version 1. If you call this method
    * with {@code fetchSize &gt; 0} and {@code fetchSize != Integer.MAX_VALUE} and the protocol
@@ -299,6 +302,9 @@ public int getFetchSize() {
    * If none of these apply, no timestamp will be sent with the query and Cassandra will generate a
    * server-side one (similar to the pre-V3 behavior).
    *
+   * <p>Note that unlike other configuration, when this statement is prepared {@link
+   * BoundStatement}s created off of {@link PreparedStatement} do not inherit this configuration.
+   *
    * @param defaultTimestamp the default timestamp for this query (must be strictly positive).
    * @return this {@code Statement} object.
    * @see Cluster.Builder#withTimestampGenerator(TimestampGenerator)
@@ -324,6 +330,9 @@ public long getDefaultTimestamp() {
    * <p>You should override this only for statements for which the coordinator may allow a longer
    * server-side timeout (for example aggregation queries).
    *
+   * <p>Note that unlike other configuration, when this statement is prepared {@link
+   * BoundStatement}s created off of {@link PreparedStatement} do not inherit this configuration.
+   *
    * @param readTimeoutMillis the timeout to set. Negative values are not allowed. If it is 0, the
    *     read timeout will be disabled for this statement.
    * @return this {@code Statement} object.
@@ -628,6 +637,9 @@ public Host getHost() {
    * distance {@link HostDistance#IGNORED} or there is no active connectivity to the host, the
    * request will fail with a {@link NoHostAvailableException}.
    *
+   * <p>Note that unlike other configuration, when this statement is prepared {@link
+   * BoundStatement}s created off of {@link PreparedStatement} do not inherit this configuration.
+   *
    * @param host The host that should be used to handle executions of this statement or null to
    *     delegate to the configured load balancing policy.
    * @return this {@code Statement} object.