This is an automated email from the ASF dual-hosted git repository.
mbenson pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/ant-antlibs-s3.git
commit da99c88a9097e79121cf7c128a6fa155264ab60d
Author: Matt Benson <mben...@apache.org>
AuthorDate: Thu Mar 31 09:04:40 2022 -0500
cleanup + javadoc
---
src/main/org/apache/ant/s3/CompareSelect.java | 27 +++++-
src/main/org/apache/ant/s3/CopyResources.java | 48 ++++++++---
src/main/org/apache/ant/s3/Delete.java | 12 ++-
src/main/org/apache/ant/s3/InlineProperties.java | 10 +--
src/main/org/apache/ant/s3/LoggingTask.java | 37 +++++----
src/main/org/apache/ant/s3/ObjectResource.java | 100 ++++++++++++++++++++---
src/main/org/apache/ant/s3/ObjectResources.java | 25 ++++--
src/main/org/apache/ant/s3/ProjectUtils.java | 20 ++---
src/main/org/apache/ant/s3/Put.java | 19 ++++-
src/main/org/apache/ant/s3/S3DataType.java | 15 ++--
10 files changed, 234 insertions(+), 79 deletions(-)
diff --git a/src/main/org/apache/ant/s3/CompareSelect.java
b/src/main/org/apache/ant/s3/CompareSelect.java
index 4cb4fd4..d3521ea 100644
--- a/src/main/org/apache/ant/s3/CompareSelect.java
+++ b/src/main/org/apache/ant/s3/CompareSelect.java
@@ -102,6 +102,7 @@ public abstract class CompareSelect extends
ResourceComparator implements Resour
* Create a new {@link CompareSelect.ForStringAttribute}.
*
* @param project
+ * Ant {@link Project}
*/
protected ForStringAttribute(final Project project) {
super(project);
@@ -112,6 +113,7 @@ public abstract class CompareSelect extends
ResourceComparator implements Resour
* Add nested text by which the value to compare is set.
*
* @param text
+ * to add
*/
public void addText(final String text) {
Optional.ofNullable(StringUtils.trimToNull(text)).map(getProject()::replaceProperties).map(String::trim)
@@ -122,7 +124,7 @@ public abstract class CompareSelect extends
ResourceComparator implements Resour
}
/**
- * Get "match as" strategy (default {@link MatchAs#LITERAL}.
+ * Get "match as" strategy (default {@link MatchAs#literal}.
*
* @return {@link MatchAs}
*/
@@ -134,6 +136,7 @@ public abstract class CompareSelect extends
ResourceComparator implements Resour
* Set "match as" strategy.
*
* @param matchAs
+ * strategy
*/
public void setMatchAs(final MatchAs matchAs) {
Exceptions.raiseIf(matchAs == null, buildException(), "@matchas
may not be null");
@@ -158,6 +161,7 @@ public abstract class CompareSelect extends
ResourceComparator implements Resour
* Set whether matching should be performed in a case-sensitive manner.
*
* @param caseSensitive
+ * flag
*/
public void setCaseSensitive(final boolean caseSensitive) {
if (caseSensitive != this.caseSensitive) {
@@ -179,6 +183,7 @@ public abstract class CompareSelect extends
ResourceComparator implements Resour
* {@link ObjectResource}.
*
* @param obj
+ * owning value
* @return {@link String}
*/
protected abstract String extractValueFrom(ObjectResource obj);
@@ -217,6 +222,7 @@ public abstract class CompareSelect extends
ResourceComparator implements Resour
* Create a new {@link Bucket} selector.
*
* @param project
+ * Ant {@link Project}
*/
public Bucket(final Project project) {
super(project);
@@ -240,6 +246,7 @@ public abstract class CompareSelect extends
ResourceComparator implements Resour
* Create a new {@link Key} selector.
*
* @param project
+ * Ant {@link Project}
*/
public Key(final Project project) {
super(project);
@@ -263,6 +270,7 @@ public abstract class CompareSelect extends
ResourceComparator implements Resour
* Create a new {@link ContentType} selector.
*
* @param project
+ * Ant {@link Project}
*/
public ContentType(final Project project) {
super(project);
@@ -287,6 +295,7 @@ public abstract class CompareSelect extends
ResourceComparator implements Resour
* Create a new {@link Meta} selector.
*
* @param project
+ * Ant {@link Project}
*/
public Meta(final Project project) {
super(project);
@@ -305,6 +314,7 @@ public abstract class CompareSelect extends
ResourceComparator implements Resour
* Set the user metadata key to match on.
*
* @param key
+ * to match
*/
public void setKey(final String key) {
this.key = key;
@@ -329,6 +339,7 @@ public abstract class CompareSelect extends
ResourceComparator implements Resour
* Create a new {@link Tag} selector.
*
* @param project
+ * Ant {@link Project}
*/
public Tag(final Project project) {
super(project);
@@ -347,6 +358,7 @@ public abstract class CompareSelect extends
ResourceComparator implements Resour
* Set the tag key to match on.
*
* @param key
+ * to match
*/
public void setKey(final String key) {
this.key = key;
@@ -370,11 +382,15 @@ public abstract class CompareSelect extends
ResourceComparator implements Resour
* Create a new {@link VersionId} selector.
*
* @param project
+ * Ant {@link Project}
*/
public VersionId(Project project) {
super(project);
}
+ /**
+ * {@inheritDoc}
+ */
@Override
protected String extractValueFrom(ObjectResource obj) {
return obj.getVersionId();
@@ -392,6 +408,9 @@ public abstract class CompareSelect extends
ResourceComparator implements Resour
* Create a new {@link CompareSelect.ForBooleanAttribute}.
*
* @param project
+ * Ant {@link Project}
+ * @param test
+ * to determine truth
*/
protected ForBooleanAttribute(Project project,
Predicate<ObjectResource> test) {
super(project);
@@ -425,6 +444,7 @@ public abstract class CompareSelect extends
ResourceComparator implements Resour
* Create a new {@link DeleteMarker}.
*
* @param project
+ * Ant {@link Project}
*/
public DeleteMarker(Project project) {
super(project, ObjectResource::isDeleteMarker);
@@ -440,6 +460,7 @@ public abstract class CompareSelect extends
ResourceComparator implements Resour
* Create a new {@link Latest}.
*
* @param project
+ * Ant {@link Project}
*/
public Latest(Project project) {
super(project, ObjectResource::isLatest);
@@ -458,6 +479,7 @@ public abstract class CompareSelect extends
ResourceComparator implements Resour
* Create a new {@link ByPrecision}.
*
* @param project
+ * Ant {@link Project}
*/
public ByPrecision(Project project) {
super(project);
@@ -476,7 +498,7 @@ public abstract class CompareSelect extends
ResourceComparator implements Resour
* Set the precision.
*
* @param precision
- * Precision
+ * {@link Precision}
*/
public void setPrecision(Precision precision) {
this.precision = precision;
@@ -512,6 +534,7 @@ public abstract class CompareSelect extends
ResourceComparator implements Resour
* Create a {@link CompareSelect} instance.
*
* @param project
+ * Ant {@link Project}
*/
protected CompareSelect(Project project) {
setProject(project);
diff --git a/src/main/org/apache/ant/s3/CopyResources.java
b/src/main/org/apache/ant/s3/CopyResources.java
index 43d9098..ea68c29 100644
--- a/src/main/org/apache/ant/s3/CopyResources.java
+++ b/src/main/org/apache/ant/s3/CopyResources.java
@@ -54,6 +54,16 @@ public abstract class CopyResources extends LoggingTask {
private boolean preserveLastModified;
/**
+ * Create a new {@link CopyResources} instance.
+ *
+ * @param project
+ * Ant {@link Project}
+ */
+ protected CopyResources(Project project) {
+ super(project);
+ }
+
+ /**
* {@inheritDoc}
*/
@Override
@@ -105,8 +115,9 @@ public abstract class CopyResources extends LoggingTask {
* Add a nested source {@link ResourceCollection}.
*
* @param sources
+ * to add
*/
- public void add(final ResourceCollection sources) {
+ public void add(ResourceCollection sources) {
this.sources.add(sources);
}
@@ -131,7 +142,7 @@ public abstract class CopyResources extends LoggingTask {
* @param fileNameMapper
* the {@link FileNameMapper} to add
*/
- public void add(final FileNameMapper fileNameMapper) {
+ public void add(FileNameMapper fileNameMapper) {
createMapper().add(fileNameMapper);
}
@@ -148,8 +159,9 @@ public abstract class CopyResources extends LoggingTask {
* Set the input encoding.
*
* @param inputEncoding
+ * to set
*/
- public void setInputEncoding(final String inputEncoding) {
+ public void setInputEncoding(String inputEncoding) {
this.inputEncoding = inputEncoding;
}
@@ -166,8 +178,9 @@ public abstract class CopyResources extends LoggingTask {
* Set the output encoding.
*
* @param outputEncoding
+ * to set
*/
- public void setOutputEncoding(final String outputEncoding) {
+ public void setOutputEncoding(String outputEncoding) {
this.outputEncoding = outputEncoding;
}
@@ -184,8 +197,9 @@ public abstract class CopyResources extends LoggingTask {
* Set whether global Ant filters should be applied to copy operations.
*
* @param filtering
+ * flag
*/
- public void setFiltering(final boolean filtering) {
+ public void setFiltering(boolean filtering) {
this.filtering = filtering;
}
@@ -224,8 +238,9 @@ public abstract class CopyResources extends LoggingTask {
* Set whether up-to-date target {@link Resource}s should be overwritten.
*
* @param overwrite
+ * flag
*/
- public void setOverwrite(final boolean overwrite) {
+ public void setOverwrite(boolean overwrite) {
this.overwrite = overwrite;
}
@@ -248,15 +263,16 @@ public abstract class CopyResources extends LoggingTask {
* be copied to.
*
* @param enableMultipleMappings
+ * flag
*/
- public void setEnableMultipleMappings(final boolean
enableMultipleMappings) {
+ public void setEnableMultipleMappings(boolean enableMultipleMappings) {
this.enableMultipleMappings = enableMultipleMappings;
}
/**
* Learn whether target {@link Resource} content should be appended.
*
- * @return
+ * @return {@code boolean}
*/
public boolean isAppend() {
return append;
@@ -266,8 +282,9 @@ public abstract class CopyResources extends LoggingTask {
* Set whether target {@link Resource} content should be appended.
*
* @param append
+ * flag
*/
- public void setAppend(final boolean append) {
+ public void setAppend(boolean append) {
this.append = append;
}
@@ -285,8 +302,9 @@ public abstract class CopyResources extends LoggingTask {
* Set whether to preserve last modified time on target {@link Resource}s.
*
* @param preserveLastModified
+ * flag
*/
- public void setPreserveLastModified(final boolean preserveLastModified) {
+ public void setPreserveLastModified(boolean preserveLastModified) {
this.preserveLastModified = preserveLastModified;
}
@@ -302,13 +320,17 @@ public abstract class CopyResources extends LoggingTask {
* {@link FilterSetCollection} and {@code filterChains}.
*
* @param source
+ * {@link Resource}
* @param dest
+ * {@link Resource}
* @param filters
+ * {@link FilterSetCollection}
* @param filterChains
- * @throws IOException
+ * {@link Vector} of {@link FilterChain}
+ * @throws IOException on error
*/
- protected void copyResource(final Resource source, final Resource dest,
final FilterSetCollection filters,
- final Vector<FilterChain> filterChains) throws IOException {
+ protected void copyResource(Resource source, Resource dest,
FilterSetCollection filters,
+ Vector<FilterChain> filterChains) throws IOException {
ResourceUtils.copyResource(source, dest, filters, filterChains,
isOverwrite(), isPreserveLastModified(),
isAppend(), getInputEncoding(), getOutputEncoding(), getProject());
}
diff --git a/src/main/org/apache/ant/s3/Delete.java
b/src/main/org/apache/ant/s3/Delete.java
index 0700d65..a71ec98 100644
--- a/src/main/org/apache/ant/s3/Delete.java
+++ b/src/main/org/apache/ant/s3/Delete.java
@@ -53,17 +53,11 @@ public class Delete extends LoggingTask {
private int blockSize = DEFAULT_BLOCK_SIZE;
/**
- * Create a new {@link Delete} task instance.
- */
- public Delete() {
- super();
- }
-
- /**
* Create a new {@link Delete} task instance bound to the specified
* {@link Project}.
*
* @param project
+ * Ant {@link Project}
*/
public Delete(Project project) {
super(project);
@@ -98,6 +92,7 @@ public class Delete extends LoggingTask {
* Add a configured {@link Client}.
*
* @param s3
+ * {@link Client}
*/
public void addConfigured(final Client s3) {
if (this.s3 != null) {
@@ -110,6 +105,7 @@ public class Delete extends LoggingTask {
* Set the {@link Client} by reference.
*
* @param refid
+ * of {@link Client}
*/
public void setClientRefid(final String refid) {
Objects.requireNonNull(StringUtils.trimToNull(refid), "@clientrefid
must not be null/empty/blank");
@@ -121,6 +117,7 @@ public class Delete extends LoggingTask {
* Add a nested {@link ResourceCollection}.
*
* @param coll
+ * {@link ResourceCollection}
*/
public synchronized void addConfigured(ResourceCollection coll) {
Exceptions.raiseIf(coll == null, IllegalArgumentException::new, "null
%s",
@@ -140,6 +137,7 @@ public class Delete extends LoggingTask {
* Add by reference a {@link ResourceCollection} to delete.
*
* @param refid
+ * of {@link ResourceCollection}
*/
public void setRefid(Reference refid) {
addConfigured(refid.<ResourceCollection>
getReferencedObject(getProject()));
diff --git a/src/main/org/apache/ant/s3/InlineProperties.java
b/src/main/org/apache/ant/s3/InlineProperties.java
index 7aff31d..22f4f89 100644
--- a/src/main/org/apache/ant/s3/InlineProperties.java
+++ b/src/main/org/apache/ant/s3/InlineProperties.java
@@ -40,9 +40,9 @@ public class InlineProperties extends S3DataType implements
DynamicElementNS {
/**
* Create a new {@link InlineProperties} instance.
*
- * @param project
+ * @param project Ant {@link Project}
*/
- public InlineProperties(final Project project) {
+ public InlineProperties(Project project) {
super(project);
}
@@ -52,7 +52,7 @@ public class InlineProperties extends S3DataType implements
DynamicElementNS {
public final class InlineProperty {
private final String name;
- private InlineProperty(final String name) {
+ private InlineProperty(String name) {
this.name = name;
}
@@ -62,7 +62,7 @@ public class InlineProperties extends S3DataType implements
DynamicElementNS {
* @param text
* to add
*/
- public void addText(final String text) {
+ public void addText(String text) {
final String value;
if (properties.containsKey(name)) {
value = Stream.of(properties.getProperty(name),
text).filter(Objects::nonNull)
@@ -91,7 +91,7 @@ public class InlineProperties extends S3DataType implements
DynamicElementNS {
* @return InlineProperty
*/
@Override
- public InlineProperty createDynamicElement(final String uri, final String
localName, final String qName) {
+ public InlineProperty createDynamicElement(String uri, String localName,
String qName) {
return new InlineProperty(localName);
}
}
\ No newline at end of file
diff --git a/src/main/org/apache/ant/s3/LoggingTask.java
b/src/main/org/apache/ant/s3/LoggingTask.java
index c69203a..2ea09d2 100644
--- a/src/main/org/apache/ant/s3/LoggingTask.java
+++ b/src/main/org/apache/ant/s3/LoggingTask.java
@@ -29,20 +29,13 @@ abstract class LoggingTask extends Task implements
ProjectUtils {
private int verbosity = Project.MSG_VERBOSE;
/**
- * Create a new {@link LoggingTask} instance.
- */
- protected LoggingTask() {
- super();
- }
-
- /**
* Create a new {@link LoggingTask} instance bound to the specified
* {@link Project}.
*
* @param project
+ * Ant {@link Project}
*/
protected LoggingTask(Project project) {
- this();
setProject(project);
}
@@ -59,8 +52,9 @@ abstract class LoggingTask extends Task implements
ProjectUtils {
* Set whether this {@link Task} should operate with increased log output.
*
* @param verbose
+ * flag
*/
- public void setVerbose(final boolean verbose) {
+ public void setVerbose(boolean verbose) {
verbosity = verbose ? Project.MSG_INFO : Project.MSG_VERBOSE;
}
@@ -69,10 +63,12 @@ abstract class LoggingTask extends Task implements
ProjectUtils {
* {@link #isVerbose()}.
*
* @param format
+ * {@link String}
* @param args
+ * format args
* @see Formatter
*/
- protected void log(final String format, final Object... args) {
+ protected void log(String format, Object... args) {
log(verbosity, format, args);
}
@@ -80,23 +76,30 @@ abstract class LoggingTask extends Task implements
ProjectUtils {
* Log a formatted message at the specified level.
*
* @param level
+ * log level
* @param format
+ * {@link String}
* @param args
+ * format args
* @see Formatter
*/
- protected void log(final int level, final String format, final Object...
args) {
+ protected void log(int level, String format, Object... args) {
log(String.format(format, args), level);
}
/**
- * Log a formatted message with accompanying/triggering {@link Throwable}.
+ * Log a formatted message at {@link Project#MSG_ERR} level with
+ * accompanying/triggering {@link Throwable}.
*
* @param t
+ * {@link Throwable}
* @param format
+ * {@link String}
* @param args
+ * format args
* @see Formatter
*/
- protected void log(final Throwable t, final String format, final Object...
args) {
+ protected void log(Throwable t, String format, Object... args) {
log(Project.MSG_ERR, t, format, args);
}
@@ -105,14 +108,16 @@ abstract class LoggingTask extends Task implements
ProjectUtils {
* a specific level.
*
* @param level
+ * log level
* @param t
+ * {@link Throwable}
* @param format
+ * {@link String}
* @param args
+ * format args
* @see Formatter
*/
- protected void log(final int level, final Throwable t, final String format,
- final Object... args) {
+ protected void log(int level, Throwable t, String format, Object... args) {
log(String.format(format, args), t, level);
}
-
}
\ No newline at end of file
diff --git a/src/main/org/apache/ant/s3/ObjectResource.java
b/src/main/org/apache/ant/s3/ObjectResource.java
index f0653fc..585243b 100644
--- a/src/main/org/apache/ant/s3/ObjectResource.java
+++ b/src/main/org/apache/ant/s3/ObjectResource.java
@@ -74,8 +74,7 @@ public class ObjectResource extends Resource implements
ProjectUtils {
@FunctionalInterface
private interface Finalizer {
- static final Finalizer NOP = () -> {
- };
+ static final Finalizer NOP = () -> {};
void run() throws Exception;
@@ -115,58 +114,122 @@ public class ObjectResource extends Resource implements
ProjectUtils {
* Create a new {@link ObjectResource}.
*
* @param project
+ * Ant {@link Project}
*/
public ObjectResource(Project project) {
setProject(project);
}
/**
- * Create a new {@link ObjectResource} from a listing.
+ * Create an {@link ObjectResource} from a listing.
*
* @param project
+ * Ant {@link Project}
* @param s3
+ * {@link S3Client}
* @param bucket
+ * of object
* @param summary
- * @param precision
+ * object info
*/
ObjectResource(Project project, S3Client s3, String bucket, S3Object
summary) {
this(project, s3, bucket, summary.key(), summary::size,
summary::lastModified, null, Precision.object);
}
+ /**
+ * Create an {@link ObjectResource} representing a delete marker.
+ *
+ * @param project
+ * Ant {@link Project}
+ * @param s3
+ * {@link S3Client}
+ * @param bucket
+ * of object
+ * @param deleteMarker
+ * info
+ */
ObjectResource(Project project, S3Client s3, String bucket,
DeleteMarkerEntry deleteMarker) {
this(project, s3, bucket, deleteMarker.key(), () -> UNKNOWN_SIZE,
deleteMarker::lastModified,
deleteMarker::versionId, Precision.version);
versionInfo = Optional.ofNullable(new VersionInfo(true,
deleteMarker.isLatest().booleanValue()));
}
+ /**
+ * Create an {@link ObjectResource} representing an object version.
+ *
+ * @param project
+ * Ant {@link Project}
+ * @param s3
+ * {@link S3Client}
+ * @param bucket
+ * of object
+ * @param version
+ * info
+ */
ObjectResource(Project project, S3Client s3, String bucket, ObjectVersion
version) {
this(project, s3, bucket, version.key(), version::size,
version::lastModified, version::versionId,
Precision.version);
versionInfo = Optional.of(new VersionInfo(false,
version.isLatest().booleanValue()));
}
+ /**
+ * Create an {@link ObjectResource}.
+ *
+ * @param project
+ * Ant {@link Project}
+ * @param s3
+ * {@link S3Client}
+ * @param bucket
+ * of object
+ * @param key
+ * of object
+ * @param size
+ * of object
+ * @param lastModified
+ * of object
+ * @param versionId
+ * of object
+ * @param precision
+ * of object
+ */
ObjectResource(Project project, S3Client s3, String bucket, String key,
LongSupplier size,
Supplier<Instant> lastModified, Supplier<String> versionId, Precision
precision) {
-
this(project, s3, bucket, key);
this.size = size;
this.lastModified = lastModified;
this.versionId = versionId;
}
+ /**
+ * Create an {@link ObjectResource} representing a prefix.
+ *
+ * @param project
+ * Ant {@link Project}
+ * @param s3
+ * {@link S3Client}
+ * @param bucket
+ * of prefix
+ * @param prefix
+ * {@link String}
+ * @return {@link ObjectResource}
+ */
static ObjectResource ofPrefix(Project project, S3Client s3, String
bucket, String prefix) {
- ObjectResource result = new ObjectResource(project,s3,bucket,prefix);
+ final ObjectResource result = new ObjectResource(project, s3, bucket,
prefix);
result._setDirectory(true);
return result;
}
/**
- * Create a new {@link ObjectResource} fully-formed.
+ * Create a new {@link ObjectResource} with complete identifying info.
*
* @param project
+ * Ant {@link Project}
* @param s3
+ * {@link S3Client}
* @param bucket
+ * of object
* @param key
+ * of object
*/
ObjectResource(Project project, S3Client s3, String bucket, String key) {
setProject(project);
@@ -188,6 +251,7 @@ public class ObjectResource extends Resource implements
ProjectUtils {
* Set the bucket of the S3 object.
*
* @param bucket
+ * of object
*/
public void setBucket(String bucket) {
checkAttributesAllowed();
@@ -210,6 +274,7 @@ public class ObjectResource extends Resource implements
ProjectUtils {
* Set the key of the S3 object within its bucket.
*
* @param key
+ * of object
*/
public void setKey(String key) {
this.key = key;
@@ -218,6 +283,9 @@ public class ObjectResource extends Resource implements
ProjectUtils {
/**
* Set the name of the S3 object, which for our purposes is equivalent to
* calling {@link #setKey(String)}.
+ *
+ * @param name
+ * {@code key}
*/
@Override
public void setName(String name) {
@@ -228,6 +296,8 @@ public class ObjectResource extends Resource implements
ProjectUtils {
* Get the name of the S3 object, which may be suffixed with the object
* version if {@link #getPrecision()} returns {@link Precision#version} and
* this object exists.
+ *
+ * @return {@link String}
*/
@Override
public String getName() {
@@ -244,7 +314,9 @@ public class ObjectResource extends Resource implements
ProjectUtils {
/**
* {@inheritDoc}
+ *
* @throws UnsupportedOperationException
+ * always
*/
@Override
public void setDirectory(boolean directory) {
@@ -295,6 +367,7 @@ public class ObjectResource extends Resource implements
ProjectUtils {
* Set the content type of the S3 object.
*
* @param contentType
+ * of object
*/
public void setContentType(String contentType) {
this.contentType = contentType;
@@ -339,6 +412,7 @@ public class ObjectResource extends Resource implements
ProjectUtils {
* Set the metadata.
*
* @param metadata
+ * of object
*/
public void setMetadata(Map<String, String> metadata) {
Exceptions.raiseIf(isReference(), UnsupportedOperationException::new,
"setMetadata");
@@ -386,6 +460,7 @@ public class ObjectResource extends Resource implements
ProjectUtils {
* Set the tagging for the S3 object.
*
* @param tagging
+ * of object
*/
public void setTagging(Map<String, String> tagging) {
if (isReference()) {
@@ -398,6 +473,7 @@ public class ObjectResource extends Resource implements
ProjectUtils {
* Add the configured {@link Client} element.
*
* @param s3
+ * {@link Client}
*/
public void addConfigured(Client s3) {
checkChildrenAllowed();
@@ -412,11 +488,11 @@ public class ObjectResource extends Resource implements
ProjectUtils {
* Set the {@link Client} by reference.
*
* @param refid
+ * of {@link Client}
*/
public void setClientRefid(String refid) {
checkAttributesAllowed();
- Exceptions.raiseIf(StringUtils.isBlank(refid), buildException(),
- "@clientrefid must not be null/empty/blank");
+ Exceptions.raiseIf(StringUtils.isBlank(refid), buildException(),
"@clientrefid must not be null/empty/blank");
addConfigured(getProject().<Client> getReference(refid));
}
@@ -521,6 +597,7 @@ public class ObjectResource extends Resource implements
ProjectUtils {
* Put a {@link File} as the content of this S3 object.
*
* @param file
+ * source
*/
public void put(File file) {
if (isReference()) {
@@ -535,7 +612,9 @@ public class ObjectResource extends Resource implements
ProjectUtils {
* {@link S3Client} client to use.
*
* @param s3
+ * {@link S3Client} to use
* @param file
+ * source
*/
public void put(S3Client s3, File file) {
if (isReference()) {
@@ -558,6 +637,7 @@ public class ObjectResource extends Resource implements
ProjectUtils {
* Delete this object from its bucket using the specified {@link S3Client}.
*
* @param s3
+ * {@link S3Client} to use
*/
public void delete(S3Client s3) {
if (isReference()) {
@@ -597,6 +677,7 @@ public class ObjectResource extends Resource implements
ProjectUtils {
* data are equal, in addition to {@link Object#equals(Object)} equality.
*
* @param other
+ * object to compare for equality
* @return {@code boolean}
*/
public boolean fullyEquals(Object other) {
@@ -709,4 +790,3 @@ public class ObjectResource extends Resource implements
ProjectUtils {
super.setDirectory(directory);
}
}
-
diff --git a/src/main/org/apache/ant/s3/ObjectResources.java
b/src/main/org/apache/ant/s3/ObjectResources.java
index ca40fc2..a447952 100644
--- a/src/main/org/apache/ant/s3/ObjectResources.java
+++ b/src/main/org/apache/ant/s3/ObjectResources.java
@@ -73,6 +73,7 @@ public class ObjectResources extends S3DataType implements
ResourceCollection {
* Create a new {@link ObjectResources} instance.
*
* @param project
+ * Ant {@link Project}
*/
public ObjectResources(final Project project) {
super(project);
@@ -84,6 +85,7 @@ public class ObjectResources extends S3DataType implements
ResourceCollection {
* Add the nested {@link Client}.
*
* @param s3
+ * {@link Client}
*/
public void addConfigured(final Client s3) {
checkChildrenAllowed();
@@ -99,6 +101,7 @@ public class ObjectResources extends S3DataType implements
ResourceCollection {
* Set {@link Client} by reference.
*
* @param refid
+ * of {@link Client}
*/
public void setClientRefid(final String refid) {
checkAttributesAllowed();
@@ -113,6 +116,7 @@ public class ObjectResources extends S3DataType implements
ResourceCollection {
* Add a configured {@link ResourceSelector}.
*
* @param selector
+ * to add
*/
public void addConfigured(ResourceSelector selector) {
checkChildrenAllowed();
@@ -215,6 +219,7 @@ public class ObjectResources extends S3DataType implements
ResourceCollection {
* Set the bucket of this {@link ObjectResources}.
*
* @param bucket
+ * where resources exist
*/
public void setBucket(String bucket) {
checkAttributesAllowed();
@@ -240,13 +245,13 @@ public class ObjectResources extends S3DataType
implements ResourceCollection {
* name property and {@link Object#toString()} value of generated
* {@link ObjectResource}s.
*
- * @param precision
+ * @param as
* {@link Precision}
*/
- public void setAs(Precision precision) {
+ public void setAs(Precision as) {
checkAttributesAllowed();
- if (precision != this.as) {
- this.as = Objects.requireNonNull(precision);
+ if (as != this.as) {
+ this.as = Objects.requireNonNull(as);
resetResourceCache();
}
}
@@ -314,6 +319,7 @@ public class ObjectResources extends S3DataType implements
ResourceCollection {
* default {@code true}.
*
* @param cache
+ * flag
*/
public void setCache(boolean cache) {
this.cache = cache;
@@ -335,7 +341,9 @@ public class ObjectResources extends S3DataType implements
ResourceCollection {
/**
* Set whether to include S3 object prefixes as "directory" type
* {@link Resource}s, default {@code false}.
- * @param includePrefixes {@code boolean}
+ *
+ * @param includePrefixes
+ * {@code boolean}
*/
public void setIncludePrefixes(boolean includePrefixes) {
checkAttributesAllowed();
@@ -349,6 +357,7 @@ public class ObjectResources extends S3DataType implements
ResourceCollection {
* Add a nested {@link PatternSet}.
*
* @param patternSet
+ * to add
*/
public void addConfigured(PatternSet patternSet) {
checkChildrenAllowed();
@@ -404,6 +413,7 @@ public class ObjectResources extends S3DataType implements
ResourceCollection {
* Set includes patterns via attribute.
*
* @param includes
+ * patterns
*/
public void setIncludes(String includes) {
checkAttributesAllowed();
@@ -415,6 +425,7 @@ public class ObjectResources extends S3DataType implements
ResourceCollection {
* Set includes file via attribute.
*
* @param includesFile
+ * {@link File}
*/
public void setIncludesFile(File includesFile) {
checkAttributesAllowed();
@@ -423,9 +434,10 @@ public class ObjectResources extends S3DataType implements
ResourceCollection {
}
/**
- * Set excludes pattersn via attribute.
+ * Set excludes patterns via attribute.
*
* @param excludes
+ * patterns
*/
public void setExcludes(String excludes) {
checkAttributesAllowed();
@@ -437,6 +449,7 @@ public class ObjectResources extends S3DataType implements
ResourceCollection {
* Set excludes file via attribute.
*
* @param excludesFile
+ * {@link File}
*/
public void setExcludesFile(File excludesFile) {
checkAttributesAllowed();
diff --git a/src/main/org/apache/ant/s3/ProjectUtils.java
b/src/main/org/apache/ant/s3/ProjectUtils.java
index fa6cd4f..e4a739a 100644
--- a/src/main/org/apache/ant/s3/ProjectUtils.java
+++ b/src/main/org/apache/ant/s3/ProjectUtils.java
@@ -35,7 +35,7 @@ interface ProjectUtils {
/**
* Attempt to determine a component name for the specified type.
*
- * @param type
+ * @param type for which component name is desired
*
* @return {@link String}
*/
@@ -47,8 +47,8 @@ interface ProjectUtils {
* Attempt to determine a component name for the specified type relative to
* the specified {@link Project}.
*
- * @param project
- * @param type
+ * @param project Ant project
+ * @param type for which component name is desired
* @return {@link String}
*/
default String componentName(final Project project, final Class<?> type) {
@@ -68,9 +68,9 @@ interface ProjectUtils {
/**
* Require the specified item.
*
- * @param <T>
- * @param item
- * @param description
+ * @param <T> type
+ * @param item required object
+ * @param description description in thrown {@link Exception} if absent
* @return {@code item}
* @throws IllegalStateException
* if {@code t == null}
@@ -83,10 +83,10 @@ interface ProjectUtils {
/**
* Require the specified component.
*
- * @param component
- * @param type
+ * @param component required component
+ * @param type of component
*
- * @param <T>
+ * @param <T> type
* @return {@code component}
*/
default <T> T requireComponent(final T component, final Class<?> type) {
@@ -97,7 +97,6 @@ interface ProjectUtils {
* Create a {@link Function} that will create a {@link BuildException} at
* the specified {@link Location}, given the {@link String} message.
*
- * @param location
* @return {@link Function}
*/
default Function<String, BuildException> buildException() {
@@ -109,7 +108,6 @@ interface ProjectUtils {
* the specified {@link Location}, given the {@link String} message and
* {@link Throwable} cause.
*
- * @param location
* @return {@link BiFunction}
*/
default BiFunction<String, Throwable, BuildException>
buildExceptionTriggered() {
diff --git a/src/main/org/apache/ant/s3/Put.java
b/src/main/org/apache/ant/s3/Put.java
index 898e376..109e4c4 100644
--- a/src/main/org/apache/ant/s3/Put.java
+++ b/src/main/org/apache/ant/s3/Put.java
@@ -23,6 +23,7 @@ import java.util.Vector;
import java.util.function.Supplier;
import org.apache.tools.ant.BuildException;
+import org.apache.tools.ant.Project;
import org.apache.tools.ant.types.FilterChain;
import org.apache.tools.ant.types.FilterSetCollection;
import org.apache.tools.ant.types.Resource;
@@ -41,9 +42,20 @@ public class Put extends CopyResources {
private String bucket;
/**
+ * Create a new {@link Put} instance.
+ *
+ * @param project
+ * Ant {@link Project}
+ */
+ public Put(Project project) {
+ super(project);
+ }
+
+ /**
* Add a configured {@link Client}.
*
* @param s3
+ * {@link Client}
*/
public void addConfigured(Client s3) {
if (this.s3 != null) {
@@ -56,6 +68,7 @@ public class Put extends CopyResources {
* Set the {@link Client} by reference.
*
* @param refid
+ * of {@link Client}
*/
public void setClientRefid(String refid) {
Objects.requireNonNull(StringUtils.trimToNull(refid), "@clientrefid
must not be null/empty/blank");
@@ -76,6 +89,7 @@ public class Put extends CopyResources {
* Set the bucket to which target objects should be written.
*
* @param bucket
+ * target
*/
public void setBucket(String bucket) {
this.bucket = StringUtils.trimToNull(bucket);
@@ -85,6 +99,7 @@ public class Put extends CopyResources {
* Disable {@code append}.
*
* @param append
+ * flag
* @throws BuildException
* if {@code append == true}
*/
@@ -97,6 +112,7 @@ public class Put extends CopyResources {
* Disable {@code preserveLastModified}.
*
* @param preserveLastModified
+ * flag
* @throws BuildException
* if {@code preserveLastModified == true}
*/
@@ -117,9 +133,10 @@ public class Put extends CopyResources {
}
/**
- * Disable {@code overwrite}.
+ * Force {@code overwrite}.
*
* @param overwrite
+ * flag
* @throws BuildException
* if {@code overwrite == false}
*/
diff --git a/src/main/org/apache/ant/s3/S3DataType.java
b/src/main/org/apache/ant/s3/S3DataType.java
index f2c38f5..fe805e2 100644
--- a/src/main/org/apache/ant/s3/S3DataType.java
+++ b/src/main/org/apache/ant/s3/S3DataType.java
@@ -28,18 +28,17 @@ public abstract class S3DataType extends DataType
implements ProjectUtils {
/**
* Create a new {@link S3DataType} instance.
*
- * @param project
+ * @param project Ant {@link Project}
*/
protected S3DataType(final Project project) {
setProject(project);
}
/**
- * Log a formatted message at the default level dictated by
- * {@link #isVerbose()}.
+ * Log a formatted message at {@link Project#MSG_INFO} level.
*
- * @param format
- * @param args
+ * @param format {@link String}
+ * @param args to format
* @see Formatter
*/
protected void log(final String format, final Object... args) {
@@ -49,9 +48,9 @@ public abstract class S3DataType extends DataType implements
ProjectUtils {
/**
* Log a formatted message at the specified level.
*
- * @param level
- * @param format
- * @param args
+ * @param level log level
+ * @param format {@link String}
+ * @param args to format
* @see Formatter
*/
protected void log(final int level, final String format, final Object...
args) {
