Skip to content

Commit c08267d

Browse files
clunclun
committed
javadocs, javadoc, javadoc...46 to go
1 parent b366490 commit c08267d

26 files changed

+575
-99
lines changed

‎astra-db-java/src/main/java/com/datastax/astra/client/DataAPIClient.java

Lines changed: 16 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -242,8 +242,10 @@ public DataAPIClient(DataAPIClientOptions options) {
242242
* }
243243
* </pre>
244244
*
245+
* @param adminOptions
246+
* The options to configure the administration client, including the authentication token.
245247
* @return An instance of {@link AstraDBAdmin} configured with the appropriate authentication token and options,
246-
* ready for administrative operations.
248+
* ready for administrative operations.
247249
*/
248250
public AstraDBAdmin getAdmin(AdminOptions adminOptions) {
249251
if (!options.isAstra()) {
@@ -319,12 +321,25 @@ public AstraDBAdmin getAdmin(String superToken) {
319321
* @return A {@link Database} client tailored for interaction with the Data API, configured according to the
320322
* provided parameters.
321323
*
324+
* @param apiEndpoint The URL of the Data API endpoint to connect to.
325+
* @param dbOptions The options to configure the database client.
322326
* @throws IllegalArgumentException If the provided parameters are invalid or insufficient for resolving the endpoint.
323327
*/
324328
public Database getDatabase(String apiEndpoint, DatabaseOptions dbOptions) {
325329
return new Database(apiEndpoint, dbOptions);
326330
}
327331

332+
/**
333+
* Retrieves a database client configured to connect to the Data API using the specified API endpoint and keyspace.
334+
* <p>
335+
* Uses default {@link DatabaseOptions} for configuration.
336+
* </p>
337+
*
338+
* @param apiEndpoint The URL of the Data API endpoint to connect to.
339+
* @param keyspace The name of the keyspace to use for database operations.
340+
* @return A {@link Database} client configured with default options for the specified endpoint and keyspace.
341+
* @see #getDatabase(String, DatabaseOptions)
342+
*/
328343
public Database getDatabase(String apiEndpoint, String keyspace) {
329344
DatabaseOptions dbOptions = new DatabaseOptions(token, options).keyspace(keyspace);
330345
return new Database(apiEndpoint, dbOptions);

‎astra-db-java/src/main/java/com/datastax/astra/client/DataAPIClients.java

Lines changed: 85 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -94,6 +94,35 @@ public static DataAPIClient clientCassandra() {
9494
UsernamePasswordTokenProvider.DEFAULT_CREDENTIALS);
9595
}
9696

97+
/**
98+
* Creates and configures a {@link DataAPIClient} for interaction with a local instance of DataAPI,
99+
* a data gateway that facilitates working with Apache Cassandra®. This method is tailored for
100+
* development and testing workflows, enabling simplified and efficient access to local database
101+
* resources without the need for extensive configuration.
102+
*
103+
* <p>The returned {@link DataAPIClient} is preconfigured with:
104+
* <ul>
105+
* <li>An authentication token from {@link UsernamePasswordTokenProvider}.</li>
106+
* <li>A destination set to {@code DataAPIDestination.CASSANDRA}.</li>
107+
* <li>Feature flags for tables enabled.</li>
108+
* <li>Request logging enabled.</li>
109+
* </ul>
110+
*
111+
* @param username The username for authenticating with the Data API. This username should have the necessary
112+
* permissions to access the local Data API instance.
113+
* @param password The password for authenticating with the Data API. This password should be kept secure and
114+
* protected from unauthorized access.
115+
* @return A fully configured {@link DataAPIClient} ready for interacting with the local DataAPI instance.
116+
* This client provides a streamlined interface for executing data operations, abstracting away
117+
* the complexity of direct database interactions.
118+
*
119+
* <p>Example usage:</p>
120+
* <pre>
121+
* {@code
122+
* DataAPIClient client = DataAPIClients.local("username", "password");
123+
* }
124+
* </pre>
125+
*/
97126
public static DataAPIClient clientCassandra(String username, String password) {
98127
return new DataAPIClient(
99128
new UsernamePasswordTokenProvider(username, password).getToken(),
@@ -103,12 +132,68 @@ public static DataAPIClient clientCassandra(String username, String password) {
103132
.logRequests());
104133
}
105134

135+
/**
136+
* Creates and configures a {@link DataAPIClient} specifically designed for interaction with a local instance
137+
* of the Data API and Cassandra. This method simplifies the setup process by combining the creation of a {@link DataAPIClient}
138+
* with the integration of a {@link Database} abstraction. It is tailored for local development and testing,
139+
* enabling seamless interaction with Apache Cassandra® through Stargate with minimal configuration.
140+
*
141+
* <p>Upon creation, this method ensures that a default keyspace is available in the local Stargate instance
142+
* by automatically invoking {@link com.datastax.astra.client.admin.DatabaseAdmin#createKeyspace(String)}. This guarantees that developers
143+
* have a ready-to-use environment for executing database operations during their development or testing workflows.
144+
*
145+
* <p>The returned {@link Database} client is preconfigured with:
146+
* <ul>
147+
* <li>A connection to the default local Stargate endpoint.</li>
148+
* <li>An automatically created keyspace, identified by {@code DEFAULT_KEYSPACE}.</li>
149+
* </ul>
150+
* This setup allows developers to focus on application logic rather than database configuration or connectivity.
151+
*
152+
* @return A {@link Database} client configured for use with a local Stargate instance, including a default
153+
* keyspace for immediate interaction. This client abstracts database connectivity and administrative tasks,
154+
* streamlining development workflows.
155+
*
156+
* <p>Example usage:</p>
157+
* <pre>
158+
* {@code
159+
* Database db = localDbWithDefaultKeyspace();
160+
* }
161+
* </pre>
162+
*/
106163
public static DataAPIClient clientHCD() {
107164
return clientHCD(
108165
UsernamePasswordTokenProvider.DEFAULT_USERNAME,
109166
UsernamePasswordTokenProvider.DEFAULT_CREDENTIALS);
110167
}
111168

169+
/**
170+
* Creates and configures a {@link DataAPIClient} specifically designed for interaction with a local instance
171+
* of the Data API and Cassandra. This method simplifies the setup process by combining the creation of a {@link DataAPIClient}
172+
* with the integration of a {@link Database} abstraction. It is tailored for local development and testing,
173+
* enabling seamless interaction with Apache Cassandra® through Stargate with minimal configuration.
174+
*
175+
* <p>Upon creation, this method ensures that a default keyspace is available in the local Stargate instance
176+
* by automatically invoking {@link com.datastax.astra.client.admin.DatabaseAdmin#createKeyspace(String)}. This guarantees that developers
177+
* have a ready-to-use environment for executing database operations during their development or testing workflows.
178+
*
179+
* <p>The returned {@link Database} client is preconfigured with:
180+
* <ul>
181+
* <li>A connection to the default local Stargate endpoint.</li>
182+
* <li>An automatically created keyspace, identified by {@code DEFAULT_KEYSPACE}.</li>
183+
* </ul>
184+
* This setup allows developers to focus on application logic rather than database configuration or connectivity.
185+
*
186+
* @return A {@link Database} client configured for use with a local Stargate instance, including a default
187+
* keyspace for immediate interaction. This client abstracts database connectivity and administrative tasks,
188+
* streamlining development workflows.
189+
*
190+
* <p>Example usage:</p>
191+
* <pre>
192+
* {@code
193+
* Database db = localDbWithDefaultKeyspace();
194+
* }
195+
* </pre>
196+
*/
112197
public static DataAPIClient clientHCD(String username, String password) {
113198
return new DataAPIClient(
114199
new UsernamePasswordTokenProvider(username, password).getToken(),
@@ -204,8 +289,6 @@ public static DataAPIClient astra(String token) {
204289
.logRequests());
205290
}
206291

207-
208-
209292
/**
210293
* Creates a {@link DataAPIClient} specifically configured for interacting with Astra in a test environment.
211294
* This method is designed for testing scenarios, providing an isolated environment to safely execute

‎astra-db-java/src/main/java/com/datastax/astra/client/collections/definition/documents/Document.java

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -83,11 +83,25 @@ public Document() {
8383
documentMap = new LinkedHashMap<>();
8484
}
8585

86+
/**
87+
* Getter for the document map.
88+
*
89+
* @return
90+
* document map
91+
*/
8692
@JsonAnyGetter
8793
public Map<String, Object> getDocumentMap() {
8894
return documentMap;
8995
}
9096

97+
/**
98+
* Setter for a property in the document map
99+
*
100+
* @param key
101+
* property name
102+
* @param value
103+
* property value
104+
*/
91105
@JsonAnySetter
92106
public void setProperty(String key, Object value) {
93107
documentMap.put(key, value);

‎astra-db-java/src/main/java/com/datastax/astra/client/core/options/DataAPIClientOptions.java

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -356,10 +356,20 @@ public DataAPIClientOptions addAdminAdditionalHeader(String key, String value) {
356356
return this;
357357
}
358358

359+
/**
360+
* Enable the feature flag tables.
361+
*
362+
* @return self reference
363+
*/
359364
public DataAPIClientOptions enableFeatureFlagTables() {
360365
return addDatabaseAdditionalHeader(HEADER_FEATURE_FLAG_TABLES, "true");
361366
}
362367

368+
/**
369+
* Disable the feature flag tables.
370+
*
371+
* @return self reference
372+
*/
363373
public DataAPIClientOptions disableFeatureFlagTables() {
364374
return addDatabaseAdditionalHeader(HEADER_FEATURE_FLAG_TABLES, null);
365375
}
@@ -368,6 +378,9 @@ public DataAPIClientOptions disableFeatureFlagTables() {
368378
// ---------- JAVA DEFAULTS -----------------
369379
// --------------------------------------------
370380

381+
/**
382+
* {@inheritDoc}
383+
*/
371384
@Override
372385
public String toString() {
373386
return new DatabaseSerializer().marshall(this);
@@ -380,6 +393,11 @@ public DataAPIClientOptions() {
380393
// defaulting values
381394
}
382395

396+
/**
397+
* Copy constructor.
398+
*
399+
* @param options options to copy
400+
*/
383401
public DataAPIClientOptions(DataAPIClientOptions options) {
384402
Assert.notNull(options, "Options");
385403
this.apiVersion = options.apiVersion;
@@ -401,6 +419,9 @@ public DataAPIClientOptions(DataAPIClientOptions options) {
401419
options.serdesOptions.clone() : null;
402420
}
403421

422+
/**
423+
* {@inheritDoc}
424+
*/
404425
@Override
405426
public DataAPIClientOptions clone() {
406427
return new DataAPIClientOptions(this);

‎astra-db-java/src/main/java/com/datastax/astra/client/core/options/TimeoutOptions.java

Lines changed: 83 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -31,16 +31,42 @@
3131
* This class is used to define the timeout options for the client.
3232
*/
3333
@Setter
34-
@NoArgsConstructor
3534
@Accessors(fluent = true, chain = true)
3635
public class TimeoutOptions implements Cloneable {
3736

37+
/**
38+
* Default timeout values
39+
*/
3840
public static final long DEFAULT_CONNECT_TIMEOUT_MILLIS = 10000L;
41+
42+
/**
43+
* Default timeout values
44+
*/
3945
public static final long DEFAULT_REQUEST_TIMEOUT_MILLIS = 10000L;
46+
47+
/**
48+
* Default timeout values
49+
*/
4050
public static final long DEFAULT_GENERAL_METHOD_TIMEOUT_MILLIS = 30000L;
51+
52+
/**
53+
* Default timeout values
54+
*/
4155
public static final long DEFAULT_COLLECTION_ADMIN_TIMEOUT_MILLIS = 60000L;
56+
57+
/**
58+
* Default timeout values
59+
*/
4260
public static final long DEFAULT_TABLE_ADMIN_TIMEOUT_MILLIS = 30000L;
61+
62+
/**
63+
* Default timeout values
64+
*/
4365
public static final long DEFAULT_DATABASE_ADMIN_TIMEOUT_MILLIS = 600000L;
66+
67+
/**
68+
* Default timeout values
69+
*/
4470
public static final long DEFAULT_KEYSPACE_ADMIN_TIMEOUT_MILLIS = 30000L;
4571

4672
/**
@@ -78,6 +104,12 @@ public class TimeoutOptions implements Cloneable {
78104
*/
79105
long tableAdminTimeoutMillis = DEFAULT_TABLE_ADMIN_TIMEOUT_MILLIS;
80106

107+
/**
108+
* Default constructor
109+
*/
110+
public TimeoutOptions() {}
111+
112+
/** {@inheritDoc} */
81113
@Override
82114
public TimeoutOptions clone() {
83115
try {
@@ -87,42 +119,92 @@ public TimeoutOptions clone() {
87119
}
88120
}
89121

122+
123+
/**
124+
* Sets the connection timeout.
125+
*
126+
* @param timeout the connection timeout, must not be {@code null}
127+
* @return the current {@code TimeoutOptions} instance for method chaining
128+
* @throws IllegalArgumentException if {@code timeout} is {@code null}
129+
*/
90130
public TimeoutOptions connectTimeout(Duration timeout) {
91131
Assert.notNull(timeout, "Timeout");
92132
this.connectTimeoutMillis = timeout.toMillis();
93133
return this;
94134
}
95135

136+
/**
137+
* Sets the request timeout.
138+
*
139+
* @param timeout the request timeout, must not be {@code null}
140+
* @return the current {@code TimeoutOptions} instance for method chaining
141+
* @throws IllegalArgumentException if {@code timeout} is {@code null}
142+
*/
96143
public TimeoutOptions requestTimeout(Duration timeout) {
97144
Assert.notNull(timeout, "Timeout");
98145
this.requestTimeoutMillis = timeout.toMillis();
99146
return this;
100147
}
101148

149+
/**
150+
* Sets the general method timeout.
151+
*
152+
* @param timeout the timeout for general methods, must not be {@code null}
153+
* @return the current {@code TimeoutOptions} instance for method chaining
154+
* @throws IllegalArgumentException if {@code timeout} is {@code null}
155+
*/
102156
public TimeoutOptions generalMethodTimeout(Duration timeout) {
103157
Assert.notNull(timeout, "Timeout");
104158
this.generalMethodTimeoutMillis = timeout.toMillis();
105159
return this;
106160
}
107161

162+
/**
163+
* Sets the timeout for database administration operations.
164+
*
165+
* @param timeout the database admin timeout, must not be {@code null}
166+
* @return the current {@code TimeoutOptions} instance for method chaining
167+
* @throws IllegalArgumentException if {@code timeout} is {@code null}
168+
*/
108169
public TimeoutOptions databaseAdminTimeout(Duration timeout) {
109170
Assert.notNull(timeout, "Timeout");
110171
this.databaseAdminTimeoutMillis = timeout.toMillis();
111172
return this;
112173
}
113174

175+
/**
176+
* Sets the timeout for keyspace administration operations.
177+
*
178+
* @param timeout the keyspace admin timeout, must not be {@code null}
179+
* @return the current {@code TimeoutOptions} instance for method chaining
180+
* @throws IllegalArgumentException if {@code timeout} is {@code null}
181+
*/
114182
public TimeoutOptions keyspaceAdminTimeout(Duration timeout) {
115183
Assert.notNull(timeout, "Timeout");
116184
this.keyspaceAdminTimeoutMillis = timeout.toMillis();
117185
return this;
118186
}
119187

188+
/**
189+
* Sets the timeout for collection administration operations.
190+
*
191+
* @param timeout the collection admin timeout, must not be {@code null}
192+
* @return the current {@code TimeoutOptions} instance for method chaining
193+
* @throws IllegalArgumentException if {@code timeout} is {@code null}
194+
*/
120195
public TimeoutOptions collectionAdminTimeout(Duration timeout) {
121196
Assert.notNull(timeout, "Timeout");
122197
this.collectionAdminTimeoutMillis = timeout.toMillis();
123198
return this;
124199
}
125200

201+
/**
202+
* Sets the timeout for table administration operations.
203+
*
204+
* @param timeout the table admin timeout, must not be {@code null}
205+
* @return the current {@code TimeoutOptions} instance for method chaining
206+
* @throws IllegalArgumentException if {@code timeout} is {@code null}
207+
*/
126208
public TimeoutOptions tableAdminTimeout(Duration timeout) {
127209
Assert.notNull(timeout, "Timeout");
128210
this.tableAdminTimeoutMillis = timeout.toMillis();

0 commit comments

Comments
 (0)