This is an automated email from the ASF dual-hosted git repository.
asf-gitbox-commits pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/ant-antlibs-cyclonedx.git
The following commit(s) were added to refs/heads/main by this push:
new 90ce8d9 document externalreferenceset
90ce8d9 is described below
commit 90ce8d9665716cfaf588ba2aa4efa3e65ec88fc5
Author: Stefan Bodewig <[email protected]>
AuthorDate: Wed May 13 06:11:02 2026 +0200
document externalreferenceset
---
docs/externalreferenceset.html | 103 +++++++++++++++++++++
docs/index.html | 4 +
.../apache/ant/cyclonedx/ExternalReferenceSet.java | 17 +++-
src/tests/antunit/externalreferences-test.xml | 20 +++-
4 files changed, 140 insertions(+), 4 deletions(-)
diff --git a/docs/externalreferenceset.html b/docs/externalreferenceset.html
new file mode 100644
index 0000000..0f416b7
--- /dev/null
+++ b/docs/externalreferenceset.html
@@ -0,0 +1,103 @@
+<!--
+ 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>Apache CycloneDX Ant Library - externalreferenceset</title>
+ </head>
+
+ <body>
+ <h2 id="externalreferenceset">externalreferenceset</h2>
+
+ <p>externalreferencesets are collections of external references
+ (typed links) that can be associated to a component or an
+ SBOM. They can be used as top-level elements and be given an id
+ so they can be later referred to via the <code>refid</code>
+ attribute -
+ see <a href="https://ant.apache.org/manual/using.html#references";>the
+ Ant manual</a>.</p>
+
+ <p>Apart from Ant's <code>id/refid</code> this element doesn't
+ support any attributes.</p>
+
+ <h3>Nested elements</h3>
+
+ <h4>externalReference</h4>
+
+ <p>Represents a single external reference to be added to the
+ BOM.</p>
+
+ <table class="attr">
+ <tr>
+ <th scope="col">Attribute</th>
+ <th scope="col">Description</th>
+ <th scope="col">Required</th>
+ </tr>
+ <tr>
+ <td>type</td>
+ <td>The type of external references. The valid values are
+ defined by the CycloneDX specification.</td>
+ <td>Yes</td>
+ </tr>
+ <tr>
+ <td>url</td>
+ <td>The url of the external reference.</td>
+ <td>Yes</td>
+ </tr>
+ </table>
+
+ <h2>Examples</h2>
+
+ <p>Below is a set of external references this Ant Library could
+ use for itself.</p>
+
+ <pre>
+ <cdx:externalreferenceset
+ id="antlib-ext-refs"
+ xmlns:cdx="antlib:org.apache.ant.cyclonedx">
+ <externalReference
+ type="vcs"
+ url="https://github.com/apache/ant-antlibs-cyclonedx"/>
+ <externalReference
+ type="license"
+ url="https://www.apache.org/licenses/LICENSE-2.0.txt"/>
+ <externalReference
+ type="build-system"
+
url="https://ci-builds.apache.org/job/Ant/job/CycloneDX%20Antlib/"/>
+ <externalReference
+ type="mailing-list"
+ url="https://ant.apache.org/mail.html"/>
+ <externalReference
+ type="issue-tracker"
+
url="https://bz.apache.org/bugzilla/buglist.cgi?component=CycloneDX%20Antlib&product=Ant"/>
+ <externalReference
+ type="website"
+ url="https://ant.apache.org/antlibs/cyclonedx/"/>
+ <externalReference
+ type="distribution"
+ url="https://ant.apache.org/antlibs/bindownload.cgi"/>
+ <externalReference
+ type="source-distribution"
+ url="https://ant.apache.org/antlibs/srcdownload.cgi"/>
+ <externalReference
+ type="security-contact"
+ url="https://www.apache.org/security/"/>
+ </cdx:externalreferenceset>
+ </pre>
+
+ </body>
diff --git a/docs/index.html b/docs/index.html
index 6523c7f..bbe6200 100644
--- a/docs/index.html
+++ b/docs/index.html
@@ -58,6 +58,10 @@ <h2>Introduction</h2>
<h2>Tasks and Types provided by this Ant Library</h2>
+ <ul>
+ <li><a href="externalreferenceset.html">externalreferenceset</a></li>
+ </ul>
+
<h2>Requirements and Dependencies of this Ant Library</h2>
<p>This Ant Library requires Java 8 at a minimum to build and at
diff --git a/src/main/org/apache/ant/cyclonedx/ExternalReferenceSet.java
b/src/main/org/apache/ant/cyclonedx/ExternalReferenceSet.java
index 50e83ff..0e264cc 100644
--- a/src/main/org/apache/ant/cyclonedx/ExternalReferenceSet.java
+++ b/src/main/org/apache/ant/cyclonedx/ExternalReferenceSet.java
@@ -6,15 +6,26 @@ import java.util.List;
import org.apache.tools.ant.types.DataType;
+/**
+ * A container for a collection of {@link ExternalReference}s.
+ *
+ * <p>This class is a type exposed by this Ant Library. When using the
+ * inherited {@code refid} attribute it can reference an instance
+ * defined previously - in which case no child elements are
+ * allowed.</p>
+ */
public class ExternalReferenceSet extends DataType {
private List<org.cyclonedx.model.ExternalReference> externalReferences =
new ArrayList<>();
+ /**
+ * Adds an external reference to this set.
+ */
public void addConfiguredExternalReference(ExternalReference ref) {
checkChildrenAllowed();
externalReferences.add(ref.toCycloneDxExternalReference());
}
- public Collection<org.cyclonedx.model.ExternalReference>
getExternalReferences() {
+ Collection<org.cyclonedx.model.ExternalReference> getExternalReferences() {
if (isReference()) {
return getRef().getExternalReferences();
}
@@ -24,8 +35,8 @@ public class ExternalReferenceSet extends DataType {
/**
* Perform the check for circular references and return the
- * referenced Organization.
- * @return <code>Organization</code>.
+ * referenced ExternalReferenceSet.
+ * @return <code>ExternalReferenceSet</code>.
*/
protected ExternalReferenceSet getRef() {
return getCheckedRef(ExternalReferenceSet.class);
diff --git a/src/tests/antunit/externalreferences-test.xml
b/src/tests/antunit/externalreferences-test.xml
index 6bf4790..6357078 100644
--- a/src/tests/antunit/externalreferences-test.xml
+++ b/src/tests/antunit/externalreferences-test.xml
@@ -15,7 +15,7 @@
See the License for the specific language governing permissions and
limitations under the License.
-->
-<project name="componentbom-test" default="antunit">
+<project name="externalreferences-test" default="antunit">
<import file="shared.xml" />
@@ -145,4 +145,22 @@
value="https://ant.apache.org/"/>
</target>
+ <target
+ name="testExternalReferenceWithRefIdDoesntAllowNestedChildren">
+ <cdx:externalreferenceset id="test-set"
+ xmlns:cdx="antlib:org.apache.ant.cyclonedx">
+ <externalReference
+ type="website" url="https://ant.apache.org/"/>
+ </cdx:externalreferenceset>
+ <au:expectfailure
+ expectedMessage='You must not specify nested elements when using refid'
+ xmlns:au="antlib:org.apache.ant.antunit">
+ <cdx:externalreferenceset
+ refid="test-set"
+ xmlns:cdx="antlib:org.apache.ant.cyclonedx">
+ <externalReference
+ type="license"
url="https://www.apache.org/licenses/LICENSE-2.0.txt"/>
+ </cdx:externalreferenceset>
+ </au:expectfailure>
+ </target>
</project>
