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 6b2f913ad126cb2443864829a7802d99b7188dd5 Author: Matt Benson <mben...@apache.org> AuthorDate: Thu Mar 10 16:13:36 2022 -0600 first cut of documentation --- docs/index.html | 96 +++++++++++++++++++++++++++++++++++ docs/inlineproperties.html | 36 +++++++++++++ docs/s3client.html | 80 +++++++++++++++++++++++++++++ docs/s3compareselect.html | 35 +++++++++++++ docs/s3delete.html | 82 ++++++++++++++++++++++++++++++ docs/s3object.html | 80 +++++++++++++++++++++++++++++ docs/s3objects.html | 122 +++++++++++++++++++++++++++++++++++++++++++++ docs/s3put.html | 96 +++++++++++++++++++++++++++++++++++ docs/style.css | 63 +++++++++++++++++++++++ 9 files changed, 690 insertions(+) diff --git a/docs/index.html b/docs/index.html new file mode 100644 index 0000000..828748f --- /dev/null +++ b/docs/index.html @@ -0,0 +1,96 @@ +<!-- + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + https://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +--> +<html> + <head> + <meta http-equiv="Content-Language" content="en-us"></meta> + <link rel="stylesheet" type="text/css" href="style.css"> + <title>S3 Ant Library</title> + </head> + + <body> + <h2>Introduction</h2> + + <p>This is a library of Ant type definitions that support working with + Amazon Web Services' Simple Storage Service AKA S3.</p> + + <h2>Requirements</h2> + + <p>The current version requires Ant 1.10.7 or later.</p> + + <h2>Where is it?</h2> + + <p>The source code for the library lives in the + ant-antlibs-s3 git repository - <a + href="https://gitbox.apache.org/repos/asf?p=ant-antlibs-s3.git">https://gitbox.apache.org/repos/asf/ant-antlibs-s3.git</a>.</p> + + <h2>Installation</h2> + + <p>If you are building this from sources, run the antlib target + and you'll get a file <code>ant-s3.jar</code>.</p> + + <p>The defined types are named so as to encourage their use via + namespace declaration. Place <code>ant-s3.jar</code> + into a directory and use <code>ant -lib + DIR-CONTAINING-THE-JAR</code> or copy it into + <code>ANT_HOME/lib</code> - and then in your build file, simply + declare the namespace on the <code>project</code> tag: + + <pre> + <project xmlns:s3="antlib:org.apache.ant.s3"> + </pre> + + ...and the types defined by this library will automatically be + available in the <code>s3</code> namespace. + + It is planned to publish the artifact with dependency information such that + tools like Apache Ivy or Apache Maven can retrieve all required dependencies. + </p> + + <h2>Supplied Tasks</h2> + + <ul> + <li><a href="s3put.html">s3:put</a> - Put an Ant + <code>ResourceCollection</code> into an S3 bucket.</li> + + <li><a href="s3delete.html">s3:delete</a> - Delete objects from an S3 bucket. + </li> + </ul> + + <h2>Supplied Types</h2> + + <ul> + <li><a href="s3client.html">s3:client</a> - Represents an instance + of the AWS SDK's <pre>AmazonS3</pre> client interface.</li> + + <li><a href="s3object.html">s3:object</a> - Ant <code>Resource</code> + implementation representing a single S3 object.</li> + + <li><a href="s3objects.html">s3:objects</a> - Ant + <code>ResourceCollection</code> collecting the objects located at a + particular bucket and prefix.</li> + </ul> + + <h3>Custom resource comparators/selectors</h3> + + A number of types are provided that implement both interfaces for use with + Ant's <code>sort</code> and <code>restrict</code> resource collections. + These are situated in a secondary Antlib namespace + <a href="s3compareselect.html"><code>org.apache.ant.s3cs</code></href>. + + <hr/> + </body> +</html> diff --git a/docs/inlineproperties.html b/docs/inlineproperties.html new file mode 100644 index 0000000..1f67ee9 --- /dev/null +++ b/docs/inlineproperties.html @@ -0,0 +1,36 @@ +<!-- +Licensed to the Apache Software Foundation (ASF) under one +or more contributor license agreements. See the NOTICE file +distributed with this work for additional information +regarding copyright ownership. The ASF licenses this file +to you under the Apache License, Version 2.0 (the +"License"); you may not use this file except in compliance +with the License. You may obtain a copy of the License at + +https://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, +software distributed under the License is distributed on an +"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +KIND, either express or implied. See the License for the +specific language governing permissions and limitations +under the License. +--> +<html> + <head> + <meta http-equiv="Content-Language" content="en-us"></meta> + <link rel="stylesheet" type="text/css" href="style.css"> + <title>Inline Properties</title> + </head> + + <body> + <h2><a name="inlineproperties">inlineproperties</a></h2> + + <h3>Description</h3> + + <p>Type to specify Java properties with XML. Element names are property keys + and their string values are the property values.</p> + + </body> +</html> + diff --git a/docs/s3client.html b/docs/s3client.html new file mode 100644 index 0000000..fc242f3 --- /dev/null +++ b/docs/s3client.html @@ -0,0 +1,80 @@ +<!-- +Licensed to the Apache Software Foundation (ASF) under one +or more contributor license agreements. See the NOTICE file +distributed with this work for additional information +regarding copyright ownership. The ASF licenses this file +to you under the Apache License, Version 2.0 (the +"License"); you may not use this file except in compliance +with the License. You may obtain a copy of the License at + +https://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, +software distributed under the License is distributed on an +"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +KIND, either express or implied. See the License for the +specific language governing permissions and limitations +under the License. +--> +<html> + <head> + <meta http-equiv="Content-Language" content="en-us"></meta> + <link rel="stylesheet" type="text/css" href="style.css"> + <title>S3 Client</title> + </head> + + <body> + <h2><a name="s3client">s3:client</a></h2> + + <h3>Description</h3> + + <p>Declare an Amazon S3 client for use in the S3 Antlib.</p> + + <h3>Parameters specified as nested elements</h3> + + <h4>builder</h4> + + <p>The builder element applies its XML configuration to an AWS SDK 2.x + <code>S3ClientBuilder</code>. Attributes are interpreted as simple + string-convertible properties, while elements are interpreted as nested + builders of the type specified by the method parameter.</p> + + <h4>credentials</h4> + + <p>The <code>credentials</code> element permits an easier mechanism + for specifying client credentials.</p> + + <h5>Parameters</h5> + <table border="1" cellpadding="2" cellspacing="0"> + <tr> + <td valign="top"><b>Attribute</b></td> + <td valign="top"><b>Description</b></td> + <td align="center" valign="top"><b>Required</b></td> + </tr> + <tr> + <td valign="top">accesskey</td> + <td valign="top">AWS Access key</td> + <td align="center">Yes, unless <code>profile</code> is specified</td> + </tr> + <tr> + <td valign="top">secretkey</td> + <td valign="top">AWS Secret key</td> + <td align="center">Yes, unless <code>profile</code> is specified</td> + </tr> + <tr> + <td valign="top">profile</td> + <td valign="top">AWS profile ID</td> + <td align="center">Yes, unless <code>@accesskey</code> and + <code>@secretkey</code> are specified + </td> + </tr> + </table> + + <h4>http</h4> + + <p><a href="inlineproperties.html">Inline properties</a> specifying + <code>SdkHttpConfigurationOption</code> constants</p> + + </body> +</html> + diff --git a/docs/s3compareselect.html b/docs/s3compareselect.html new file mode 100644 index 0000000..fdac69f --- /dev/null +++ b/docs/s3compareselect.html @@ -0,0 +1,35 @@ +<!-- +Licensed to the Apache Software Foundation (ASF) under one +or more contributor license agreements. See the NOTICE file +distributed with this work for additional information +regarding copyright ownership. The ASF licenses this file +to you under the Apache License, Version 2.0 (the +"License"); you may not use this file except in compliance +with the License. You may obtain a copy of the License at + +https://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, +software distributed under the License is distributed on an +"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +KIND, either express or implied. See the License for the +specific language governing permissions and limitations +under the License. +--> +<html> + <head> + <meta http-equiv="Content-Language" content="en-us"></meta> + <link rel="stylesheet" type="text/css" href="style.css"> + <title>S3 Comparator/Selector library</title> + </head> + + <body> + <h2>org.apache.ant.s3cs</h2> + + <h3>Description</h3> + + <p>Antlib defining a number of types which can act both as resource comparators and resource selectors.</p> + <p>TODO</p> + + </body> +</html> diff --git a/docs/s3delete.html b/docs/s3delete.html new file mode 100644 index 0000000..180ba88 --- /dev/null +++ b/docs/s3delete.html @@ -0,0 +1,82 @@ +<!-- +Licensed to the Apache Software Foundation (ASF) under one +or more contributor license agreements. See the NOTICE file +distributed with this work for additional information +regarding copyright ownership. The ASF licenses this file +to you under the Apache License, Version 2.0 (the +"License"); you may not use this file except in compliance +with the License. You may obtain a copy of the License at + +https://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, +software distributed under the License is distributed on an +"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +KIND, either express or implied. See the License for the +specific language governing permissions and limitations +under the License. +--> +<html> + <head> + <meta http-equiv="Content-Language" content="en-us"></meta> + <link rel="stylesheet" type="text/css" href="style.css"> + <title>S3 Delete Task</title> + </head> + + <body> + <h2><a name="s3delete">s3:delete</a></h2> + + <h3>Description</h3> + + <p>Delete the objects represented by a collection of + <a href="s3object.html">s3:object</a> resources.</p> + + <h3>Parameters</h3> + <table border="1" cellpadding="2" cellspacing="0"> + <tr> + <td valign="top"><b>Attribute</b></td> + <td valign="top"><b>Description</b></td> + <td align="center" valign="top"><b>Required</b></td> + </tr> + <tr> + <td valign="top">clientrefid</td> + <td valign="top">Ant reference ID to an <a href="s3client.html">s3:client</a> + defined elsewhere</td> + <td align="center">No, default <code>object</code></td> + </tr> + <tr> + <td valign="top">as</td> + <td valign="top">object precision: <code>object|version</code></td> + <td align="center">No, default <code>object</code></td> + </tr> + <tr> + <td valign="top">blocksize</td> + <td valign="top">Size of delete batches when operating in batch mode</td> + <td align="center">No, default 1000</td> + </tr> + </table> + + <h3>Parameters specified as nested elements</h3> + + <h4>s3:client</h4> + + <p><a href="s3client.html">s3:client</a> to use for deletion. If a client is + specified either in this manner or by use of <code>@clientrefid</code>, the + <code>delete</code> operation is put into batch mode. If the collection of + <code>s3:object</code> resources come from an + <a href="s3objects.html">s3:objects</a> collection, and therefore already + have a reference to the client that discovered them, this task does not need + a client reference and each object will be requested to delete itself. + </p> + + <h4>resource collection</h4> + + <p>Any number of nested resource collections may be specified; however + resources other than <a href="s3object.html">s3:object</a> are ignored. + Further, if <code>@as</code> is <code>object</code> an <code>s3:object</code> + that is a delete marker will also be ignored, as it indicates the object + has already been deleted, so far as it goes.</p> + + </body> +</html> + diff --git a/docs/s3object.html b/docs/s3object.html new file mode 100644 index 0000000..ee28c5c --- /dev/null +++ b/docs/s3object.html @@ -0,0 +1,80 @@ +<!-- +Licensed to the Apache Software Foundation (ASF) under one +or more contributor license agreements. See the NOTICE file +distributed with this work for additional information +regarding copyright ownership. The ASF licenses this file +to you under the Apache License, Version 2.0 (the +"License"); you may not use this file except in compliance +with the License. You may obtain a copy of the License at + +https://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, +software distributed under the License is distributed on an +"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +KIND, either express or implied. See the License for the +specific language governing permissions and limitations +under the License. +--> +<html> + <head> + <meta http-equiv="Content-Language" content="en-us"></meta> + <link rel="stylesheet" type="text/css" href="style.css"> + <title>S3 Object</title> + </head> + + <body> + <h2><a name="s3object">s3:object</a></h2> + + <h3>Description</h3> + + <p>Ant resource representing an S3 object or object version (an object + version will ordinarily come from <a href="s3objects.html">s3:objects</a>). + Supports a client although in normal usage this is unnecessary.</p> + + <h3>Parameters</h3> + <table border="1" cellpadding="2" cellspacing="0"> + <tr> + <td valign="top"><b>Attribute</b></td> + <td valign="top"><b>Description</b></td> + <td align="center" valign="top"><b>Required</b></td> + </tr> + <tr> + <td valign="top">bucket</td> + <td valign="top">S3 bucket</td> + <td align="center">Yes</td> + </tr> + <tr> + <td valign="top">key</td> + <td valign="top">S3 key</td> + <td align="center">Yes</td> + </tr> + <tr> + <td valign="top">clientrefid</td> + <td valign="top">Ant reference ID of an <a href="s3client.html">s3:client</a> + defined elsewhere</td> + <td align="center">No</td> + </tr> + <tr> + <td valign="top">contenttype</td> + <td valign="top">MIME type of this resource</td> + <td align="center">No</td> + </tr> + </table> + + <h3>Parameters specified as nested elements</h3> + + <h4>client</h4> + + <p><a href="s3client.html">s3:client</p> + + <h4>metadata</h4> + + <p><a href="inlineproperties.html">Inline properties specifying S3 object metadata</p> + + <h4>tagging</h4> + + <p><a href="inlineproperties.html">Inline properties specifying S3 object tagging</p> + + </body> +</html> diff --git a/docs/s3objects.html b/docs/s3objects.html new file mode 100644 index 0000000..76f74ed --- /dev/null +++ b/docs/s3objects.html @@ -0,0 +1,122 @@ +<!-- +Licensed to the Apache Software Foundation (ASF) under one +or more contributor license agreements. See the NOTICE file +distributed with this work for additional information +regarding copyright ownership. The ASF licenses this file +to you under the Apache License, Version 2.0 (the +"License"); you may not use this file except in compliance +with the License. You may obtain a copy of the License at + +https://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, +software distributed under the License is distributed on an +"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +KIND, either express or implied. See the License for the +specific language governing permissions and limitations +under the License. +--> +<html> + <head> + <meta http-equiv="Content-Language" content="en-us"></meta> + <link rel="stylesheet" type="text/css" href="style.css"> + <title>S3 Objects</title> + </head> + + <body> + <h2><a name="s3objects">s3:objects</a></h2> + + <h3>Description</h3> + + <p>Ant resource collection of <a href="s3object.html">s3:object</a> + resources.</p> + + <h3>Parameters</h3> + <table border="1" cellpadding="2" cellspacing="0"> + <tr> + <td valign="top"><b>Attribute</b></td> + <td valign="top"><b>Description</b></td> + <td align="center" valign="top"><b>Required</b></td> + </tr> + <tr> + <td valign="top">bucket</td> + <td valign="top">S3 bucket</td> + <td align="center">Yes</td> + </tr> + <tr> + <td valign="top">delimiter</td> + <td valign="top">S3 delimiter</td> + <td align="center">No, default <code>/</code></td> + </tr> + <tr> + <td valign="top">cache</td> + <td valign="top">Whether to cache discovered resources</td> + <td align="center">No, default <code>true</code></td> + </tr> + <tr> + <td valign="top">casesensitive</td> + <td valign="top">Whether the resource search is performed in a case-sensitive manner</td> + <td align="center">No, default <code>true</code></td> + </tr> + <tr> + <td valign="top">as</td> + <td valign="top">object precision: <code>object|version</code></td> + <td align="center">No, default <code>object</code></td> + </tr> + <tr> + <td valign="top">includeprefixes</td> + <td valign="top">Whether to include s3 prefix objects as directory resources</td> + <td align="center">No, default <code>false</code></td> + </tr> + <tr> + <td valign="top">clientrefid</td> + <td valign="top">Ant reference ID of an <a href="s3client.html">s3:client</a> + defined elsewhere</td> + <td align="center">Yes, unless a nested <code>s3:client</code> is specified</td> + </tr> + <tr> + <td valign="top">includes</td> + <td valign="top">comma-delimited include patterns</td> + <td align="center">No</td> + </tr> + <tr> + <td valign="top">includesfile</td> + <td valign="top">file containing line-delimited include patterns</td> + <td align="center">No</td> + </tr> + <tr> + <td valign="top">excludes</td> + <td valign="top">comma-delimited exclude patterns</td> + <td align="center">No</td> + </tr> + <tr> + <td valign="top">excludesfile</td> + <td valign="top">file containing line-delimited exclude patterns</td> + <td align="center">No</td> + </tr> + </table> + + <h3>Parameters specified as nested elements</h3> + + <h4>client</h4> + + <p><a href="s3client.html">s3:client</p> + + <h4>patternset</h4> + + <p>Any number of nested <code>patternset</code>s are permitted.</p> + + <h4>include</h4> + + <p>Any number of nested <code>include</code> elements are permitted.</p> + + <h4>exclude</h4> + + <p>Any number of nested <code>exclude</code> elements are permitted.</p> + + <h4>selector</h4> + + <p>Any number of nested resource selectors are permitted and applied in <code>OR</code> fashion.</p> + + </body> +</html> diff --git a/docs/s3put.html b/docs/s3put.html new file mode 100644 index 0000000..a8f10aa --- /dev/null +++ b/docs/s3put.html @@ -0,0 +1,96 @@ +<!-- +Licensed to the Apache Software Foundation (ASF) under one +or more contributor license agreements. See the NOTICE file +distributed with this work for additional information +regarding copyright ownership. The ASF licenses this file +to you under the Apache License, Version 2.0 (the +"License"); you may not use this file except in compliance +with the License. You may obtain a copy of the License at + +https://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, +software distributed under the License is distributed on an +"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +KIND, either express or implied. See the License for the +specific language governing permissions and limitations +under the License. +--> +<html> + <head> + <meta http-equiv="Content-Language" content="en-us"></meta> + <link rel="stylesheet" type="text/css" href="style.css"> + <title>S3 Put Task</title> + </head> + + <body> + <h2><a name="s3put">s3:put</a></h2> + + <h3>Description</h3> + + <p>Puts nested resources into an S3 bucket.</p> + + <h3>Parameters</h3> + <table border="1" cellpadding="2" cellspacing="0"> + <tr> + <td valign="top"><b>Attribute</b></td> + <td valign="top"><b>Description</b></td> + <td align="center" valign="top"><b>Required</b></td> + </tr> + <tr> + <td valign="top">bucket</td> + <td valign="top">destination bucket</td> + <td align="center">Yes</td> + </tr> + <tr> + <td valign="top">clientrefid</td> + <td valign="top">Ant reference ID of an <a href="s3client.html">s3:client</a> + defined elsewhere</td> + <td align="center">Yes, unless a nested <code>s3:client</code> is specified</td> + </tr> + <tr> + <td valign="top">enablemultiplemappings</td> + <td valign="top">Enable multiple destinations generated from nested mapper elements</td> + <td align="center">No, default <code>false</code></td> + </tr> + <tr> + <td valign="top">filtering</td> + <td valign="top">Whether to apply global Ant filters</td> + <td align="center">No, default <code>false</code></td> + </tr> + <tr> + <td valign="top">inputencoding</td> + <td valign="top">Input encoding</td> + <td align="center">No</td> + </tr> + <tr> + <td valign="top">outputencoding</td> + <td valign="top">Output encoding</td> + <td align="center">No</td> + </tr> + </table> + + <h3>Parameters specified as nested elements</h3> + + <h4>resource collection</h4> + + <p>Any number of nested resource collections are accepted.</p> + + <h4>FilterSet</h4> + + <p>Any number of nested filtersets are accepted.</p> + + <h4>FilterChain</h4> + + <p>Any number of nested filterchains are accepted.</p> + + <h4>Mapper</h4> + + <p>Any number of nested mapper elements are accepted.</p> + + <h4>FileNameMapper</h4> + + <p>Any number of type defined mappers are accepted.</p> + + </body> +</html> diff --git a/docs/style.css b/docs/style.css new file mode 100644 index 0000000..a09991e --- /dev/null +++ b/docs/style.css @@ -0,0 +1,63 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * https://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +h2 { + font-size: 200%; + background-color: ffffff; +} + +h3 { + font-size: 130%; + color: #ffffff; + background-color: #525D76; +} + +h4 { + color: #ffffff; + background-color: #828DA6; +} + +td { + background-color: eeeeee; + color: 000000; +} + + /* first row */ +table tr:first-child td { + background-color: cccccc; + color: 000000; +} + + /* or th as first row */ +table th { + background-color: cccccc; + color: 000000; +} + +pre { + background-color: efefef; +} + +.copyright { + font-family: arial,helvetica,sanserif; + font-size: 90%; + clear: both; + text-align: center; + margin: 0px; + border-top: thin solid #4C6C8F; +}