From e79884edae37c716f7b688ac48321634b1ad08af Mon Sep 17 00:00:00 2001 From: David Noble Date: Thu, 3 Oct 2019 12:12:12 -0700 Subject: [PATCH] Addressed a number of javadoc issues and the javadocs now build. --- .../azure/data/cosmos/core/UtfAnyString.java | 14 +++++ .../hybridrow/layouts/Layout.java | 23 ++++++-- .../hybridrow/layouts/LayoutBoolean.java | 2 +- .../hybridrow/layouts/LayoutCodeTraits.java | 11 ++-- .../hybridrow/layouts/LayoutColumn.java | 53 +++++++++++++----- .../hybridrow/layouts/LayoutNull.java | 10 ++-- .../hybridrow/layouts/LayoutType.java | 54 ++++++++++++++----- .../layouts/LayoutTypePrimitive.java | 49 ++++++++++++----- .../hybridrow/layouts/LayoutTypeScope.java | 24 ++++++--- .../hybridrow/layouts/LayoutUniqueScope.java | 11 ++-- .../hybridrow/layouts/StringTokenizer.java | 2 + .../hybridrow/layouts/TypeArgument.java | 6 ++- .../hybridrow/layouts/TypeArgumentList.java | 6 ++- .../hybridrow/schemas/MapPropertyType.java | 4 ++ .../hybridrow/schemas/ObjectPropertyType.java | 2 + .../hybridrow/schemas/PrimarySortKey.java | 6 +++ .../schemas/PrimitivePropertyType.java | 4 ++ .../hybridrow/schemas/Schema.java | 18 +++++-- .../hybridrow/schemas/SchemaHash.java | 2 +- .../hybridrow/schemas/SchemaOptions.java | 22 +++++--- .../hybridrow/schemas/ScopePropertyType.java | 5 +- .../hybridrow/schemas/StaticKey.java | 2 + .../hybridrow/schemas/TuplePropertyType.java | 5 +- 23 files changed, 254 insertions(+), 81 deletions(-) diff --git a/java/src/main/java/com/azure/data/cosmos/core/UtfAnyString.java b/java/src/main/java/com/azure/data/cosmos/core/UtfAnyString.java index 157860b..cfadd65 100644 --- a/java/src/main/java/com/azure/data/cosmos/core/UtfAnyString.java +++ b/java/src/main/java/com/azure/data/cosmos/core/UtfAnyString.java @@ -41,6 +41,8 @@ public final class UtfAnyString implements CharSequence, Comparable * Usually this is the name of the {@link Schema} from which this {@link Layout} was generated. + * + * @return name of the layout. */ public String name() { return this.name; @@ -151,6 +153,8 @@ public final class Layout { *

* A presence bit is allocated for each fixed and variable-length field. Sparse columns never have presence bits. * Fixed boolean allocate an additional bit from the bitmask to store their value. + * + * @return the number of bit mask bytes allocated with the layout. */ public int numBitmaskBytes() { return this.numBitmaskBytes; @@ -158,6 +162,8 @@ public final class Layout { /** * The number of fixed columns. + * + * @return the number of fixed columns. */ public int numFixed() { return this.numFixed; @@ -165,6 +171,8 @@ public final class Layout { /** * The number of variable-length columns. + * + * @return the number of variable-length columns. */ public int numVariable() { return this.numVariable; @@ -172,27 +180,34 @@ public final class Layout { /** * Unique identifier of the schema from which this {@link Layout} was generated. + * + * @return the unique identifier of the schema from which this {@link Layout} was generated. */ public SchemaId schemaId() { return this.schemaId; } /** - * Minimum required size of a row of this layout. + * The minimum required size of a row with this layout. *

* This size excludes all sparse columns, and assumes all columns (including variable) are * null. + * + * @return the minimum required size of a row with this layout. */ public int size() { return this.size; } /** - * Returns a human readable diagnostic string representation of this {@link Layout}. + * A human readable diagnostic string representing this {@link Layout}. *

* This representation should only be used for debugging and diagnostic purposes. + * + * @return a human readable diagnostic string representing this {@link Layout}. */ @Override + @Nonnull public String toString() { StringBuilder sb = new StringBuilder(); @@ -217,7 +232,9 @@ public final class Layout { } /** - * A tokenizer for path strings. + * A {@linkplain StringTokenizer tokenizer} for path strings. + * + * @return a {@linkplain StringTokenizer tokenizer} for path strings. */ public StringTokenizer tokenizer() { return this.tokenizer; diff --git a/java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/layouts/LayoutBoolean.java b/java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/layouts/LayoutBoolean.java index 4d692f0..23abd09 100644 --- a/java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/layouts/LayoutBoolean.java +++ b/java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/layouts/LayoutBoolean.java @@ -135,7 +135,7 @@ public final class LayoutBoolean extends LayoutTypePrimitive implements @Override @Nonnull - public Result writeSparse(RowBuffer buffer, RowCursor edit, Boolean value) { + public Result writeSparse(@Nonnull RowBuffer buffer, @Nonnull RowCursor edit, @Nonnull Boolean value) { return this.writeSparse(buffer, edit, value, UpdateOptions.UPSERT); } } \ No newline at end of file diff --git a/java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/layouts/LayoutCodeTraits.java b/java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/layouts/LayoutCodeTraits.java index fb6c5c3..055efc2 100644 --- a/java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/layouts/LayoutCodeTraits.java +++ b/java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/layouts/LayoutCodeTraits.java @@ -5,23 +5,25 @@ package com.azure.data.cosmos.serialization.hybridrow.layouts; public final class LayoutCodeTraits { /** - * {@code true} if the specified layout code indicates that an element type always requires a type code + * {@code true} if the specified layout code indicates that an element type always requires a type code. *

* When this method returns {@code true} it indicates that the element value is in the type code. * * @param code The element type code. + * @return {@code true} if the specified layout code indicates that an element type always requires a type code. */ public static boolean alwaysRequiresTypeCode(LayoutCode code) { return (code == LayoutCode.BOOLEAN) || (code == LayoutCode.BOOLEAN_FALSE) || (code == LayoutCode.NULL); } /** - * Returns a canonicalized version of the specified layout code. + * A canonicalized version of the specified layout code. *

* Some codes (e.g. {@link LayoutCode#BOOLEAN} use multiple type codes to also encode values. This function converts * actual value based code into the canonicalized type code for schema comparisons. * - * @param code The code to canonicalize. + * @param code the code to canonicalize. + * @return a canonicalized version of the specified layout code. */ public static LayoutCode canonicalize(LayoutCode code) { return (code == LayoutCode.BOOLEAN_FALSE) ? LayoutCode.BOOLEAN : code; @@ -30,7 +32,8 @@ public final class LayoutCodeTraits { /** * Returns the same scope code without the immutable bit set. * - * @param code The scope type code + * @param code The scope type code. + * @return the same scope code without the immutable bit set. */ public static LayoutCode clearImmutableBit(LayoutCode code) { return LayoutCode.from((byte) (code.value() & 0xFE)); diff --git a/java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/layouts/LayoutColumn.java b/java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/layouts/LayoutColumn.java index 17b38ec..60ff3c7 100644 --- a/java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/layouts/LayoutColumn.java +++ b/java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/layouts/LayoutColumn.java @@ -68,33 +68,41 @@ public final class LayoutColumn { } /** - * For bool fields, zero-based index into the bit mask for the bool value. + * For boolean fields, the zero-based index into the bit mask for the boolean value. + * + * @return for boolean fields, the zero-based index into the bit mask for the boolean value. */ public @Nonnull LayoutBit booleanBit() { return this.booleanBit; } /** - * Full logical path of the field within the row + * Full logical path of the field within the row. *

* Paths are expressed in dotted notation: e.g. a relative {@link #path()} of 'b.c' within the scope 'a' yields a * full path of 'a.b.c'. + * + * @return Full logical path of the field within the row. */ public @Nonnull Utf8String fullPath() { return this.fullPath; } /** - * Zero-based index of the column within the structure + * Zero-based index of the column within the structure. *

* This value also indicates which presence bit controls this column. + * + * @return Zero-based index of the column within the structure. */ public int index() { return this.index; } /** - * For nullable fields, the zero-based index into the bit mask for the null bit + * For nullable fields, the zero-based index into the bit mask for the null bit. + * + * @return For nullable fields, the zero-based index into the bit mask for the null bit. */ public @Nonnull LayoutBit nullBit() { return this.nullBit; @@ -107,13 +115,17 @@ public final class LayoutColumn { * beginning of the variable length segment. *

* For all other values of {@link #storage()}, {@code offset} is ignored. + * + * @return If {@link #storage()} equals {@link StorageKind#FIXED} then the byte offset to the field location. */ public int offset() { return this.offset; } /** - * Layout of the parent scope, if a nested column, otherwise null. + * Layout of the parent scope, if a nested column, otherwise {@code null}. + * + * @return Layout of the parent scope, if a nested column, otherwise {@code null}. */ public LayoutColumn parent() { return this.parent; @@ -124,14 +136,19 @@ public final class LayoutColumn { *

* Paths are expressed in dotted notation: e.g. a relative {@link #path} of 'b.c' within the scope 'a' yields a * {@link #fullPath} of 'a.b.c'. + * + * @return the relative path of the field within its parent scope. */ public @Nonnull Utf8String path() { return this.path; } /** - * If {@link LayoutType#isBoolean()} then the zero-based extra index within the bool byte - * holding the value of this type, otherwise must be 0. + * If {@link LayoutType#isBoolean()} then the zero-based extra index within the boolean byte holding the value of + * this type, otherwise must be 0. + * + * @return If {@link LayoutType#isBoolean()} then the zero-based extra index within the boolean byte holding the + * value of this type, otherwise must be 0. */ public int size() { return this.size; @@ -139,6 +156,8 @@ public final class LayoutColumn { /** * The storage kind of the field. + * + * @return the storage kind of the field. */ public @Nonnull StorageKind storage() { return this.storage; @@ -146,13 +165,17 @@ public final class LayoutColumn { /** * The physical layout type of the field. + * + * @return the physical layout type of the field. */ public @Nonnull LayoutType type() { return this.type; } /** - * The full logical type + * The full logical type. + * + * @return the full logical type. */ public @Nonnull TypeArgument typeArg() { return this.typeArg; @@ -160,6 +183,8 @@ public final class LayoutColumn { /** * For types with generic parameters (e.g. {@link LayoutTuple}, the type parameters. + * + * @return for types with generic parameters (e.g. {@link LayoutTuple}, the type parameters. */ public @Nonnull TypeArgumentList typeArgs() { return this.typeArgs; @@ -167,6 +192,10 @@ public final class LayoutColumn { /** * The physical layout type of the field cast to the specified type. + * + * @param a type that implements {@code ILayoutType}. + * + * @return The physical layout type of the field cast to the specified type. */ @SuppressWarnings("unchecked") public @Nonnull T typeAs() { @@ -184,11 +213,11 @@ public final class LayoutColumn { } /** - * Computes the full logical path to the column + * Computes the full logical path to the column. * - * @param parent The layout of the parent scope, if a nested column, otherwise null - * @param path The path to the field relative to parent scope - * @return The full logical path + * @param parent The layout of the parent scope, if a nested column, otherwise null. + * @param path The path to the field relative to parent scope. + * @return The full logical path. */ private static @Nonnull String fullPath(final LayoutColumn parent, @Nonnull final String path) { diff --git a/java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/layouts/LayoutNull.java b/java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/layouts/LayoutNull.java index cd20afa..3a22ff2 100644 --- a/java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/layouts/LayoutNull.java +++ b/java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/layouts/LayoutNull.java @@ -34,7 +34,7 @@ public final class LayoutNull extends LayoutTypePrimitive implements @Override @Nonnull - public Result readFixed(RowBuffer buffer, RowCursor scope, LayoutColumn column, Out value) { + public Result readFixed(@Nonnull RowBuffer buffer, @Nonnull RowCursor scope, @Nonnull LayoutColumn column, @Nonnull Out value) { checkArgument(scope.scopeType() instanceof LayoutUDT); value.set(NullValue.DEFAULT); if (!buffer.readBit(scope.start(), column.nullBit())) { @@ -45,7 +45,7 @@ public final class LayoutNull extends LayoutTypePrimitive implements @Override @Nonnull - public Result readSparse(RowBuffer buffer, RowCursor edit, Out value) { + public Result readSparse(@Nonnull RowBuffer buffer, @Nonnull RowCursor edit, @Nonnull Out value) { Result result = prepareSparseRead(buffer, edit, this.layoutCode()); if (result != Result.SUCCESS) { value.set(null); @@ -57,7 +57,7 @@ public final class LayoutNull extends LayoutTypePrimitive implements @Override @Nonnull - public Result writeFixed(RowBuffer buffer, RowCursor scope, LayoutColumn column, NullValue value) { + public Result writeFixed(@Nonnull RowBuffer buffer, @Nonnull RowCursor scope, @Nonnull LayoutColumn column, @Nonnull NullValue value) { checkArgument(scope.scopeType() instanceof LayoutUDT); if (scope.immutable()) { return Result.INSUFFICIENT_PERMISSIONS; @@ -68,7 +68,7 @@ public final class LayoutNull extends LayoutTypePrimitive implements @Override @Nonnull - public Result writeSparse(RowBuffer buffer, RowCursor edit, NullValue value, UpdateOptions options) { + public Result writeSparse(@Nonnull RowBuffer buffer, @Nonnull RowCursor edit, @Nonnull NullValue value, @Nonnull UpdateOptions options) { Result result = prepareSparseWrite(buffer, edit, this.typeArg(), options); if (result != Result.SUCCESS) { return result; @@ -79,7 +79,7 @@ public final class LayoutNull extends LayoutTypePrimitive implements @Override @Nonnull - public Result writeSparse(RowBuffer buffer, RowCursor edit, NullValue value) { + public Result writeSparse(@Nonnull RowBuffer buffer, @Nonnull RowCursor edit, @Nonnull NullValue value) { return this.writeSparse(buffer, edit, value, UpdateOptions.UPSERT); } } \ No newline at end of file diff --git a/java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/layouts/LayoutType.java b/java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/layouts/LayoutType.java index f0096e9..c567f6e 100644 --- a/java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/layouts/LayoutType.java +++ b/java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/layouts/LayoutType.java @@ -14,11 +14,10 @@ import javax.annotation.Nonnull; import static com.google.common.base.Preconditions.checkArgument; import static com.google.common.base.Preconditions.checkNotNull; -import static com.google.common.base.Strings.lenientFormat; /** * Describes the physical byte layout of a hybrid row field of a specific physical type {@code T}. - * + *

* {@link LayoutType} provides methods for manipulating hybrid row fields of a particular type, and properties that * describe the layout of fields of that type. */ @@ -40,6 +39,10 @@ public abstract class LayoutType /*implements ILayoutType*/ { /** * Initializes a new instance of the {@link LayoutType} class. + * + * @param code the {@linkplain LayoutCode} layout code of the instance. + * @param immutable {@code true} if edits to fields with this layout type are prohibited. + * @param size size of fields with this layout type in bytes. */ protected LayoutType(@Nonnull final LayoutCode code, final boolean immutable, final int size) { @@ -55,47 +58,63 @@ public abstract class LayoutType /*implements ILayoutType*/ { /** * Initializes a new instance of the {@link LayoutType} class. + * + * @param code the {@linkplain LayoutCode} layout code of the instance. + * @param size size of fields with this layout type in bytes. */ protected LayoutType(LayoutCode code, int size) { this(code, false, size); } /** - * True if this type is a boolean. + * {@code true} if this type is a boolean. + * + * @return {@code true} if this type is a boolean. */ public boolean isBoolean() { return false; } /** - * True if this type is always fixed length. + * {@code true} if this type is always fixed length. + * + * @return {@code true} if this type is always fixed length. */ public abstract boolean isFixed(); /** - * If true, this edit's nested fields cannot be updated individually. - * The entire edit can still be replaced. + * {@code true} if this {@link LayoutType}'s nested fields cannot be updated individually. + *

+ * Instances of this {@link LayoutType} can still be replaced in their entirety. + * + * @return {@code true} if this {@link LayoutType}'s nested fields cannot be updated individually. */ public boolean isImmutable() { return this.immutable; } /** - * True if this type is a literal null. + * {@code true} if this type is a literal null. + * + * @return {@code true} if this type is a literal null. */ public boolean isNull() { return false; } /** - * True if this type is a variable-length encoded integer type (either signed or unsigned). + * {@code true} if this type is a variable-length encoded integer type (either signed or unsigned). + * + * @return {@code true} if this type is a variable-length encoded integer type (either signed or unsigned). */ public boolean isVarint() { return false; } /** - * True if this type can be used in the variable-length segment. + * {@code true} if this type can be used in the variable-length segment. + * + * @return {@code true} if this type can be used in the variable-length segment. */ public final boolean allowVariable() { return !this.isFixed(); @@ -114,6 +133,8 @@ public abstract class LayoutType /*implements ILayoutType*/ { /** * The physical layout code used to represent the type within the serialization. + * + * @return the physical layout code used to represent the type within the serialization. */ @Nonnull public LayoutCode layoutCode() { @@ -122,6 +143,8 @@ public abstract class LayoutType /*implements ILayoutType*/ { /** * Human readable name of the type. + * + * @return human readable name of the type. */ @Nonnull public abstract String name(); @@ -129,9 +152,9 @@ public abstract class LayoutType /*implements ILayoutType*/ { /** * Helper for preparing the delete of a sparse field. * - * @param buffer The row to delete from. - * @param edit The parent edit containing the field to delete. - * @param code The expected type of the field. + * @param buffer The row to delete from. + * @param edit The parent edit containing the field to delete. + * @param code The expected type of the field. * @return Success if the delete is permitted, the error code otherwise. */ @Nonnull @@ -339,6 +362,8 @@ public abstract class LayoutType /*implements ILayoutType*/ { /** * If fixed, the fixed size of the type's serialization in bytes, otherwise undefined. + * + * @return If fixed, the fixed size of the type's serialization in bytes, otherwise undefined. */ public int size() { return this.size; @@ -360,10 +385,13 @@ public abstract class LayoutType /*implements ILayoutType*/ { /** * The physical layout type of the field cast to the specified type. + * + * @param a type that implements {@link ILayoutType}. + * @return the physical layout type of the field cast to the specified type. */ @SuppressWarnings("unchecked") public final T typeAs() { - return (T)this; + return (T) this; } public int writeTypeArgument(@Nonnull final RowBuffer buffer, int offset, @Nonnull final TypeArgumentList value) { diff --git a/java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/layouts/LayoutTypePrimitive.java b/java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/layouts/LayoutTypePrimitive.java index 9dce995..21fb63c 100644 --- a/java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/layouts/LayoutTypePrimitive.java +++ b/java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/layouts/LayoutTypePrimitive.java @@ -17,9 +17,9 @@ public abstract class LayoutTypePrimitive extends LayoutType implements ILayo /** * Initializes a new instance of the {@link LayoutTypePrimitive} class. * - * @param code - * @param immutable - * @param size + * @param code the {@link LayoutCode} of this layout type. + * @param immutable indicates whether edits of instances fields with this layout type are permitted. + * @param size the size of fields with this layout type in bytes. */ protected LayoutTypePrimitive(@Nonnull LayoutCode code, boolean immutable, int size) { super(code, immutable, size); @@ -28,12 +28,13 @@ public abstract class LayoutTypePrimitive extends LayoutType implements ILayo /** * Initializes a new instance of the {@link LayoutTypePrimitive} class. * - * @param code - * @param size + * @param code the {@link LayoutCode} of this layout type. + * @param size the size of fields with this layout type in bytes. */ protected LayoutTypePrimitive(LayoutCode code, int size) { super(code, size); } + // TODO: DANOBLE: move methods implemented by the C# code LayoutType to this type from LayoutType // Also: // * Convert LayoutType to a non-generic type (LayoutType, not LayoutType) @@ -81,8 +82,10 @@ public abstract class LayoutTypePrimitive extends LayoutType implements ILayo *

* If a value exists, then it is removed. The remainder of the row is resized to accommodate * a decrease in required space. If no value exists this operation is a no-op. - * @param buffer - * @param edit + * + * @param buffer target {@link RowBuffer}. + * @param edit a {@link RowCursor} that identifies and locates the field to be deleted. + * @return {@link Result#SUCCESS} if the value was deleted; otherwise an error {@link Result}. */ @Nonnull public final Result deleteSparse(RowBuffer buffer, RowCursor edit) { @@ -100,8 +103,13 @@ public abstract class LayoutTypePrimitive extends LayoutType implements ILayo /** * Delete an existing value. *

- * If a value exists, then it is removed. The remainder of the row is resized to accommodate a decrease in - * required space. If no value exists this operation is a no-op. + * If a value exists, then it is removed. The remainder of the row is resized to accommodate a decrease in required + * space. If no value exists this operation is a no-op. + * + * @param buffer the target {@link RowBuffer}. + * @param scope a {@linkplain RowCursor cursor} that identifies and locates the scope of the deletion. + * @param column identifies and locates the value within the scope to be deleted. + * @return {@link Result#SUCCESS} if the value was deleted; otherwise an error {@link Result}. */ @Nonnull public final Result deleteVariable( @@ -159,16 +167,31 @@ public abstract class LayoutTypePrimitive extends LayoutType implements ILayo } @Nonnull - public abstract Result writeFixed(@Nonnull RowBuffer buffer, @Nonnull RowCursor scope, @Nonnull LayoutColumn column, @Nonnull T value); + public abstract Result writeFixed( + @Nonnull RowBuffer buffer, + @Nonnull RowCursor scope, + @Nonnull LayoutColumn column, + @Nonnull T value); @Nonnull - public abstract Result writeSparse(@Nonnull RowBuffer buffer, @Nonnull RowCursor edit, @Nonnull T value); + public abstract Result writeSparse( + @Nonnull RowBuffer buffer, + @Nonnull RowCursor edit, + @Nonnull T value); @Nonnull - public abstract Result writeSparse(@Nonnull RowBuffer buffer, @Nonnull RowCursor edit, @Nonnull T value, @Nonnull UpdateOptions options); + public abstract Result writeSparse( + @Nonnull RowBuffer buffer, + @Nonnull RowCursor edit, + @Nonnull T value, + @Nonnull UpdateOptions options); @Nonnull - public Result writeVariable(@Nonnull RowBuffer buffer, @Nonnull RowCursor scope, @Nonnull LayoutColumn column, @Nonnull T value) { + public Result writeVariable( + @Nonnull RowBuffer buffer, + @Nonnull RowCursor scope, + @Nonnull LayoutColumn column, + @Nonnull T value) { return Result.FAILURE; } } diff --git a/java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/layouts/LayoutTypeScope.java b/java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/layouts/LayoutTypeScope.java index cdc30bb..ccaac8d 100644 --- a/java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/layouts/LayoutTypeScope.java +++ b/java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/layouts/LayoutTypeScope.java @@ -40,9 +40,9 @@ public abstract class LayoutTypeScope extends LayoutType { } /** - * Returns {@code false} to indicate that a {@link LayoutTypeScope} is a variable length, not fixed length layout type + * {@code true} if the {@link LayoutTypeScope} has a fixed-, not variable-length layout type. * - * @return {@code false} + * @return {@code true} if the {@link LayoutTypeScope} has a fixed-, not variable-length layout type. */ @Override public boolean isFixed() { @@ -50,35 +50,45 @@ public abstract class LayoutTypeScope extends LayoutType { } /** - * Returns true if this is a fixed arity scope. + * {@code true} if this is a fixed arity scope. + * + * @return {@code true} if this is a fixed arity scope. */ public boolean isFixedArity() { return this.isFixedArity; } /** - * Returns true if this is an indexed scope. + * {@code true} if this is an indexed scope. + * + * @return {@code true} if this is an indexed scope. */ public boolean isIndexedScope() { return this.isIndexedScope; } /** - * Returns true if this is a sized scope. + * {@code true} if this is a sized scope. + * + * @return {@code true} if this is a sized scope. */ public boolean isSizedScope() { return this.isSizedScope; } /** - * Returns true if this is a typed scope. + * {@code true} if this is a typed scope. + * + * @return {@code true} if this is a typed scope. */ public boolean isTypedScope() { return this.isTypedScope; } /** - * Returns true if the scope's elements cannot be updated directly. + * {@code true} if the scope's elements cannot be updated directly. + * + * @return {@code true} if the scope's elements cannot be updated directly. */ public boolean isUniqueScope() { return this.isUniqueScope; diff --git a/java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/layouts/LayoutUniqueScope.java b/java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/layouts/LayoutUniqueScope.java index 940ce1e..fa34ff4 100644 --- a/java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/layouts/LayoutUniqueScope.java +++ b/java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/layouts/LayoutUniqueScope.java @@ -90,15 +90,18 @@ public abstract class LayoutUniqueScope extends LayoutIndexedScope implements IL * @param buffer The row to move within. * @param destinationScope The parent unique indexed edit into which the field should be moved. * @param sourceEdit The field to be moved. - * @return Success if the field is permitted within the unique index, the error code otherwise. + * @return {@link Result#SUCCESS} if the field is moved; an error {@link Result} otherwise. *

* The source field MUST be a field whose type arguments match the element type of the * destination unique index. - * - * The source field is delete whether the move succeeds or fails. + *

+ * The source field is deleted whether the move succeeds or fails. */ @Nonnull - public final Result moveField(RowBuffer buffer, RowCursor destinationScope, RowCursor sourceEdit) { + public final Result moveField( + @Nonnull final RowBuffer buffer, + @Nonnull final RowCursor destinationScope, + @Nonnull final RowCursor sourceEdit) { return this.moveField(buffer, destinationScope, sourceEdit, UpdateOptions.UPSERT); } diff --git a/java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/layouts/StringTokenizer.java b/java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/layouts/StringTokenizer.java index 82c81fa..61c10c9 100644 --- a/java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/layouts/StringTokenizer.java +++ b/java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/layouts/StringTokenizer.java @@ -83,6 +83,8 @@ public final class StringTokenizer { /** * The number of unique tokens described by the encoding. + * + * @return the number of unique tokens described by the encoding. */ public int count() { return this.count; diff --git a/java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/layouts/TypeArgument.java b/java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/layouts/TypeArgument.java index f1a20b3..da4c560 100644 --- a/java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/layouts/TypeArgument.java +++ b/java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/layouts/TypeArgument.java @@ -22,7 +22,7 @@ public final class TypeArgument { /** * Initializes a new instance of the {@link TypeArgument} struct. * - * @param type The type of the constraint. + * @param type the type of the constraint. */ public TypeArgument(@Nonnull LayoutType type) { checkNotNull(type, "expected non-null type"); @@ -72,6 +72,8 @@ public final class TypeArgument { /** * The physical layout type. + * + * @return the physical layout type. */ public LayoutType type() { return this.type; @@ -79,6 +81,8 @@ public final class TypeArgument { /** * If the type argument is itself generic, then its type arguments. + * + * @return it the type argument is itself generic, then its type arguments. */ public TypeArgumentList typeArgs() { return this.typeArgs; diff --git a/java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/layouts/TypeArgumentList.java b/java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/layouts/TypeArgumentList.java index 0c4c9f2..be164fe 100644 --- a/java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/layouts/TypeArgumentList.java +++ b/java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/layouts/TypeArgumentList.java @@ -30,9 +30,9 @@ public final class TypeArgumentList { private final SchemaId schemaId; /** - * Initializes a new instance of the {@link TypeArgumentList} class + * Initializes a new instance of the {@link TypeArgumentList} class. * - * @param args arguments in the list + * @param args arguments in the list. */ public TypeArgumentList(@Nonnull final TypeArgument... args) { checkNotNull(args); @@ -109,6 +109,8 @@ public final class TypeArgumentList { /** * For UDT fields, the schema id of the nested layout. + * + * @return for UDT fields, the Schema ID of the nested layout. */ public SchemaId schemaId() { return this.schemaId; diff --git a/java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/schemas/MapPropertyType.java b/java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/schemas/MapPropertyType.java index cbab255..02e3c33 100644 --- a/java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/schemas/MapPropertyType.java +++ b/java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/schemas/MapPropertyType.java @@ -18,6 +18,8 @@ public class MapPropertyType extends ScopePropertyType { /** * (Optional) type of the keys of the map, if a typed map, otherwise {@code null}. + * + * @return type of the keys of the map, if a type map, otherwise {@code null}. */ public final PropertyType keys() { return this.keys; @@ -30,6 +32,8 @@ public class MapPropertyType extends ScopePropertyType { /** * (Optional) type of the values of the map, if a typed map, otherwise {@code null}. + * + * @return type of the values of the map, if a typed map, otherwise {@code null}. */ public final PropertyType values() { return this.values; diff --git a/java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/schemas/ObjectPropertyType.java b/java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/schemas/ObjectPropertyType.java index ae2e9bf..fed6462 100644 --- a/java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/schemas/ObjectPropertyType.java +++ b/java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/schemas/ObjectPropertyType.java @@ -26,6 +26,8 @@ public class ObjectPropertyType extends ScopePropertyType { /** * A list of zero or more property definitions that define the columns within the schema. + * + * @return a list of zero or more property definitions that define the columns within the schema. */ public final List properties() { return this.properties; diff --git a/java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/schemas/PrimarySortKey.java b/java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/schemas/PrimarySortKey.java index 19a72ff..aa18a48 100644 --- a/java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/schemas/PrimarySortKey.java +++ b/java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/schemas/PrimarySortKey.java @@ -14,7 +14,10 @@ public class PrimarySortKey { /** * The logical path of the referenced property. + *

* Primary keys MUST refer to properties defined within the same {@link Schema}. + * + * @return the logical path of the referenced property. */ public final SortDirection direction() { return this.direction; @@ -27,7 +30,10 @@ public class PrimarySortKey { /** * The logical path of the referenced property. + *

* Primary keys MUST refer to properties defined within the same {@link Schema}. + * + * @return the logical path of the referenced property. */ public final String path() { return this.path; diff --git a/java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/schemas/PrimitivePropertyType.java b/java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/schemas/PrimitivePropertyType.java index 5cf560d..d9aed1c 100644 --- a/java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/schemas/PrimitivePropertyType.java +++ b/java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/schemas/PrimitivePropertyType.java @@ -23,6 +23,8 @@ public class PrimitivePropertyType extends PropertyType { * The maximum allowable length in bytes. *

* This annotation is only valid for non-fixed length types. A value of 0 means the maximum allowable length. + * + * @return the maximum allowable length in bytes. */ public final int length() { return this.length; @@ -35,6 +37,8 @@ public class PrimitivePropertyType extends PropertyType { /** * Storage requirements of the property. + * + * @return storage requirements of the property. */ public final StorageKind storage() { return this.storage; diff --git a/java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/schemas/Schema.java b/java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/schemas/Schema.java index 84b1a65..eb855b3 100644 --- a/java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/schemas/Schema.java +++ b/java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/schemas/Schema.java @@ -138,7 +138,9 @@ public class Schema { } /** - * Schema-wide operations. + * Schema-wide options. + * + * @return schema-wide options. */ public final SchemaOptions options() { return this.options; @@ -215,6 +217,8 @@ public class Schema { * The unique identifier for a schema. *

* Identifiers must be unique within the scope of the database in which they are used. + * + * @return the unique identifier for a schema. */ public final SchemaId schemaId() { return this.id; @@ -226,13 +230,15 @@ public class Schema { } /** - * An (optional) list of zero or more logical paths that hold data shared by all documents with same partition key. + * A list of zero or more logical paths that hold data shared by all documents with same partition key. + *

* All paths referenced MUST map to a property within the schema. - * + *

* This field is never null. * - * @return + * @return A list of zero or more logical paths that hold data shared by all documents with same partition key. */ + @Nonnull public final List staticKeys() { return this.staticKeys; } @@ -256,6 +262,8 @@ public class Schema { * The type of this schema. *

* This value MUST be {@link TypeKind#SCHEMA}. + * + * @return the type of this schema. */ public final TypeKind type() { return this.type; @@ -268,6 +276,8 @@ public class Schema { /** * The version of the HybridRow Schema Definition Language used to encode this schema. + * + * @return the version of the HybridRow Schema Definition Language used to encode this schema. */ public final SchemaLanguageVersion version() { return this.version; diff --git a/java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/schemas/SchemaHash.java b/java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/schemas/SchemaHash.java index 650c7ce..1eb42e4 100644 --- a/java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/schemas/SchemaHash.java +++ b/java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/schemas/SchemaHash.java @@ -18,7 +18,7 @@ public final class SchemaHash { /** * Computes the logical hash for a logical schema. * - * @param namespace The namespace within which is defined. + * @param namespace The namespace within which {@code schema} is defined. * @param schema The logical schema to compute the hash of. * @param seed The seed to initialized the hash function. * @return The logical 128-bit hash as a two-tuple (low, high). diff --git a/java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/schemas/SchemaOptions.java b/java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/schemas/SchemaOptions.java index 7dbe4db..4db307e 100644 --- a/java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/schemas/SchemaOptions.java +++ b/java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/schemas/SchemaOptions.java @@ -13,8 +13,11 @@ public class SchemaOptions { private boolean enablePropertyLevelTimestamp; /** - * If the is value true, then disables prefixing the system properties with a prefix __sys_ - * for reserved properties owned by the store layer. + * {@code true} if prefixing system properties with a prefix of {@code "__sys_"} is disabled. + *

+ * The system property prefix is required to distinguish properties owned by the store layer. + * + * @return {@code true} if prefixing system properties with a prefix of {@code "__sys_"} is disabled. */ public final boolean disableSystemPrefix() { return this.disableSystemPrefix; @@ -25,7 +28,7 @@ public class SchemaOptions { } /** - * If true then structural schema validation is enabled. + * {@code true} if structural schema validation is enabled. *

* When structural schema validation is enabled then attempting to store an unschematized * path in the row, or a value whose type does not conform to the type constraints defined for that @@ -33,6 +36,8 @@ public class SchemaOptions { * NOT enabled, then storing an unschematized path or non-confirming value will lead to a sparse * column override of the path. The value will be stored (and any existing value at that path will be * overwritten). No error will be given. + * + * @return {@code true} if structural schema validation is enabled. */ public final boolean disallowUnschematized() { return this.disallowUnschematized; @@ -43,10 +48,13 @@ public class SchemaOptions { } /** - * If set and has the value true, then triggers behavior in the Schema that acts based on property - * level timestamps. In Cassandra, this means that new columns are added for each top level property - * that has values of the client side timestamp. This is then used in conflict resolution to independently - * resolve each property based on the timestamp value of that property. + * {@code true} if behavior in the Schema that acts based on property level timestamps is triggered. + *

+ * In Cassandra, this means that new columns are added for each top level property that has values of the client + * side timestamp. This is then used in conflict resolution to independently resolve each property based on the + * timestamp value of that property. + * + * @return {@code true} if behavior in the Schema that acts based on property level timestamps is triggered. */ public final boolean enablePropertyLevelTimestamp() { return this.enablePropertyLevelTimestamp; diff --git a/java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/schemas/ScopePropertyType.java b/java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/schemas/ScopePropertyType.java index e05754f..d8c68e6 100644 --- a/java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/schemas/ScopePropertyType.java +++ b/java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/schemas/ScopePropertyType.java @@ -8,8 +8,11 @@ public abstract class ScopePropertyType extends PropertyType { private boolean immutable; /** - * True if the property's child elements cannot be mutated in place. + * {@code true} if the property's child elements cannot be mutated in place. + *

* Immutable properties can still be replaced in their entirety. + * + * @return {@code true} if the property's child elements cannot be mutated in place. */ public final boolean immutable() { return this.immutable; diff --git a/java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/schemas/StaticKey.java b/java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/schemas/StaticKey.java index 9b40a9c..ede2e4a 100644 --- a/java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/schemas/StaticKey.java +++ b/java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/schemas/StaticKey.java @@ -14,6 +14,8 @@ public class StaticKey { * The logical path of the referenced property. *

* Static path MUST refer to properties defined within the same {@link Schema}. + * + * @return the logical path of the referenced property. */ public final String path() { return this.path; diff --git a/java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/schemas/TuplePropertyType.java b/java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/schemas/TuplePropertyType.java index edd08d5..e7571ae 100644 --- a/java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/schemas/TuplePropertyType.java +++ b/java/src/main/java/com/azure/data/cosmos/serialization/hybridrow/schemas/TuplePropertyType.java @@ -24,10 +24,9 @@ public class TuplePropertyType extends ScopePropertyType { /** * Types of the elements of the tuple in element order. - * @return + * + * @return types of the elements of the tuple in element order. */ - // TODO: C# TO JAVA CONVERTER: Java annotations will not correspond to .NET attributes: - //ORIGINAL LINE: [JsonProperty(PropertyName = "items")] public List Items public final List items() { return this.items; }