Skip to content

Commit

Permalink
Fixing javadoc error (opensearch-project#9976)
Browse files Browse the repository at this point in the history
* Fixing javadoc error
fixing javadoc error and warning
javadoc for org.opensearch.core.indices.breaker
javadoc for org.opensearch.core.index.shard.ShardId
javadoc for org.opensearch.core.index.Index
fixing a mishap in formatting rule
fixing javadoc of org.opensearch.cli.Terminal

Signed-off-by: Laurent Laborde <[email protected]>

* removing unsupported @ImplNote

Signed-off-by: Laurent Laborde <[email protected]>

* Update libs/common/src/main/java/org/opensearch/common/collect/Iterators.java

Co-authored-by: Andriy Redko <[email protected]>
Signed-off-by: Laurent Laborde <[email protected]>

* Update libs/compress/src/main/java/org/opensearch/compress/ZstdCompressor.java

Co-authored-by: Andriy Redko <[email protected]>
Signed-off-by: Laurent Laborde <[email protected]>

* Apply suggestions from code review

Co-authored-by: Andriy Redko <[email protected]>
Signed-off-by: Laurent Laborde <[email protected]>

* Apply suggestions from code review

Co-authored-by: Andriy Redko <[email protected]>
Signed-off-by: Laurent Laborde <[email protected]>

* Apply suggestions from code review

Co-authored-by: Andriy Redko <[email protected]>
Signed-off-by: Laurent Laborde <[email protected]>

* Apply suggestions from code review

Co-authored-by: Andriy Redko <[email protected]>
Signed-off-by: Laurent Laborde <[email protected]>

* Update CollectionUtils.java

Signed-off-by: Laurent Laborde <[email protected]>

* fixing javadoc warnings

Signed-off-by: Laurent Laborde <[email protected]>

* remove useless p tag

Signed-off-by: Laurent Laborde <[email protected]>

* removing a p tag

Co-authored-by: Andriy Redko <[email protected]>
Signed-off-by: Laurent Laborde <[email protected]>

* proper capitalization

Co-authored-by: Andriy Redko <[email protected]>
Signed-off-by: Laurent Laborde <[email protected]>

---------

Signed-off-by: Laurent Laborde <[email protected]>
Co-authored-by: Andriy Redko <[email protected]>
  • Loading branch information
ker2x and reta authored Sep 14, 2023
1 parent 28724ce commit 71f6136
Show file tree
Hide file tree
Showing 16 changed files with 512 additions and 30 deletions.
Original file line number Diff line number Diff line change
Expand Up @@ -41,6 +41,15 @@
* @opensearch.internal
*/
public class Iterators {

/**
* Concat iterators
*
* @param iterators the iterators to concat
* @param <T> the type of iterator
* @return a new {@link ConcatenatedIterator}
* @throws NullPointerException if iterators is null
*/
public static <T> Iterator<T> concat(Iterator<? extends T>... iterators) {
if (iterators == null) {
throw new NullPointerException("iterators");
Expand Down Expand Up @@ -71,6 +80,11 @@ static class ConcatenatedIterator<T> implements Iterator<T> {
this.iterators = iterators;
}

/**
* Returns {@code true} if the iteration has more elements. (In other words, returns {@code true} if {@link #next} would return an
* element rather than throwing an exception.)
* @return {@code true} if the iteration has more elements
*/
@Override
public boolean hasNext() {
boolean hasNext = false;
Expand All @@ -81,6 +95,11 @@ public boolean hasNext() {
return hasNext;
}

/**
* Returns the next element in the iteration.
* @return the next element in the iteration
* @throws NoSuchElementException if the iteration has no more elements
*/
@Override
public T next() {
if (!hasNext()) {
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -30,10 +30,13 @@
* @opensearch.experimental - class methods might change
*/
public class ZstdCompressor implements Compressor {
// An arbitrary header that we use to identify compressed streams
// It needs to be different from other compressors and to not be specific
// enough so that no stream starting with these bytes could be detected as
// a XContent

/**
* An arbitrary header that we use to identify compressed streams
* It needs to be different from other compressors and to not be specific
* enough so that no stream starting with these bytes could be detected as
* a XContent
* */
private static final byte[] HEADER = new byte[] { 'Z', 'S', 'T', 'D', '\0' };

/**
Expand All @@ -44,10 +47,20 @@ public class ZstdCompressor implements Compressor {
@PublicApi(since = "2.10.0")
public static final String NAME = "ZSTD";

/**
* The compression level for {@link ZstdOutputStreamNoFinalizer}
*/
private static final int LEVEL = 3;

/** The buffer size for {@link BufferedInputStream} and {@link BufferedOutputStream}
*/
private static final int BUFFER_SIZE = 4096;

/**
* Compares the given bytes with the {@link ZstdCompressor#HEADER} of a compressed stream
* @param bytes the bytes to compare to ({@link ZstdCompressor#HEADER})
* @return true if the bytes are the {@link ZstdCompressor#HEADER}, false otherwise
*/
@Override
public boolean isCompressed(BytesReference bytes) {
if (bytes.length() < HEADER.length) {
Expand All @@ -61,11 +74,22 @@ public boolean isCompressed(BytesReference bytes) {
return true;
}

/**
* Returns the length of the {@link ZstdCompressor#HEADER}
* @return the {@link ZstdCompressor#HEADER} length
*/
@Override
public int headerLength() {
return HEADER.length;
}

/**
* Returns a new {@link ZstdInputStreamNoFinalizer} from the given compressed {@link InputStream}
* @param in the compressed {@link InputStream}
* @return a new {@link ZstdInputStreamNoFinalizer} from the given compressed {@link InputStream}
* @throws IOException if an I/O error occurs
* @throws IllegalArgumentException if the input stream is not compressed with ZSTD
*/
@Override
public InputStream threadLocalInputStream(InputStream in) throws IOException {
final byte[] header = in.readNBytes(HEADER.length);
Expand All @@ -75,17 +99,36 @@ public InputStream threadLocalInputStream(InputStream in) throws IOException {
return new ZstdInputStreamNoFinalizer(new BufferedInputStream(in, BUFFER_SIZE), RecyclingBufferPool.INSTANCE);
}

/**
* Returns a new {@link ZstdOutputStreamNoFinalizer} from the given {@link OutputStream}
* @param out the {@link OutputStream}
* @return a new {@link ZstdOutputStreamNoFinalizer} from the given {@link OutputStream}
* @throws IOException if an I/O error occurs
*/
@Override
public OutputStream threadLocalOutputStream(OutputStream out) throws IOException {
out.write(HEADER);
return new ZstdOutputStreamNoFinalizer(new BufferedOutputStream(out, BUFFER_SIZE), RecyclingBufferPool.INSTANCE, LEVEL);
}

/**
* Always throws an {@link UnsupportedOperationException} as ZSTD compression is supported only for snapshotting
* @param bytesReference a reference to the bytes to uncompress
* @return always throws an exception
* @throws UnsupportedOperationException if the method is called
* @throws IOException is never thrown
*/
@Override
public BytesReference uncompress(BytesReference bytesReference) throws IOException {
throw new UnsupportedOperationException("ZSTD compression is supported only for snapshotting");
}

/**
* Always throws an {@link UnsupportedOperationException} as ZSTD compression is supported only for snapshotting
* @param bytesReference a reference to the bytes to compress
* @return always throws an exception
* @throws UnsupportedOperationException if the method is called
*/
@Override
public BytesReference compress(BytesReference bytesReference) throws IOException {
throw new UnsupportedOperationException("ZSTD compression is supported only for snapshotting");
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -71,17 +71,23 @@ public interface CircuitBreaker {

/**
* The type of breaker
*
* can be {@link #MEMORY}, {@link #PARENT}, or {@link #NOOP}
* @opensearch.internal
*/
enum Type {
// A regular or ChildMemoryCircuitBreaker
/** A regular or ChildMemoryCircuitBreaker */
MEMORY,
// A special parent-type for the hierarchy breaker service
/** A special parent-type for the hierarchy breaker service */
PARENT,
// A breaker where every action is a noop, it never breaks
/** A breaker where every action is a noop, it never breaks */
NOOP;

/**
* Converts string (case-insensitive) to breaker {@link Type}
* @param value "noop", "parent", or "memory" (case-insensitive)
* @return the breaker {@link Type}
* @throws IllegalArgumentException if value is not "noop", "parent", or "memory"
*/
public static Type parseValue(String value) {
switch (value.toLowerCase(Locale.ROOT)) {
case "noop":
Expand All @@ -98,13 +104,13 @@ public static Type parseValue(String value) {

/**
* The breaker durability
*
* can be {@link #TRANSIENT} or {@link #PERMANENT}
* @opensearch.internal
*/
enum Durability {
// The condition that tripped the circuit breaker fixes itself eventually.
/** The condition that tripped the circuit breaker fixes itself eventually. */
TRANSIENT,
// The condition that tripped the circuit breaker requires manual intervention.
/** The condition that tripped the circuit breaker requires manual intervention. */
PERMANENT
}

Expand All @@ -120,11 +126,14 @@ enum Durability {
* @param bytes number of bytes to add
* @param label string label describing the bytes being added
* @return the number of "used" bytes for the circuit breaker
* @throws CircuitBreakingException if the breaker tripped
*/
double addEstimateBytesAndMaybeBreak(long bytes, String label) throws CircuitBreakingException;

/**
* Adjust the circuit breaker without tripping
* @param bytes number of bytes to add
* @return the number of "used" bytes for the circuit breaker
*/
long addWithoutBreaking(long bytes);

Expand Down Expand Up @@ -154,7 +163,10 @@ enum Durability {
String getName();

/**
* @return whether a tripped circuit breaker will reset itself (transient) or requires manual intervention (permanent).
* Returns the {@link Durability} of this breaker
* @return whether a tripped circuit breaker will
* reset itself ({@link Durability#TRANSIENT})
* or requires manual intervention ({@link Durability#PERMANENT}).
*/
Durability getDurability();

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -46,8 +46,11 @@
*/
public class CircuitBreakingException extends OpenSearchException {

/** The number of bytes wanted */
private final long bytesWanted;
/** The circuit breaker limit */
private final long byteLimit;
/** The {@link CircuitBreaker.Durability} of the circuit breaker */
private final CircuitBreaker.Durability durability;

public CircuitBreakingException(StreamInput in) throws IOException {
Expand Down Expand Up @@ -88,6 +91,7 @@ public CircuitBreaker.Durability getDurability() {
return durability;
}

/** Always returns {@link RestStatus#TOO_MANY_REQUESTS} */
@Override
public RestStatus status() {
return RestStatus.TOO_MANY_REQUESTS;
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -33,65 +33,120 @@
package org.opensearch.core.common.breaker;

/**
* A CircuitBreaker that doesn't increment or adjust, and all operations are
* basically noops
*
* A {@link CircuitBreaker} that doesn't increment or adjust, and all operations are
* basically noops.
* It never trips, limit is always -1, always returns 0 for all metrics.
* @opensearch.internal
*/
public class NoopCircuitBreaker implements CircuitBreaker {
public static final int LIMIT = -1;

/** The limit of this breaker is always -1 */
public static final int LIMIT = -1;
/** Name of this breaker */
private final String name;

/**
* Creates a new NoopCircuitBreaker (that never trip) with the given name
* @param name the name of this breaker
*/
public NoopCircuitBreaker(String name) {
this.name = name;
}

/**
* This is a noop, a noop breaker never trip
* @param fieldName name of this noop breaker
* @param bytesNeeded bytes needed
*/
@Override
public void circuitBreak(String fieldName, long bytesNeeded) {
// noop
}

/**
* This is a noop, always return 0 and never throw/trip
* @param bytes number of bytes to add
* @param label string label describing the bytes being added
* @return always return 0
* @throws CircuitBreakingException never thrown
*/
@Override
public double addEstimateBytesAndMaybeBreak(long bytes, String label) throws CircuitBreakingException {
return 0;
}

/**
* This is a noop, nothing is added, always return 0
* @param bytes number of bytes to add (ignored)
* @return always return 0
*/
@Override
public long addWithoutBreaking(long bytes) {
return 0;
}

/**
* This is a noop, always return 0
* @return always return 0
*/
@Override
public long getUsed() {
return 0;
}

/**
* A noop breaker have a constant limit of -1
* @return always return -1
*/
@Override
public long getLimit() {
return LIMIT;
}

/**
* A noop breaker have no overhead, always return 0
* @return always return 0
*/
@Override
public double getOverhead() {
return 0;
}

/**
* A noop breaker never trip, always return 0
* @return always return 0
*/
@Override
public long getTrippedCount() {
return 0;
}

/**
* return the name of this breaker
* @return the name of this breaker
*/
@Override
public String getName() {
return this.name;
}

/**
* A noop breaker {@link Durability} is always {@link Durability#PERMANENT}
* @return always return {@link Durability#PERMANENT }
*/
@Override
public Durability getDurability() {
return Durability.PERMANENT;
}

/**
* Limit and overhead are constant for a noop breaker.
* this is a noop.
* @param limit the desired limit (ignored)
* @param overhead the desired overhead (ignored)
*/
@Override
public void setLimitAndOverhead(long limit, double overhead) {}
public void setLimitAndOverhead(long limit, double overhead) {
// noop
}
}
Original file line number Diff line number Diff line change
Expand Up @@ -49,7 +49,8 @@
*/
public abstract class AbstractBytesReference implements BytesReference {

private Integer hash = null; // we cache the hash of this reference since it can be quite costly to re-calculated it
/** we cache the hash of this reference since it can be quite costly to re-calculated it */
private Integer hash = null;
private static final int MAX_UTF16_LENGTH = Integer.MAX_VALUE >> 1;

@Override
Expand Down
Loading

0 comments on commit 71f6136

Please sign in to comment.