Package com.datastax.driver.core

Interface PreparedStatement

  • All Known Implementing Classes:
    DefaultPreparedStatement
    public interface PreparedStatement
    Represents a prepared statement, a query with bound variables that has been prepared (pre-parsed) by the database.

    A prepared statement can be executed once concrete values have been provided for the bound variables. A prepared statement and the values for its bound variables constitute a BoundStatement and can be executed (by Session.execute(java.lang.String)).

    A PreparedStatement object allows you to define specific defaults for the different properties of a Statement (Consistency level, tracing, ...), in which case those properties will be inherited as default by every BoundedStatement created from the {PreparedStatement}. The default for those PreparedStatement properties is the same that in Statement if the PreparedStatement is created by Session.prepare(String) but will inherit of the properties of the RegularStatement used for the preparation if Session.prepare(RegularStatement) is used.

    • Method Detail

      • getVariables

        ColumnDefinitions getVariables()
        Returns metadata on the bounded variables of this prepared statement.
        Returns:
        the variables bounded in this prepared statement.

      • bind

        BoundStatement bind​(Object... values)
        Creates a new BoundStatement object and bind its variables to the provided values.

        While the number of values cannot be greater than the number of bound variables, the number of values may be fewer than the number of bound variables. In that case, the remaining variables will have to be bound to values by another mean because the resulting BoundStatement being executable.

        This method is a convenience for new BoundStatement(this).bind(...).

        Parameters:
        values - the values to bind to the variables of the newly created BoundStatement.
        Returns:
        the newly created BoundStatement with its variables bound to values.
        Throws:
        IllegalArgumentException - if more values are provided than there is of bound variables in this statement.
        InvalidTypeException - if any of the provided value is not of correct type to be bound to the corresponding bind variable.
        NullPointerException - if one of values is a collection (List, Set or Map) containing a null value. Nulls are not supported in collections by CQL.
        See Also:
        BoundStatement.bind(java.lang.Object...)

      • getRoutingKey

        ByteBuffer getRoutingKey()
        Returns the routing key set for this query.
        Returns:
        the routing key for this query or null if none has been explicitly set on this PreparedStatement.

      • setConsistencyLevel

        PreparedStatement setConsistencyLevel​(ConsistencyLevel consistency)
        Sets a default consistency level for all bound statements created from this prepared statement.

        If no consistency level is set through this method, the bound statement created from this object will use the default consistency level (LOCAL_ONE).

        Changing the default consistency level is not retroactive, it only applies to BoundStatement created after the change.

        Parameters:
        consistency - the default consistency level to set.
        Returns:
        this PreparedStatement object.

      • setSerialConsistencyLevel

        PreparedStatement setSerialConsistencyLevel​(ConsistencyLevel serialConsistency)
        Sets a default serial consistency level for all bound statements created from this prepared statement.

        If no serial consistency level is set through this method, the bound statement created from this object will use the default serial consistency level (SERIAL).

        Changing the default serial consistency level is not retroactive, it only applies to BoundStatement created after the change.

        Parameters:
        serialConsistency - the default serial consistency level to set.
        Returns:
        this PreparedStatement object.
        Throws:
        IllegalArgumentException - if serialConsistency is not one of ConsistencyLevel.SERIAL or ConsistencyLevel.LOCAL_SERIAL.

      • getQueryString

        String getQueryString()
        Returns the string of the query that was prepared to yield this PreparedStatement.

        Note that a CQL3 query may be implicitly applied to the current keyspace (that is, if the keyspace is not explicitly qualified in the query itself). For prepared queries, the current keyspace used is the one at the time of the preparation, not the one at execution time. The current keyspace at the time of the preparation can be retrieved through getQueryKeyspace().

        Returns:
        the query that was prepared to yield this PreparedStatement.

      • getQueryKeyspace

        String getQueryKeyspace()
        Returns the keyspace at the time that this prepared statement was prepared, (that is the one on which this statement applies unless it specified a keyspace explicitly).
        Returns:
        the keyspace at the time that this statement was prepared or null if no keyspace was set when the query was prepared (which is possible since keyspaces can be explicitly qualified in queries and so may not require a current keyspace to be set).

      • enableTracing

        PreparedStatement enableTracing()
        Convenience method to enables tracing for all bound statements created from this prepared statement.
        Returns:
        this Query object.

      • disableTracing

        PreparedStatement disableTracing()
        Convenience method to disable tracing for all bound statements created from this prepared statement.
        Returns:
        this PreparedStatement object.

      • isTracing

        boolean isTracing()
        Returns whether tracing is enabled for this prepared statement, i.e. if BoundStatement created from it will use tracing by default.
        Returns:
        true if this prepared statement has tracing enabled, false otherwise.

      • setRetryPolicy

        PreparedStatement setRetryPolicy​(RetryPolicy policy)
        Convenience method to set a default retry policy for the BoundStatement created from this prepared statement.

        Note that this method is completely optional. By default, the retry policy used is the one returned Policies.getRetryPolicy() in the cluster configuration. This method is only useful if you want to override this default policy for the BoundStatement created from this PreparedStatement. to punctually override the default policy for this request.

        Parameters:
        policy - the retry policy to use for this prepared statement.
        Returns:
        this PreparedStatement object.

      • getRetryPolicy

        RetryPolicy getRetryPolicy()
        Returns the retry policy sets for this prepared statement, if any.
        Returns:
        the retry policy sets specifically for this prepared statement or null if none have been set.

      • getPartitioner

        com.datastax.driver.core.Token.Factory getPartitioner()
        The partitioner for this prepared statement.
        Returns:
        the partitioner for this query, or null if no partitioner has been specified. In the latter case, the cluster-wide partitioner will be used.

      • getPreparedId

        PreparedId getPreparedId()
        Returns the prepared Id for this statement.
        Returns:
        the PreparedId corresponding to this statement.

      • getIncomingPayload

        Map<String,​ByteBuffer> getIncomingPayload()
        Return the incoming payload, that is, the payload that the server sent back with its PREPARED response, if any, or null, if the server did not include any custom payload.

        Note that if an incoming payload is present, and if no outgoing payload has been explicitly set, then each time a BoundStatement is created (with either bind() or bind(Object...)), the resulting BoundStatement will inherit from this value as its default outgoing payload.

        Implementors should return a read-only view of the original map, but even though, its values would remain inherently mutable. Callers should take care not to modify the returned map in any way.

        This feature is only available with ProtocolVersion.V4 or above; with lower versions, this method will always return null.

        Returns:
        the custom payload that the server sent back with its response, if any, or null, if the server did not include any custom payload.
        Since:
        2.2

      • getOutgoingPayload

        Map<String,​ByteBuffer> getOutgoingPayload()
        Return the outgoing payload currently associated with this statement.

        If this is set to a non-null value, each time a BoundStatement is created (with either bind() or bind(Object...)), the resulting BoundStatement will inherit from this value as its default outgoing payload.

        Implementors should return a read-only view of the original map, but even though, its values would remain inherently mutable. Callers should take care not to modify the returned map in any way.

        This feature is only available with ProtocolVersion.V4 or above.

        Returns:
        this statement's outgoing payload, if any, or null if no outgoing payload is set
        Since:
        2.2

      • setOutgoingPayload

        PreparedStatement setOutgoingPayload​(Map<String,​ByteBuffer> payload)
        Associate the given payload with this prepared statement.

        If this is set to a non-null value, each time a BoundStatement is created (with either bind() or bind(Object...)), the resulting BoundStatement will inherit from this value as its default outgoing payload.

        Implementors should make a defensive, thread-safe copy of the given map, but even though, its values would remain inherently mutable. Callers should take care not to modify the original map once it is passed to this method.

        This feature is only available with ProtocolVersion.V4 or above. Trying to include custom payloads in requests sent by the driver under lower protocol versions will result in an UnsupportedFeatureException (wrapped in a NoHostAvailableException).

        Parameters:
        payload - the outgoing payload to associate with this statement, or null to clear any previously associated payload.
        Returns:
        this Statement object.
        Since:
        2.2

      • getCodecRegistry

        CodecRegistry getCodecRegistry()
        Return the CodecRegistry instance associated with this prepared statement. Implementations should never return null; instead, they should always return the CodecRegistry instance registered with the Cluster instance this prepared statement belongs to.
        Returns:
        the CodecRegistry instance associated with this prepared statement.

      • setIdempotent

        PreparedStatement setIdempotent​(Boolean idempotent)
        Sets whether this statement is idempotent.

        See Statement.isIdempotent() for more explanations about this property.

        Parameters:
        idempotent - the new value.
        Returns:
        this IdempotenceAwarePreparedStatement object.

      • isIdempotent

        Boolean isIdempotent()
        Whether this statement is idempotent, i.e. whether it can be applied multiple times without changing the result beyond the initial application.

        See Statement.isIdempotent() for more explanations about this property.

        Please note that idempotence will be propagated to all BoundStatements created from this prepared statement.

        Returns:
        whether this statement is idempotent, or null to use QueryOptions.getDefaultIdempotence().

      • isLWT

        boolean isLWT()
        Whether a prepared statement is LWT statement