com.ing.data.cassandra.jdbc.CassandraResultSetJsonSupport Maven / Gradle / Ivy

Go to download

Show more of this group Show more artifacts with this name
Show all versions of cassandra-jdbc-wrapper Show documentation

JDBC wrapper of the Java Driver for Apache Cassandra®.

There is a newer version: 4.13.1

Show newest version

/*
 *
 *   Licensed 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.
 */

package com.ing.data.cassandra.jdbc;

import java.net.InetAddress;
import java.nio.ByteBuffer;
import java.sql.Date;
import java.sql.ResultSet;
import java.sql.SQLException;
import java.time.LocalDate;
import java.time.LocalTime;
import java.time.OffsetDateTime;
import java.util.List;
import java.util.Map;
import java.util.Set;
import java.util.UUID;

/**
 * Extension of {@link ResultSet} interface providing additional methods specific to Cassandra result sets for
 * JSON-formatted results provided by Cassandra features {@code SELECT JSON} and {@code toJson()}.
 * 
 *     The CQL {@code SELECT} queries using JSON support will return a map where the keys are the column labels. So,
 *     don't forget that if you use JSON formatting for only one column of type {@code T}, the result will be an object
 *     like this one: { "columnLabel": { ... } } and should be deserialized to an object extending
 *     {@code Map} and not directly to {@code T}.
 * 
 * Using the methods defined into this interface requires some considerations relative to the acceptable types for
 * result deserialization. The table below lists the acceptable type(s) in the target object to which the JSON will be
 * deserialized. Note that all non-collection types can also be deserialized to {@link String} and the collections can
 * be deserialized to {@link List} (for CQL types {@code list}, {@code set} and {@code tuple}) or {@link Map} (for CQL
 * types {@code map} and {@code udt}) of {@link String} items.
 *     
 *         
 *         
 *         
 *         
 *         
 *         
 *         
 *         
 *         
 *         
 *         
 *         
 *         
 *         
 *         
 *         
 *         
 *         
 *         
 *         
 *         
 *         
 *         
 *         
 *         
 *         
 *     CQL Type JSON type   Acceptable Java types         
ascii    string     {@link String}                 
bigint   integer    {@link Number}                 
blob     string     {@link ByteBuffer}             
boolean  boolean    {@link Boolean}                
date     string     {@link Date}, {@link LocalDate}
decimal  float      {@link Number}                 
double   float      {@link Number}                 
float    float      {@link Number}                 
inet     string     {@link InetAddress}            
int      integer    {@link Number}                 
list     list       {@link List}                   
map      map        {@link Map}                    
set      list       {@link Set}, {@link List}      
smallint integer    {@link Number}                 
text     string     {@link String}                 
time     string     {@link LocalTime}              
timestamp string     {@link OffsetDateTime}         
timeuuid string     {@link UUID}                   
tinyint  integer    {@link Number}                 
tuple    list       {@link List}                   
udt      map        {@link Map} or a suitable object to which the map can be
 *         deserialized                                                                 
uuid     string     {@link UUID}                   
varchar  string     {@link String}                 
varint   integer    {@link Number}                 
vector   list       {@link List}                   
 *     See: 
 *         CQL reference for JSON support.
 */
public interface CassandraResultSetJsonSupport extends ResultSet {

    /**
     * Retrieves the value of the designated column in the current row of this {@code ResultSet} object as an instance
     * of type {@code T} from a JSON string.
     * 
     * Typically, this method can be called on a result set returned by a CQL query like:

     * 
     * SELECT JSON col1, col2 FROM exampleTable;
     * 
     * 
or on a result column defined with the function {@code toJson()}.
     * 
     *
     * @param columnIndex The column index (the first column is 1).
     * @param type        The class representing the Java data type to convert the designated column to.
     * @param          The type of the object represented by the JSON string.
     * @return The column value converted to an instance of {@code T}. If the value is SQL {@code NULL}, it should
     * return {@code null}.
     * @throws SQLException if the columnIndex is not valid; if a database access error occurs; if this method is called
     *                      on a closed result set or if the value is cannot be parsed to an object of type {@code T}.
     * @see Cassandra JSON support
     */
     T getObjectFromJson(int columnIndex, Class type) throws SQLException;

    /**
     * Retrieves the value of the designated column in the current row of this {@code ResultSet} object as an instance
     * of type {@code T} from a JSON string.
     * 
     * Typically, this method can be called on a result set returned by a CQL query like:

     * 
     * SELECT JSON col1, col2 FROM exampleTable;
     * 
     * 
or on a result column defined with the function {@code toJson()}.
     * 
     *
     * @param columnLabel The label for the column specified with the SQL AS clause. If the SQL AS clause was not
     *                    specified, then the label is the name of the column.
     * @param type        The class representing the Java data type to convert the designated column to.
     * @param          The type of the object represented by the JSON string.
     * @return The column value converted to an instance of {@code T}. If the value is SQL {@code NULL}, it should
     * return {@code null}.
     * @throws SQLException if the columnIndex is not valid; if a database access error occurs; if this method is called
     *                      on a closed result set or if the value is cannot be parsed to an object of type {@code T}.
     * @see Cassandra JSON support
     */
     T getObjectFromJson(String columnLabel, Class type) throws SQLException;

    /**
     * Retrieves the value of the column labelled "{@code [json]}", containing a JSON string, in the current row of
     * this {@code ResultSet} object as an instance of type {@code T}.
     * 
     * Typically, this method can be called on a result set returned by a CQL query like:

     * 
     * SELECT JSON * FROM exampleTable;
     * 
     * 
     *
     * @param type The class representing the Java data type to convert the column value to.
     * @param   The type of the object represented by the JSON string.
     * @return The column value converted to an instance of {@code T}. If the value is SQL {@code NULL}, it should
     * return {@code null}.
     * @throws SQLException if the columnIndex is not valid; if a database access error occurs; if this method is called
     *                      on a closed result set or if the value is cannot be parsed to an object of type {@code T}.
     * @see Cassandra JSON support
     */
     T getObjectFromJson(Class type) throws SQLException;

}

CQL Type	JSON type	Acceptable Java types
ascii	string	{@link String}
bigint	integer	{@link Number}
blob	string	{@link ByteBuffer}
boolean	boolean	{@link Boolean}
date	string	{@link Date}, {@link LocalDate}
decimal	float	{@link Number}
double	float	{@link Number}
float	float	{@link Number}
inet	string	{@link InetAddress}
int	integer	{@link Number}
list	list	{@link List}
map	map	{@link Map}
set	list	{@link Set}, {@link List}
smallint	integer	{@link Number}
text	string	{@link String}
time	string	{@link LocalTime}
timestamp	string	{@link OffsetDateTime}
timeuuid	string	{@link UUID}
tinyint	integer	{@link Number}
tuple	list	{@link List}
udt	map	{@link Map} or a suitable object to which the map can be * deserialized
uuid	string	{@link UUID}
varchar	string	{@link String}
varint	integer	{@link Number}
vector	list	{@link List}