diff --git a/README.md b/README.md index 3867a412d6d..51f1496aa21 100644 --- a/README.md +++ b/README.md @@ -37,8 +37,10 @@ The driver contains the following modules: - driver-core: the core layer. - driver-mapping: the object mapper. +- driver-extras: optional features for the Java driver. - driver-examples: example applications using the other modules which are only meant for demonstration purposes. +- driver-tests: tests for the java-driver. **Useful links:** diff --git a/changelog/README.md b/changelog/README.md index 94f67b5e15f..4484eef0b97 100644 --- a/changelog/README.md +++ b/changelog/README.md @@ -20,6 +20,8 @@ - [bug] JAVA-1046: (Dynamic)CompositeTypes need to be parsed as string literal, not blob. - [improvement] JAVA-1164: Clarify documentation on Host.listenAddress and broadcastAddress. - [improvement] JAVA-1171: Add Host method to determine if DSE Graph is enabled. +- [improvement]: JAVA-1069: Bootstrap driver-examples module. +- [documentation] JAVA-1150: Add example and FAQ entry about ByteBuffer/BLOB. Merged from 2.1 branch: diff --git a/driver-examples/README.md b/driver-examples/README.md new file mode 100644 index 00000000000..553cdbc5117 --- /dev/null +++ b/driver-examples/README.md @@ -0,0 +1,10 @@ +# DataStax Java Driver for Apache Cassandra - Examples + +This module contains examples of how to use the DataStax Java driver for +Apache Cassandra. + +## Usage + +Unless otherwise stated, all examples assume that you have a single-node Cassandra 3.0 cluster +listening on localhost:9042. + diff --git a/driver-examples/pom.xml b/driver-examples/pom.xml index b278ea3c165..be29915a546 100644 --- a/driver-examples/pom.xml +++ b/driver-examples/pom.xml @@ -15,16 +15,18 @@ limitations under the License. --> - - 4.0.0 + - com.datastax.cassandra cassandra-driver-parent + com.datastax.cassandra 3.0.1-SNAPSHOT - cassandra-driver-examples-parent - pom - DataStax Java Driver for Apache Cassandra Examples + 4.0.0 + + cassandra-driver-examples + + DataStax Java Driver for Apache Cassandra - Examples A collection of examples to demonstrate DataStax Java Driver for Apache Cassandra. https://github.com/datastax/java-driver @@ -32,36 +34,26 @@ ${project.parent.basedir} - - stress - osgi - + - - - Apache 2 - http://www.apache.org/licenses/LICENSE-2.0.txt - repo - Apache License Version 2.0 - - + + com.datastax.cassandra + cassandra-driver-core + ${project.parent.version} + - - scm:git:git@github.com:datastax/java-driver.git - scm:git:git@github.com:datastax/java-driver.git - https://github.com/datastax/java-driver - HEAD - + + ch.qos.logback + logback-classic + 1.1.3 + - - - Various - DataStax - - + + + org.apache.maven.plugins maven-install-plugin @@ -70,6 +62,7 @@ true + org.apache.maven.plugins maven-deploy-plugin @@ -78,6 +71,32 @@ true + + + + + + Apache 2 + http://www.apache.org/licenses/LICENSE-2.0.txt + repo + Apache License Version 2.0 + + + + + scm:git:git@github.com:datastax/java-driver.git + scm:git:git@github.com:datastax/java-driver.git + https://github.com/datastax/java-driver + HEAD + + + + + Various + DataStax + + + diff --git a/driver-examples/src/main/java/com/datastax/driver/examples/basic/CreateAndPopulateKeyspace.java b/driver-examples/src/main/java/com/datastax/driver/examples/basic/CreateAndPopulateKeyspace.java new file mode 100644 index 00000000000..14c843dd58c --- /dev/null +++ b/driver-examples/src/main/java/com/datastax/driver/examples/basic/CreateAndPopulateKeyspace.java @@ -0,0 +1,166 @@ +/* + * Copyright (C) 2012-2015 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.examples.basic; + +import com.datastax.driver.core.Cluster; +import com.datastax.driver.core.ResultSet; +import com.datastax.driver.core.Row; +import com.datastax.driver.core.Session; + +/** + * Creates a keyspace and tables, and loads some data into them. + *

+ * Preconditions: + * - a Cassandra cluster is running and accessible through the contacts points identified by CONTACT_POINTS and PORT. + *

