You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@ignite.apache.org by ag...@apache.org on 2021/03/04 12:59:35 UTC
[ignite-3] branch ignite-14198 updated: IGNITE-14198 Added javadocs
for conditions and updates.
This is an automated email from the ASF dual-hosted git repository.
agura pushed a commit to branch ignite-14198
in repository https://gitbox.apache.org/repos/asf/ignite-3.git
The following commit(s) were added to refs/heads/ignite-14198 by this push:
new 32e69ed IGNITE-14198 Added javadocs for conditions and updates.
32e69ed is described below
commit 32e69ed6cc9f1120b62cb244c64883b22cbbcbda
Author: Andrey Gura <ag...@apache.org>
AuthorDate: Thu Mar 4 15:59:15 2021 +0300
IGNITE-14198 Added javadocs for conditions and updates.
---
.../ignite/metastorage/common/Condition.java | 175 ++++++++++++++++++---
.../ignite/metastorage/common/Conditions.java | 21 +++
.../apache/ignite/metastorage/common/Update.java | 30 ++++
.../apache/ignite/metastorage/common/Updates.java | 25 +++
4 files changed, 227 insertions(+), 24 deletions(-)
diff --git a/modules/metastorage-common/src/main/java/org/apache/ignite/metastorage/common/Condition.java b/modules/metastorage-common/src/main/java/org/apache/ignite/metastorage/common/Condition.java
index 6fa3758..575d1bd 100644
--- a/modules/metastorage-common/src/main/java/org/apache/ignite/metastorage/common/Condition.java
+++ b/modules/metastorage-common/src/main/java/org/apache/ignite/metastorage/common/Condition.java
@@ -20,29 +20,67 @@ package org.apache.ignite.metastorage.common;
import java.util.Arrays;
/**
- * Represents condition for conditional update.
+ * Represents a condition for conditional update.
*/
public final class Condition {
- private final InnerCondition cnd;
-
- Condition(InnerCondition cnd) {
- this.cnd = cnd;
+ /** Actual condition implementation. */
+ private final InnerCondition cond;
+
+ /**
+ * Constructs a condition which wraps the actual condition implementation.
+ *
+ * @param cond The actual condition implementation.
+ */
+ Condition(InnerCondition cond) {
+ this.cond = cond;
}
+ /**
+ * Tests the given entry on satisfaction of the condition.
+ *
+ * @param e Entry.
+ * @return The result of condition test. {@code true} - if the entry satisfies to the condition,
+ * otherwise - {@code false}/
+ */
public boolean test(Entry e) {
- return cnd.test(e);
+ return cond.test(e);
}
+ /**
+ * Represents condition on entry revision. Only one type of condition could be applied to
+ * the one instance of condition. Subsequent invocations of any method which produces condition will throw
+ * {@link IllegalStateException}.
+ */
public static final class RevisionCondition implements InnerCondition {
+ /**
+ * The type of condition.
+ *
+ * @see Type
+ */
private Type type;
+
+ /**
+ * The revision as the condition argument.
+ */
private long rev;
+ /**
+ * Default no-op constructor.
+ */
RevisionCondition() {
// No-op.
}
+ /**
+ * Produces the condition of type {@link Type#EQUAL}. This condition tests the given revision on equality with
+ * target entry revision.
+ *
+ * @param rev The revision.
+ * @return The condition of type {@link Type#EQUAL}.
+ * @throws IllegalStateException In case when the condition is already defined.
+ */
public Condition equal(long rev) {
- validate();
+ validate(type);
this.type = Type.EQUAL;
this.rev = rev;
@@ -50,8 +88,16 @@ public final class Condition {
return new Condition(this);
}
+ /**
+ * Produces the condition of type {@link Type#NOT_EQUAL}. This condition tests the given revision on inequality
+ * with target entry revision.
+ *
+ * @param rev The revision.
+ * @return The condition of type {@link Type#NOT_EQUAL}.
+ * @throws IllegalStateException In case when the condition is already defined.
+ */
public Condition notEqual(long rev) {
- validate();
+ validate(type);
this.type = Type.NOT_EQUAL;
this.rev = rev;
@@ -59,8 +105,16 @@ public final class Condition {
return new Condition(this);
}
+ /**
+ * Produces the condition of type {@link Type#GREATER}. This condition tests that the target entry revision
+ * is greater than given revision.
+ *
+ * @param rev The revision.
+ * @return The condition of type {@link Type#GREATER}.
+ * @throws IllegalStateException In case when the condition is already defined.
+ */
public Condition greater(long rev) {
- validate();
+ validate(type);
this.type = Type.GREATER;
this.rev = rev;
@@ -68,8 +122,16 @@ public final class Condition {
return new Condition(this);
}
+ /**
+ * Produces the condition of type {@link Type#LESS}. This condition tests that target entry revision
+ * is less than the given revision.
+ *
+ * @param rev The revision.
+ * @return The condition of type {@link Type#LESS}.
+ * @throws IllegalStateException In case when the condition is already defined.
+ */
public Condition less(long rev) {
- validate();
+ validate(type);
this.type = Type.LESS;
this.rev = rev;
@@ -77,6 +139,7 @@ public final class Condition {
return new Condition(this);
}
+ /** {@inheritDoc} */
@Override public boolean test(Entry e) {
int res = Long.compare(e.revision(), rev);
@@ -86,26 +149,59 @@ public final class Condition {
(type == Type.LESS && res < 0);
}
- private void validate() {
- if (type != null)
- throw new IllegalStateException("Condition type " + type.name() + " is already defined.");
- }
-
+ /**
+ * Defines possible condition types which can be applied to the revision.
+ */
enum Type {
- EQUAL, NOT_EQUAL, GREATER, LESS;
+ /** Equality condition type. */
+ EQUAL,
+
+ /** Inequality condition type. */
+ NOT_EQUAL,
+
+ /** Greater than condition type. */
+ GREATER,
+
+ /** Less than condition type. */
+ LESS
}
}
+ /**
+ * Represents condition on entry value. Only one type of condition could be applied to
+ * the one instance of condition. Subsequent invocations of any method which produces condition will throw
+ * {@link IllegalStateException}.
+ */
public static final class ValueCondition implements InnerCondition {
+ /**
+ * The type of condition.
+ *
+ * @see Type
+ */
private Type type;
+
+ /**
+ * The value as the condition argument.
+ */
private byte[] val;
+ /**
+ * Default no-op constructor.
+ */
ValueCondition() {
// No-op.
}
+ /**
+ * Produces the condition of type {@link Type#EQUAL}. This condition tests the given value on equality with
+ * target entry value.
+ *
+ * @param val The value.
+ * @return The condition of type {@link Type#EQUAL}.
+ * @throws IllegalStateException In case when the condition is already defined.
+ */
public Condition equal(byte[] val) {
- validate();
+ validate(type);
this.type = Type.EQUAL;
this.val = val;
@@ -113,8 +209,16 @@ public final class Condition {
return new Condition(this);
}
+ /**
+ * Produces the condition of type {@link Type#NOT_EQUAL}. This condition tests the given мфдгу on inequality
+ * with target entry мфдгу.
+ *
+ * @param val The value.
+ * @return The condition of type {@link Type#NOT_EQUAL}.
+ * @throws IllegalStateException In case when the condition is already defined.
+ */
public Condition notEqual(byte[] val) {
- validate();
+ validate(type);
this.type = Type.NOT_EQUAL;
this.val = val;
@@ -122,6 +226,7 @@ public final class Condition {
return new Condition(this);
}
+ /** {@inheritDoc} */
@Override public boolean test(Entry e) {
int res = Arrays.compare(e.value(), val);
@@ -129,17 +234,39 @@ public final class Condition {
(type == Type.NOT_EQUAL && res != 0);
}
- private void validate() {
- if (type != null)
- throw new IllegalStateException("Condition type " + type.name() + " is already defined.");
- }
-
+ /**
+ * Defines possible condition types which can be applied to the value.
+ */
enum Type {
- EQUAL, NOT_EQUAL
+ /** Equality condition type. */
+ EQUAL,
+
+ /** Inequality condition type. */
+ NOT_EQUAL
}
}
+ /**
+ * Checks that condition is not defined yet. If the condition is already defined then exception will be thrown.
+ *
+ * @throws IllegalStateException In case when the condition is already defined.
+ */
+ private static void validate(Enum<?> type) {
+ if (type != null)
+ throw new IllegalStateException("Condition type " + type.name() + " is already defined.");
+ }
+
+ /**
+ * Defines condition interface.
+ */
private interface InnerCondition {
+ /**
+ * Tests the given entry on satisfaction of the condition.
+ *
+ * @param e Entry.
+ * @return The result of condition test. {@code true} - if the entry satisfies to the condition,
+ * otherwise - {@code false}/
+ */
boolean test(Entry e);
}
}
diff --git a/modules/metastorage-common/src/main/java/org/apache/ignite/metastorage/common/Conditions.java b/modules/metastorage-common/src/main/java/org/apache/ignite/metastorage/common/Conditions.java
index 08e5326..f83849a 100644
--- a/modules/metastorage-common/src/main/java/org/apache/ignite/metastorage/common/Conditions.java
+++ b/modules/metastorage-common/src/main/java/org/apache/ignite/metastorage/common/Conditions.java
@@ -17,15 +17,36 @@
package org.apache.ignite.metastorage.common;
+/**
+ * This class contains fabric methods which produce conditions needed for conditional multi update functionality
+ * provided by meta storage service.
+ *
+ * @see Condition
+ */
public final class Conditions {
+ /**
+ * Creates condition on entry revision.
+ *
+ * @return Condition on entry revision.
+ * @see Condition.RevisionCondition
+ */
public static Condition.RevisionCondition revision() {
return new Condition.RevisionCondition();
}
+ /**
+ * Creates condition on entry value.
+ *
+ * @return Condition on entry value.
+ * @see Condition.ValueCondition
+ */
public static Condition.ValueCondition value() {
return new Condition.ValueCondition();
}
+ /**
+ * Default no-op constructor.
+ */
private Conditions() {
// No-op.
}
diff --git a/modules/metastorage-common/src/main/java/org/apache/ignite/metastorage/common/Update.java b/modules/metastorage-common/src/main/java/org/apache/ignite/metastorage/common/Update.java
index d5a6b46..67b130d 100644
--- a/modules/metastorage-common/src/main/java/org/apache/ignite/metastorage/common/Update.java
+++ b/modules/metastorage-common/src/main/java/org/apache/ignite/metastorage/common/Update.java
@@ -21,32 +21,62 @@ package org.apache.ignite.metastorage.common;
* Defines update command for meta storage conditional update.
*/
public final class Update {
+ /** Actual condition implementation. */
private final InnerUpdate upd;
+ /**
+ * Constructs a condition which wraps the actual condition implementation.
+ *
+ * @param upd The actual condition implementation.
+ */
Update(InnerUpdate upd) {
this.upd = upd;
}
+ /**
+ * Represents update of type <i>remove</i>.
+ */
public static final class RemoveUpdate implements InnerUpdate {
+ /**
+ * Default no-op constructor.
+ */
RemoveUpdate() {
// No-op.
}
}
+ /**
+ * Represents update of type <i>put</i>.
+ */
public static final class PutUpdate implements InnerUpdate {
+ /** Value. */
private final byte[] val;
+ /**
+ * Constructs update of type <i>put</i>.
+ *
+ * @param val The value to which the entry should be updated.
+ */
PutUpdate(byte[] val) {
this.val = val;
}
}
+ /**
+ * Represents update of type <i>no-op</i>.
+ */
public static final class NoOpUpdate implements InnerUpdate {
+ /**
+ * Default no-op constructor.
+ */
NoOpUpdate() {
// No-op.
}
}
+ /**
+ * Defines update interface.
+ */
private interface InnerUpdate {
// Marker interface.
}
diff --git a/modules/metastorage-common/src/main/java/org/apache/ignite/metastorage/common/Updates.java b/modules/metastorage-common/src/main/java/org/apache/ignite/metastorage/common/Updates.java
index afa7cbe..d9b120e 100644
--- a/modules/metastorage-common/src/main/java/org/apache/ignite/metastorage/common/Updates.java
+++ b/modules/metastorage-common/src/main/java/org/apache/ignite/metastorage/common/Updates.java
@@ -17,19 +17,44 @@
package org.apache.ignite.metastorage.common;
+/**
+ * This class contains fabric methods which produce update items needed for conditional multi update functionality
+ * provided by meta storage service.
+ *
+ * @see Update
+ */
public final class Updates {
+ /**
+ * Creates update of type <i>remove</i>. This type of update removes entry.
+ *
+ * @return Update of type <i>remove</i>.
+ */
public static Update remove() {
return new Update(new Update.RemoveUpdate());
}
+ /**
+ * Creates update of type <i>put</i>. This type of update inserts or updates value of entry.
+ *
+ * @param value Value.
+ * @return Update of type <i>put</i>.
+ */
public static Update put(byte[] value) {
return new Update(new Update.PutUpdate(value));
}
+ /**
+ * Creates update of type <i>noop</i>. It is a special type of update which doesn't produce any action.
+ *
+ * @return Update of type <i>noop</i>.
+ */
public static Update noop() {
return new Update(new Update.NoOpUpdate());
}
+ /**
+ * Default no-op constructor.
+ */
private Updates() {
// No-op.
}