Spring/spring-framework
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Improve javadoc on reactive classes

Browse Source 
Ensure type-level Javadoc in every class, comply with guidelines for
80 char on Javadoc, and minor polish.
This commit is contained in:
Rossen Stoyanchev
2016-07-18 08:46:47 -04:00
parent 7a0c2422c6
commit 3e096ce810
62 changed files with 255 additions and 161 deletions
Download Patch File Download Diff File Expand all files Collapse all files

11
spring-core/src/main/java/org/springframework/core/codec/AbstractDecoder.java
View File

@@ -28,6 +28,8 @@ import org.springframework.core.io.buffer.DataBuffer;
import org.springframework.util.MimeType;
/**
* Abstract base class for {@link Decoder} implementations.
*
* @author Sebastien Deleuze
* @author Arjen Poutsma
* @since 5.0
@@ -36,6 +38,7 @@ public abstract class AbstractDecoder<T> implements Decoder<T> {
private List<MimeType> decodableMimeTypes = Collections.emptyList();
protected AbstractDecoder(MimeType... supportedMimeTypes) {
this.decodableMimeTypes = Arrays.asList(supportedMimeTypes);
}
@@ -51,12 +54,14 @@ public abstract class AbstractDecoder<T> implements Decoder<T> {
if (mimeType == null) {
return true;
}
return this.decodableMimeTypes.stream().
anyMatch(mt -> mt.isCompatibleWith(mimeType));
return this.decodableMimeTypes.stream().anyMatch(m -> m.isCompatibleWith(mimeType));
}
@Override
public Mono<T> decodeToMono(Publisher<DataBuffer> inputStream, ResolvableType elementType, MimeType mimeType, Object... hints) {
public Mono<T> decodeToMono(Publisher<DataBuffer> inputStream, ResolvableType elementType,
MimeType mimeType, Object... hints) {
throw new UnsupportedOperationException();
}
}

6
spring-core/src/main/java/org/springframework/core/codec/AbstractEncoder.java
View File

@@ -24,6 +24,8 @@ import org.springframework.core.ResolvableType;
import org.springframework.util.MimeType;
/**
* Abstract base class for {@link Decoder} implementations.
*
* @author Sebastien Deleuze
* @author Arjen Poutsma
* @since 5.0
@@ -32,6 +34,7 @@ public abstract class AbstractEncoder<T> implements Encoder<T> {
private List<MimeType> encodableMimeTypes = Collections.emptyList();
protected AbstractEncoder(MimeType... supportedMimeTypes) {
this.encodableMimeTypes = Arrays.asList(supportedMimeTypes);
}
@@ -47,8 +50,7 @@ public abstract class AbstractEncoder<T> implements Encoder<T> {
if (mimeType == null) {
return true;
}
return this.encodableMimeTypes.stream().
anyMatch(mt -> mt.isCompatibleWith(mimeType));
return this.encodableMimeTypes.stream().anyMatch(m -> m.isCompatibleWith(mimeType));
}
}

11
spring-core/src/main/java/org/springframework/core/codec/AbstractSingleValueEncoder.java
View File

@@ -25,21 +25,25 @@ import org.springframework.core.io.buffer.DataBufferFactory;
import org.springframework.util.MimeType;
/**
* Abstract base class for {@link org.springframework.core.codec.Encoder} classes that
* can only deal with a single value.
* Abstract base class for {@link org.springframework.core.codec.Encoder}
* classes that can only deal with a single value.
*
* @author Arjen Poutsma
* @since 5.0
*/
public abstract class AbstractSingleValueEncoder<T> extends AbstractEncoder<T> {
public AbstractSingleValueEncoder(MimeType... supportedMimeTypes) {
super(supportedMimeTypes);
}
@Override
public final Flux<DataBuffer> encode(Publisher<? extends T> inputStream,
DataBufferFactory bufferFactory, ResolvableType elementType, MimeType mimeType,
Object... hints) {
return Flux.from(inputStream).
take(1).
concatMap(t -> {
@@ -53,7 +57,7 @@ public abstract class AbstractSingleValueEncoder<T> extends AbstractEncoder<T> {
}
/**
* Encodes {@code T} to an output {@link DataBuffer} stream.
* Encode {@code T} to an output {@link DataBuffer} stream.
* @param t the value to process
* @param dataBufferFactory a buffer factory used to create the output
* @param type the stream element type to process
@@ -65,5 +69,4 @@ public abstract class AbstractSingleValueEncoder<T> extends AbstractEncoder<T> {
protected abstract Flux<DataBuffer> encode(T t, DataBufferFactory dataBufferFactory,
ResolvableType type, MimeType mimeType, Object... hints) throws Exception;
}

3
spring-core/src/main/java/org/springframework/core/codec/ByteBufferDecoder.java
View File

@@ -28,6 +28,8 @@ import org.springframework.util.MimeType;
import org.springframework.util.MimeTypeUtils;
/**
* Decoder for {@link ByteBuffer}s.
*
* @author Sebastien Deleuze
* @author Arjen Poutsma
* @since 5.0
@@ -49,6 +51,7 @@ public class ByteBufferDecoder extends AbstractDecoder<ByteBuffer> {
@Override
public Flux<ByteBuffer> decode(Publisher<DataBuffer> inputStream, ResolvableType elementType,
MimeType mimeType, Object... hints) {
return Flux.from(inputStream).map((dataBuffer) -> {
ByteBuffer copy = ByteBuffer.allocate(dataBuffer.readableByteCount());
copy.put(dataBuffer.asByteBuffer());

3
spring-core/src/main/java/org/springframework/core/codec/ByteBufferEncoder.java
View File

@@ -28,11 +28,14 @@ import org.springframework.util.MimeType;
import org.springframework.util.MimeTypeUtils;
/**
* Encoder for {@link ByteBuffer}s.
*
* @author Sebastien Deleuze
* @since 5.0
*/
public class ByteBufferEncoder extends AbstractEncoder<ByteBuffer> {
public ByteBufferEncoder() {
super(MimeTypeUtils.ALL);
}

15
spring-core/src/main/java/org/springframework/core/codec/ResourceDecoder.java
View File

@@ -32,17 +32,19 @@ import org.springframework.util.MimeType;
import org.springframework.util.MimeTypeUtils;
/**
* A decoder for {@link Resource}s.
* Decoder for {@link Resource}s.
*
* @author Arjen Poutsma
* @since 5.0
*/
public class ResourceDecoder extends AbstractDecoder<Resource> {
public ResourceDecoder() {
super(MimeTypeUtils.ALL);
}
@Override
public boolean canDecode(ResolvableType elementType, MimeType mimeType, Object... hints) {
Class<?> clazz = elementType.getRawClass();
@@ -54,6 +56,7 @@ public class ResourceDecoder extends AbstractDecoder<Resource> {
@Override
public Flux<Resource> decode(Publisher<DataBuffer> inputStream, ResolvableType elementType,
MimeType mimeType, Object... hints) {
Class<?> clazz = elementType.getRawClass();
Mono<byte[]> byteArray = Flux.from(inputStream).
@@ -67,17 +70,13 @@ public class ResourceDecoder extends AbstractDecoder<Resource> {
if (InputStreamResource.class.equals(clazz)) {
return Flux.from(byteArray.
map(ByteArrayInputStream::new).
map(InputStreamResource::new));
return Flux.from(byteArray.map(ByteArrayInputStream::new).map(InputStreamResource::new));
}
else if (clazz.isAssignableFrom(ByteArrayResource.class)) {
return Flux.from(byteArray.
map(ByteArrayResource::new));
return Flux.from(byteArray.map(ByteArrayResource::new));
}
else {
return Flux.error(new IllegalStateException(
"Unsupported resource class: " + clazz));
return Flux.error(new IllegalStateException("Unsupported resource class: " + clazz));
}
}
}

13
spring-core/src/main/java/org/springframework/core/codec/ResourceEncoder.java
View File

@@ -32,7 +32,8 @@ import org.springframework.util.MimeTypeUtils;
import org.springframework.util.StreamUtils;
/**
* An encoder for {@link Resource}s.
* Encoder for {@link Resource}s.
*
* @author Arjen Poutsma
* @since 5.0
*/
@@ -40,8 +41,10 @@ public class ResourceEncoder extends AbstractSingleValueEncoder<Resource> {
public static final int DEFAULT_BUFFER_SIZE = StreamUtils.BUFFER_SIZE;
private final int bufferSize;
public ResourceEncoder() {
this(DEFAULT_BUFFER_SIZE);
}
@@ -52,17 +55,17 @@ public class ResourceEncoder extends AbstractSingleValueEncoder<Resource> {
this.bufferSize = bufferSize;
}
@Override
public boolean canEncode(ResolvableType elementType, MimeType mimeType, Object... hints) {
Class<?> clazz = elementType.getRawClass();
return (super.canEncode(elementType, mimeType, hints) &&
Resource.class.isAssignableFrom(clazz));
return (super.canEncode(elementType, mimeType, hints) && Resource.class.isAssignableFrom(clazz));
}
@Override
protected Flux<DataBuffer> encode(Resource resource,
DataBufferFactory dataBufferFactory,
protected Flux<DataBuffer> encode(Resource resource, DataBufferFactory dataBufferFactory,
ResolvableType type, MimeType mimeType, Object... hints) throws IOException {
InputStream is = resource.getInputStream();
return DataBufferUtils.read(is, dataBufferFactory, bufferSize);
}

6
spring-core/src/main/java/org/springframework/core/codec/StringEncoder.java
View File

@@ -38,6 +38,7 @@ public class StringEncoder extends AbstractEncoder<String> {
public static final Charset DEFAULT_CHARSET = StandardCharsets.UTF_8;
public StringEncoder() {
super(new MimeType("text", "plain", DEFAULT_CHARSET));
}
@@ -51,8 +52,9 @@ public class StringEncoder extends AbstractEncoder<String> {
@Override
public Flux<DataBuffer> encode(Publisher<? extends String> inputStream,
DataBufferFactory bufferFactory, ResolvableType elementType, MimeType mimeType,
Object... hints) {
DataBufferFactory bufferFactory, ResolvableType elementType,
MimeType mimeType, Object... hints) {
Charset charset;
if (mimeType != null && mimeType.getCharset() != null) {
charset = mimeType.getCharset();

5
spring-core/src/main/java/org/springframework/core/convert/support/MonoToCompletableFutureConverter.java
View File

@@ -27,11 +27,15 @@ import org.springframework.core.convert.TypeDescriptor;
import org.springframework.core.convert.converter.GenericConverter;
/**
* Converter to adapt {@link CompletableFuture} to Reactive Streams and
* Reactor {@link Mono}.
*
* @author Sebastien Deleuze
* @since 5.0
*/
public class MonoToCompletableFutureConverter implements GenericConverter {
@Override
public Set<GenericConverter.ConvertiblePair> getConvertibleTypes() {
Set<GenericConverter.ConvertiblePair> pairs = new LinkedHashSet<>(2);
@@ -40,6 +44,7 @@ public class MonoToCompletableFutureConverter implements GenericConverter {
return pairs;
}
@Override
public Object convert(Object source, TypeDescriptor sourceType, TypeDescriptor targetType) {
if (source == null) {

3
spring-core/src/main/java/org/springframework/core/convert/support/ReactorToRxJava1Converter.java
View File

@@ -31,6 +31,9 @@ import org.springframework.core.convert.TypeDescriptor;
import org.springframework.core.convert.converter.GenericConverter;
/**
* Converter to adapt RxJava1 {@link Observable}, {@link Single}, and
* {@link Completable} to Reactive Streams and Reactor types.
*
* @author Stephane Maldini
* @author Sebastien Deleuze
* @since 5.0

18
spring-core/src/main/java/org/springframework/core/io/buffer/DataBufferFactory.java
View File

@@ -19,8 +19,8 @@ package org.springframework.core.io.buffer;
import java.nio.ByteBuffer;
/**
* A factory for {@link DataBuffer}s, allowing for allocation and wrapping of data
* buffers.
* A factory for {@link DataBuffer}s,allowing for allocation and wrapping of
* data buffers.
*
* @author Arjen Poutsma
* @see DataBuffer
@@ -29,22 +29,24 @@ import java.nio.ByteBuffer;
public interface DataBufferFactory {
/**
* Allocates a data buffer of a default initial capacity. Depending on the underlying
* implementation and its configuration, this will be heap-based or direct buffer.
* Allocate a data buffer of a default initial capacity. Depending on the
* underlying implementation and its configuration, this will be heap-based
* or direct buffer.
* @return the allocated buffer
*/
DataBuffer allocateBuffer();
/**
* Allocates a data buffer of the given initial capacity. Depending on the underlying
* implementation and its configuration, this will be heap-based or direct buffer.
* @param initialCapacity the initial capacity of the buffer to allocateBuffer
* Allocate a data buffer of the given initial capacity. Depending on the
* underlying implementation and its configuration, this will be heap-based
* or direct buffer.
* @param initialCapacity the initial capacity of the buffer to allocate
* @return the allocated buffer
*/
DataBuffer allocateBuffer(int initialCapacity);
/**
* Wraps the given {@link ByteBuffer} in a {@code DataBuffer}.
* Wrap the given {@link ByteBuffer} in a {@code DataBuffer}.
* @param byteBuffer the NIO byte buffer to wrap
* @return the wrapped buffer
*/

5
spring-core/src/main/java/org/springframework/core/io/buffer/DefaultDataBuffer.java
View File

@@ -47,8 +47,9 @@ public class DefaultDataBuffer implements DataBuffer {
private int writePosition;
/**
* Creates a new {@code DefaultDataBuffer} based on the given {@code ByteBuffer}. Both
* reading and writing position of this buffer are based on the current {@linkplain
* Create a new {@code DefaultDataBuffer} based on the given
* {@code ByteBuffer}. Both reading and writing position of this buffer are
* based on the current {@linkplain
* ByteBuffer#position() position} of the given buffer.
* @param byteBuffer the buffer to base this buffer on
*/

26
spring-core/src/main/java/org/springframework/core/io/buffer/DefaultDataBufferFactory.java
View File

@@ -22,8 +22,8 @@ import org.springframework.util.Assert;
/**
* Default implementation of the {@code DataBufferFactory} interface. Allows for
* specification of the default initial capacity at construction time, as well as whether
* heap-based or direct buffers are to be preferred.
* specification of the default initial capacity at construction time, as well
* as whether heap-based or direct buffers are to be preferred.
*
* @author Arjen Poutsma
* @since 5.0
@@ -42,6 +42,7 @@ public class DefaultDataBufferFactory implements DataBufferFactory {
private final int defaultInitialCapacity;
/**
* Creates a new {@code DefaultDataBufferFactory} with default settings.
*/
@@ -50,21 +51,23 @@ public class DefaultDataBufferFactory implements DataBufferFactory {
}
/**
* Creates a new {@code DefaultDataBufferFactory}, indicating whether direct buffers
* should be created by {@link #allocateBuffer()} and {@link #allocateBuffer(int)}.
* @param preferDirect {@code true} if direct buffers are to be preferred; {@code
* false} otherwise
* Creates a new {@code DefaultDataBufferFactory}, indicating whether direct
* buffers should be created by {@link #allocateBuffer()} and
* {@link #allocateBuffer(int)}.
* @param preferDirect {@code true} if direct buffers are to be preferred;
* {@code false} otherwise
*/
public DefaultDataBufferFactory(boolean preferDirect) {
this(preferDirect, DEFAULT_INITIAL_CAPACITY);
}
/**
* Creates a new {@code DefaultDataBufferFactory}, indicating whether direct buffers
* should be created by {@link #allocateBuffer()} and {@link #allocateBuffer(int)},
* and what the capacity is to be used for {@link #allocateBuffer()}.
* @param preferDirect {@code true} if direct buffers are to be preferred; {@code
* false} otherwise
* Creates a new {@code DefaultDataBufferFactory}, indicating whether direct
* buffers should be created by {@link #allocateBuffer()} and
* {@link #allocateBuffer(int)}, and what the capacity is to be used for
* {@link #allocateBuffer()}.
* @param preferDirect {@code true} if direct buffers are to be preferred;
* {@code false} otherwise
*/
public DefaultDataBufferFactory(boolean preferDirect, int defaultInitialCapacity) {
Assert.isTrue(defaultInitialCapacity > 0,
@@ -73,6 +76,7 @@ public class DefaultDataBufferFactory implements DataBufferFactory {
this.defaultInitialCapacity = defaultInitialCapacity;
}
@Override
public DefaultDataBuffer allocateBuffer() {
return allocateBuffer(this.defaultInitialCapacity);

4
spring-core/src/main/java/org/springframework/core/io/buffer/FlushingDataBuffer.java
View File

@@ -22,8 +22,8 @@ import java.nio.ByteBuffer;
import java.util.function.IntPredicate;
/**
* Empty {@link DataBuffer} that indicates to the file or the socket writing it that
* previously buffered data should be flushed.
* Empty {@link DataBuffer} that indicates to the file or the socket writing it
* that previously buffered data should be flushed.
*
* @author Sebastien Deleuze
* @since 5.0

4
spring-core/src/main/java/org/springframework/core/io/buffer/NettyDataBuffer.java
View File

@@ -32,8 +32,8 @@ import org.springframework.util.Assert;
import org.springframework.util.ObjectUtils;
/**
* Implementation of the {@code DataBuffer} interface that wraps a Netty {@link ByteBuf}.
* Typically constructed using the {@link NettyDataBufferFactory}.
* Implementation of the {@code DataBuffer} interface that wraps a Netty
* {@link ByteBuf}. Typically constructed with {@link NettyDataBufferFactory}.
*
* @author Arjen Poutsma
* @since 5.0

2
spring-core/src/main/java/org/springframework/core/io/buffer/NettyDataBufferFactory.java
View File

@@ -37,6 +37,7 @@ public class NettyDataBufferFactory implements DataBufferFactory {
private final ByteBufAllocator byteBufAllocator;
/**
* Creates a new {@code NettyDataBufferFactory} based on the given factory.
* @param byteBufAllocator the factory to use
@@ -49,6 +50,7 @@ public class NettyDataBufferFactory implements DataBufferFactory {
this.byteBufAllocator = byteBufAllocator;
}
@Override
public NettyDataBuffer allocateBuffer() {
ByteBuf byteBuf = this.byteBufAllocator.buffer();

8
spring-core/src/main/java/org/springframework/core/io/buffer/PooledDataBuffer.java
View File

@@ -17,8 +17,8 @@
package org.springframework.core.io.buffer;
/**
* Extension of {@link DataBuffer} that allows for buffer that share a memory pool.
* Introduces methods for reference counting.
* Extension of {@link DataBuffer} that allows for buffer that share a memory
* pool. Introduces methods for reference counting.
*
* @author Arjen Poutsma
* @since 5.0
@@ -32,8 +32,8 @@ public interface PooledDataBuffer extends DataBuffer {
PooledDataBuffer retain();
/**
* Decreases the reference count for this buffer by one, and releases it once the
* count reaches zero.
* Decreases the reference count for this buffer by one, and releases it
* once the count reaches zero.
* @return {@code true} if the buffer was released; {@code false} otherwise.
*/
boolean release();

4
spring-core/src/main/java/org/springframework/core/io/buffer/support/DataBufferUtils.java
View File

@@ -89,8 +89,8 @@ public abstract class DataBufferUtils {
/**
* Relays buffers from the given {@link Publisher} until the total
* {@linkplain DataBuffer#readableByteCount() byte count} reaches the given maximum
* byte count, or until the publisher is complete.
* {@linkplain DataBuffer#readableByteCount() byte count} reaches the given
* maximum byte count, or until the publisher is complete.
* @param publisher the publisher to filter
* @param maxByteCount the maximum byte count
* @return a flux whose maximum byte count is {@code maxByteCount}