+ * Side effects: + * - creates a new keyspace "simplex" in the cluster. It a keyspace with this name already exists, it will be reused; + * - creates two tables "simplex.songs" and "simplex.playlists". If they exist already, they will be reused; + * - inserts a row in each table. + * + * @see Java driver online manual + */ +public class CreateAndPopulateKeyspace { + + static String[] CONTACT_POINTS = {"127.0.0.1"}; + static int PORT = 9042; + + public static void main(String[] args) { + + CreateAndPopulateKeyspace client = new CreateAndPopulateKeyspace(); + + try { + + client.connect(CONTACT_POINTS, PORT); + client.createSchema(); + client.loadData(); + client.querySchema(); + + } finally { + client.close(); + } + } + + private Cluster cluster; + + private Session session; + + /** + * Initiates a connection to the cluster + * specified by the given contact point. + * + * @param contactPoints the contact points to use. + * @param port the port to use. + */ + public void connect(String[] contactPoints, int port) { + + cluster = Cluster.builder() + .addContactPoints(contactPoints).withPort(port) + .build(); + + System.out.printf("Connected to cluster: %s%n", cluster.getMetadata().getClusterName()); + + session = cluster.connect(); + } + + /** + * Creates the schema (keyspace) and tables + * for this example. + */ + public void createSchema() { + + session.execute("CREATE KEYSPACE IF NOT EXISTS simplex WITH replication " + + "= {'class':'SimpleStrategy', 'replication_factor':1};"); + + session.execute( + "CREATE TABLE IF NOT EXISTS simplex.songs (" + + "id uuid PRIMARY KEY," + + "title text," + + "album text," + + "artist text," + + "tags set," + + "data blob" + + ");"); + + session.execute( + "CREATE TABLE IF NOT EXISTS simplex.playlists (" + + "id uuid," + + "title text," + + "album text, " + + "artist text," + + "song_id uuid," + + "PRIMARY KEY (id, title, album, artist)" + + ");"); + } + + /** + * Inserts data into the tables. + */ + public void loadData() { + + session.execute( + "INSERT INTO simplex.songs (id, title, album, artist, tags) " + + "VALUES (" + + "756716f7-2e54-4715-9f00-91dcbea6cf50," + + "'La Petite Tonkinoise'," + + "'Bye Bye Blackbird'," + + "'Joséphine Baker'," + + "{'jazz', '2013'})" + + ";"); + + session.execute( + "INSERT INTO simplex.playlists (id, song_id, title, album, artist) " + + "VALUES (" + + "2cc9ccb7-6221-4ccb-8387-f22b6a1b354d," + + "756716f7-2e54-4715-9f00-91dcbea6cf50," + + "'La Petite Tonkinoise'," + + "'Bye Bye Blackbird'," + + "'Joséphine Baker'" + + ");"); + } + + /** + * Queries and displays data. + */ + public void querySchema() { + + ResultSet results = session.execute( + "SELECT * FROM simplex.playlists " + + "WHERE id = 2cc9ccb7-6221-4ccb-8387-f22b6a1b354d;"); + + System.out.printf("%-30s\t%-20s\t%-20s%n", "title", "album", "artist"); + System.out.println("-------------------------------+-----------------------+--------------------"); + + for (Row row : results) { + + System.out.printf("%-30s\t%-20s\t%-20s%n", + row.getString("title"), + row.getString("album"), + row.getString("artist")); + + } + + } + + /** + * Closes the session and the cluster. + */ + public void close() { + session.close(); + cluster.close(); + } + +} diff --git a/driver-examples/src/main/java/com/datastax/driver/examples/basic/ReadCassandraVersion.java b/driver-examples/src/main/java/com/datastax/driver/examples/basic/ReadCassandraVersion.java new file mode 100644 index 00000000000..69bac907119 --- /dev/null +++ b/driver-examples/src/main/java/com/datastax/driver/examples/basic/ReadCassandraVersion.java @@ -0,0 +1,72 @@ +/* + * Copyright (C) 2012-2015 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.examples.basic; + +import com.datastax.driver.core.Cluster; +import com.datastax.driver.core.ResultSet; +import com.datastax.driver.core.Row; +import com.datastax.driver.core.Session; + +/** + * Connects to a Cassandra cluster and extracts basic information from it. + *

+ * Preconditions: + * - a Cassandra cluster is running and accessible through the contacts points identified by CONTACT_POINTS and PORT. + *

+ * Side effects: none. + * + * @see Java driver online manual + */ +public class ReadCassandraVersion { + + static String[] CONTACT_POINTS = {"127.0.0.1"}; + static int PORT = 9042; + + public static void main(String[] args) { + + Cluster cluster = null; + try { + // The Cluster object is the main entry point of the driver. + // It holds the known state of the actual Cassandra cluster (notably the Metadata). + // This class is thread-safe, you should create a single instance (per target Cassandra cluster), and share + // it throughout your application. + cluster = Cluster.builder() + .addContactPoints(CONTACT_POINTS).withPort(PORT) + .build(); + + // The Session is what you use to execute queries. Likewise, it is thread-safe and should be reused. + Session session = cluster.connect(); + + // We use execute to send a query to Cassandra. This returns a ResultSet, which is essentially a collection + // of Row objects. + ResultSet rs = session.execute("select release_version from system.local"); + // Extract the first row (which is the only one in this case). + Row row = rs.one(); + + // Extract the value of the first (and only) column from the row. + String releaseVersion = row.getString("release_version"); + System.out.printf("Cassandra version is: %s%n", releaseVersion); + + } finally { + // Close the cluster after we’re done with it. This will also close any session that was created from this + // cluster. + // This step is important because it frees underlying resources (TCP connections, thread pools...). In a + // real application, you would typically do this at shutdown (for example, when undeploying your webapp). + if (cluster != null) + cluster.close(); + } + } +} diff --git a/driver-examples/src/main/java/com/datastax/driver/examples/basic/ReadTopologyAndSchemaMetadata.java b/driver-examples/src/main/java/com/datastax/driver/examples/basic/ReadTopologyAndSchemaMetadata.java new file mode 100644 index 00000000000..feebe7aa990 --- /dev/null +++ b/driver-examples/src/main/java/com/datastax/driver/examples/basic/ReadTopologyAndSchemaMetadata.java @@ -0,0 +1,64 @@ +/* + * Copyright (C) 2012-2015 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.examples.basic; + +import com.datastax.driver.core.*; + +/** + * Gathers information about a Cassandra cluster's topology (which nodes belong to the cluster) and schema (what + * keyspaces, tables, etc. exist in this cluster). + *

+ * Preconditions: + * - a Cassandra cluster is running and accessible through the contacts points identified by CONTACT_POINTS and PORT. + *

+ * Side effects: none. + * + * @see Java driver online manual + */ +public class ReadTopologyAndSchemaMetadata { + + static String[] CONTACT_POINTS = {"127.0.0.1"}; + static int PORT = 9042; + + public static void main(String[] args) { + + Cluster cluster = null; + try { + cluster = Cluster.builder() + .addContactPoints(CONTACT_POINTS).withPort(PORT) + .build(); + + Metadata metadata = cluster.getMetadata(); + System.out.printf("Connected to cluster: %s%n", metadata.getClusterName()); + + for (Host host : metadata.getAllHosts()) { + System.out.printf("Datatacenter: %s; Host: %s; Rack: %s%n", + host.getDatacenter(), host.getAddress(), host.getRack()); + } + + for (KeyspaceMetadata keyspace : metadata.getKeyspaces()) { + for (TableMetadata table : keyspace.getTables()) { + System.out.printf("Keyspace: %s; Table: %s%n", + keyspace.getName(), table.getName()); + } + } + + } finally { + if (cluster != null) + cluster.close(); + } + } +} diff --git a/driver-examples/src/main/java/com/datastax/driver/examples/datatypes/Blobs.java b/driver-examples/src/main/java/com/datastax/driver/examples/datatypes/Blobs.java new file mode 100644 index 00000000000..70aa1f8efb0 --- /dev/null +++ b/driver-examples/src/main/java/com/datastax/driver/examples/datatypes/Blobs.java @@ -0,0 +1,253 @@ +/* + * Copyright (C) 2012-2015 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.examples.datatypes; + +import com.datastax.driver.core.*; +import com.datastax.driver.core.utils.Bytes; +import com.google.common.collect.ImmutableMap; + +import java.io.*; +import java.nio.ByteBuffer; +import java.nio.channels.FileChannel; +import java.util.Map; + +/** + * Inserts and retrieves values in BLOB columns. + *

+ * By default, the Java driver maps this type to {@link java.nio.ByteBuffer}. The ByteBuffer API is a bit tricky to use + * at times, so we will show common pitfalls as well. We strongly recommend that you read the {@link java.nio.Buffer} + * and {@link ByteBuffer} API docs and become familiar with the capacity, limit and position properties. + * This tutorial might also help. + *

+ * Preconditions: + * - a Cassandra cluster is running and accessible through the contacts points identified by CONTACT_POINTS and PORT; + * - FILE references an existing file. + *

+ * Side effects: + * - creates a new keyspace "examples" in the cluster. It a keyspace with this name already exists, it will be reused; + * - creates a table "examples.blobs". If it already exists, it will be reused; + * - inserts data in the table. + */ +public class Blobs { + + static String[] CONTACT_POINTS = {"127.0.0.1"}; + static int PORT = 9042; + + static File FILE = new File(Blobs.class.getResource("/cassandra_logo.png").getFile()); + + public static void main(String[] args) throws IOException { + Cluster cluster = null; + try { + cluster = Cluster.builder() + .addContactPoints(CONTACT_POINTS).withPort(PORT) + .build(); + Session session = cluster.connect(); + + createSchema(session); + allocateAndInsert(session); + retrieveSimpleColumn(session); + retrieveMapColumn(session); + insertConcurrent(session); + insertFromAndRetrieveToFile(session); + } finally { + if (cluster != null) cluster.close(); + } + } + + private static void createSchema(Session session) { + session.execute("CREATE KEYSPACE IF NOT EXISTS examples " + + "WITH replication = {'class': 'SimpleStrategy', 'replication_factor': 1}"); + session.execute("CREATE TABLE IF NOT EXISTS examples.blobs(k int PRIMARY KEY, b blob, m map)"); + } + + private static void allocateAndInsert(Session session) { + // One way to get a byte buffer is to allocate it and fill it yourself: + ByteBuffer buffer = ByteBuffer.allocate(16); + while (buffer.hasRemaining()) + buffer.put((byte) 0xFF); + + // Don't forget to flip! The driver expects a buffer that is ready for reading. That is, it will consider all + // the data between buffer.position() and buffer.limit(). + // Right now we are positioned at the end because we just finished writing, so if we passed the buffer as-is it + // would appear to be empty: + assert buffer.limit() - buffer.position() == 0; + + buffer.flip(); + // Now position is back to the beginning, so the driver will see all 16 bytes. + assert buffer.limit() - buffer.position() == 16; + + session.execute("INSERT INTO examples.blobs (k, b, m) VALUES (1, ?, ?)", + buffer, ImmutableMap.of("test", buffer)); + } + + private static void retrieveSimpleColumn(Session session) { + Row row = session.execute("SELECT b, m FROM examples.blobs WHERE k = 1").one(); + + ByteBuffer buffer = row.getBytes("b"); + + // The driver always returns buffers that are ready for reading. + assert buffer.limit() - buffer.position() == 16; + + // One way to read from the buffer is to use absolute getters. Do NOT start reading at index 0, as the buffer + // might start at a different position (we'll see an example of that later). + for (int i = buffer.position(); i < buffer.limit(); i++) { + byte b = buffer.get(i); + assert b == (byte) 0xFF; + } + + // Another way is to use relative getters. + while (buffer.hasRemaining()) { + byte b = buffer.get(); + assert b == (byte) 0xFF; + } + // Note that relative getters change the position, so when we're done reading we're at the end again. + assert buffer.position() == buffer.limit(); + + // Reset the position for the next operation. + buffer.flip(); + + // Yet another way is to convert the buffer to a byte array. Do NOT use buffer.array(), because it returns the + // buffer's *backing array*, which is not the same thing as its contents: + // - not all byte buffers have backing arrays + // - even then, the backing array might be larger than the buffer's contents + // + // The driver provides a utility method that handles those details for you: + byte[] array = Bytes.getArray(buffer); + assert array.length == 16; + for (byte b : array) { + assert b == (byte) 0xFF; + } + } + + private static void retrieveMapColumn(Session session) { + Row row = session.execute("SELECT b, m FROM examples.blobs WHERE k = 1").one(); + + // The map columns illustrates the pitfalls with position() and array(). + Map m = row.getMap("m", String.class, ByteBuffer.class); + ByteBuffer buffer = m.get("test"); + + // We did get back a buffer that contains 16 bytes as expected. + assert buffer.limit() - buffer.position() == 16; + // However, it is not positioned at 0. And you can also see that its backing array contains more than 16 bytes. + // What happens is that the buffer is a "view" of the last 16 of a 32-byte array. + // This is an implementation detail and you shouldn't have to worry about it if you process the buffer correctly + // (don't iterate from 0, use Bytes.getArray()). + assert buffer.position() == 16; + assert buffer.array().length == 32; + } + + private static void insertConcurrent(Session session) { + PreparedStatement preparedStatement = session.prepare("INSERT INTO examples.blobs (k, b) VALUES (1, :b)"); + + // This is another convenient utility provided by the driver. It's useful for tests. + ByteBuffer buffer = Bytes.fromHexString("0xffffff"); + + // When you pass a byte buffer to a bound statement, it creates a shallow copy internally with the + // buffer.duplicate() method. + BoundStatement boundStatement = preparedStatement.bind(); + boundStatement.setBytes("b", buffer); + + // This means you can now move in the original buffer, without affecting the insertion if it happens later. + buffer.position(buffer.limit()); + + session.execute(boundStatement); + Row row = session.execute("SELECT b FROM examples.blobs WHERE k = 1").one(); + assert Bytes.toHexString(row.getBytes("b")).equals("0xffffff"); + + buffer.flip(); + + // HOWEVER duplicate() only performs a shallow copy. The two buffers still share the same contents. So if you + // modify the contents of the original buffer, this will affect another execution of the bound statement. + buffer.put(0, (byte) 0xaa); + session.execute(boundStatement); + row = session.execute("SELECT b FROM examples.blobs WHERE k = 1").one(); + assert Bytes.toHexString(row.getBytes("b")).equals("0xaaffff"); + + // This will also happen if you use the async API, e.g. create the bound statement, call executeAsync() on it + // and reuse the buffer immediately. + + // If you reuse buffers concurrently and want to avoid those issues, perform a deep copy of the buffer before + // passing it to the bound statement. + int startPosition = buffer.position(); + ByteBuffer buffer2 = ByteBuffer.allocate(buffer.limit() - startPosition); + buffer2.put(buffer); + buffer.position(startPosition); + buffer2.flip(); + boundStatement.setBytes("b", buffer2); + session.execute(boundStatement); + + // Note: unlike BoundStatement, SimpleStatement does not duplicate its arguments, so even the position will be + // affected if you change it before executing the statement. Again, resort to deep copies if required. + } + + private static void insertFromAndRetrieveToFile(Session session) throws IOException { + ByteBuffer buffer = readAll(FILE); + session.execute("INSERT INTO examples.blobs (k, b) VALUES (1, ?)", buffer); + + File tmpFile = File.createTempFile("blob", ".png"); + System.out.printf("Writing retrieved buffer to %s%n", tmpFile.getAbsoluteFile()); + + Row row = session.execute("SELECT b FROM examples.blobs WHERE k = 1").one(); + writeAll(row.getBytes("b"), tmpFile); + } + + // Note: + // - this is written with Java 6 APIs; if you're on a more recent version this can be improved (try-with-resources, + // new-new io...) + // - this reads the whole file in memory in one go. If your file does not fit in memory you should probably not + // insert it into Cassandra either ;) + private static ByteBuffer readAll(File file) throws IOException { + FileInputStream inputStream = null; + boolean threw = false; + try { + inputStream = new FileInputStream(file); + FileChannel channel = inputStream.getChannel(); + ByteBuffer buffer = ByteBuffer.allocate((int) channel.size()); + channel.read(buffer); + buffer.flip(); + return buffer; + } catch (IOException e) { + threw = true; + throw e; + } finally { + close(inputStream, threw); + } + } + + private static void writeAll(ByteBuffer buffer, File file) throws IOException { + FileOutputStream outputStream = null; + boolean threw = false; + try { + outputStream = new FileOutputStream(file); + FileChannel channel = outputStream.getChannel(); + channel.write(buffer); + } catch (IOException e) { + threw = true; + throw e; + } finally { + close(outputStream, threw); + } + } + + private static void close(Closeable inputStream, boolean threw) throws IOException { + if (inputStream != null) + try { + inputStream.close(); + } catch (IOException e) { + if (!threw) throw e; // else preserve original exception + } + } +} diff --git a/driver-examples/src/main/resources/cassandra_logo.png b/driver-examples/src/main/resources/cassandra_logo.png new file mode 100644 index 00000000000..1637e61c14e Binary files /dev/null and b/driver-examples/src/main/resources/cassandra_logo.png differ diff --git a/driver-examples/src/main/resources/logback.xml b/driver-examples/src/main/resources/logback.xml new file mode 100644 index 00000000000..3fb2dcf5269 --- /dev/null +++ b/driver-examples/src/main/resources/logback.xml @@ -0,0 +1,39 @@ + + + + + + + + %-5level - %msg%n + + + + + + + + + + + + diff --git a/driver-examples/osgi/README.md b/driver-tests/osgi/README.md similarity index 86% rename from driver-examples/osgi/README.md rename to driver-tests/osgi/README.md index ed9530d380e..0a4d698eb3d 100644 --- a/driver-examples/osgi/README.md +++ b/driver-tests/osgi/README.md @@ -1,7 +1,6 @@ # OSGi Example -A simple example application that demonstrates using the Java Driver in -an OSGi service. +A simple test for the Java Driver in an OSGi environment. `MailboxService` is an OSGi service that uses Cassandra to store messages that can be retrieved by email address. @@ -25,7 +24,7 @@ Once `mvn verify` completes, the bundle jar will be present in the `target/` dir The project includes integration tests that verify the service can be activated and used in an OSGi container. It also verifies that -driver-core can be used in an OSGi container in the following +the Java driver can be used in an OSGi container in the following configurations: 1. Default (default classifier with all dependencies) diff --git a/driver-examples/osgi/pom.xml b/driver-tests/osgi/pom.xml similarity index 97% rename from driver-examples/osgi/pom.xml rename to driver-tests/osgi/pom.xml index 707103caff4..d132e8a791a 100644 --- a/driver-examples/osgi/pom.xml +++ b/driver-tests/osgi/pom.xml @@ -20,14 +20,14 @@ 4.0.0 com.datastax.cassandra - cassandra-driver-examples-parent + cassandra-driver-tests-parent 3.0.1-SNAPSHOT - cassandra-driver-examples-osgi + cassandra-driver-tests-osgi bundle - DataStax Java Driver for Apache Cassandra Examples - OSGi - An example of using DataStax Java Driver in an OSGi container. + DataStax Java Driver for Apache Cassandra Tests - OSGi + A test for the DataStax Java Driver in an OSGi container. https://github.com/datastax/java-driver diff --git a/driver-examples/osgi/src/main/java/com/datastax/driver/osgi/api/MailboxException.java b/driver-tests/osgi/src/main/java/com/datastax/driver/osgi/api/MailboxException.java similarity index 100% rename from driver-examples/osgi/src/main/java/com/datastax/driver/osgi/api/MailboxException.java rename to driver-tests/osgi/src/main/java/com/datastax/driver/osgi/api/MailboxException.java diff --git a/driver-examples/osgi/src/main/java/com/datastax/driver/osgi/api/MailboxMessage.java b/driver-tests/osgi/src/main/java/com/datastax/driver/osgi/api/MailboxMessage.java similarity index 100% rename from driver-examples/osgi/src/main/java/com/datastax/driver/osgi/api/MailboxMessage.java rename to driver-tests/osgi/src/main/java/com/datastax/driver/osgi/api/MailboxMessage.java diff --git a/driver-examples/osgi/src/main/java/com/datastax/driver/osgi/api/MailboxService.java b/driver-tests/osgi/src/main/java/com/datastax/driver/osgi/api/MailboxService.java similarity index 100% rename from driver-examples/osgi/src/main/java/com/datastax/driver/osgi/api/MailboxService.java rename to driver-tests/osgi/src/main/java/com/datastax/driver/osgi/api/MailboxService.java diff --git a/driver-examples/osgi/src/main/java/com/datastax/driver/osgi/impl/Activator.java b/driver-tests/osgi/src/main/java/com/datastax/driver/osgi/impl/Activator.java similarity index 100% rename from driver-examples/osgi/src/main/java/com/datastax/driver/osgi/impl/Activator.java rename to driver-tests/osgi/src/main/java/com/datastax/driver/osgi/impl/Activator.java diff --git a/driver-examples/osgi/src/main/java/com/datastax/driver/osgi/impl/MailboxImpl.java b/driver-tests/osgi/src/main/java/com/datastax/driver/osgi/impl/MailboxImpl.java similarity index 100% rename from driver-examples/osgi/src/main/java/com/datastax/driver/osgi/impl/MailboxImpl.java rename to driver-tests/osgi/src/main/java/com/datastax/driver/osgi/impl/MailboxImpl.java diff --git a/driver-examples/osgi/src/test/java/com/datastax/driver/osgi/BundleOptions.java b/driver-tests/osgi/src/test/java/com/datastax/driver/osgi/BundleOptions.java similarity index 100% rename from driver-examples/osgi/src/test/java/com/datastax/driver/osgi/BundleOptions.java rename to driver-tests/osgi/src/test/java/com/datastax/driver/osgi/BundleOptions.java diff --git a/driver-examples/osgi/src/test/java/com/datastax/driver/osgi/CCMBridgeListener.java b/driver-tests/osgi/src/test/java/com/datastax/driver/osgi/CCMBridgeListener.java similarity index 100% rename from driver-examples/osgi/src/test/java/com/datastax/driver/osgi/CCMBridgeListener.java rename to driver-tests/osgi/src/test/java/com/datastax/driver/osgi/CCMBridgeListener.java diff --git a/driver-examples/osgi/src/test/java/com/datastax/driver/osgi/MailboxServiceDefaultIT.java b/driver-tests/osgi/src/test/java/com/datastax/driver/osgi/MailboxServiceDefaultIT.java similarity index 100% rename from driver-examples/osgi/src/test/java/com/datastax/driver/osgi/MailboxServiceDefaultIT.java rename to driver-tests/osgi/src/test/java/com/datastax/driver/osgi/MailboxServiceDefaultIT.java diff --git a/driver-examples/osgi/src/test/java/com/datastax/driver/osgi/MailboxServiceGuava17IT.java b/driver-tests/osgi/src/test/java/com/datastax/driver/osgi/MailboxServiceGuava17IT.java similarity index 100% rename from driver-examples/osgi/src/test/java/com/datastax/driver/osgi/MailboxServiceGuava17IT.java rename to driver-tests/osgi/src/test/java/com/datastax/driver/osgi/MailboxServiceGuava17IT.java diff --git a/driver-examples/osgi/src/test/java/com/datastax/driver/osgi/MailboxServiceGuava18IT.java b/driver-tests/osgi/src/test/java/com/datastax/driver/osgi/MailboxServiceGuava18IT.java similarity index 100% rename from driver-examples/osgi/src/test/java/com/datastax/driver/osgi/MailboxServiceGuava18IT.java rename to driver-tests/osgi/src/test/java/com/datastax/driver/osgi/MailboxServiceGuava18IT.java diff --git a/driver-examples/osgi/src/test/java/com/datastax/driver/osgi/MailboxServiceGuava19IT.java b/driver-tests/osgi/src/test/java/com/datastax/driver/osgi/MailboxServiceGuava19IT.java similarity index 100% rename from driver-examples/osgi/src/test/java/com/datastax/driver/osgi/MailboxServiceGuava19IT.java rename to driver-tests/osgi/src/test/java/com/datastax/driver/osgi/MailboxServiceGuava19IT.java diff --git a/driver-examples/osgi/src/test/java/com/datastax/driver/osgi/MailboxServiceShadedIT.java b/driver-tests/osgi/src/test/java/com/datastax/driver/osgi/MailboxServiceShadedIT.java similarity index 100% rename from driver-examples/osgi/src/test/java/com/datastax/driver/osgi/MailboxServiceShadedIT.java rename to driver-tests/osgi/src/test/java/com/datastax/driver/osgi/MailboxServiceShadedIT.java diff --git a/driver-examples/osgi/src/test/java/com/datastax/driver/osgi/MailboxServiceTests.java b/driver-tests/osgi/src/test/java/com/datastax/driver/osgi/MailboxServiceTests.java similarity index 100% rename from driver-examples/osgi/src/test/java/com/datastax/driver/osgi/MailboxServiceTests.java rename to driver-tests/osgi/src/test/java/com/datastax/driver/osgi/MailboxServiceTests.java diff --git a/driver-examples/osgi/src/test/java/com/datastax/driver/osgi/VersionProvider.java b/driver-tests/osgi/src/test/java/com/datastax/driver/osgi/VersionProvider.java similarity index 100% rename from driver-examples/osgi/src/test/java/com/datastax/driver/osgi/VersionProvider.java rename to driver-tests/osgi/src/test/java/com/datastax/driver/osgi/VersionProvider.java diff --git a/driver-examples/osgi/src/test/resources/exam.properties b/driver-tests/osgi/src/test/resources/exam.properties similarity index 100% rename from driver-examples/osgi/src/test/resources/exam.properties rename to driver-tests/osgi/src/test/resources/exam.properties diff --git a/driver-examples/osgi/src/test/resources/logback.xml b/driver-tests/osgi/src/test/resources/logback.xml similarity index 100% rename from driver-examples/osgi/src/test/resources/logback.xml rename to driver-tests/osgi/src/test/resources/logback.xml diff --git a/driver-tests/pom.xml b/driver-tests/pom.xml new file mode 100644 index 00000000000..a8c65650b5d --- /dev/null +++ b/driver-tests/pom.xml @@ -0,0 +1,83 @@ + + + 4.0.0 + + com.datastax.cassandra + cassandra-driver-parent + 3.0.1-SNAPSHOT + + cassandra-driver-tests-parent + pom + DataStax Java Driver for Apache Cassandra Tests + Tests for the DataStax Java Driver for Apache Cassandra. + https://github.com/datastax/java-driver + + + ${project.parent.basedir} + + + + stress + osgi + + + + + Apache 2 + http://www.apache.org/licenses/LICENSE-2.0.txt + repo + Apache License Version 2.0 + + + + + scm:git:git@github.com:datastax/java-driver.git + scm:git:git@github.com:datastax/java-driver.git + https://github.com/datastax/java-driver + HEAD + + + + + Various + DataStax + + + + + + + org.apache.maven.plugins + maven-install-plugin + 2.5.1 + + true + + + + org.apache.maven.plugins + maven-deploy-plugin + 2.8.1 + + true + + + + + diff --git a/driver-examples/stress/README.md b/driver-tests/stress/README.md similarity index 77% rename from driver-examples/stress/README.md rename to driver-tests/stress/README.md index 6c946719ecc..ea0ea61bc88 100644 --- a/driver-examples/stress/README.md +++ b/driver-tests/stress/README.md @@ -1,11 +1,11 @@ # Stress application -A simple example application that uses the java driver to stress test -Cassandra. This also somewhat stress test the java driver as a result. +A simple example application that uses the Java driver to stress test +Cassandra. This also somewhat stress tests the Java driver as a result. Please note that this simple example is far from being a complete stress application. In particular it currently supports a very limited number of -stress scenario. +stress scenarios. ## Usage diff --git a/driver-examples/stress/bin/build b/driver-tests/stress/bin/build similarity index 100% rename from driver-examples/stress/bin/build rename to driver-tests/stress/bin/build diff --git a/driver-examples/stress/bin/stress b/driver-tests/stress/bin/stress similarity index 87% rename from driver-examples/stress/bin/stress rename to driver-tests/stress/bin/stress index 8a3165a47ce..e47ec0d7955 100755 --- a/driver-examples/stress/bin/stress +++ b/driver-tests/stress/bin/stress @@ -12,7 +12,7 @@ fi if [ "x$STRESS_JAR" = "x" ]; then - STRESS_JAR="$SCRIPT_DIR/../target/cassandra-driver-examples-stress-*-jar-with-dependencies.jar" + STRESS_JAR="$SCRIPT_DIR/../target/cassandra-driver-tests-stress-*-jar-with-dependencies.jar" if [ ! -f $STRESS_JAR ]; then # Trash the version file in case there was some crap in it diff --git a/driver-examples/stress/pom.xml b/driver-tests/stress/pom.xml similarity index 94% rename from driver-examples/stress/pom.xml rename to driver-tests/stress/pom.xml index edc9fe3e95f..97083ac6b6e 100644 --- a/driver-examples/stress/pom.xml +++ b/driver-tests/stress/pom.xml @@ -19,12 +19,12 @@ 4.0.0 com.datastax.cassandra - cassandra-driver-examples-parent + cassandra-driver-tests-parent 3.0.1-SNAPSHOT - cassandra-driver-examples-stress + cassandra-driver-tests-stress jar - DataStax Java Driver for Apache Cassandra Examples - Stress + DataStax Java Driver for Apache Cassandra Tests - Stress A stress test example for DataStax Java Driver for Apache Cassandra. https://github.com/datastax/java-driver diff --git a/driver-examples/stress/src/main/java/com/datastax/driver/stress/AsynchronousConsumer.java b/driver-tests/stress/src/main/java/com/datastax/driver/stress/AsynchronousConsumer.java similarity index 100% rename from driver-examples/stress/src/main/java/com/datastax/driver/stress/AsynchronousConsumer.java rename to driver-tests/stress/src/main/java/com/datastax/driver/stress/AsynchronousConsumer.java diff --git a/driver-examples/stress/src/main/java/com/datastax/driver/stress/BlockingConsumer.java b/driver-tests/stress/src/main/java/com/datastax/driver/stress/BlockingConsumer.java similarity index 100% rename from driver-examples/stress/src/main/java/com/datastax/driver/stress/BlockingConsumer.java rename to driver-tests/stress/src/main/java/com/datastax/driver/stress/BlockingConsumer.java diff --git a/driver-examples/stress/src/main/java/com/datastax/driver/stress/ConsistencyLevelConverter.java b/driver-tests/stress/src/main/java/com/datastax/driver/stress/ConsistencyLevelConverter.java similarity index 100% rename from driver-examples/stress/src/main/java/com/datastax/driver/stress/ConsistencyLevelConverter.java rename to driver-tests/stress/src/main/java/com/datastax/driver/stress/ConsistencyLevelConverter.java diff --git a/driver-examples/stress/src/main/java/com/datastax/driver/stress/Consumer.java b/driver-tests/stress/src/main/java/com/datastax/driver/stress/Consumer.java similarity index 100% rename from driver-examples/stress/src/main/java/com/datastax/driver/stress/Consumer.java rename to driver-tests/stress/src/main/java/com/datastax/driver/stress/Consumer.java diff --git a/driver-examples/stress/src/main/java/com/datastax/driver/stress/Generators.java b/driver-tests/stress/src/main/java/com/datastax/driver/stress/Generators.java similarity index 100% rename from driver-examples/stress/src/main/java/com/datastax/driver/stress/Generators.java rename to driver-tests/stress/src/main/java/com/datastax/driver/stress/Generators.java diff --git a/driver-examples/stress/src/main/java/com/datastax/driver/stress/QueryGenerator.java b/driver-tests/stress/src/main/java/com/datastax/driver/stress/QueryGenerator.java similarity index 100% rename from driver-examples/stress/src/main/java/com/datastax/driver/stress/QueryGenerator.java rename to driver-tests/stress/src/main/java/com/datastax/driver/stress/QueryGenerator.java diff --git a/driver-examples/stress/src/main/java/com/datastax/driver/stress/Reporter.java b/driver-tests/stress/src/main/java/com/datastax/driver/stress/Reporter.java similarity index 100% rename from driver-examples/stress/src/main/java/com/datastax/driver/stress/Reporter.java rename to driver-tests/stress/src/main/java/com/datastax/driver/stress/Reporter.java diff --git a/driver-examples/stress/src/main/java/com/datastax/driver/stress/Stress.java b/driver-tests/stress/src/main/java/com/datastax/driver/stress/Stress.java similarity index 100% rename from driver-examples/stress/src/main/java/com/datastax/driver/stress/Stress.java rename to driver-tests/stress/src/main/java/com/datastax/driver/stress/Stress.java diff --git a/faq/README.md b/faq/README.md index 57a8603485a..0f92ec4fe58 100644 --- a/faq/README.md +++ b/faq/README.md @@ -11,6 +11,7 @@ Native protocol v1 does not support paging, but you can emulate it in CQL with `LIMIT` and the `token()` function. See [this conversation](https://groups.google.com/a/lists.datastax.com/d/msg/java-driver-user/U2KzAHruWO4/6vDmUVDDkOwJ) on the mailing list. + ### Can I check if a conditional statement (lightweight transaction) was successful? When executing a conditional statement, the `ResultSet` will contain a single `Row` with a @@ -36,6 +37,7 @@ Note that, unlike manual inspection, `wasApplied` does not consume the first row [wasApplied]: http://docs.datastax.com/en/drivers/java/2.1/com/datastax/driver/core/ResultSet.html#wasApplied-- + ### What is a parameterized statement and how can I use it? Starting with Cassandra 2.0, normal statements (that is non-prepared statements) do @@ -49,12 +51,14 @@ session.execute( "INSERT INTO contacts (email, firstname, lastname) See [Simple statements](../manual/statements/simple/) for more information. + ### Does a parameterized statement escape parameters? A parameterized statement sends the values of parameters separate from the query (similar to the way a prepared statement does) as bytes so there is no need to escape parameters. + ### What's the difference between a parameterized statement and a Prepared statement? The only similarity between a parameterized statement and a prepared statement is in @@ -67,6 +71,7 @@ the way that the parameters are sent. The difference is that a prepared statemen See [Prepared statements](../manual/statements/prepared/) for more information. + ### Can I combine `PreparedStatements` and normal statements in a batch? Yes. A batch can include both bound statements and simple statements: @@ -82,6 +87,7 @@ batch.add(new SimpleStatement( "INSERT INTO contacts (email, firstname, lastname session.execute(batch); ``` + ### Can I get the raw bytes of a text column? If you need to access the raw bytes of a text column, call the @@ -90,6 +96,7 @@ If you need to access the raw bytes of a text column, call the Trying to use `Row.getBytes("columnName")` for the same purpose results in an exception, as the `getBytes` method can only be used if the column has the CQL type `BLOB`. + ### How do I increment counters with `QueryBuilder`? Considering the following query: @@ -106,6 +113,7 @@ Statement query = QueryBuilder.update("clickstream") .where(eq("userid", id)); ``` + ### Is there a way to control the batch size of the results returned from a query? Use the `setFetchSize()` method on your `Statement` object. The fetch size controls @@ -118,6 +126,7 @@ only affects what is retrieved at a time, not the overall number of rows. See [Paging](../manual/paging/) for more information. + ### What's the difference between using `setFetchSize()` and `LIMIT`? Basically, `LIMIT` controls the maximum number of results returned by the query, @@ -128,3 +137,13 @@ For example, if you limit is 30 and your fetch size is 10, the `ResultSet` will rows each. See [Paging](../manual/paging/) for more information. + + +### I'm reading a BLOB column and the driver returns incorrect data. + +Check your code to ensure that you read the returned `ByteBuffer` correctly. `ByteBuffer` is a very error-prone API, +and we've had many reports where the problem turned out to be in user code. + +See [Blobs.java] in the `driver-examples` module for some examples and explanations. + +[Blobs.java]: https://github.com/datastax/java-driver/tree/3.0.x/driver-examples/src/main/java/com/datastax/driver/examples/datatypes/Blobs.java \ No newline at end of file diff --git a/pom.xml b/pom.xml index d60f5f61253..07d819ede40 100644 --- a/pom.xml +++ b/pom.xml @@ -41,6 +41,7 @@ driver-mapping driver-extras driver-examples + driver-tests driver-dist