All Downloads are FREE. Search and download functionalities are using the official Maven repository.

com.datastax.driver.core.GettableByIndexData Maven / Gradle / Ivy

/*
 * Copyright DataStax, Inc.
 *
 * 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.datastax.driver.core;

import com.datastax.driver.core.exceptions.CodecNotFoundException;
import com.datastax.driver.core.exceptions.InvalidTypeException;
import com.google.common.reflect.TypeToken;
import java.math.BigDecimal;
import java.math.BigInteger;
import java.net.InetAddress;
import java.nio.ByteBuffer;
import java.util.Date;
import java.util.List;
import java.util.Map;
import java.util.Set;
import java.util.UUID;

/** Collection of (typed) CQL values that can be retrieved by index (starting at zero). */
public interface GettableByIndexData {

  /**
   * Returns whether the {@code i}th value is NULL.
   *
   * @param i the index ({@code 0 <= i < size()}) of the value to check.
   * @return whether the {@code i}th value is NULL.
   * @throws IndexOutOfBoundsException if {@code i} is not a valid index for this object.
   */
  public boolean isNull(int i);

  /**
   * Returns the {@code i}th value as a boolean.
   *
   * 

This method uses the {@link CodecRegistry} to find a codec to convert the underlying CQL * type to a Java {@code boolean} (for CQL type {@code boolean}, this will be the built-in codec). * * @param i the index ({@code 0 <= i < size()}) to retrieve. * @return the boolean value of the {@code i}th element. If the value is NULL, {@code false} is * returned. If you need to distinguish NULL and false values, check first with {@link * #isNull(int)} or use {@code get(i, Boolean.class)}. * @throws IndexOutOfBoundsException if {@code i} is not a valid index for this object. * @throws CodecNotFoundException if there is no registered codec to convert the element's CQL * type to a boolean. */ public boolean getBool(int i); /** * Returns the {@code i}th value as a byte. * *

This method uses the {@link CodecRegistry} to find a codec to convert the underlying CQL * type to a Java {@code byte} (for CQL type {@code tinyint}, this will be the built-in codec). * * @param i the index ({@code 0 <= i < size()}) to retrieve. * @return the value of the {@code i}th element as a byte. If the value is NULL, {@code 0} is * returned. If you need to distinguish NULL and 0, check first with {@link #isNull(int)} or * use {@code get(i, Byte.class)}. * @throws IndexOutOfBoundsException if {@code i} is not a valid index for this object. * @throws CodecNotFoundException if there is no registered codec to convert the element's CQL * type to a byte. */ public byte getByte(int i); /** * Returns the {@code i}th value as a short. * *

This method uses the {@link CodecRegistry} to find a codec to convert the underlying CQL * type to a Java {@code short} (for CQL type {@code smallint}, this will be the built-in codec). * * @param i the index ({@code 0 <= i < size()}) to retrieve. * @return the value of the {@code i}th element as a short. If the value is NULL, {@code 0} is * returned. If you need to distinguish NULL and 0, check first with {@link #isNull(int)} or * use {@code get(i, Short.class)}. * @throws IndexOutOfBoundsException if {@code i} is not a valid index for this object. * @throws CodecNotFoundException if there is no registered codec to convert the element's CQL * type to a short. */ public short getShort(int i); /** * Returns the {@code i}th value as an integer. * *

This method uses the {@link CodecRegistry} to find a codec to convert the underlying CQL * type to a Java {@code int} (for CQL type {@code int}, this will be the built-in codec). * * @param i the index ({@code 0 <= i < size()}) to retrieve. * @return the value of the {@code i}th element as an integer. If the value is NULL, {@code 0} is * returned. If you need to distinguish NULL and 0, check first with {@link #isNull(int)} or * use {@code get(i, Integer.class)}. * @throws IndexOutOfBoundsException if {@code i} is not a valid index for this object. * @throws CodecNotFoundException if there is no registered codec to convert the element's CQL * type to an int. */ public int getInt(int i); /** * Returns the {@code i}th value as a long. * *

This method uses the {@link CodecRegistry} to find a codec to convert the underlying CQL * type to a Java {@code byte} (for CQL types {@code bigint} and {@code counter}, this will be the * built-in codec). * * @param i the index ({@code 0 <= i < size()}) to retrieve. * @return the value of the {@code i}th element as a long. If the value is NULL, {@code 0L} is * returned. If you need to distinguish NULL and 0L, check first with {@link #isNull(int)} or * use {@code get(i, Long.class)}. * @throws IndexOutOfBoundsException if {@code i} is not a valid index for this object. * @throws CodecNotFoundException if there is no registered codec to convert the element's CQL * type to a long. */ public long getLong(int i); /** * Returns the {@code i}th value as a date. * *

This method uses the {@link CodecRegistry} to find a codec to convert the underlying CQL * type to a {@code Date} (for CQL type {@code timestamp}, this will be the built-in codec). * * @param i the index ({@code 0 <= i < size()}) to retrieve. * @return the value of the {@code i}th element as a data. If the value is NULL, {@code null} is * returned. * @throws IndexOutOfBoundsException if {@code i} is not a valid index for this object. * @throws CodecNotFoundException if there is no registered codec to convert the element's CQL * type to a {@code Date}. */ public Date getTimestamp(int i); /** * Returns the {@code i}th value as a date (without time). * *

This method uses the {@link CodecRegistry} to find a codec to convert the underlying CQL * type to a {@link LocalDate} (for CQL type {@code date}, this will be the built-in codec). * * @param i the index ({@code 0 <= i < size()}) to retrieve. * @return the value of the {@code i}th element as an date. If the value is NULL, {@code null} is * returned. * @throws IndexOutOfBoundsException if {@code i} is not a valid index for this object. * @throws CodecNotFoundException if there is no registered codec to convert the element's CQL * type to a {@code LocalDate}. */ public LocalDate getDate(int i); /** * Returns the {@code i}th value as a long in nanoseconds since midnight. * *

This method uses the {@link CodecRegistry} to find a codec to convert the underlying CQL * type to a Java {@code long} (for CQL type {@code time}, this will be the built-in codec). * * @param i the index ({@code 0 <= i < size()}) to retrieve. * @return the value of the {@code i}th element as a long. If the value is NULL, {@code 0L} is * returned. * @throws IndexOutOfBoundsException if {@code i} is not a valid index for this object. * @throws CodecNotFoundException if there is no registered codec to convert the element's CQL * type to a long. */ public long getTime(int i); /** * Returns the {@code i}th value as a float. * *

This method uses the {@link CodecRegistry} to find a codec to convert the underlying CQL * type to a Java {@code float} (for CQL type {@code float}, this will be the built-in codec). * * @param i the index ({@code 0 <= i < size()}) to retrieve. * @return the value of the {@code i}th element as a float. If the value is NULL, {@code 0.0f} is * returned. If you need to distinguish NULL and 0.0f, check first with {@link #isNull(int)} * or use {@code get(i, Float.class)}. * @throws IndexOutOfBoundsException if {@code i} is not a valid index for this object. * @throws CodecNotFoundException if there is no registered codec to convert the element's CQL * type to a float. */ public float getFloat(int i); /** * Returns the {@code i}th value as a double. * *

This method uses the {@link CodecRegistry} to find a codec to convert the underlying CQL * type to a Java {@code double} (for CQL type {@code double}, this will be the built-in codec). * * @param i the index ({@code 0 <= i < size()}) to retrieve. * @return the value of the {@code i}th element as a double. If the value is NULL, {@code 0.0} is * returned. If you need to distinguish NULL and 0.0, check first with {@link #isNull(int)} or * use {@code get(i, Double.class)}. * @throws IndexOutOfBoundsException if {@code i} is not a valid index for this object. * @throws CodecNotFoundException if there is no registered codec to convert the element's CQL * type to a double. */ public double getDouble(int i); /** * Returns the {@code i}th value as a {@code ByteBuffer}. * *

This method does not use any codec; it returns a copy of the binary representation of the * value. It is up to the caller to convert the returned value appropriately. * * @param i the index ({@code 0 <= i < size()}) to retrieve. * @return the value of the {@code i}th element as a ByteBuffer. If the value is NULL, {@code * null} is returned. * @throws IndexOutOfBoundsException if {@code i} is not a valid index for this object. */ public ByteBuffer getBytesUnsafe(int i); /** * Returns the {@code i}th value as a byte array. * *

This method uses the {@link CodecRegistry} to find a codec to convert the underlying CQL * type to a Java {@code ByteBuffer} (for CQL type {@code blob}, this will be the built-in codec). * * @param i the index ({@code 0 <= i < size()}) to retrieve. * @return the value of the {@code i}th element as a byte array. If the value is NULL, {@code * null} is returned. * @throws IndexOutOfBoundsException if {@code i} is not a valid index for this object. * @throws CodecNotFoundException if there is no registered codec to convert the element's CQL * type to a {@code ByteBuffer}. */ public ByteBuffer getBytes(int i); /** * Returns the {@code i}th value as a string. * *

This method uses the {@link CodecRegistry} to find a codec to convert the underlying CQL * type to a Java string (for CQL types {@code text}, {@code varchar} and {@code ascii}, this will * be the built-in codec). * * @param i the index ({@code 0 <= i < size()}) to retrieve. * @return the value of the {@code i}th element as a string. If the value is NULL, {@code null} is * returned. * @throws IndexOutOfBoundsException if {@code i} is not a valid index for this object. * @throws CodecNotFoundException if there is no registered codec to convert the element's CQL * type to a string. */ public String getString(int i); /** * Returns the {@code i}th value as a variable length integer. * *

This method uses the {@link CodecRegistry} to find a codec to convert the underlying CQL * type to a {@code BigInteger} (for CQL type {@code varint}, this will be the built-in codec). * * @param i the index ({@code 0 <= i < size()}) to retrieve. * @return the value of the {@code i}th element as a variable length integer. If the value is * NULL, {@code null} is returned. * @throws IndexOutOfBoundsException if {@code i} is not a valid index for this object. * @throws CodecNotFoundException if there is no registered codec to convert the element's CQL * type to a {@code BigInteger}. */ public BigInteger getVarint(int i); /** * Returns the {@code i}th value as a variable length decimal. * *

This method uses the {@link CodecRegistry} to find a codec to convert the underlying CQL * type to a {@code BigDecimal} (for CQL type {@code decimal}, this will be the built-in codec). * * @param i the index ({@code 0 <= i < size()}) to retrieve. * @return the value of the {@code i}th element as a variable length decimal. If the value is * NULL, {@code null} is returned. * @throws IndexOutOfBoundsException if {@code i} is not a valid index for this object. * @throws CodecNotFoundException if there is no registered codec to convert the element's CQL * type to a {@code BigDecimal}. */ public BigDecimal getDecimal(int i); /** * Returns the {@code i}th value as a UUID. * *

This method uses the {@link CodecRegistry} to find a codec to convert the underlying CQL * type to a {@code UUID} (for CQL types {@code uuid} and {@code timeuuid}, this will be the * built-in codec). * * @param i the index ({@code 0 <= i < size()}) to retrieve. * @return the value of the {@code i}th element as a UUID. If the value is NULL, {@code null} is * returned. * @throws IndexOutOfBoundsException if {@code i} is not a valid index for this object. * @throws CodecNotFoundException if there is no registered codec to convert the element's CQL * type to a {@code UUID}. */ public UUID getUUID(int i); /** * Returns the {@code i}th value as an InetAddress. * *

This method uses the {@link CodecRegistry} to find a codec to convert the underlying CQL * type to an {@code InetAddress} (for CQL type {@code inet}, this will be the built-in codec). * * @param i the index ({@code 0 <= i < size()}) to retrieve. * @return the value of the {@code i}th element as an InetAddress. If the value is NULL, {@code * null} is returned. * @throws IndexOutOfBoundsException if {@code i} is not a valid index for this object. * @throws CodecNotFoundException if there is no registered codec to convert the element's CQL * type to a {@code InetAddress}. */ public InetAddress getInet(int i); /** * Returns the {@code i}th value as a list. * *

This method uses the {@link CodecRegistry} to find a codec to convert the underlying CQL * type to a list of the specified type. * *

If the type of the elements is generic, use {@link #getList(int, TypeToken)}. * *

Implementation note: the actual {@link List} implementation will depend on the {@link * TypeCodec codec} being used; therefore, callers should make no assumptions concerning its * mutability nor its thread-safety. Furthermore, the behavior of this method in respect to CQL * {@code NULL} values is also codec-dependent. By default, the driver will return mutable * instances, and a CQL {@code NULL} will be mapped to an empty collection (note that Cassandra * makes no distinction between {@code NULL} and an empty collection). * * @param i the index ({@code 0 <= i < size()}) to retrieve. * @param elementsClass the class for the elements of the list to retrieve. * @return the value of the {@code i}th element as a list of {@code T} objects. * @throws IndexOutOfBoundsException if {@code i} is not a valid index for this object. * @throws CodecNotFoundException if there is no registered codec to convert the element's CQL * type to a list. */ public List getList(int i, Class elementsClass); /** * Returns the {@code i}th value as a list. * *

This method uses the {@link CodecRegistry} to find a codec to convert the underlying CQL * type to a list of the specified type. * *

Use this variant with nested collections, which produce a generic element type: * *

   * {@code List> l = row.getList(1, new TypeToken>() {});}
   * 
* *

Implementation note: the actual {@link List} implementation will depend on the {@link * TypeCodec codec} being used; therefore, callers should make no assumptions concerning its * mutability nor its thread-safety. Furthermore, the behavior of this method in respect to CQL * {@code NULL} values is also codec-dependent. By default, the driver will return mutable * instances, and a CQL {@code NULL} will mapped to an empty collection (note that Cassandra makes * no distinction between {@code NULL} and an empty collection). * * @param i the index ({@code 0 <= i < size()}) to retrieve. * @param elementsType the type of the elements of the list to retrieve. * @return the value of the {@code i}th element as a list of {@code T} objects. * @throws IndexOutOfBoundsException if {@code i} is not a valid index for this object. * @throws CodecNotFoundException if there is no registered codec to convert the element's CQL * type to a list. */ public List getList(int i, TypeToken elementsType); /** * Returns the {@code i}th value as a set. * *

This method uses the {@link CodecRegistry} to find a codec to convert the underlying CQL * type to a set of the specified type. * *

If the type of the elements is generic, use {@link #getSet(int, TypeToken)}. * *

Implementation note: the actual {@link Set} implementation will depend on the {@link * TypeCodec codec} being used; therefore, callers should make no assumptions concerning its * mutability nor its thread-safety. Furthermore, the behavior of this method in respect to CQL * {@code NULL} values is also codec-dependent. By default, the driver will return mutable * instances, and a CQL {@code NULL} will mapped to an empty collection (note that Cassandra makes * no distinction between {@code NULL} and an empty collection). * * @param i the index ({@code 0 <= i < size()}) to retrieve. * @param elementsClass the class for the elements of the set to retrieve. * @return the value of the {@code i}th element as a set of {@code T} objects. * @throws IndexOutOfBoundsException if {@code i} is not a valid index for this object. * @throws CodecNotFoundException if there is no registered codec to convert the element's CQL * type to a set. */ public Set getSet(int i, Class elementsClass); /** * Returns the {@code i}th value as a set. * *

This method uses the {@link CodecRegistry} to find a codec to convert the underlying CQL * type to a set of the specified type. * *

Use this variant with nested collections, which produce a generic element type: * *

   * {@code Set> l = row.getSet(1, new TypeToken>() {});}
   * 
* *

Implementation note: the actual {@link Set} implementation will depend on the {@link * TypeCodec codec} being used; therefore, callers should make no assumptions concerning its * mutability nor its thread-safety. Furthermore, the behavior of this method in respect to CQL * {@code NULL} values is also codec-dependent. By default, the driver will return mutable * instances, and a CQL {@code NULL} will mapped to an empty collection (note that Cassandra makes * no distinction between {@code NULL} and an empty collection). * * @param i the index ({@code 0 <= i < size()}) to retrieve. * @param elementsType the type for the elements of the set to retrieve. * @return the value of the {@code i}th element as a set of {@code T} objects. * @throws IndexOutOfBoundsException if {@code i} is not a valid index for this object. * @throws CodecNotFoundException if there is no registered codec to convert the element's CQL * type to a set. */ public Set getSet(int i, TypeToken elementsType); /** * Returns the {@code i}th value as a map. * *

This method uses the {@link CodecRegistry} to find a codec to convert the underlying CQL * type to a map of the specified types. * *

If the type of the keys and/or values is generic, use {@link #getMap(int, TypeToken, * TypeToken)}. * *

Implementation note: the actual {@link Map} implementation will depend on the {@link * TypeCodec codec} being used; therefore, callers should make no assumptions concerning its * mutability nor its thread-safety. Furthermore, the behavior of this method in respect to CQL * {@code NULL} values is also codec-dependent. By default, the driver will return mutable * instances, and a CQL {@code NULL} will mapped to an empty collection (note that Cassandra makes * no distinction between {@code NULL} and an empty collection). * * @param i the index ({@code 0 <= i < size()}) to retrieve. * @param keysClass the class for the keys of the map to retrieve. * @param valuesClass the class for the values of the map to retrieve. * @return the value of the {@code i}th element as a map of {@code K} to {@code V} objects. * @throws IndexOutOfBoundsException if {@code i} is not a valid index for this object. * @throws CodecNotFoundException if there is no registered codec to convert the element's CQL * type to a map. */ public Map getMap(int i, Class keysClass, Class valuesClass); /** * Returns the {@code i}th value as a map. * *

This method uses the {@link CodecRegistry} to find a codec to convert the underlying CQL * type to a map of the specified types. * *

Use this variant with nested collections, which produce a generic element type: * *

   * {@code Map> l = row.getMap(1, TypeToken.of(Integer.class), new TypeToken>() {});}
   * 
* *

Implementation note: the actual {@link Map} implementation will depend on the {@link * TypeCodec codec} being used; therefore, callers should make no assumptions concerning its * mutability nor its thread-safety. Furthermore, the behavior of this method in respect to CQL * {@code NULL} values is also codec-dependent. By default, the driver will return mutable * instances, and a CQL {@code NULL} will mapped to an empty collection (note that Cassandra makes * no distinction between {@code NULL} and an empty collection). * * @param i the index ({@code 0 <= i < size()}) to retrieve. * @param keysType the type for the keys of the map to retrieve. * @param valuesType the type for the values of the map to retrieve. * @return the value of the {@code i}th element as a map of {@code K} to {@code V} objects. * @throws IndexOutOfBoundsException if {@code i} is not a valid index for this object. * @throws CodecNotFoundException if there is no registered codec to convert the element's CQL * type to a map. */ public Map getMap(int i, TypeToken keysType, TypeToken valuesType); /** * Return the {@code i}th value as a UDT value. * *

This method uses the {@link CodecRegistry} to find a codec to convert the underlying CQL * type to a {@code UDTValue} (if the CQL type is a UDT, the registry will generate a codec * automatically). * * @param i the index ({@code 0 <= i < size()}) to retrieve. * @return the value of the {@code i}th element as a UDT value. If the value is NULL, then {@code * null} will be returned. * @throws IndexOutOfBoundsException if {@code i} is not a valid index for this object. * @throws CodecNotFoundException if there is no registered codec to convert the element's CQL * type to a {@code UDTValue}. */ public UDTValue getUDTValue(int i); /** * Return the {@code i}th value as a tuple value. * *

This method uses the {@link CodecRegistry} to find a codec to convert the underlying CQL * type to a {@code TupleValue} (if the CQL type is a tuple, the registry will generate a codec * automatically). * * @param i the index ({@code 0 <= i < size()}) to retrieve. * @return the value of the {@code i}th element as a tuple value. If the value is NULL, then * {@code null} will be returned. * @throws IndexOutOfBoundsException if {@code i} is not a valid index for this object. * @throws CodecNotFoundException if there is no registered codec to convert the element's CQL * type to a {@code TupleValue}. */ public TupleValue getTupleValue(int i); /** * Returns the {@code i}th value as the Java type matching its CQL type. * *

This method uses the {@link CodecRegistry} to find the first codec that handles the * underlying CQL type. The Java type of the returned object will be determined by the codec that * was selected. * *

Use this method to dynamically inspect elements when types aren't known in advance, for * instance if you're writing a generic row logger. If you know the target Java type, it is * generally preferable to use typed getters, such as the ones for built-in types ({@link * #getBool(int)}, {@link #getInt(int)}, etc.), or {@link #get(int, Class)} and {@link #get(int, * TypeToken)} for custom types. * * @param i the index to retrieve. * @return the value of the {@code i}th value as the Java type matching its CQL type. * @throws IndexOutOfBoundsException if {@code i} is not a valid index for this object. * @see CodecRegistry#codecFor(DataType) */ public Object getObject(int i); /** * Returns the {@code i}th value converted to the given Java type. * *

This method uses the {@link CodecRegistry} to find a codec to convert the underlying CQL * type to the given Java type. * *

If the target type is generic, use {@link #get(int, TypeToken)}. * *

Implementation note: the actual object returned by this method will depend on the {@link * TypeCodec codec} being used; therefore, callers should make no assumptions concerning its * mutability nor its thread-safety. Furthermore, the behavior of this method in respect to CQL * {@code NULL} values is also codec-dependent; by default, a CQL {@code NULL} value translates to * {@code null} for simple CQL types, UDTs and tuples, and to empty collections for all CQL * collection types. * * @param i the index to retrieve. * @param targetClass The Java type the value should be converted to. * @return the value of the {@code i}th value converted to the given Java type. * @throws IndexOutOfBoundsException if {@code i} is not a valid index for this object. * @throws CodecNotFoundException if there is no registered codec to convert the element's CQL * type to {@code targetClass}. */ T get(int i, Class targetClass); /** * Returns the {@code i}th value converted to the given Java type. * *

This method uses the {@link CodecRegistry} to find a codec to convert the underlying CQL * type to the given Java type. * *

Implementation note: the actual object returned by this method will depend on the {@link * TypeCodec codec} being used; therefore, callers should make no assumptions concerning its * mutability nor its thread-safety. Furthermore, the behavior of this method in respect to CQL * {@code NULL} values is also codec-dependent; by default, a CQL {@code NULL} value translates to * {@code null} for simple CQL types, UDTs and tuples, and to empty collections for all CQL * collection types. * * @param i the index to retrieve. * @param targetType The Java type the value should be converted to. * @return the value of the {@code i}th value converted to the given Java type. * @throws IndexOutOfBoundsException if {@code i} is not a valid index for this object. * @throws CodecNotFoundException if there is no registered codec to convert the element's CQL * type to {@code targetType}. */ T get(int i, TypeToken targetType); /** * Returns the {@code i}th value converted using the given {@link TypeCodec}. * *

This method entirely bypasses the {@link CodecRegistry} and forces the driver to use the * given codec instead. This can be useful if the codec would collide with a previously registered * one, or if you want to use the codec just once without registering it. * *

It is the caller's responsibility to ensure that the given codec {@link * TypeCodec#accepts(DataType) accepts} the underlying CQL type; failing to do so may result in * {@link InvalidTypeException}s being thrown. * *

Implementation note: the actual object returned by this method will depend on the {@link * TypeCodec codec} being used; therefore, callers should make no assumptions concerning its * mutability nor its thread-safety. Furthermore, the behavior of this method in respect to CQL * {@code NULL} values is also codec-dependent; by default, a CQL {@code NULL} value translates to * {@code null} for simple CQL types, UDTs and tuples, and to empty collections for all CQL * collection types. * * @param i the index to retrieve. * @param codec The {@link TypeCodec} to use to deserialize the value; may not be {@code null}. * @return the value of the {@code i}th value converted using the given {@link TypeCodec}. * @throws InvalidTypeException if the given codec does not {@link TypeCodec#accepts(DataType) * accept} the underlying CQL type. * @throws IndexOutOfBoundsException if {@code i} is not a valid index for this object. */ T get(int i, TypeCodec codec); }





© 2015 - 2024 Weber Informatics LLC | Privacy Policy