<!--
Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements.  See the NOTICE file
distributed with this work for additional information
regarding copyright ownership.  The ASF licenses this file
to you 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.
-->

## Core driver

The core module handles cluster connectivity and request execution. It is published under the
following coordinates:

```xml
<dependency>
  <groupId>org.apache.cassandra</groupId>
  <artifactId>java-driver-core</artifactId>
  <version>${driver.version}</version>
</dependency>
```

(For more details on setting up your build tool, see the [integration](integration/README.md) page.)

### Quick start

Here's a short program that connects to Cassandra and executes a query:

```java
import com.datastax.oss.driver.api.core.CqlSession;
import com.datastax.oss.driver.api.core.cql.*;

try (CqlSession session = CqlSession.builder().build()) {                                  // (1)
  ResultSet rs = session.execute("select release_version from system.local");              // (2)
  Row row = rs.one();
  System.out.println(row.getString("release_version"));                                    // (3)
}
```

1. [CqlSession] is the main entry point of the driver. It holds the known state of the actual
   Cassandra cluster, and is what you use to execute queries. It is thread-safe, you should create a
   single instance (per target Cassandra cluster), and share it throughout your application;
2. we use `execute` to send a query to Cassandra. This returns a [ResultSet], which is an iterable 
   of [Row] objects. On the next line, we extract the first row (which is the only one in this case);
3. we extract the value of the first (and only) column from the row.

Always close the `CqlSession` once you're done with it, in order to free underlying resources (TCP 
connections, thread pools...). In this simple example, we can use a try-with-resources block because
`CqlSession` implements `java.lang.AutoCloseable`; in a real application, you'll probably call one
of the close methods (`close`, `closeAsync`, `forceCloseAsync`) explicitly.

This example uses the synchronous API. Most methods have asynchronous equivalents (look for `*Async`
variants that return a `CompletionStage`).


### Setting up the driver

#### [CqlSession]

