This is an automated email from the ASF dual-hosted git repository. asf-gitbox-commits pushed a commit to branch master in repository https://gitbox.apache.org/repos/asf/groovy.git
commit 5b6460b81fa9db60a6d0d0832569c0680fe3e1d3 Author: Daniel Sun <[email protected]> AuthorDate: Sun May 10 01:41:39 2026 +0900 Add missing javadoc --- .../groovy/runtime/memoize/CommonCache.java | 39 ++++++++++++- .../runtime/memoize/ConcurrentCommonCache.java | 34 ++++++++++- .../groovy/runtime/memoize/EvictableCache.java | 6 +- .../groovy/runtime/memoize/FlexibleCache.java | 9 +++ .../codehaus/groovy/runtime/memoize/LRUCache.java | 21 ++++++- .../runtime/memoize/LRUProtectionStorage.java | 5 ++ .../groovy/runtime/memoize/MemoizeCache.java | 5 +- .../groovy/runtime/memoize/ProtectionStorage.java | 7 +++ .../groovy/runtime/memoize/StampedCommonCache.java | 34 ++++++++++- .../runtime/memoize/UnlimitedConcurrentCache.java | 32 ++++++++++- .../runtime/powerassert/PowerAssertionError.java | 10 ++++ .../SourceTextNotAvailableException.java | 12 +++- .../codehaus/groovy/runtime/powerassert/Value.java | 18 ++++++ .../groovy/runtime/powerassert/ValueRecorder.java | 16 ++++++ .../groovy/runtime/wrappers/BooleanWrapper.java | 9 +++ .../groovy/runtime/wrappers/ByteWrapper.java | 9 +++ .../groovy/runtime/wrappers/CharWrapper.java | 9 +++ .../groovy/runtime/wrappers/DoubleWrapper.java | 9 +++ .../groovy/runtime/wrappers/FloatWrapper.java | 9 +++ .../runtime/wrappers/GroovyObjectWrapper.java | 58 +++++++++++++++---- .../groovy/runtime/wrappers/IntWrapper.java | 9 +++ .../groovy/runtime/wrappers/LongWrapper.java | 9 +++ .../groovy/runtime/wrappers/PojoWrapper.java | 65 ++++++++++++++++++---- .../groovy/runtime/wrappers/ShortWrapper.java | 16 ++++-- .../codehaus/groovy/runtime/wrappers/Wrapper.java | 41 +++++++++++++- 25 files changed, 450 insertions(+), 41 deletions(-) diff --git a/src/main/java/org/codehaus/groovy/runtime/memoize/CommonCache.java b/src/main/java/org/codehaus/groovy/runtime/memoize/CommonCache.java index 20d5796f08..06a364d1fa 100644 --- a/src/main/java/org/codehaus/groovy/runtime/memoize/CommonCache.java +++ b/src/main/java/org/codehaus/groovy/runtime/memoize/CommonCache.java @@ -143,6 +143,9 @@ public class CommonCache<K, V> implements FlexibleCache<K, V>, ValueConvertable< return getAndPut(key, valueProvider, true); } + /** + * {@inheritDoc} + */ @Override public V getAndPut(K key, ValueProvider<? super K, ? extends V> valueProvider, boolean shouldCache) { V value = get(key); @@ -166,6 +169,11 @@ public class CommonCache<K, V> implements FlexibleCache<K, V>, ValueConvertable< return map.values(); } + /** + * Returns a live view of the cache entries. + * + * @return the cache entries + */ @Override public Set<Entry<K, V>> entrySet() { return map.entrySet(); @@ -179,6 +187,12 @@ public class CommonCache<K, V> implements FlexibleCache<K, V>, ValueConvertable< return map.keySet(); } + /** + * Determines whether the cache contains the specified stored value. + * + * @param value the value whose presence should be tested + * @return {@code true} if the cache contains the value + */ @Override public boolean containsValue(Object value) { return map.containsValue(value); @@ -200,6 +214,11 @@ public class CommonCache<K, V> implements FlexibleCache<K, V>, ValueConvertable< return map.size(); } + /** + * Returns whether the cache currently holds no entries. + * + * @return {@code true} if the cache is empty + */ @Override public boolean isEmpty() { return size() == 0; @@ -213,11 +232,21 @@ public class CommonCache<K, V> implements FlexibleCache<K, V>, ValueConvertable< return map.remove(key); } + /** + * Copies all mappings from the supplied map into this cache. + * + * @param m the mappings to copy + */ @Override public void putAll(Map<? extends K, ? extends V> m) { map.putAll(m); } + /** + * Returns a live view of the keys in this cache. + * + * @return the cache keys + */ @Override public Set<K> keySet() { return map.keySet(); @@ -255,13 +284,21 @@ public class CommonCache<K, V> implements FlexibleCache<K, V>, ValueConvertable< } } + /** + * Returns a string representation of the current cache contents. + * + * @return a string form of the backing map + */ @Override public String toString() { return map.toString(); } /** - * {@inheritDoc} + * Returns the stored value unchanged. + * + * @param value the stored value + * @return {@code value} */ @Override public Object convertValue(V value) { diff --git a/src/main/java/org/codehaus/groovy/runtime/memoize/ConcurrentCommonCache.java b/src/main/java/org/codehaus/groovy/runtime/memoize/ConcurrentCommonCache.java index daa52c05eb..ace36a7100 100644 --- a/src/main/java/org/codehaus/groovy/runtime/memoize/ConcurrentCommonCache.java +++ b/src/main/java/org/codehaus/groovy/runtime/memoize/ConcurrentCommonCache.java @@ -115,6 +115,9 @@ public class ConcurrentCommonCache<K, V> implements FlexibleCache<K, V>, ValueCo return getAndPut(key, valueProvider, true); } + /** + * {@inheritDoc} + */ @Override public V getAndPut(K key, ValueProvider<? super K, ? extends V> valueProvider, boolean shouldCache) { V value; @@ -156,6 +159,11 @@ public class ConcurrentCommonCache<K, V> implements FlexibleCache<K, V>, ValueCo return doWithReadLock(EvictableCache::values); } + /** + * Returns a live view of the cache entries. + * + * @return the cache entries + */ @Override public Set<Entry<K, V>> entrySet() { return doWithReadLock(Map::entrySet); @@ -177,6 +185,12 @@ public class ConcurrentCommonCache<K, V> implements FlexibleCache<K, V>, ValueCo return doWithReadLock(c -> c.containsKey(key)); } + /** + * Determines whether the cache contains the specified stored value. + * + * @param value the value whose presence should be tested + * @return {@code true} if the cache contains the value + */ @Override public boolean containsValue(Object value) { return doWithReadLock(c -> c.containsValue(value)); @@ -190,6 +204,11 @@ public class ConcurrentCommonCache<K, V> implements FlexibleCache<K, V>, ValueCo return doWithReadLock(EvictableCache::size); } + /** + * Returns whether the cache currently holds no entries. + * + * @return {@code true} if the cache is empty + */ @Override public boolean isEmpty() { return size() == 0; @@ -203,6 +222,11 @@ public class ConcurrentCommonCache<K, V> implements FlexibleCache<K, V>, ValueCo return doWithWriteLock(c -> c.remove(key)); } + /** + * Copies all mappings from the supplied map into this cache. + * + * @param m the mappings to copy + */ @Override public void putAll(Map<? extends K, ? extends V> m) { doWithWriteLock(c -> { @@ -211,6 +235,11 @@ public class ConcurrentCommonCache<K, V> implements FlexibleCache<K, V>, ValueCo }); } + /** + * Returns a live view of the keys in this cache. + * + * @return the cache keys + */ @Override public Set<K> keySet() { return keys(); @@ -236,7 +265,10 @@ public class ConcurrentCommonCache<K, V> implements FlexibleCache<K, V>, ValueCo } /** - * {@inheritDoc} + * Returns the stored value unchanged. + * + * @param value the stored value + * @return {@code value} */ @Override public Object convertValue(V value) { diff --git a/src/main/java/org/codehaus/groovy/runtime/memoize/EvictableCache.java b/src/main/java/org/codehaus/groovy/runtime/memoize/EvictableCache.java index 5b0789c3cb..ac8d54acdf 100644 --- a/src/main/java/org/codehaus/groovy/runtime/memoize/EvictableCache.java +++ b/src/main/java/org/codehaus/groovy/runtime/memoize/EvictableCache.java @@ -108,8 +108,10 @@ public interface EvictableCache<K, V> extends MemoizeCache<K, V>, Map<K, V>/* */ @FunctionalInterface interface Action<K, V, R> { /** - * Deal with the cache - * @param evictableCache + * Performs work against the supplied cache. + * + * @param evictableCache the cache to operate on + * @return the result produced by the action */ R doWith(EvictableCache<K, V> evictableCache); } diff --git a/src/main/java/org/codehaus/groovy/runtime/memoize/FlexibleCache.java b/src/main/java/org/codehaus/groovy/runtime/memoize/FlexibleCache.java index 87eaf55755..6b6b18132b 100644 --- a/src/main/java/org/codehaus/groovy/runtime/memoize/FlexibleCache.java +++ b/src/main/java/org/codehaus/groovy/runtime/memoize/FlexibleCache.java @@ -24,5 +24,14 @@ package org.codehaus.groovy.runtime.memoize; * @since 5.0.0 */ public interface FlexibleCache<K, V> extends EvictableCache<K, V> { + /** + * Returns the value associated with {@code key}, creating it with the + * supplied provider when necessary and optionally caching the result. + * + * @param key the key to look up + * @param valueProvider supplies a value when the key is not cached + * @param shouldCache whether a newly created value should be stored + * @return the cached or newly created value + */ V getAndPut(K key, ValueProvider<? super K, ? extends V> valueProvider, boolean shouldCache); } diff --git a/src/main/java/org/codehaus/groovy/runtime/memoize/LRUCache.java b/src/main/java/org/codehaus/groovy/runtime/memoize/LRUCache.java index 798d2b72d2..ddea075e74 100644 --- a/src/main/java/org/codehaus/groovy/runtime/memoize/LRUCache.java +++ b/src/main/java/org/codehaus/groovy/runtime/memoize/LRUCache.java @@ -33,17 +33,35 @@ import java.util.concurrent.ConcurrentMap; public final class LRUCache<K, V> implements MemoizeCache<K, V> { private final ConcurrentMap<K, V> map; + /** + * Creates an LRU cache with the supplied maximum size. + * + * @param maxCacheSize the maximum number of cached entries + */ public LRUCache(final int maxCacheSize) { map = new ConcurrentLinkedHashMap.Builder<K, V>() .maximumWeightedCapacity(maxCacheSize) .build(); } + /** + * Associates the specified value with the specified key in this cache. + * + * @param key the key with which the value is to be associated + * @param value the value to cache + * @return the previous value associated with {@code key}, or {@code null} + */ @Override public V put(final K key, final V value) { return map.put(key, value); } + /** + * Returns the value associated with the supplied key. + * + * @param key the key to look up + * @return the cached value, or {@code null} if none is present + */ @Override public V get(final K key) { return map.get(key); @@ -55,8 +73,9 @@ public final class LRUCache<K, V> implements MemoizeCache<K, V> { * * The operation is completed atomically. * - * @param key + * @param key the key to look up * @param valueProvider provide the value if the associated value not found + * @return the cached or newly created value */ @Override public V getAndPut(K key, ValueProvider<? super K, ? extends V> valueProvider) { diff --git a/src/main/java/org/codehaus/groovy/runtime/memoize/LRUProtectionStorage.java b/src/main/java/org/codehaus/groovy/runtime/memoize/LRUProtectionStorage.java index be4a046fbe..f0ccbbb7dd 100644 --- a/src/main/java/org/codehaus/groovy/runtime/memoize/LRUProtectionStorage.java +++ b/src/main/java/org/codehaus/groovy/runtime/memoize/LRUProtectionStorage.java @@ -33,6 +33,11 @@ final class LRUProtectionStorage extends LinkedHashMap<Object, Object> implement private final int maxSize; + /** + * Creates a protection storage with the supplied maximum size. + * + * @param maxSize the maximum number of protected entries to retain + */ public LRUProtectionStorage(final int maxSize) { this.maxSize = maxSize; } diff --git a/src/main/java/org/codehaus/groovy/runtime/memoize/MemoizeCache.java b/src/main/java/org/codehaus/groovy/runtime/memoize/MemoizeCache.java index dfa4438c5c..72fb0b670e 100644 --- a/src/main/java/org/codehaus/groovy/runtime/memoize/MemoizeCache.java +++ b/src/main/java/org/codehaus/groovy/runtime/memoize/MemoizeCache.java @@ -74,7 +74,10 @@ public interface MemoizeCache<K, V> { @FunctionalInterface interface ValueProvider<K, V> { /** - * Provide the created value + * Creates a value for the supplied key. + * + * @param key the key being resolved + * @return the created value */ V provide(K key); } diff --git a/src/main/java/org/codehaus/groovy/runtime/memoize/ProtectionStorage.java b/src/main/java/org/codehaus/groovy/runtime/memoize/ProtectionStorage.java index cc4f32892d..5e26133cf3 100644 --- a/src/main/java/org/codehaus/groovy/runtime/memoize/ProtectionStorage.java +++ b/src/main/java/org/codehaus/groovy/runtime/memoize/ProtectionStorage.java @@ -23,5 +23,12 @@ package org.codehaus.groovy.runtime.memoize; * The touch method can be used to renew an element and move it to the from the LRU queue. */ interface ProtectionStorage<K, V> { + /** + * Marks an entry as recently used and updates the protected value stored + * for the supplied key. + * + * @param key the key to refresh + * @param value the value to protect + */ void touch(K key, V value); } diff --git a/src/main/java/org/codehaus/groovy/runtime/memoize/StampedCommonCache.java b/src/main/java/org/codehaus/groovy/runtime/memoize/StampedCommonCache.java index 7248f2de70..64df3ea7c3 100644 --- a/src/main/java/org/codehaus/groovy/runtime/memoize/StampedCommonCache.java +++ b/src/main/java/org/codehaus/groovy/runtime/memoize/StampedCommonCache.java @@ -117,6 +117,9 @@ public class StampedCommonCache<K, V> implements FlexibleCache<K, V>, ValueConve return getAndPut(key, valueProvider, true); } + /** + * {@inheritDoc} + */ @Override public V getAndPut(K key, ValueProvider<? super K, ? extends V> valueProvider, boolean shouldCache) { V value; @@ -178,6 +181,11 @@ public class StampedCommonCache<K, V> implements FlexibleCache<K, V>, ValueConve return doWithReadLock(c -> c.values()); } + /** + * Returns a live view of the cache entries. + * + * @return the cache entries + */ @Override public Set<Entry<K, V>> entrySet() { return doWithReadLock(c -> c.entrySet()); @@ -199,6 +207,12 @@ public class StampedCommonCache<K, V> implements FlexibleCache<K, V>, ValueConve return doWithReadLock(c -> c.containsKey(key)); } + /** + * Determines whether the cache contains the specified stored value. + * + * @param value the value whose presence should be tested + * @return {@code true} if the cache contains the value + */ @Override public boolean containsValue(Object value) { return doWithReadLock(c -> c.containsValue(value)); @@ -212,6 +226,11 @@ public class StampedCommonCache<K, V> implements FlexibleCache<K, V>, ValueConve return doWithReadLock(c -> c.size()); } + /** + * Returns whether the cache currently holds no entries. + * + * @return {@code true} if the cache is empty + */ @Override public boolean isEmpty() { return size() == 0; @@ -225,6 +244,11 @@ public class StampedCommonCache<K, V> implements FlexibleCache<K, V>, ValueConve return doWithWriteLock(c -> c.remove(key)); } + /** + * Copies all mappings from the supplied map into this cache. + * + * @param m the mappings to copy + */ @Override public void putAll(Map<? extends K, ? extends V> m) { doWithWriteLock(c -> { @@ -233,6 +257,11 @@ public class StampedCommonCache<K, V> implements FlexibleCache<K, V>, ValueConve }); } + /** + * Returns a live view of the keys in this cache. + * + * @return the cache keys + */ @Override public Set<K> keySet() { return keys(); @@ -258,7 +287,10 @@ public class StampedCommonCache<K, V> implements FlexibleCache<K, V>, ValueConve } /** - * {@inheritDoc} + * Returns the stored value unchanged. + * + * @param value the stored value + * @return {@code value} */ @Override public Object convertValue(V value) { diff --git a/src/main/java/org/codehaus/groovy/runtime/memoize/UnlimitedConcurrentCache.java b/src/main/java/org/codehaus/groovy/runtime/memoize/UnlimitedConcurrentCache.java index fdfb0b708a..aaa95a6252 100644 --- a/src/main/java/org/codehaus/groovy/runtime/memoize/UnlimitedConcurrentCache.java +++ b/src/main/java/org/codehaus/groovy/runtime/memoize/UnlimitedConcurrentCache.java @@ -64,7 +64,7 @@ public final class UnlimitedConcurrentCache<K, V> implements EvictableCache<K, V /** * Remove the cached value by the key * - * @param key + * @param key the key whose mapping should be removed * @return returns the removed value */ @Override @@ -72,11 +72,21 @@ public final class UnlimitedConcurrentCache<K, V> implements EvictableCache<K, V return map.remove(key); } + /** + * Copies all mappings from the supplied map into this cache. + * + * @param m the mappings to copy + */ @Override public void putAll(Map<? extends K, ? extends V> m) { map.putAll(m); } + /** + * Returns a live view of the keys in this cache. + * + * @return the cache keys + */ @Override public Set<K> keySet() { return map.keySet(); @@ -115,6 +125,11 @@ public final class UnlimitedConcurrentCache<K, V> implements EvictableCache<K, V return map.values(); } + /** + * Returns a live view of the cache entries. + * + * @return the cache entries + */ @Override public Set<Entry<K, V>> entrySet() { return map.entrySet(); @@ -141,6 +156,12 @@ public final class UnlimitedConcurrentCache<K, V> implements EvictableCache<K, V return map.containsKey(key); } + /** + * Determines whether the cache contains the specified stored value. + * + * @param value the value whose presence should be tested + * @return {@code true} if the cache contains the value + */ @Override public boolean containsValue(Object value) { return map.containsValue(value); @@ -156,6 +177,11 @@ public final class UnlimitedConcurrentCache<K, V> implements EvictableCache<K, V return map.size(); } + /** + * Returns whether the cache currently holds no entries. + * + * @return {@code true} if the cache is empty + */ @Override public boolean isEmpty() { return map.isEmpty(); @@ -188,9 +214,9 @@ public final class UnlimitedConcurrentCache<K, V> implements EvictableCache<K, V * Try to get the value from cache. * If not found, create the value by {@link MemoizeCache.ValueProvider} and put it into the cache, at last return the value. * - * @param key + * @param key the key to look up * @param valueProvider provide the value if the associated value not found - * @return the cached value + * @return the cached or newly created value */ @Override public V getAndPut(K key, ValueProvider<? super K, ? extends V> valueProvider) { diff --git a/src/main/java/org/codehaus/groovy/runtime/powerassert/PowerAssertionError.java b/src/main/java/org/codehaus/groovy/runtime/powerassert/PowerAssertionError.java index c83b508538..9d18d7b6f0 100644 --- a/src/main/java/org/codehaus/groovy/runtime/powerassert/PowerAssertionError.java +++ b/src/main/java/org/codehaus/groovy/runtime/powerassert/PowerAssertionError.java @@ -26,10 +26,20 @@ import java.io.Serial; public class PowerAssertionError extends java.lang.AssertionError { @Serial private static final long serialVersionUID = -2204531294530022591L; + /** + * Creates an error containing the rendered power assertion output. + * + * @param msg the rendered assertion failure details + */ public PowerAssertionError(String msg) { super(msg); } + /** + * Returns the standard power assertion failure message shown to callers. + * + * @return the formatted assertion failure text + */ @Override public String toString() { return String.format("Assertion failed: %n%n%s%n", getMessage()); diff --git a/src/main/java/org/codehaus/groovy/runtime/powerassert/SourceTextNotAvailableException.java b/src/main/java/org/codehaus/groovy/runtime/powerassert/SourceTextNotAvailableException.java index 838a12b605..268c758603 100644 --- a/src/main/java/org/codehaus/groovy/runtime/powerassert/SourceTextNotAvailableException.java +++ b/src/main/java/org/codehaus/groovy/runtime/powerassert/SourceTextNotAvailableException.java @@ -29,7 +29,17 @@ import java.io.Serial; public class SourceTextNotAvailableException extends RuntimeException { @Serial private static final long serialVersionUID = -3815868502019514479L; - // only accepts AssertStatementS so that better error messages can be produced + /** + * Creates an exception describing why the source text for an assertion + * could not be obtained. + * <p> + * The constructor accepts an {@link AssertStatement} so the generated + * message can include the asserted expression text. + * + * @param stat the assertion statement whose source text was requested + * @param unit the source unit containing the assertion statement + * @param msg the failure reason to include in the generated message + */ public SourceTextNotAvailableException(AssertStatement stat, SourceUnit unit, String msg) { super(String.format("%s for %s at (%d,%d)-(%d,%d) in %s", msg, stat.getBooleanExpression().getText(), stat.getLineNumber(), stat.getColumnNumber(), diff --git a/src/main/java/org/codehaus/groovy/runtime/powerassert/Value.java b/src/main/java/org/codehaus/groovy/runtime/powerassert/Value.java index 12dcc98b72..9657480401 100644 --- a/src/main/java/org/codehaus/groovy/runtime/powerassert/Value.java +++ b/src/main/java/org/codehaus/groovy/runtime/powerassert/Value.java @@ -26,15 +26,33 @@ public class Value { private final Object value; private final int column; + /** + * Creates a recorded assertion value. + * + * @param value the recorded value + * @param column the 1-based column in the normalized assertion text, or a + * non-positive value if the source position is unknown + */ public Value(Object value, int column) { this.value = value; this.column = column; } + /** + * Returns the recorded value. + * + * @return the recorded value + */ public Object getValue() { return value; } + /** + * Returns the source column associated with the recorded value. + * + * @return the 1-based column in the normalized assertion text, or a + * non-positive value if the source position is unknown + */ public int getColumn() { return column; } diff --git a/src/main/java/org/codehaus/groovy/runtime/powerassert/ValueRecorder.java b/src/main/java/org/codehaus/groovy/runtime/powerassert/ValueRecorder.java index 86342c7079..8e4194f50e 100644 --- a/src/main/java/org/codehaus/groovy/runtime/powerassert/ValueRecorder.java +++ b/src/main/java/org/codehaus/groovy/runtime/powerassert/ValueRecorder.java @@ -28,15 +28,31 @@ import java.util.List; public class ValueRecorder { private final List<Value> values = new ArrayList<Value>(); + /** + * Removes all values recorded for the current assertion evaluation. + */ public void clear() { values.clear(); } + /** + * Records a value at the supplied anchor column and returns it unchanged. + * + * @param value the value produced while evaluating the assertion + * @param anchor the 1-based column in the normalized assertion text, or a + * non-positive value if the position is unknown + * @return {@code value} + */ public Object record(Object value, int anchor) { values.add(new Value(value, anchor)); return value; } + /** + * Returns the recorded values in recording order. + * + * @return the live list of recorded values + */ public List<Value> getValues() { return values; } diff --git a/src/main/java/org/codehaus/groovy/runtime/wrappers/BooleanWrapper.java b/src/main/java/org/codehaus/groovy/runtime/wrappers/BooleanWrapper.java index 7624f6b852..6b7d8d74bb 100644 --- a/src/main/java/org/codehaus/groovy/runtime/wrappers/BooleanWrapper.java +++ b/src/main/java/org/codehaus/groovy/runtime/wrappers/BooleanWrapper.java @@ -18,7 +18,16 @@ */ package org.codehaus.groovy.runtime.wrappers; +/** + * Wrapper for {@code boolean} values that preserves the primitive constrained + * type. + */ public class BooleanWrapper extends PojoWrapper { + /** + * Creates a wrapper for a boolean value. + * + * @param wrapped the boolean value to wrap + */ public BooleanWrapper(final boolean wrapped) { super(wrapped ? Boolean.TRUE : Boolean.FALSE, boolean.class); } diff --git a/src/main/java/org/codehaus/groovy/runtime/wrappers/ByteWrapper.java b/src/main/java/org/codehaus/groovy/runtime/wrappers/ByteWrapper.java index f20df0ba8f..7373c0d8a3 100644 --- a/src/main/java/org/codehaus/groovy/runtime/wrappers/ByteWrapper.java +++ b/src/main/java/org/codehaus/groovy/runtime/wrappers/ByteWrapper.java @@ -18,7 +18,16 @@ */ package org.codehaus.groovy.runtime.wrappers; +/** + * Wrapper for {@code byte} values that preserves the primitive constrained + * type. + */ public class ByteWrapper extends PojoWrapper { + /** + * Creates a wrapper for a byte value. + * + * @param wrapped the byte value to wrap + */ public ByteWrapper(final byte wrapped) { super(wrapped, byte.class); } diff --git a/src/main/java/org/codehaus/groovy/runtime/wrappers/CharWrapper.java b/src/main/java/org/codehaus/groovy/runtime/wrappers/CharWrapper.java index 9cc42f38a4..0032c9c38e 100644 --- a/src/main/java/org/codehaus/groovy/runtime/wrappers/CharWrapper.java +++ b/src/main/java/org/codehaus/groovy/runtime/wrappers/CharWrapper.java @@ -18,7 +18,16 @@ */ package org.codehaus.groovy.runtime.wrappers; +/** + * Wrapper for {@code char} values that preserves the primitive constrained + * type. + */ public class CharWrapper extends PojoWrapper { + /** + * Creates a wrapper for a char value. + * + * @param wrapped the char value to wrap + */ public CharWrapper(final char wrapped) { super(wrapped, char.class); } diff --git a/src/main/java/org/codehaus/groovy/runtime/wrappers/DoubleWrapper.java b/src/main/java/org/codehaus/groovy/runtime/wrappers/DoubleWrapper.java index 8eafb947ad..9f28348917 100644 --- a/src/main/java/org/codehaus/groovy/runtime/wrappers/DoubleWrapper.java +++ b/src/main/java/org/codehaus/groovy/runtime/wrappers/DoubleWrapper.java @@ -18,7 +18,16 @@ */ package org.codehaus.groovy.runtime.wrappers; +/** + * Wrapper for {@code double} values that preserves the primitive constrained + * type. + */ public class DoubleWrapper extends PojoWrapper { + /** + * Creates a wrapper for a double value. + * + * @param wrapped the double value to wrap + */ public DoubleWrapper(final double wrapped) { super(wrapped, double.class); } diff --git a/src/main/java/org/codehaus/groovy/runtime/wrappers/FloatWrapper.java b/src/main/java/org/codehaus/groovy/runtime/wrappers/FloatWrapper.java index 689fa0d6c1..d5aea17a2f 100644 --- a/src/main/java/org/codehaus/groovy/runtime/wrappers/FloatWrapper.java +++ b/src/main/java/org/codehaus/groovy/runtime/wrappers/FloatWrapper.java @@ -18,7 +18,16 @@ */ package org.codehaus.groovy.runtime.wrappers; +/** + * Wrapper for {@code float} values that preserves the primitive constrained + * type. + */ public class FloatWrapper extends PojoWrapper { + /** + * Creates a wrapper for a float value. + * + * @param wrapped the float value to wrap + */ public FloatWrapper(final float wrapped) { super(wrapped, float.class); } diff --git a/src/main/java/org/codehaus/groovy/runtime/wrappers/GroovyObjectWrapper.java b/src/main/java/org/codehaus/groovy/runtime/wrappers/GroovyObjectWrapper.java index 347fc0f689..bef72f518e 100644 --- a/src/main/java/org/codehaus/groovy/runtime/wrappers/GroovyObjectWrapper.java +++ b/src/main/java/org/codehaus/groovy/runtime/wrappers/GroovyObjectWrapper.java @@ -21,56 +21,90 @@ package org.codehaus.groovy.runtime.wrappers; import groovy.lang.GroovyObject; import groovy.lang.MetaClass; +/** + * Wraps an existing {@link GroovyObject} while constraining the type it should + * present to the runtime. + */ public class GroovyObjectWrapper extends Wrapper { + /** + * The wrapped Groovy object. + */ protected final GroovyObject wrapped; + /** + * Creates a wrapper for a Groovy object constrained to the supplied type. + * + * @param wrapped the wrapped Groovy object + * @param constrainedType the type the wrapped object should report + */ public GroovyObjectWrapper(final GroovyObject wrapped, final Class constrainedType) { super(constrainedType); this.wrapped = wrapped; } + /** + * {@inheritDoc} + */ @Override public Object unwrap() { return this.wrapped; } - /* (non-Javadoc) - * @see groovy.lang.GroovyObject#getProperty(java.lang.String) - */ + /** + * Returns a property value from the wrapped Groovy object. + * + * @param property the property name + * @return the resolved property value + */ @Override public Object getProperty(final String property) { return this.wrapped.getProperty(property); } - /* (non-Javadoc) - * @see groovy.lang.GroovyObject#invokeMethod(java.lang.String, java.lang.Object) - */ + /** + * Invokes a method on the wrapped Groovy object. + * + * @param name the method name + * @param args the invocation arguments + * @return the invocation result + */ @Override public Object invokeMethod(final String name, final Object args) { return this.wrapped.invokeMethod(name, args); } - /* (non-Javadoc) - * @see groovy.lang.GroovyObject#setMetaClass(groovy.lang.MetaClass) - */ + /** + * Updates the wrapped object's meta class. + * + * @param metaClass the new meta class + */ @Override public void setMetaClass(final MetaClass metaClass) { this.wrapped.setMetaClass(metaClass); } - /* (non-Javadoc) - * @see groovy.lang.GroovyObject#setProperty(java.lang.String, java.lang.Object) - */ + /** + * Sets a property on the wrapped Groovy object. + * + * @param property the property name + * @param newValue the new property value + */ @Override public void setProperty(final String property, final Object newValue) { this.wrapped.setProperty(property, newValue); } + /** + * {@inheritDoc} + */ @Override protected Object getWrapped() { return this.wrapped; } + /** + * {@inheritDoc} + */ @Override protected MetaClass getDelegatedMetaClass() { return this.wrapped.getMetaClass(); diff --git a/src/main/java/org/codehaus/groovy/runtime/wrappers/IntWrapper.java b/src/main/java/org/codehaus/groovy/runtime/wrappers/IntWrapper.java index 5032e4887c..2d29247c00 100644 --- a/src/main/java/org/codehaus/groovy/runtime/wrappers/IntWrapper.java +++ b/src/main/java/org/codehaus/groovy/runtime/wrappers/IntWrapper.java @@ -18,7 +18,16 @@ */ package org.codehaus.groovy.runtime.wrappers; +/** + * Wrapper for {@code int} values that preserves the primitive constrained + * type. + */ public class IntWrapper extends PojoWrapper { + /** + * Creates a wrapper for an int value. + * + * @param wrapped the int value to wrap + */ public IntWrapper(final int wrapped) { super(wrapped, int.class); } diff --git a/src/main/java/org/codehaus/groovy/runtime/wrappers/LongWrapper.java b/src/main/java/org/codehaus/groovy/runtime/wrappers/LongWrapper.java index 2e637d35a8..741430213a 100644 --- a/src/main/java/org/codehaus/groovy/runtime/wrappers/LongWrapper.java +++ b/src/main/java/org/codehaus/groovy/runtime/wrappers/LongWrapper.java @@ -18,7 +18,16 @@ */ package org.codehaus.groovy.runtime.wrappers; +/** + * Wrapper for {@code long} values that preserves the primitive constrained + * type. + */ public class LongWrapper extends PojoWrapper { + /** + * Creates a wrapper for a long value. + * + * @param wrapped the long value to wrap + */ public LongWrapper(final long wrapped) { super(wrapped, long.class); } diff --git a/src/main/java/org/codehaus/groovy/runtime/wrappers/PojoWrapper.java b/src/main/java/org/codehaus/groovy/runtime/wrappers/PojoWrapper.java index 5dffa414c3..010dff73f1 100644 --- a/src/main/java/org/codehaus/groovy/runtime/wrappers/PojoWrapper.java +++ b/src/main/java/org/codehaus/groovy/runtime/wrappers/PojoWrapper.java @@ -20,57 +20,98 @@ package org.codehaus.groovy.runtime.wrappers; import groovy.lang.MetaClass; +/** + * Wraps a plain Java object and routes GroovyObject operations through a + * delegated {@link MetaClass}. + */ public class PojoWrapper extends Wrapper { + /** + * The meta class used to dispatch GroovyObject operations to the wrapped + * object. + */ protected MetaClass delegate; + /** + * The wrapped plain Java object. + */ protected final Object wrapped; + /** + * Creates a wrapper for a plain Java object constrained to the supplied + * type. + * + * @param wrapped the wrapped object + * @param constrainedType the type the wrapped object should report + */ public PojoWrapper(final Object wrapped, final Class constrainedType) { super(constrainedType); this.wrapped = wrapped; } + /** + * {@inheritDoc} + */ @Override public Object unwrap() { return this.wrapped; } - /* (non-Javadoc) - * @see groovy.lang.GroovyObject#getProperty(java.lang.String) - */ + /** + * Returns a property value from the wrapped object using the delegated meta + * class. + * + * @param property the property name + * @return the resolved property value + */ @Override public Object getProperty(final String property) { return this.delegate.getProperty(this.wrapped, property); } - /* (non-Javadoc) - * @see groovy.lang.GroovyObject#invokeMethod(java.lang.String, java.lang.Object) - */ + /** + * Invokes a method on the wrapped object using the delegated meta class. + * + * @param methodName the method name + * @param arguments the invocation arguments + * @return the invocation result + */ @Override public Object invokeMethod(final String methodName, final Object arguments) { return this.delegate.invokeMethod(this.wrapped, methodName, arguments); } - /* (non-Javadoc) - * @see groovy.lang.GroovyObject#setMetaClass(groovy.lang.MetaClass) - */ + /** + * Sets the meta class used to dispatch GroovyObject operations for the + * wrapped object. + * + * @param metaClass the meta class to delegate to + */ @Override public void setMetaClass(final MetaClass metaClass) { this.delegate = metaClass; } - /* (non-Javadoc) - * @see groovy.lang.GroovyObject#setProperty(java.lang.String, java.lang.Object) - */ + /** + * Sets a property on the wrapped object using the delegated meta class. + * + * @param property the property name + * @param newValue the new property value + */ @Override public void setProperty(final String property, final Object newValue) { this.delegate.setProperty(this.wrapped, property, newValue); } + /** + * {@inheritDoc} + */ @Override protected Object getWrapped() { return this.wrapped; } + /** + * {@inheritDoc} + */ @Override protected MetaClass getDelegatedMetaClass() { return this.delegate; diff --git a/src/main/java/org/codehaus/groovy/runtime/wrappers/ShortWrapper.java b/src/main/java/org/codehaus/groovy/runtime/wrappers/ShortWrapper.java index 2fe5af0de1..44ff193de0 100644 --- a/src/main/java/org/codehaus/groovy/runtime/wrappers/ShortWrapper.java +++ b/src/main/java/org/codehaus/groovy/runtime/wrappers/ShortWrapper.java @@ -18,9 +18,17 @@ */ package org.codehaus.groovy.runtime.wrappers; +/** + * Wrapper for {@code short} values that preserves the primitive constrained + * type. + */ public class ShortWrapper extends PojoWrapper { - public ShortWrapper(final short wrapped) { - super(wrapped, short.class); - } - + /** + * Creates a wrapper for a short value. + * + * @param wrapped the short value to wrap + */ + public ShortWrapper(final short wrapped) { + super(wrapped, short.class); + } } diff --git a/src/main/java/org/codehaus/groovy/runtime/wrappers/Wrapper.java b/src/main/java/org/codehaus/groovy/runtime/wrappers/Wrapper.java index 11077a701e..363eb72ed5 100644 --- a/src/main/java/org/codehaus/groovy/runtime/wrappers/Wrapper.java +++ b/src/main/java/org/codehaus/groovy/runtime/wrappers/Wrapper.java @@ -21,28 +21,65 @@ package org.codehaus.groovy.runtime.wrappers; import groovy.lang.GroovyObject; import groovy.lang.MetaClass; +/** + * Base class for runtime wrappers that expose a value through + * {@link GroovyObject} while reporting a constrained type. + */ public abstract class Wrapper implements GroovyObject { + /** + * The constrained type the wrapped value should present to the runtime. + */ protected final Class constrainedType; + /** + * Creates a wrapper for values that should appear as the supplied type. + * + * @param constrainedType the type the wrapped value should report + */ public Wrapper(final Class constrainedType) { this.constrainedType = constrainedType; } - /* (non-Javadoc) - * @see groovy.lang.GroovyObject#getMetaClass() + /** + * Returns the {@link MetaClass} used to service GroovyObject operations for + * the wrapped value. + * + * @return the delegated meta class */ @Override public MetaClass getMetaClass() { return getDelegatedMetaClass(); } + /** + * Returns the constrained type associated with this wrapper. + * + * @return the type the wrapped value should be treated as + */ public Class getType() { return this.constrainedType; } + /** + * Returns the wrapped value. + * + * @return the underlying value represented by this wrapper + */ public abstract Object unwrap(); + /** + * Returns the object used as the delegation target for meta-class-based + * operations. + * + * @return the underlying wrapped object + */ protected abstract Object getWrapped(); + /** + * Returns the meta class that should handle GroovyObject operations for the + * wrapped value. + * + * @return the delegated meta class + */ protected abstract MetaClass getDelegatedMetaClass(); }
