Skip to content
Permalink
Browse files
first cut of documentation
  • Loading branch information
@mbenson
mbenson committed Mar 10, 2022
1 parent b81ff5a commit 6b2f913ad126cb2443864829a7802d99b7188dd5
Showing 9 changed files with 690 additions and 0 deletions.
96 docs/index.html
View file
@@ -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>
&lt;project xmlns:s3="antlib:org.apache.ant.s3"&gt;
</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>
36 docs/inlineproperties.html
View file
@@ -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>

80 docs/s3client.html
View file
@@ -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>

35 docs/s3compareselect.html
View file
@@ -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>
82 docs/s3delete.html
View file
@@ -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>

0 comments on commit 6b2f913

Please sign in to comment.