[CqlSession#builder()] provides a fluent API to create an instance programmatically. Most of the
customization is done through the driver configuration (refer to the
[corresponding section](configuration/README.md) of this manual for full details).

We recommend that you take a look at the [reference configuration](configuration/reference/README.md) for the
list of available options, and cross-reference with the sub-sections in this manual for more
explanations.

By default, `CqlSession.builder().build()` fails immediately if the cluster is not available. If you
want to retry instead, you can set the [reconnect-on-init](reconnection/README.md#at-init-time) option in the
configuration.

##### Contact points

If you don't specify any contact point, the driver defaults to `127.0.0.1:9042`:

```java
CqlSession session = CqlSession.builder().build();
```

This is fine for a quick start on a developer workstation, but you'll quickly want to provide
specific addresses. There are two ways to do this:

* via [SessionBuilder.addContactPoint()] or [SessionBuilder.addContactPoints()];
* in the [configuration](configuration/README.md) via the `basic.contact-points` option.

As soon as there are explicit contact points, you also need to provide the name of the local
datacenter. All contact points must belong to it (as reported in their system tables:
`system.local.data_center` and `system.peers.data_center`). Again this can be specified either:

* via [SessionBuilder.withLocalDatacenter()];
* in the configuration via the `basic.load-balancing-policy.local-datacenter` option.

Here is a full programmatic example:

```java
CqlSession session = CqlSession.builder()
    .addContactPoint(new InetSocketAddress("1.2.3.4", 9042))
    .addContactPoint(new InetSocketAddress("5.6.7.8", 9042))
    .withLocalDatacenter("datacenter1")
    .build();
```

And a full configuration example:

```
// Add `application.conf` to your classpath with the following contents:
datastax-java-driver {
  basic {
    contact-points = [ "1.2.3.4:9042", "5.6.7.8:9042" ]
    load-balancing-policy.local-datacenter = datacenter1
  }
}
```

For more details about the local datacenter, refer to the [load balancing
policy](load_balancing/README.md#datacenter-locality) section.

##### Keyspace

By default, a session isn't tied to any specific keyspace. You'll need to prefix table names in your
queries:

```java
session.execute("SELECT * FROM my_keyspace.my_table WHERE id = 1");
```

You can also specify a keyspace at construction time, either through the
[configuration](configuration/README.md):

```
datastax-java-driver {
  basic.session-keyspace = my_keyspace
}
```

Or with the builder:

```java
CqlSession session = CqlSession.builder()
  .withKeyspace(CqlIdentifier.fromCql("my_keyspace"))
  .build();
```

That keyspace will be used as the default when table names are not qualified:

```java
session.execute("SELECT * FROM my_table WHERE id = 1");
session.execute("SELECT * FROM other_keyspace.other_table WHERE id = 1");
```

You might be tempted to open a separate session for each keyspace used in your application; however,
connection pools are created at the session level, so each new session will consume additional
system resources:

```java
// Anti-pattern: creating two sessions doubles the number of TCP connections opened by the driver
CqlSession session1 = CqlSession.builder().withKeyspace(CqlIdentifier.fromCql("ks1")).build();
CqlSession session2 = CqlSession.builder().withKeyspace(CqlIdentifier.fromCql("ks2")).build();
```

If you issue a `USE` statement, it will change the default keyspace on that session:

```java
CqlSession session = CqlSession.builder().build();
// No default keyspace set, need to prefix:
session.execute("SELECT * FROM my_keyspace.my_table WHERE id = 1");

session.execute("USE my_keyspace");
// Now the keyspace is set, unqualified query works:
session.execute("SELECT * FROM my_table WHERE id = 1");
```

Be very careful though: switching the keyspace at runtime is inherently thread-unsafe, so if the
session is shared by multiple threads (and is usually is), it could easily cause unexpected query
failures.

Finally, if you're connecting to Cassandra 4 or above, you can specify the keyspace independently
for each request:

```java
CqlSession session = CqlSession.builder().build();
session.execute(
  SimpleStatement.newInstance("SELECT * FROM my_table WHERE id = 1")
      .setKeyspace(CqlIdentifier.fromCql("my_keyspace")));
``` 

### Running queries

You run queries with the session's `execute*` methods:

```java
ResultSet rs = session.execute("SELECT release_version FROM system.local");
```

As shown here, the simplest form is to pass a query string directly. You can also pass a
[Statement](statements/README.md) instance.

#### Processing rows

Executing a query produces a [ResultSet], which is an iterable of [Row]. The basic way to process
all rows is to use Java's for-each loop:

```java
for (Row row : rs) {
    // process the row
}
```

This will return **all results** without limit (even though the driver might use multiple queries in
the background). To handle large result sets, you might want to use a `LIMIT` clause in your CQL
query, or use one of the techniques described in the [paging](paging/README.md) documentation.

When you know that there is only one row (or are only interested in the first one), the driver
provides a convenience method:

```java
Row row = rs.one();
```

#### Reading columns

[Row] provides getters to extract column values; they can be either positional or named:

```java
Row row = session.execute("SELECT first_name, last_name FROM users WHERE id = 1").one();

// The two are equivalent:
String firstName = row.getString(0);
String firstName = row.getString(CqlIdentifier.fromCql("first_name"));
```

[CqlIdentifier] is a string wrapper that deals with case-sensitivity. If you don't want to create an
instance for each getter call, the driver also provides convenience methods that take a raw string:

```java
String firstName = row.getString("first_name");
```

See [AccessibleByName] for an explanation of the conversion rules.

##### CQL to Java type mapping

| CQL3 data type     | Getter name    | Java type            | See also                          |
|--------------------|----------------|----------------------|-----------------------------------|
| ascii              | getString      | java.lang.String     |                                   |
| bigint             | getLong        | long                 |                                   |
| blob               | getByteBuffer  | java.nio.ByteBuffer  |                                   |
| boolean            | getBoolean     | boolean              |                                   |
| counter            | getLong        | long                 |                                   |
| date               | getLocalDate   | java.time.LocalDate  | [Temporal types](temporal_types/README.md) |
| decimal            | getBigDecimal  | java.math.BigDecimal |                                   |
| double             | getDouble      | double               |                                   |
| duration           | getCqlDuration | [CqlDuration]        | [Temporal types](temporal_types/README.md) |
| float              | getFloat       | float                |                                   |
| inet               | getInetAddress | java.net.InetAddress |                                   |
| int                | getInt         | int                  |                                   |
| list               | getList        | java.util.List<T>    |                                   |
| map                | getMap         | java.util.Map<K, V>  |                                   |
| set                | getSet         | java.util.Set<T>     |                                   |
| smallint           | getShort       | short                |                                   |
| text               | getString      | java.lang.String     |                                   |
| time               | getLocalTime   | java.time.LocalTime  | [Temporal types](temporal_types/README.md) |
| timestamp          | getInstant     | java.time.Instant    | [Temporal types](temporal_types/README.md) |
| timeuuid           | getUuid        | java.util.UUID       |                                   |
| tinyint            | getByte        | byte                 |                                   |
| tuple              | getTupleValue  | [TupleValue]         | [Tuples](tuples/README.md)                 |
| user-defined types | getUDTValue    | [UDTValue]           | [User-defined types](udts/README.md)       |
| uuid               | getUuid        | java.util.UUID       |                                   |
| varchar            | getString      | java.lang.String     |                                   |
| varint             | getBigInteger  | java.math.BigInteger |                                   |
| vector             | getVector      | [CqlVector]          | [Custom Codecs](custom_codecs/README.md)   |

Sometimes the driver has to infer a CQL type from a Java type (for example when handling the values 
of [simple statements](statements/simple/README.md)); for those that have multiple CQL equivalents, it makes
the following choices:

* `java.lang.String`: `text`
* `long`: `bigint`
* `java.util.UUID`: `uuid`

In addition to these default mappings, you can register your own types with
[custom codecs](custom_codecs/README.md).

##### Primitive types

For performance reasons, the driver uses primitive Java types wherever possible (`boolean`,
`int`...); the CQL value `NULL` is encoded as the type's default value (`false`, `0`...), which can
be ambiguous. To distinguish `NULL` from actual values, use `isNull`:

```java
Integer age = row.isNull("age") ? null : row.getInt("age");
```
##### Collection types

To ensure type safety, collection getters are generic. You need to provide type parameters matching
your CQL type when calling the methods:

```java
// Assuming given_names is a list<text>:
List<String> givenNames = row.getList("given_names", String.class);
```

For nested collections, element types are generic and cannot be expressed as Java `Class` instances.
Use [GenericType] instead:

```java
// Assuming teams is a set<list<text>>:
GenericType<Set<List<String>>> listOfStrings = new GenericType<Set<List<String>>>() {};
Set<List<String>> teams = row.get("teams", listOfStrings);
```

Since generic types are anonymous inner classes, it's recommended to store them as constants in a
utility class instead of re-creating them each time.

##### Row metadata

[ResultSet] and [Row] expose an API to explore the column metadata at runtime:

```java
for (ColumnDefinitions.Definition definition : row.getColumnDefinitions()) {
    System.out.printf("Column %s has type %s%n",
            definition.getName(),
            definition.getType());
}
```

[CqlSession]:                           https://docs.datastax.com/en/drivers/java/4.17/com/datastax/oss/driver/api/core/CqlSession.html
[CqlSession#builder()]:                 https://docs.datastax.com/en/drivers/java/4.17/com/datastax/oss/driver/api/core/CqlSession.html#builder--
[ResultSet]:                            https://docs.datastax.com/en/drivers/java/4.17/com/datastax/oss/driver/api/core/cql/ResultSet.html
[Row]:                                  https://docs.datastax.com/en/drivers/java/4.17/com/datastax/oss/driver/api/core/cql/Row.html
[CqlIdentifier]:                        https://docs.datastax.com/en/drivers/java/4.17/com/datastax/oss/driver/api/core/CqlIdentifier.html
[AccessibleByName]:                     https://docs.datastax.com/en/drivers/java/4.17/com/datastax/oss/driver/api/core/data/AccessibleByName.html
[GenericType]:                          https://docs.datastax.com/en/drivers/java/4.17/com/datastax/oss/driver/api/core/type/reflect/GenericType.html
[CqlDuration]:                          https://docs.datastax.com/en/drivers/java/4.17/com/datastax/oss/driver/api/core/data/CqlDuration.html
[CqlVector]:                            https://docs.datastax.com/en/drivers/java/4.17/com/datastax/oss/driver/api/core/data/CqlVector.html
[TupleValue]:                           https://docs.datastax.com/en/drivers/java/4.17/com/datastax/oss/driver/api/core/data/TupleValue.html
[UdtValue]:                             https://docs.datastax.com/en/drivers/java/4.17/com/datastax/oss/driver/api/core/data/UdtValue.html
[SessionBuilder.addContactPoint()]:     https://docs.datastax.com/en/drivers/java/4.17/com/datastax/oss/driver/api/core/session/SessionBuilder.html#addContactPoint-java.net.InetSocketAddress-
[SessionBuilder.addContactPoints()]:    https://docs.datastax.com/en/drivers/java/4.17/com/datastax/oss/driver/api/core/session/SessionBuilder.html#addContactPoints-java.util.Collection-
[SessionBuilder.withLocalDatacenter()]: https://docs.datastax.com/en/drivers/java/4.17/com/datastax/oss/driver/api/core/session/SessionBuilder.html#withLocalDatacenter-java.lang.String-

[CASSANDRA-10145]: https://issues.apache.org/jira/browse/CASSANDRA-10145
