Apache CycloneDX Ant Library - component

## component

Components are central to CycloneDX SBOMs. There is the component the whole SBOM is about - and there are more components specified inside the SBOM as (transitive) dependencies or parts of the other components.

The component elements can be used as top-level elements and be given an id so they can be later referred to via the `refid` attribute - see the Ant manual. The can also be referred to by a dependency of another component via `componentRef`.

### Attributes

Attribute | Description | Required
--- | --- | ---
name | The name of the component. | Yes
type | The type of the component. Valid types are defined by the CycloneDX specification. | No, the default is "library"
group | The group of the component. | No
version | The version of the component. | No
purl | The Package-URL (purl) of the component. | No - if not set but `name`, `group` and `version` are present an implicit purl is calculated as `pkg:maven` jar purl from these values.
bomRef | The bom-ref of the component. | No - if not set, the component's - potentially calculated - purl will be used.
scope | The scope of the component. Valid scopes are defined by the CycloneDX specification. | No, `scope` is prohibited for the main component of the SBOM.
isExternal | Whether the component is external. The CycloneDX Specification says: An external component is one that is not part of an assembly, but is expected to be provided by the environment, regardless of the component's scope. This attribute doesn't have any effect as long as CycloneDX Core doesn't support version 1.7 of the specification. | No, `isExternal` must not be `true` for the main component of the SBOM.
description | The description of the component. | No
publisher | The publisher of the component. | No
copyright | The copyright of the component. | No
mimetype | The MIME-type of the component. | No
supplierIsManufacturer | Whether the nested supplier shall be used as manufacturer as well. | No - defaults to `false`. Must not be `true` if a nested manufacturer exists.
unknownDependencies | Whether the dependencies of this component are unknown. If set to `false` then a component without any nested dependency elements is treated as having no dependencies at all. | No - defaults to `false`.

### Nested elements

#### any file-system resource

At most one nested resource specifies the file the component describes. This is required if you want to include hashes for the component in your SBOM.

#### sbomLink

At most one resource can be specified as `sbomLink`. When present the referenced resource is read as CycloneDX SBOM and:

- `type`, `name`, `group`, `version`, `purl`, `bomRef`, `scope`, `decription`, `publisher`, `copright`, `mimeType` and `supplier` are taken from the SBOM's metadata component unless they are explicitly specified on the component element itself.
- `manufacturer` is taken from the SBOM's metadata component unless it is explicitly specified on the component element itself or `supplierismanufacturer` is `true`.
- Tags are merged wiht those of the SBOM's metadata component.
- `author`s, `license`s, `exteranlReference`s, `dependency`s and nested `components` are taken from the SBOM's metadata component if and only if there is no corresponding element in this component element.
- Hashes of the linked SBOM are ignored completely.
- Other components specified in the linked SBOM are also added to the SBOM created by the compomentbom task if they are direct dependencies of the current component element. And their dependencies are set to "unknown" as handling of transitive dependencies is beyond the scope of this library.
  Components specified explicitly in the SBOM take precedence over those found by parsing an SBOM link. If there already exists a component as part of the SBOM with the same name and group as one read from the linked SBOM, the linked component will be ignored. Here the version is ignored, it is assumed the component explicitly specified is the result of a process that resolved conflicts in dependency versions. Currently this only applies to Components with `pkg:maven/` Package-URLs as bom-ref.

The CycloneDX Core (Java) library is used to read the linked SBOM.

#### manufacturer

At most one nested organization specifies the manufacturer of the component.

#### supplier

At most one nested organization specifies the supplier of the component.

#### author

Adds an author to the component.

##### Attributes

Attribute | Description | Required
--- | --- | ---
bomRef | The bom-ref of the author. | No
name | The name of the author. | No
email | The email of the author. | No
phone | The phone of the author. | No

#### tag

Adds a tag to the component. Tags haven't got any attributes or nested elements, the nested text is used as tag.

#### property

Adds a property to the component.

##### Attributes

Attribute | Description | Required
--- | --- | ---
name | The name of the property. | No
value | The value of the property. | No

#### license

A nested license specifies the license information of the component.

#### externalReference

A nested externalReference specifies an external reference for the component.

#### externalReferenceSet

A nested externalreferenceset specifies external references for the component.

#### dependency

Adds a dependency to the component.

Inside the SBOM both the dependee and the dependency side are identified by their bom-ref. Therefore nested dependency children are only allowed in components that provide a bom-ref - either via an explicit `bomRef` attribute or an explicit or calculated `purl`.

##### Attributes

Attribute | Description | Required
--- | --- | ---
bomRef | References the dependency by its `bom-ref`. | Exactly one of the two.
componentRef | References the dependency by its Ant `id` attribute. The referenced component must have a `bom-ref`.

#### component

Adds a nested component to the component.

Nested components can be used to represent a hierarchy of components into sub-components and so on.

Components can be added as full elements or via the `refid` attribute as references to components defined elsewhere in the build file. Ant verifies this doesn't cause a circular dependency between a component and one higher up in the hierarchy.

### Examples

Below is a component that could describe this Antlib.

          <cdx:component
              name="ant"
              group="org.apache.ant"
              version="1.10.17"
              isExternal="true"
              unknownDependencies="true"
              id="ant"
              xmlns:cdx="antlib:org.apache.ant.cyclonedx">
            <supplier refid="ant-team"/>
            <license refid="apache-2"/>
            <externalReference
                type="VCS"
                url="https://github.com/apache/ant"/>
            <externalReference
                type="WEBSITE"
                url="https://ant.apache.org/"/>
          </cdx:component>
          <cdx:component
              name="ant-cyclonedx"
              group="org.apache.ant"
              version="0.1"
              description="Apache CycloneDX Antlib"
              publisher="The Apache Software Foundation"
              supplierIsManufacturer="true"
              xmlns:cdx="antlib:org.apache.ant.cyclonedx">
            <file file="ant-antlibs-cyclonedx-0.1.jar"/>
            <supplier refid="ant-team"/>
            <license refid="apache-2"/>
            <externalReferenceSet refid="antlib-ext-refs"/>
            <dependency componentRef="ant"/>
            <dependency bomRef="pkg:maven/org.cyclonedx/cyclonedx-core-java@12.2.0?type=jar"/>
          </cdx:component>