Add usage notice in readme file

README.adoc

@@ -1,18 +1,242 @@
 = docker-artifact-resolution
 
-=== License
+This project allows to perform downloads for different types of artifacts.
+The main use case for this tool is downloading plugins, themes and other files inside a Kubernetes init-container to customize applications.
+
+.Supported artifact types
+* A file via regular web call
+* One or more files from a Git repository in a specific directory
+* An Artifact from a Maven2 repository
+
+Other artifact types are planned.
+
+== Usage
+
+The tool expects a task name as the fist argument to perform downloads with a specific strategy.
+
+[cols="7,7,15,1",options="header"]
+|===
+
+|command line parameter
+|environment variable
+|description
+|required
+
+4+|Task: `resolve-web` *grab files via regular web call*
+
+|`‑r` +
+`‑‑url`
+|`URL`
+|The file to be downloaded.
+|yes
+
+|`‑x` +
+`‑‑headers`
+|`HEADERS`
+|A newline-separated list of headers used for the web call.
+|no
+
+4+|Task: `resolve-git` *grab files via Git-clone action*
+
+|`‑r` +
+`‑‑url`
+|`URL`
+|The URL or path to a Git repository.
+|yes
+
+|`‑b` +
+`‑‑branch`
+|`BRANCH`
+|A specific branch used for the clone action. If unspecified the default branch is used.
+|no
+
+|`‑s` +
+`‑‑source‑path`
+|`SOURCE_PATH`
+|A path to a specific subdirectory or file which will be cloned. If unspecified the whole repository will be cloned.
+|no
+
+|
+|`GIT_USERNAME`
+|The Git username as part of the credentials.
+|no
+
+|
+|`GIT_PASSWORD`
+|The user password as part of the credentials.
+|no
+
+4+|Task: `resolve-maven` *grab files using Maven*
+
+|`‑r` +
+`‑‑remote‑repo‑urls`
+|`REMOTE_REPO_URLS`
+|A newline-separated list of Maven2 remote repositories.
+|no
+
+|`‑l` +
+`‑‑local‑repo‑dir`
+|`LOCAL_REPO_DIR`
+|The path to the local Maven2 repository.
+|no
+
+|`‑s` +
+`‑‑mirror‑url`
+|`MIRROR_URL`
+|The URL to a Maven2 mirror.
+|no
+
+|`‑a` +
+`‑‑artifact`
+|`ARTIFACT`
+|The Maven2 artifact name. `groupId:artifactId:version`
+|yes
+
+|
+|`MAVEN_MIRROR_USERNAME`
+|The username used for the Maven mirror as part of the credentials.
+|no
+
+|
+|`MAVEN_MIRROR_PASSWORD`
+|The user password used for the Maven mirror as part of the credentials.
+|no
+
+4+|*Parameters used for all artifact types* +
+The parameters below can be used for all tasks except `resolve-using-config`.
+
+|`‑d` +
+`‑‑target‑dir`
+|`TARGET_DIR`
+|The target directory where the artifacts will be deployed.
+|yes
+
+|`‑u` +
+`‑‑target‑user`
+|`TARGET_USER`
+|Specifies the user for deployed files.
+|no
+
+|`‑g` +
+`‑‑target‑group`
+|`TARGET_GROUP`
+|Specifies the group for deployed files.
+|no
+
+|`‑m` +
+`‑‑target‑mode`
+|`TARGET_MODE`
+|Specifies the mode for deployed files.
+|no
+
+|`‑c` +
+`‑‑cache‑dir`
+|`CACHE_DIR`
+|Caching artifacts is enabled if a path to the cache directory is defined. See feature description below.
+|no
+
+4+|Task: `resolve-using-config` *grab files of any kind by using a JSON file* +
+This task only uses the following parameters. All other values must be set via the configuration file.
+
+|`‑j` +
+`‑‑json‑config‑file`
+|`JSON_CONFIG_FILE`
+|The path to a JSON file which contains a list of artifacts. See example below.
+|yes
+
+|`‑c` +
+`‑‑cache‑dir`
+|`CACHE_DIR`
+|Caching artifacts is enabled if a path is defined. This setting is used for all downloads described in the JSON file. See feature description below.
+|no
+
+4+|*Other parameters*
+
+|`‑h` +
+`‑‑help`
+|
+|Shows the help text and ignores other arguments.
+|
+
+|`‑v` +
+`‑‑version`
+|
+|Shows the tool version and ignores other arguments.
+|
+
+|===
+
+=== Examples
+
+.Example of a regular web call using the `resolve-web` task
+[source,bash]
+----
+./src/main.sh resolve-web --url "https://repo1.maven.org/maven2/org/slf4j/slf4j-api/2.0.3/slf4j-api-2.0.3.jar"
+----
+
+.Example how to grab files from a Git repository using the `resolve-git` task
+[source,bash]
+----
+./src/main.sh resolve-git --url "https://github.com/qos-ch/slf4j.git" --branch "v_2.0.3"
+----
+
+.Example how to grab Maven artifacts using the `resolve-maven` task
+[source,bash]
+----
+## optional: resolve Maven artifacts behind a proxy
+# export MAVEN_OPTS="-Dhttp.proxyHost=... -Dhttp.proxyHost=... -Dhttp.nonLocalHosts=..."
+
+./src/main.sh resolve-maven --artifact "org.slf4j:slf4j-api:2.0.3"
+----
+
+.Example how to grab files using a list of artifacts with the `resolve-using-config` task
+[source,bash]
+----
+./src/main.sh resolve-using-config --json-config-file "my-file.json"
+----
+
+.Example artifact list
+[source,json]
+----
+[
+  {
+    "task": "resolve-web",
+    "arguments": {
+      "url": "https://repo1.maven.org/maven2/org/slf4j/slf4j-api/2.0.3/slf4j-api-2.0.3.jar",
+      "headers": [],
+      "target-dir": "./my-output-dir"
+    }
+  },
+  {
+    "task": "resolve-git",
+    "arguments": {
+      "url": "https://github.com/qos-ch/slf4j.git",
+      "branch": "v_2.0.3",
+      "source-path": "slf4j-api",
+      "target-dir": "./my-output-dir"
+    }
+  },
+  {
+    "task": "resolve-maven",
+    "arguments": {
+      "artifact": "org.slf4j:slf4j-api:2.0.3",
+      "target-dir": "./my-output-dir"
+    }
+  }
+]
+----
+
+== About artifact caching
+Sometimes there is the requirement to mirror artifacts to guarantee their permanent availability. Read link:caching.adoc[here] to learn more about the caching feature.
+
+== License
 
 Copyright (c) 2022 ASERVO Software GmbH
 
