This is an automated email from the ASF dual-hosted git repository.
ptupitsyn pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/ignite-3.git
The following commit(s) were added to refs/heads/main by this push:
new 720d316f9c IGNITE-22267 Improve Table API javadocs (#4242)
720d316f9c is described below
commit 720d316f9c365236d7658c600d1565dc53c47b45
Author: Mirza Aliev <[email protected]>
AuthorDate: Fri Aug 16 19:23:05 2024 +0400
IGNITE-22267 Improve Table API javadocs (#4242)
1. Remove "started table" term, "table" is enough
2. Remove "binary object" mentions
3. Explain how KV view projects row data into key-value pairs
4. Replace "Transaction or null to auto-commit" with "Transaction or null
for implicit transaction"
5. Remove "@throws IgniteException If an unspecified platform exception has
occurred internally", it is not useful
6. Describe the order of tables in tables() and tablesAsync()
---------
Co-authored-by: Pavel Tupitsyn <[email protected]>
---
.../java/org/apache/ignite/table/IgniteTables.java | 21 +-----
.../java/org/apache/ignite/table/KeyValueView.java | 74 +++++++++++-----------
.../java/org/apache/ignite/table/RecordView.java | 68 ++++++++++----------
.../main/java/org/apache/ignite/table/Table.java | 24 ++++---
.../ignite/internal/table/InternalTable.java | 2 +-
5 files changed, 88 insertions(+), 101 deletions(-)
diff --git
a/modules/api/src/main/java/org/apache/ignite/table/IgniteTables.java
b/modules/api/src/main/java/org/apache/ignite/table/IgniteTables.java
index a2c15f2175..e7c71aa4ec 100644
--- a/modules/api/src/main/java/org/apache/ignite/table/IgniteTables.java
+++ b/modules/api/src/main/java/org/apache/ignite/table/IgniteTables.java
@@ -19,31 +19,22 @@ package org.apache.ignite.table;
import java.util.List;
import java.util.concurrent.CompletableFuture;
-import org.apache.ignite.lang.IgniteException;
/**
* Interface that provides methods for managing tables.
*/
public interface IgniteTables {
/**
- * Gets a list of all started tables.
+ * Gets a list of all tables. The order of tables in the returned list is
not defined.
*
* @return List of tables.
- * @throws IgniteException If an unspecified platform exception has
occurred internally. Is thrown when:
- * <ul>
- * <li>the node is stopping.</li>
- * </ul>
*/
List<Table> tables();
/**
- * Gets a list of all started tables.
+ * Gets a list of all tables. The order of tables in the returned list is
not defined.
*
* @return Future that represents the pending completion of the operation.
- * @throws IgniteException If an unspecified platform exception has
occurred internally. Is thrown when:
- * <ul>
- * <li>the node is stopping.</li>
- * </ul>
*/
CompletableFuture<List<Table>> tablesAsync();
@@ -53,10 +44,6 @@ public interface IgniteTables {
* @param name Name of the table with SQL-parser style quotation, e.g.
* "tbl0" - the table "TBL0" will be looked up, "\"Tbl0\"" -
"Tbl0", etc.
* @return Table identified by name or {@code null} if table doesn't exist.
- * @throws IgniteException If an unspecified platform exception has
occurred internally. Is thrown when:
- * <ul>
- * <li>the node is stopping.</li>
- * </ul>
*/
Table table(String name);
@@ -66,10 +53,6 @@ public interface IgniteTables {
* @param name Name of the table with SQL-parser style quotation, e.g.
* "tbl0" - the table "TBL0" will be looked up, "\"Tbl0\"" -
"Tbl0", etc.
* @return Future that represents the pending completion of the operation.
- * @throws IgniteException If an unspecified platform exception has
occurred internally. Is thrown when:
- * <ul>
- * <li>the node is stopping.</li>
- * </ul>
*/
CompletableFuture<Table> tableAsync(String name);
}
diff --git
a/modules/api/src/main/java/org/apache/ignite/table/KeyValueView.java
b/modules/api/src/main/java/org/apache/ignite/table/KeyValueView.java
index c3940e2752..33a485c1c7 100644
--- a/modules/api/src/main/java/org/apache/ignite/table/KeyValueView.java
+++ b/modules/api/src/main/java/org/apache/ignite/table/KeyValueView.java
@@ -43,7 +43,7 @@ public interface KeyValueView<K, V> extends
DataStreamerTarget<Entry<K, V>>, Cri
* <p>Note: If the value mapper implies a value can be {@code null}, a
suitable method
* {@link #getNullable(Transaction, Object)} must be used.
*
- * @param tx Transaction or {@code null} to auto-commit.
+ * @param tx Transaction or {@code null} for implicit transaction.
* @param key Key whose value is to be returned. The key cannot be {@code
null}.
* @return Value or {@code null}, if it does not exist.
* @throws MarshallerException if the key doesn't match the schema.
@@ -58,7 +58,7 @@ public interface KeyValueView<K, V> extends
DataStreamerTarget<Entry<K, V>>, Cri
* <p>Note: If the value mapper implies a value can be {@code null}, a
suitable method
* {@link #getNullableAsync(Transaction, Object)} must be used.
*
- * @param tx Transaction or {@code null} to auto-commit.
+ * @param tx Transaction or {@code null} for implicit transaction.
* @param key Key whose value is to be returned. The key cannot be {@code
null}.
* @return Future that represents the pending completion of the operation.
* @throws MarshallerException if the key doesn't match the schema.
@@ -84,7 +84,7 @@ public interface KeyValueView<K, V> extends
DataStreamerTarget<Entry<K, V>>, Cri
/**
* Gets a nullable value associated with a given key.
*
- * @param tx Transaction or {@code null} to auto-commit.
+ * @param tx Transaction or {@code null} for implicit transaction.
* @param key Key whose value is to be returned. The key cannot be {@code
null}.
* @return Future that represents the pending completion of the operation.
* The future returns wrapped nullable value or {@code null} if the
row with the given key does not exist.
@@ -96,7 +96,7 @@ public interface KeyValueView<K, V> extends
DataStreamerTarget<Entry<K, V>>, Cri
/**
* Gets a value associated with a given key, if it exists and is not null,
otherwise returns {@code defaultValue}.
*
- * @param tx Transaction or {@code null} to auto-commit.
+ * @param tx Transaction or {@code null} for implicit transaction.
* @param key Key whose value is to be returned. The key cannot be {@code
null}.
* @param defaultValue Default value.
* @return Value or {@code defaultValue} if does not exist.
@@ -107,7 +107,7 @@ public interface KeyValueView<K, V> extends
DataStreamerTarget<Entry<K, V>>, Cri
/**
* Gets a value associated with a given key, if it exists and is not null,
otherwise returns {@code defaultValue}.
*
- * @param tx Transaction or {@code null} to auto-commit.
+ * @param tx Transaction or {@code null} for implicit transaction.
* @param key Key whose value is to be returned. The key cannot be {@code
null}.
* @param defaultValue Default value.
* @return Future that represents the pending completion of the operation.
@@ -140,7 +140,7 @@ public interface KeyValueView<K, V> extends
DataStreamerTarget<Entry<K, V>>, Cri
/**
* Determines whether a table contains an entry for the specified key.
*
- * @param tx Transaction or {@code null} to auto-commit.
+ * @param tx Transaction or {@code null} for implicit transaction.
* @param key Key whose presence is to be verified. The key cannot be
{@code null}.
* @return {@code True} if a value exists for every specified key, {@code
false} otherwise.
* @throws MarshallerException if the key doesn't match the schema.
@@ -150,7 +150,7 @@ public interface KeyValueView<K, V> extends
DataStreamerTarget<Entry<K, V>>, Cri
/**
* Determines whether a table contains an entry for the specified key.
*
- * @param tx Transaction or {@code null} to auto-commit.
+ * @param tx Transaction or {@code null} for implicit transaction.
* @param key Key whose presence is to be verified. The key cannot be
{@code null}.
* @return Future that represents the pending completion of the operation.
* @throws MarshallerException if the key doesn't match the schema.
@@ -160,7 +160,7 @@ public interface KeyValueView<K, V> extends
DataStreamerTarget<Entry<K, V>>, Cri
/**
* Determines whether a table contains entries for all given keys.
*
- * @param tx Transaction or {@code null} to auto-commit.
+ * @param tx Transaction or {@code null} for implicit transaction.
* @param keys Keys whose presence is to be verified. The collection and
it's values cannot be {@code null}.
* @return {@code True} if a value exists for every specified key, {@code
false} otherwise.
* @throws MarshallerException if the key doesn't match the schema.
@@ -170,7 +170,7 @@ public interface KeyValueView<K, V> extends
DataStreamerTarget<Entry<K, V>>, Cri
/**
* Determines whether a table contains entries for all given keys.
*
- * @param tx Transaction or {@code null} to auto-commit.
+ * @param tx Transaction or {@code null} for implicit transaction.
* @param keys Keys whose presence is to be verified. The collection and
it's values cannot be {@code null}.
* @return Future that represents the pending completion of the operation.
The result of the future will be {@code true} if a value
* exists for every specified key, {@code false} otherwise.
@@ -181,7 +181,7 @@ public interface KeyValueView<K, V> extends
DataStreamerTarget<Entry<K, V>>, Cri
/**
* Puts into a table a value associated with the given key.
*
- * @param tx Transaction or {@code null} to auto-commit.
+ * @param tx Transaction or {@code null} for implicit transaction.
* @param key Key with which the specified value is to be associated. The
key cannot be {@code null}.
* @param val Value to be associated with the specified key. Can be null
when mapped to a single column with a simple type.
* @throws MarshallerException if the key and/or the value doesn't match
the schema.
@@ -191,7 +191,7 @@ public interface KeyValueView<K, V> extends
DataStreamerTarget<Entry<K, V>>, Cri
/**
* Asynchronously puts into a table a value associated with the given key.
*
- * @param tx Transaction or {@code null} to auto-commit.
+ * @param tx Transaction or {@code null} for implicit transaction.
* @param key Key with which the specified value is to be associated. The
key cannot be {@code null}.
* @param val Value to be associated with the specified key. Can be null
when mapped to a single column with a simple type.
* @return Future that represents the pending completion of the operation.
@@ -202,7 +202,7 @@ public interface KeyValueView<K, V> extends
DataStreamerTarget<Entry<K, V>>, Cri
/**
* Puts associated key-value pairs.
*
- * @param tx Transaction or {@code null} to auto-commit.
+ * @param tx Transaction or {@code null} for implicit transaction.
* @param pairs Key-value pairs. The pairs cannot be {@code null}.
* @throws MarshallerException if one of key, or values doesn't match the
schema.
*/
@@ -211,7 +211,7 @@ public interface KeyValueView<K, V> extends
DataStreamerTarget<Entry<K, V>>, Cri
/**
* Asynchronously puts associated key-value pairs.
*
- * @param tx Transaction or {@code null} to auto-commit.
+ * @param tx Transaction or {@code null} for implicit transaction.
* @param pairs Key-value pairs. The pairs cannot be {@code null}.
* @return Future that represents the pending completion of the operation.
* @throws MarshallerException if one of key, or values doesn't match the
schema.
@@ -223,7 +223,7 @@ public interface KeyValueView<K, V> extends
DataStreamerTarget<Entry<K, V>>, Cri
*
* <p>NB: The method doesn't support {@code null} column value, use {@link
#getNullableAndPut(Transaction, Object, Object)} instead.
*
- * @param tx Transaction or {@code null} to auto-commit.
+ * @param tx Transaction or {@code null} for implicit transaction.
* @param key Key with which the specified value is to be associated. The
key cannot be {@code null}.
* @param val Value to be associated with the specified key. Can be {@code
null} when mapped to a single column with a simple type.
* @return Replaced value or {@code null} if it did not exist.
@@ -238,7 +238,7 @@ public interface KeyValueView<K, V> extends
DataStreamerTarget<Entry<K, V>>, Cri
* <p>NB: The method doesn't support {@code null} column value, use {@link
#getNullableAndPutAsync(Transaction, Object, Object)}
* instead.
*
- * @param tx Transaction or {@code null} to auto-commit.
+ * @param tx Transaction or {@code null} for implicit transaction.
* @param key Key with which the specified value is to be associated. The
key cannot be {@code null}.
* @param val Value to be associated with the specified key. Can be {@code
null} when mapped to a single column with a simple type.
* @return Future that represents the pending completion of the operation.
@@ -249,7 +249,7 @@ public interface KeyValueView<K, V> extends
DataStreamerTarget<Entry<K, V>>, Cri
/**
* Puts into a table a new, or replaces an existing, value associated with
given key.
*
- * @param tx Transaction or {@code null} to auto-commit.
+ * @param tx Transaction or {@code null} for implicit transaction.
* @param key Key with which the specified value is to be associated. The
key cannot be {@code null}.
* @param val Value to be associated with the specified key. Can be {@code
null} when mapped to a single column with a simple type.
* @return Wrapped nullable value that was replaced or {@code null} if it
did no exist.
@@ -260,7 +260,7 @@ public interface KeyValueView<K, V> extends
DataStreamerTarget<Entry<K, V>>, Cri
/**
* Asynchronously puts into a table a new, or replaces an existing, value
associated with given key.
*
- * @param tx Transaction or {@code null} to auto-commit.
+ * @param tx Transaction or {@code null} for implicit transaction.
* @param key Key with which the specified value is to be associated. The
key cannot be {@code null}.
* @param val Value to be associated with the specified key. Can be {@code
null} when mapped to a single column with a simple type.
* @return Future that represents the pending completion of the operation.
@@ -271,7 +271,7 @@ public interface KeyValueView<K, V> extends
DataStreamerTarget<Entry<K, V>>, Cri
/**
* Puts into a table a value associated with the given key if this value
does not exists.
*
- * @param tx Transaction or {@code null} to auto-commit.
+ * @param tx Transaction or {@code null} for implicit transaction.
* @param key Key with which the specified value is to be associated. The
key cannot be {@code null}.
* @param val Value to be associated with the specified key. Can be {@code
null} when mapped to a single column with a simple type.
* @return {@code True} if successful, {@code false} otherwise.
@@ -282,7 +282,7 @@ public interface KeyValueView<K, V> extends
DataStreamerTarget<Entry<K, V>>, Cri
/**
* Asynchronously puts into a table a value associated with the given key
if this value does not exist.
*
- * @param tx Transaction or {@code null} to auto-commit.
+ * @param tx Transaction or {@code null} for implicit transaction.
* @param key Key with which the specified value is to be associated. The
key cannot be {@code null}.
* @param val Value to be associated with the specified key. Can be {@code
null} when mapped to a single column with a simple type.
* @return Future that represents the pending completion of the operation.
@@ -293,7 +293,7 @@ public interface KeyValueView<K, V> extends
DataStreamerTarget<Entry<K, V>>, Cri
/**
* Removes from a table a value associated with the given key.
*
- * @param tx Transaction or {@code null} to auto-commit.
+ * @param tx Transaction or {@code null} for implicit transaction.
* @param key Key whose value is to be removed from the table. The key
cannot be {@code null}.
* @return {@code True} if a value associated with the specified key was
successfully removed, {@code false} otherwise.
* @throws MarshallerException if the key doesn't match the schema.
@@ -303,7 +303,7 @@ public interface KeyValueView<K, V> extends
DataStreamerTarget<Entry<K, V>>, Cri
/**
* Removes from a table an expected value associated with the given key.
*
- * @param tx Transaction or {@code null} to auto-commit.
+ * @param tx Transaction or {@code null} for implicit transaction.
* @param key Key whose value is to be removed from the table. The key
cannot be {@code null}.
* @param val Expected value.
* @return {@code True} if the expected value for the specified key was
successfully removed, {@code false} otherwise.
@@ -314,7 +314,7 @@ public interface KeyValueView<K, V> extends
DataStreamerTarget<Entry<K, V>>, Cri
/**
* Asynchronously removes from a table a value associated with the given
key.
*
- * @param tx Transaction or {@code null} to auto-commit.
+ * @param tx Transaction or {@code null} for implicit transaction.
* @param key A key whose value is to be removed from the table. The key
cannot be {@code null}.
* @return Future that represents the pending completion of the operation.
* @throws MarshallerException if the key doesn't match the schema.
@@ -324,7 +324,7 @@ public interface KeyValueView<K, V> extends
DataStreamerTarget<Entry<K, V>>, Cri
/**
* Asynchronously removes from a table an expected value associated with
the given key.
*
- * @param tx Transaction or {@code null} to auto-commit.
+ * @param tx Transaction or {@code null} for implicit transaction.
* @param key Key whose value is to be removed from the table. The key
cannot be {@code null}.
* @param val Expected value.
* @return Future that represents the pending completion of the operation.
@@ -335,7 +335,7 @@ public interface KeyValueView<K, V> extends
DataStreamerTarget<Entry<K, V>>, Cri
/**
* Removes from a table values associated with the given keys.
*
- * @param tx Transaction or {@code null} to auto-commit.
+ * @param tx Transaction or {@code null} for implicit transaction.
* @param keys Keys whose values are to be removed from the table. The
keys cannot be {@code null}.
* @return Keys that did not exist.
* @throws MarshallerException if one of keys doesn't match the schema.
@@ -345,7 +345,7 @@ public interface KeyValueView<K, V> extends
DataStreamerTarget<Entry<K, V>>, Cri
/**
* Asynchronously remove from a table values associated with the given
keys.
*
- * @param tx Transaction or {@code null} to auto-commit.
+ * @param tx Transaction or {@code null} for implicit transaction.
* @param keys Keys whose values are to be removed from the table. The
keys cannot be {@code null}.
* @return Future that represents the pending completion of the operation.
* @throws MarshallerException if one of the keys doesn't match the schema.
@@ -357,7 +357,7 @@ public interface KeyValueView<K, V> extends
DataStreamerTarget<Entry<K, V>>, Cri
*
* <p>NB: Method doesn't support {@code null} column value, use {@link
#getNullableAndRemove(Transaction, Object)} instead.
*
- * @param tx Transaction or {@code null} to auto-commit.
+ * @param tx Transaction or {@code null} for implicit transaction.
* @param key Key whose value is to be removed from the table. The key
cannot be {@code null}.
* @return Removed value or {@code null} if the value did not exist.
* @throws UnexpectedNullValueException If the key value is {@code null}.
@@ -370,7 +370,7 @@ public interface KeyValueView<K, V> extends
DataStreamerTarget<Entry<K, V>>, Cri
*
* <p>NB: Method doesn't support {@code null} column value, use {@link
#getNullableAndRemoveAsync(Transaction, Object)} instead.
*
- * @param tx Transaction or {@code null} to auto-commit.
+ * @param tx Transaction or {@code null} for implicit transaction.
* @param key Key whose value is to be removed from the table. The key
cannot be {@code null}.
* @return Future that represents the pending completion of the operation.
* @throws MarshallerException if the key doesn't match the schema.
@@ -380,7 +380,7 @@ public interface KeyValueView<K, V> extends
DataStreamerTarget<Entry<K, V>>, Cri
/**
* Gets and removes from a table a value associated with the given key.
*
- * @param tx Transaction or {@code null} to auto-commit.
+ * @param tx Transaction or {@code null} for implicit transaction.
* @param key Key whose value is to be removed from the table. The key
cannot be {@code null}.
* @return Wrapped nullable value that was removed or {@code null} if it
did not exist.
* @throws MarshallerException if the key doesn't match the schema.
@@ -390,7 +390,7 @@ public interface KeyValueView<K, V> extends
DataStreamerTarget<Entry<K, V>>, Cri
/**
* Asynchronously gets and removes from a table a value associated with
the given key.
*
- * @param tx Transaction or {@code null} to auto-commit.
+ * @param tx Transaction or {@code null} for implicit transaction.
* @param key Key whose value is to be removed from the table. The key
cannot be {@code null}.
* @return Future that represents the pending completion of the operation.
* @throws MarshallerException if the key doesn't match the schema.
@@ -408,7 +408,7 @@ public interface KeyValueView<K, V> extends
DataStreamerTarget<Entry<K, V>>, Cri
* }</code></pre>
* except the action is performed atomically.
*
- * @param tx Transaction or {@code null} to auto-commit.
+ * @param tx Transaction or {@code null} for implicit transaction.
* @param key Key the specified value is associated with. The key cannot
be {@code null}.
* @param val Value to be associated with the specified key. Can be {@code
null} when mapped to a single column with a simple type.
* @return {@code True} if an old value was replaced, {@code false}
otherwise.
@@ -427,7 +427,7 @@ public interface KeyValueView<K, V> extends
DataStreamerTarget<Entry<K, V>>, Cri
* }</code></pre>
* except the action is performed atomically.
*
- * @param tx Transaction or {@code null} to auto-commit.
+ * @param tx Transaction or {@code null} for implicit transaction.
* @param key Key the specified value is associated with. The key cannot
be {@code null}.
* @param oldValue Expected value associated with the specified key. Can
be {@code null} when mapped to a single column
* with a simple type.
@@ -440,7 +440,7 @@ public interface KeyValueView<K, V> extends
DataStreamerTarget<Entry<K, V>>, Cri
/**
* Asynchronously replaces a value for a key if it exists. See {@link
#replace(Transaction, Object, Object)}.
*
- * @param tx Transaction or {@code null} to auto-commit.
+ * @param tx Transaction or {@code null} for implicit transaction.
* @param key Key the specified value is associated with. The key cannot
be {@code null}.
* @param val Value to be associated with the specified key. Can be {@code
null} when mapped to a single column with a simple type.
* @return Future that represents the pending completion of the operation.
@@ -451,7 +451,7 @@ public interface KeyValueView<K, V> extends
DataStreamerTarget<Entry<K, V>>, Cri
/**
* Asynchronously replaces an expected value for a key. See {@link
#replace(Transaction, Object, Object, Object)}
*
- * @param tx Transaction or {@code null} to auto-commit.
+ * @param tx Transaction or {@code null} for implicit transaction.
* @param key Key the specified value is associated with. The key cannot
be {@code null}.
* @param oldVal Expected value associated with the specified key. Can be
{@code null} when mapped to a single column
* with a simple type.
@@ -476,7 +476,7 @@ public interface KeyValueView<K, V> extends
DataStreamerTarget<Entry<K, V>>, Cri
*
* <p>NB: Method doesn't support {@code null} column value, use {@link
#getNullableAndReplace(Transaction, Object, Object)} instead.
*
- * @param tx Transaction or {@code null} to auto-commit.
+ * @param tx Transaction or {@code null} for implicit transaction.
* @param key Key the specified value is associated with. The key cannot
be {@code null}.
* @param val Value to be associated with the specified key. Can be {@code
null} when mapped to a single column with a simple type.
* @return Replaced value, or {@code null} if it did not exist.
@@ -491,7 +491,7 @@ public interface KeyValueView<K, V> extends
DataStreamerTarget<Entry<K, V>>, Cri
* <p>NB: Method doesn't support {@code null} column value, use {@link
#getNullableAndReplaceAsync(Transaction, Object, Object)}
* instead.
*
- * @param tx Transaction or {@code null} to auto-commit.
+ * @param tx Transaction or {@code null} for implicit transaction.
* @param key Key the specified value is associated with. The key cannot
be {@code null}.
* @param val Value to be associated with the specified key. Can be {@code
null} when mapped to a single column with a simple type.
* @return Future that represents the pending completion of the operation.
@@ -503,7 +503,7 @@ public interface KeyValueView<K, V> extends
DataStreamerTarget<Entry<K, V>>, Cri
/**
* Replaces a value for a given key if it exists.
*
- * @param tx Transaction or {@code null} to auto-commit.
+ * @param tx Transaction or {@code null} for implicit transaction.
* @param key Key the specified value is associated with. The key cannot
be {@code null}.
* @param val Value to be associated with the specified key. Can be {@code
null} when mapped to a single column with a simple type.
* @return Wrapped nullable value that was replaced or {@code null} if it
did not exist.
@@ -515,7 +515,7 @@ public interface KeyValueView<K, V> extends
DataStreamerTarget<Entry<K, V>>, Cri
/**
* Asynchronously replaces a value for a given key if it exists.
*
- * @param tx Transaction or {@code null} to auto-commit.
+ * @param tx Transaction or {@code null} for implicit transaction.
* @param key Key the specified value is associated with. The key cannot
be {@code null}.
* @param val Value to be associated with the specified key. Can be {@code
null} when mapped to a single column with a simple type.
* @return Future that represents the pending completion of the operation.
diff --git a/modules/api/src/main/java/org/apache/ignite/table/RecordView.java
b/modules/api/src/main/java/org/apache/ignite/table/RecordView.java
index 846e846393..055eae766f 100644
--- a/modules/api/src/main/java/org/apache/ignite/table/RecordView.java
+++ b/modules/api/src/main/java/org/apache/ignite/table/RecordView.java
@@ -35,7 +35,7 @@ public interface RecordView<R> extends DataStreamerTarget<R>,
CriteriaQuerySourc
/**
* Gets a record with the same key column values as the given one from a
table.
*
- * @param tx Transaction or {@code null} to auto-commit.
+ * @param tx Transaction or {@code null} for implicit transaction.
* @param keyRec Record with the key columns set. The record cannot be
{@code null}.
* @return Record with all columns filled from the table.
*/
@@ -44,7 +44,7 @@ public interface RecordView<R> extends DataStreamerTarget<R>,
CriteriaQuerySourc
/**
* Asynchronously gets a record with the same key column values as the
given one from a table.
*
- * @param tx Transaction or {@code null} to auto-commit.
+ * @param tx Transaction or {@code null} for implicit transaction.
* @param keyRec Record with the key columns set. The record cannot be
{@code null}.
* @return Future that represents the pending completion of the operation.
*/
@@ -53,7 +53,7 @@ public interface RecordView<R> extends DataStreamerTarget<R>,
CriteriaQuerySourc
/**
* Gets records from a table.
*
- * @param tx Transaction or {@code null} to auto-commit.
+ * @param tx Transaction or {@code null} for implicit transaction.
* @param keyRecs Records with key columns set. The records cannot be
{@code null}.
* @return Records with all columns filled from the table. The order of
collection elements is
* guaranteed to be the same as the order of {@code keyRecs}. If a
record does not exist, the
@@ -64,7 +64,7 @@ public interface RecordView<R> extends DataStreamerTarget<R>,
CriteriaQuerySourc
/**
* Asynchronously gets records from a table.
*
- * @param tx Transaction or {@code null} to auto-commit.
+ * @param tx Transaction or {@code null} for implicit transaction.
* @param keyRecs Records with the key columns set. The records cannot be
{@code null}.
* @return Future that will return records with all columns filled from
the table. The order of collection elements is
* guaranteed to be the same as the order of {@code keyRecs}. If a
record does not exist, the
@@ -75,7 +75,7 @@ public interface RecordView<R> extends DataStreamerTarget<R>,
CriteriaQuerySourc
/**
* Determines whether a table contains an entry for the specified key.
*
- * @param tx Transaction or {@code null} to auto-commit.
+ * @param tx Transaction or {@code null} for implicit transaction.
* @param keyRec A record with key columns set. The key cannot be {@code
null}.
* @return {@code True} if a value exists for every specified key, {@code
false} otherwise.
* @throws MarshallerException if the key doesn't match the schema.
@@ -85,7 +85,7 @@ public interface RecordView<R> extends DataStreamerTarget<R>,
CriteriaQuerySourc
/**
* Determines whether a table contains an entry for the specified key.
*
- * @param tx Transaction or {@code null} to auto-commit.
+ * @param tx Transaction or {@code null} for implicit transaction.
* @param keyRec A record with key columns set. The key cannot be {@code
null}.
* @return Future that represents the pending completion of the operation.
* @throws MarshallerException if the key doesn't match the schema.
@@ -95,7 +95,7 @@ public interface RecordView<R> extends DataStreamerTarget<R>,
CriteriaQuerySourc
/**
* Determines whether a table contains entries for all given keys.
*
- * @param tx Transaction or {@code null} to auto-commit.
+ * @param tx Transaction or {@code null} for implicit transaction.
* @param keys Keys whose presence is to be verified. The collection and
it's values cannot be {@code null}.
* @return {@code True} if a value exists for every specified key, {@code
false} otherwise.
* @throws MarshallerException if the key doesn't match the schema.
@@ -105,7 +105,7 @@ public interface RecordView<R> extends
DataStreamerTarget<R>, CriteriaQuerySourc
/**
* Determines whether a table contains entries for all given keys.
*
- * @param tx Transaction or {@code null} to auto-commit.
+ * @param tx Transaction or {@code null} for implicit transaction.
* @param keys Keys whose presence is to be verified. The collection and
it's values cannot be {@code null}.
* @return Future that represents the pending completion of the operation.
The result of the future will be {@code true} if a value
* exists for every specified key, {@code false} otherwise.
@@ -116,7 +116,7 @@ public interface RecordView<R> extends
DataStreamerTarget<R>, CriteriaQuerySourc
/**
* Inserts a record into a table, if it does not exist, or replaces an
existing one.
*
- * @param tx Transaction or {@code null} to auto-commit.
+ * @param tx Transaction or {@code null} for implicit transaction.
* @param rec Record to insert into the table. The record cannot be {@code
null}.
*/
void upsert(@Nullable Transaction tx, R rec);
@@ -124,7 +124,7 @@ public interface RecordView<R> extends
DataStreamerTarget<R>, CriteriaQuerySourc
/**
* Asynchronously inserts a record into a table, if it does not exist, or
replaces the existing one.
*
- * @param tx Transaction or {@code null} to auto-commit.
+ * @param tx Transaction or {@code null} for implicit transaction.
* @param rec Record to insert into the table. The record cannot be {@code
null}.
* @return Future that represents the pending completion of the operation.
*/
@@ -133,7 +133,7 @@ public interface RecordView<R> extends
DataStreamerTarget<R>, CriteriaQuerySourc
/**
* Inserts records into a table, if they do not exist, or replaces the
existing ones.
*
- * @param tx Transaction or {@code null} to auto-commit.
+ * @param tx Transaction or {@code null} for implicit transaction.
* @param recs Records to insert into the table. The records cannot be
{@code null}.
*/
void upsertAll(@Nullable Transaction tx, Collection<R> recs);
@@ -141,7 +141,7 @@ public interface RecordView<R> extends
DataStreamerTarget<R>, CriteriaQuerySourc
/**
* Asynchronously inserts a record into a table, if it does not exist, or
replaces the existing one.
*
- * @param tx Transaction or {@code null} to auto-commit.
+ * @param tx Transaction or {@code null} for implicit transaction.
* @param recs Records to insert into the table. The records cannot be
{@code null}.
* @return Future that represents the pending completion of the operation.
*/
@@ -150,7 +150,7 @@ public interface RecordView<R> extends
DataStreamerTarget<R>, CriteriaQuerySourc
/**
* Inserts a record into a table, or replaces an existing record and
returns the replaced record.
*
- * @param tx Transaction or {@code null} to auto-commit.
+ * @param tx Transaction or {@code null} for implicit transaction.
* @param rec A record to insert into the table. The record cannot be
{@code null}.
* @return Replaced record or {@code null} if it did not exist.
*/
@@ -159,7 +159,7 @@ public interface RecordView<R> extends
DataStreamerTarget<R>, CriteriaQuerySourc
/**
* Asynchronously inserts a record into a table, or replaces an existing
record and returns the replaced record.
*
- * @param tx Transaction or {@code null} to auto-commit.
+ * @param tx Transaction or {@code null} for implicit transaction.
* @param rec Record to insert into the table. The record cannot be {@code
null}.
* @return Future that represents the pending completion of the operation.
*/
@@ -168,7 +168,7 @@ public interface RecordView<R> extends
DataStreamerTarget<R>, CriteriaQuerySourc
/**
* Inserts a record into a table if it does not exists.
*
- * @param tx Transaction or {@code null} to auto-commit.
+ * @param tx Transaction or {@code null} for implicit transaction.
* @param rec Record to insert into the table. The record cannot be {@code
null}.
* @return {@code True} if successful, {@code false} otherwise.
*/
@@ -177,7 +177,7 @@ public interface RecordView<R> extends
DataStreamerTarget<R>, CriteriaQuerySourc
/**
* Asynchronously inserts a record into a table if it does not exists.
*
- * @param tx Transaction or {@code null} to auto-commit.
+ * @param tx Transaction or {@code null} for implicit transaction.
* @param rec Record to insert into the table. The record cannot be {@code
null}.
* @return Future that represents the pending completion of the operation.
*/
@@ -186,7 +186,7 @@ public interface RecordView<R> extends
DataStreamerTarget<R>, CriteriaQuerySourc
/**
* Inserts into a table records that do not exist, skips those that exist.
*
- * @param tx Transaction or {@code null} to auto-commit.
+ * @param tx Transaction or {@code null} for implicit transaction.
* @param recs Records to insert into the table. The records cannot be
{@code null}.
* @return Skipped records. The order of collection elements is guaranteed
to be the same as the order of {@code recs}. If a record is
* inserted, the element will be excluded from the collection
result.
@@ -196,7 +196,7 @@ public interface RecordView<R> extends
DataStreamerTarget<R>, CriteriaQuerySourc
/**
* Asynchronously inserts into a table records that do not exist, skips
those that exist.
*
- * @param tx Transaction or {@code null} to auto-commit.
+ * @param tx Transaction or {@code null} for implicit transaction.
* @param recs Records to insert into the table. The records cannot be
{@code null}.
* @return Future representing pending completion of the operation, with
rejected rows for insertion in the result. The order of
* collection elements is guaranteed to be the same as the order
of {@code recs}. If a record is inserted, the element will be
@@ -207,7 +207,7 @@ public interface RecordView<R> extends
DataStreamerTarget<R>, CriteriaQuerySourc
/**
* Replaces an existing record associated with the same key column values
as the given record.
*
- * @param tx Transaction or {@code null} to auto-commit.
+ * @param tx Transaction or {@code null} for implicit transaction.
* @param rec Record to replace with. The record cannot be {@code null}.
* @return {@code True} if a record was found and replaced successfully,
{@code false} otherwise.
*/
@@ -216,7 +216,7 @@ public interface RecordView<R> extends
DataStreamerTarget<R>, CriteriaQuerySourc
/**
* Replaces an expected record in the table with the given new one.
*
- * @param tx Transaction or {@code null} to auto-commit.
+ * @param tx Transaction or {@code null} for implicit transaction.
* @param oldRec Record to replace. The record cannot be {@code null}.
* @param newRec Record to replace with. The record cannot be {@code null}.
* @return {@code True} if a record was replaced successfully, {@code
false} otherwise.
@@ -226,7 +226,7 @@ public interface RecordView<R> extends
DataStreamerTarget<R>, CriteriaQuerySourc
/**
* Asynchronously replaces an existing record associated with the same key
columns values as the given record.
*
- * @param tx Transaction or {@code null} to auto-commit.
+ * @param tx Transaction or {@code null} for implicit transaction.
* @param rec Record to replace with. The record cannot be {@code null}.
* @return Future that represents the pending completion of the operation.
*/
@@ -235,7 +235,7 @@ public interface RecordView<R> extends
DataStreamerTarget<R>, CriteriaQuerySourc
/**
* Asynchronously replaces an existing record in the table with the given
new one.
*
- * @param tx Transaction or {@code null} to auto-commit.
+ * @param tx Transaction or {@code null} for implicit transaction.
* @param oldRec Record to replace. The record cannot be {@code null}.
* @param newRec Record to replace with. The record cannot be {@code null}.
* @return Future that represents the pending completion of the operation.
@@ -245,7 +245,7 @@ public interface RecordView<R> extends
DataStreamerTarget<R>, CriteriaQuerySourc
/**
* Gets an existing record associated with the same key columns values as
the given one, then replaces it with the given one.
*
- * @param tx Transaction or {@code null} to auto-commit.
+ * @param tx Transaction or {@code null} for implicit transaction.
* @param rec Record to replace with. The record cannot be {@code null}.
* @return Replaced record or {@code null} if it did not exist.
*/
@@ -255,7 +255,7 @@ public interface RecordView<R> extends
DataStreamerTarget<R>, CriteriaQuerySourc
* Asynchronously gets an existing record associated with the same key
column values as the given one,
* then replaces it with the given one.
*
- * @param tx Transaction or {@code null} to auto-commit.
+ * @param tx Transaction or {@code null} for implicit transaction.
* @param rec Record to replace with. The record cannot be {@code null}.
* @return Future that represents the pending completion of the operation.
*/
@@ -264,7 +264,7 @@ public interface RecordView<R> extends
DataStreamerTarget<R>, CriteriaQuerySourc
/**
* Deletes a record with the same key column values as the given one from
a table.
*
- * @param tx Transaction or {@code null} to auto-commit.
+ * @param tx Transaction or {@code null} for implicit transaction.
* @param keyRec Record with the key columns set. The record cannot be
{@code null}.
* @return {@code True} if removed successfully, {@code false} otherwise.
*/
@@ -273,7 +273,7 @@ public interface RecordView<R> extends
DataStreamerTarget<R>, CriteriaQuerySourc
/**
* Asynchronously deletes a record with the same key column values as the
given one from a table.
*
- * @param tx Transaction or {@code null} to auto-commit.
+ * @param tx Transaction or {@code null} for implicit transaction.
* @param keyRec Record with the key columns set. The record cannot be
{@code null}.
* @return Future that represents the pending completion of the operation.
*/
@@ -282,7 +282,7 @@ public interface RecordView<R> extends
DataStreamerTarget<R>, CriteriaQuerySourc
/**
* Deletes the given record from a table.
*
- * @param tx Transaction or {@code null} to auto-commit.
+ * @param tx Transaction or {@code null} for implicit transaction.
* @param rec Record to delete. The record cannot be {@code null}.
* @return {@code True} if removed successfully, {@code false} otherwise.
*/
@@ -291,7 +291,7 @@ public interface RecordView<R> extends
DataStreamerTarget<R>, CriteriaQuerySourc
/**
* Asynchronously deletes the given record from a table.
*
- * @param tx Transaction or {@code null} to auto-commit.
+ * @param tx Transaction or {@code null} for implicit transaction.
* @param rec Record to delete. The record cannot be {@code null}.
* @return Future tha represents the pending completion of the operation.
*/
@@ -300,7 +300,7 @@ public interface RecordView<R> extends
DataStreamerTarget<R>, CriteriaQuerySourc
/**
* Gets and deletes from a table a record with the same key column values
as the given one.
*
- * @param tx Transaction or {@code null} to auto-commit.
+ * @param tx Transaction or {@code null} for implicit transaction.
* @param keyRec Record with the key columns set. The record cannot be
{@code null}.
* @return Removed record or {@code null} if it did not exist.
*/
@@ -309,7 +309,7 @@ public interface RecordView<R> extends
DataStreamerTarget<R>, CriteriaQuerySourc
/**
* Asynchronously gets and deletes from a table a record with the same key
columns values as the given one.
*
- * @param tx Transaction or {@code null} to auto-commit.
+ * @param tx Transaction or {@code null} for implicit transaction.
* @param keyRec Record with the key columns set. The record cannot be
{@code null}.
* @return Future that represents the pending completion of the operation.
*/
@@ -318,7 +318,7 @@ public interface RecordView<R> extends
DataStreamerTarget<R>, CriteriaQuerySourc
/**
* Removes from a table records with the same key column values as the
given one.
*
- * @param tx Transaction or {@code null} to auto-commit.
+ * @param tx Transaction or {@code null} for implicit transaction.
* @param keyRecs Records with the key columns set. The records cannot be
{@code null}.
* @return Records with the key columns set that did not exist. The order
of collection elements is guaranteed to be the same as the
* order of {@code keyRecs}. If a record is removed, the element
will be excluded from the collection result.
@@ -328,7 +328,7 @@ public interface RecordView<R> extends
DataStreamerTarget<R>, CriteriaQuerySourc
/**
* Asynchronously removes from a table records with the same key column
values as the given one.
*
- * @param tx Transaction or {@code null} to auto-commit.
+ * @param tx Transaction or {@code null} for implicit transaction.
* @param keyRecs Records with the key columns set. The records cannot be
{@code null}.
* @return Future represents the pending completion of the operation, with
rejected rows for deletion in the result. The order of
* collection elements is guaranteed to be the same as the order
of {@code keyRecs}. If a record is removed, the element will be
@@ -339,7 +339,7 @@ public interface RecordView<R> extends
DataStreamerTarget<R>, CriteriaQuerySourc
/**
* Remove the given records from a table.
*
- * @param tx Transaction or {@code null} to auto-commit.
+ * @param tx Transaction or {@code null} for implicit transaction.
* @param recs Records to delete. The records cannot be {@code null}.
* @return Records that were not deleted. The order of collection elements
is guaranteed to be the same as the order of {@code recs}. If
* a record is removed, the element will be excluded from the
collection result.
@@ -349,7 +349,7 @@ public interface RecordView<R> extends
DataStreamerTarget<R>, CriteriaQuerySourc
/**
* Asynchronously removes the given records from a table.
*
- * @param tx Transaction or {@code null} to auto-commit.
+ * @param tx Transaction or {@code null} for implicit transaction.
* @param recs Records to delete. The records cannot be {@code null}.
* @return Future represents the pending completion of the operation, with
rejected rows for deletion in the result. The order of
* collection elements is guaranteed to be the same as the order
of {@code recs}. If a record is removed, the element will be
diff --git a/modules/api/src/main/java/org/apache/ignite/table/Table.java
b/modules/api/src/main/java/org/apache/ignite/table/Table.java
index 3f39df5e74..5522fb4734 100644
--- a/modules/api/src/main/java/org/apache/ignite/table/Table.java
+++ b/modules/api/src/main/java/org/apache/ignite/table/Table.java
@@ -21,32 +21,36 @@ import org.apache.ignite.table.mapper.Mapper;
import org.apache.ignite.table.partition.PartitionManager;
/**
- * Table provides the different views (key-value vs record) and approaches
(mapped-object vs binary) to access the data.
+ * Table provides different views (key-value vs record) and approaches
(mapped-object vs binary) to access the data.
*
- * <p>Binary table views might be useful in the various scenarios, including
when the user key-value classes
+ * <p>Binary table views might be useful in the various scenarios, including
when the user key-value classes
* are not in classpath and/or when deserialization of the entire table record
is undesirable for performance reasons.
*
+ * <p>Key-value views project table rows into key-value pairs, where all key
columns are mapped to the key object,
+ * and the rest of the columns are mapped to the value object.
+ * Record and key-value views provide identical functionality, the projection
is performed on the client side.
+ *
* @see RecordView
* @see KeyValueView
* @see org.apache.ignite.table.mapper.Mapper
*/
public interface Table {
/**
- * Gets a name of a table.
+ * Gets the name of the table.
*
* @return Table name.
*/
String name();
/**
- * Gets a partition manager of a table.
+ * Gets the partition manager.
*
* @return Partition manager.
*/
PartitionManager partitionManager();
/**
- * Creates a record view of a table for the record class mapper provided.
+ * Gets a record view of the table using the specified record class mapper.
*
* @param recMapper Record class mapper.
* @param <R> Record type.
@@ -55,14 +59,14 @@ public interface Table {
<R> RecordView<R> recordView(Mapper<R> recMapper);
/**
- * Creates a record view of a table for the binary object concept.
+ * Gets a record view of the table.
*
* @return Table record view.
*/
RecordView<Tuple> recordView();
/**
- * Creates a record view of a table for the record class provided.
+ * Gets a record view of the table using the default mapper for the
specified record class.
*
* @param recCls Record class.
* @param <R> Record type.
@@ -73,7 +77,7 @@ public interface Table {
}
/**
- * Creates a key-value view of a table for the key-value class mappers
provided.
+ * Gets a key-value view of the table using the specified key-value class
mappers.
*
* @param keyMapper Key class mapper.
* @param valMapper Value class mapper.
@@ -84,14 +88,14 @@ public interface Table {
<K, V> KeyValueView<K, V> keyValueView(Mapper<K> keyMapper, Mapper<V>
valMapper);
/**
- * Creates a key-value view of a table for the binary object concept.
+ * Gets a key-value view of the table.
*
* @return Table key-value view.
*/
KeyValueView<Tuple, Tuple> keyValueView();
/**
- * Creates a key-value view of a table for the key and value classes
provided.
+ * Gets a key-value view of the table using the default mapper for the
specified key and value classes.
*
* @param keyCls Key class.
* @param valCls Value class.
diff --git
a/modules/table/src/main/java/org/apache/ignite/internal/table/InternalTable.java
b/modules/table/src/main/java/org/apache/ignite/internal/table/InternalTable.java
index ee381cd859..a7e211a61d 100644
---
a/modules/table/src/main/java/org/apache/ignite/internal/table/InternalTable.java
+++
b/modules/table/src/main/java/org/apache/ignite/internal/table/InternalTable.java
@@ -110,7 +110,7 @@ public interface InternalTable extends ManuallyCloseable {
* Asynchronously get rows from the table.
*
* @param keyRows Rows with key columns set.
- * @param tx Transaction or {@code null} to auto-commit.
+ * @param tx Transaction or {@code null} for implicit transaction.
* @return Future that will return rows with all columns filled from the
table. The order of collection elements is
* guaranteed to be the same as the order of {@code keyRows}. If a
record does not exist, the
* element at the corresponding index of the resulting collection is
{@code null}.