-Licensed under the Apache License, Version 2.0 (the "License");
-you may not use this file except in compliance with the License.
+Licensed 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
 
 _http://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.
-
+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.

caching.adoc

@@ -0,0 +1,18 @@
+== About artifact caching
+Sometimes there is the requirement to mirror artifacts to guarantee their availability. The caching feature is disabled by default. To enable it, a cache directory must be specified. If there is a cache miss the artifacts will be saved and if there is a cache hit an unnecessary download action is skipped.
+
+NOTE: There is currently no mechanism for deleting obsolete cache entries. However, the metadata of the cache can be used to implement one or more cleanup strategies.
+
+Each cache entry gets its own subdirectory under the specified cache directory. The name of such a subdirectory is a hash, calculated from attributes that make the artifacts unique. The hash calculation is documented in the file _src/utils.sh_ at function _make_hash_. Every cache entry includes a file _cache-entry.txt_ with some metadata.
+
+.File structure of a cache entry
+* /<entry-hash>/cache-entry.txt
+* /<entry-hash>/files/<my-artifact>
+
+.Example metadata
+[source]
+----
+ENTRY_ID=1d38d6b91bb668badebb6a72b1c17560b6fdf5d5e33298a3eea2928d64de03db
+ENTRY_NAME=org.slf4j:slf4j-api:2.0.3
+DATE_TIME=2023-01-01T10:00:00+01:00
+----

src/utils.sh

@@ -42,6 +42,10 @@ function checksum {
   echo -n "$1" | sha256sum | cut -f 1 -d ' '
 }
 
+# The hash calculation
+# This function takes zero, one or more arguments, to create a SHA-256 checksum for each argument. If there are
+# multiple arguments, the checksums are concatenated by a single space delimiter. This string is used to create a final
+# hash string.
 function make_hash {
 
   local VALUE