Package org.apache.ant.cyclonedx

Class Component

  • All Implemented Interfaces:
    java.lang.Cloneable
    public class Component
extends org.apache.tools.ant.types.DataType
    The central concept of an SBOM which describes components and their dependencies.

    The CycloneDX specification supports more information for a component than this type currently exposes.

    This class is a type exposed by this Ant Library. When using the inherited refid attribute it can reference an instance defined previously - in which case no child elements or other attributes are allowed.

    • Nested Class Summary

      Nested Classes 
      Modifier and Type Class Description
      static class  Component.Dependency
      Represents a dependency of a component.
      static class  Component.Tag
      Represents a tag.

    • Field Summary

      Fields 
      Modifier and Type Field Description
      static java.util.Comparator<Component> ComponentComparator
      Comparator for components.
      static java.util.Comparator<org.cyclonedx.model.Component> CycloneDxComponentComparator
      Comparator for CycloneDX components.

      • Fields inherited from class org.apache.tools.ant.types.DataType

        checked, ref

      • Fields inherited from class org.apache.tools.ant.ProjectComponent

        location, project

    • Constructor Summary

      Constructors 
      Modifier Constructor Description
        Component()
      Default constructor.
      protected Component​(Component other)
      Copy constructor creating a shallow copy.

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      void add​(ComponentResolver resolver)
      Resolver that uses external data to enrich this component.
      void add​(org.apache.tools.ant.types.Resource resource)
      Sets the resource the component is about.
      void addAuthor​(org.cyclonedx.model.OrganizationalContact author)
      Adds an author to the component.
      void addComponent​(Component c)
      Adds a nested component.
      void addConfiguredExternalReference​(ExternalReference ref)
      Adds an external reference to the component.
      void addConfiguredExternalReferenceSet​(ExternalReferenceSet set)
      Adds a set of external references to the component.
      void addConfiguredLicense​(License l)
      Adds a license to this component.
      void addConfiguredProperty​(org.cyclonedx.model.Property property)
      Adds a property to the component.
      void addConfiguredPropertySet​(PropertySet set)
      Adds a set of properties to the component.
      void addConfiguredTag​(Component.Tag tag)
      Adds a tag to the component.
      void addDependency​(Component.Dependency d)
      Adds a dependency to this component.
      protected void addHashes​(org.cyclonedx.model.Component component, org.cyclonedx.Version bomVersion)
      If this component has a nested resource child, all hashes supported by the CycloneDX Core library for the spec version are created and added to the given component.
      void addManufacturer​(Organization manufacturer)
      Sets the manufacturer of the component.
      void addSupplier​(Organization supplier)
      Sets the supplier of the component.
      boolean areDependenciesUnknown()
      Whether dependencies are unknoown.
      static Component createFileComponent​(org.apache.tools.ant.Project project, org.apache.tools.ant.types.Resource r)
      Creates a new "file" type component for a resource.
      protected void dieOnCircularReference​(java.util.Stack<java.lang.Object> stk, org.apache.tools.ant.Project p)  
      protected void fillFrom​(org.cyclonedx.model.Component real, java.util.List<org.cyclonedx.model.Dependency> allDependencies)
      Enriches this instance with data read from a CycloneDX component and its dependencies.
      protected static Component from​(org.cyclonedx.model.Component real, java.util.List<org.cyclonedx.model.Dependency> dependencies)
      Maps from a CycloneDX Component to an incstance of this type.
      java.util.Collection<org.cyclonedx.model.OrganizationalContact> getAuthors()
      Gets the authors of the component.
      java.lang.String getBomRef()
      Gets the bom-ref of the component.
      org.apache.tools.ant.types.Resource getComponentFile()
      Gets the resource the component is about.
      CompositionAggregate getCompositionAggregate()
      Gets the composition aggregate of the component.
      java.lang.String getCopyright()
      Gets the copyright of the component.
      java.util.Collection<Component.Dependency> getDependencies()
      Gets the dependencies of the component.
      java.lang.String getDescription()
      Gets the decription of the component.
      java.util.Collection<org.cyclonedx.model.ExternalReference> getExternalReferences()
      Gets the merged external references added via {@see #addConfiguredExternalReference} or {@see #addConfiguredExternalReferenceSet} to the component.
      java.lang.String getGroup()
      Gets the group of the component.
      boolean getIsExternal()
      Gets whether the isExternal flag is true.
      java.util.Collection<License> getLicenses()
      Gets licenses added to this component.
      Organization getManufacturer()
      Gets the manufacturer of the component.
      java.lang.String getMimeType()
      Gets the mime-type of the component.
      java.lang.String getName()
      Gets the name of the component.
      java.util.List<Component> getNestedComponents()
      Recursively returns the nested components of this component.
      java.util.Collection<org.cyclonedx.model.Property> getProperties()
      Gets merged properties added via addConfiguredProperty(org.cyclonedx.model.Property) or addConfiguredPropertySet(org.apache.ant.cyclonedx.PropertySet) to the component.
      java.lang.String getPublisher()
      Gets the publisher of the component.
      java.lang.String getPurl()
      Gets the Package-URL (purl) of the component.
      protected Component getRef()
      Perform the check for circular references and return the referenced Component.
      ComponentScope getScope()
      Gets the scope of this component.
      Organization getSupplier()
      Gets the supplier of the component.
      boolean getSupplierIsManufacturer()
      Gets whether the supplier shall also be used to provide the manufacturer information.
      java.util.Collection<Component.Tag> getTags()
      Gets the tags of the component.
      ComponentType getType()
      Gets the component type.
      java.lang.String getVersion()
      Gets the version of the component.
      java.util.Collection<Component> resolve()
      Read the linked SBOM (if any) and merge its content with the one already defined for this component.
      void setBomRef​(java.lang.String bomRef)
      Sets the bom-ref of the component.
      void setCompositionAggregate​(CompositionAggregate compositionAggregate)
      Sets the composition aggregate of this component.
      void setCopyright​(java.lang.String copyright)
      Sets the copyright of the component.
      void setDescription​(java.lang.String description)
      Sets the decription of the component.
      void setGroup​(java.lang.String group)
      Sets the group of the component.
      void setIsExternal​(boolean isExternal)
      Sets whether the component is external.
      void setMimeType​(java.lang.String mimeType)
      Sets the mime-type of the component.
      void setName​(java.lang.String name)
      Sets the name of the component.
      void setPublisher​(java.lang.String publisher)
      Sets the publisher of the component.
      void setPurl​(java.lang.String purl)
      Sets the Package-URL (purl) of the component.
      void setScope​(ComponentScope scope)
      Sets the scope of this component.
      void setSupplierIsManufacturer​(boolean supplierIsManufacturer)
      If set to true the supplier will also be used to provide the manufacturer information.
      void setType​(ComponentType type)
      Sets the type of the component.
      void setUnknownDependencies​(boolean unknownDependencies)
      Sets whether the dependencies of this component are unknown.
      void setVersion​(java.lang.String version)
      Sets the version of the component.
      org.cyclonedx.model.Component toAdditionalCycloneDxComponent​(org.cyclonedx.Version bomVersion)
      Translates this component to a CycloneDX component suitable for the components.component.
      protected org.cyclonedx.model.Component toCycloneDxComponent​(org.cyclonedx.Version bomVersion)
      Maps all common data except for scope and isExternal.
      org.cyclonedx.model.Component toMainCycloneDxComponent​(org.cyclonedx.Version bomVersion)
      Translates this component to a CycloneDX component suitable for the metadata.component.

      • Methods inherited from class org.apache.tools.ant.types.DataType

        checkAttributesAllowed, checkChildrenAllowed, circularReference, clone, dieOnCircularReference, dieOnCircularReference, getCheckedRef, getCheckedRef, getCheckedRef, getCheckedRef, getCheckedRef, getDataTypeName, getRefid, invokeCircularReferenceCheck, isChecked, isReference, noChildrenAllowed, pushAndInvokeCircularReferenceCheck, setChecked, setRefid, tooManyAttributes, toString

      • Methods inherited from class org.apache.tools.ant.ProjectComponent

        getLocation, getProject, log, log, setLocation, setProject

      • Methods inherited from class java.lang.Object

        equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

    • Field Detail

      • ComponentComparator

        public static final java.util.Comparator<Component> ComponentComparator
        Comparator for components.

        Sorts by bom-ref (if present) and falls back to sorting by name, then by group (if present) and version (if present).

        Since:
        CycloneDX Antlib 0.2

      • CycloneDxComponentComparator

        public static final java.util.Comparator<org.cyclonedx.model.Component> CycloneDxComponentComparator
        Comparator for CycloneDX components.

        Sorts by bom-ref (if present) and falls back to sorting by name, then by group (if present) and version (if present).

        Since:
        CycloneDX Antlib 0.2

    • Constructor Detail

      • Component

        public Component()
        Default constructor.

      • Component

        protected Component​(Component other)
        Copy constructor creating a shallow copy.
        Parameters:
        other - component to copy data from
        Since:
        CycloneDX Antlib 0.2

    • Method Detail

      • add

        public void add​(org.apache.tools.ant.types.Resource resource)
        Sets the resource the component is about.

        At most one resource can be set. Without a nested resource the component will not have any "hashes" when written to the SBOM.

        Parameters:
        resource - the resource holding the component's content

      • setType

        public void setType​(ComponentType type)
        Sets the type of the component.

        Defaults to "library".

        Parameters:
        type - component type

      • setName

        public void setName​(java.lang.String name)
        Sets the name of the component.
        Parameters:
        name - component name

      • setGroup

        public void setGroup​(java.lang.String group)
        Sets the group of the component.
        Parameters:
        group - component group

      • setVersion

        public void setVersion​(java.lang.String version)
        Sets the version of the component.
        Parameters:
        version - component version

      • setPurl

        public void setPurl​(java.lang.String purl)
        Sets the Package-URL (purl) of the component.
        Parameters:
        purl - component Package URL

      • setBomRef

        public void setBomRef​(java.lang.String bomRef)
        Sets the bom-ref of the component.
        Parameters:
        bomRef - component bom-ref

      • setDescription

        public void setDescription​(java.lang.String description)
        Sets the decription of the component.
        Overrides:
        setDescription in class org.apache.tools.ant.ProjectComponent
        Parameters:
        description - component description

      • setPublisher

        public void setPublisher​(java.lang.String publisher)
        Sets the publisher of the component.
        Parameters:
        publisher - component publisher

      • setCopyright

        public void setCopyright​(java.lang.String copyright)
        Sets the copyright of the component.
        Parameters:
        copyright - component copyright

      • setMimeType

        public void setMimeType​(java.lang.String mimeType)
        Sets the mime-type of the component.
        Parameters:
        mimeType - component mime-type

      • setCompositionAggregate

        public void setCompositionAggregate​(CompositionAggregate compositionAggregate)
        Sets the composition aggregate of this component.
        Parameters:
        compositionAggregate - composition aggregate
        Since:
        CycloneDX Antlib 0.2

      • addManufacturer

        public void addManufacturer​(Organization manufacturer)
        Sets the manufacturer of the component.

        At most one manufacturer can be set.

        Parameters:
        manufacturer - component manufacturer

      • addSupplier

        public void addSupplier​(Organization supplier)
        Sets the supplier of the component.

        At most one supplier can be set.

        Parameters:
        supplier - component supplier

      • addAuthor

        public void addAuthor​(org.cyclonedx.model.OrganizationalContact author)
        Adds an author to the component.
        Parameters:
        author - component author

      • addConfiguredTag

        public void addConfiguredTag​(Component.Tag tag)
        Adds a tag to the component.
        Parameters:
        tag - component tag

      • addConfiguredProperty

        public void addConfiguredProperty​(org.cyclonedx.model.Property property)
        Adds a property to the component.
        Parameters:
        property - component property

      • addConfiguredPropertySet

        public void addConfiguredPropertySet​(PropertySet set)
        Adds a set of properties to the component.
        Parameters:
        set - set of properties of component
        Since:
        CycloneDX Antlib 0.2

      • setSupplierIsManufacturer

        public void setSupplierIsManufacturer​(boolean supplierIsManufacturer)
        If set to true the supplier will also be used to provide the manufacturer information.
        Parameters:
        supplierIsManufacturer - whether to use supplier as manufacturer as well

      • addConfiguredLicense

        public void addConfiguredLicense​(License l)
        Adds a license to this component.
        Parameters:
        l - component license

      • addConfiguredExternalReference

        public void addConfiguredExternalReference​(ExternalReference ref)
        Adds an external reference to the component.
        Parameters:
        ref - external reference of component

      • addConfiguredExternalReferenceSet

        public void addConfiguredExternalReferenceSet​(ExternalReferenceSet set)
        Adds a set of external references to the component.
        Parameters:
        set - set of external references of component

      • setScope

        public void setScope​(ComponentScope scope)
        Sets the scope of this component.

        Must not be set for the main component of the SBOM.

        Parameters:
        scope - component scope

      • setIsExternal

        public void setIsExternal​(boolean isExternal)
        Sets 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.

        Must not be set to true for the main component of the SBOM.

        Parameters:
        isExternal - whether the component is external

      • addDependency

        public void addDependency​(Component.Dependency d)
        Adds a dependency to this component.
        Parameters:
        d - component dependency

      • setUnknownDependencies

        public void setUnknownDependencies​(boolean unknownDependencies)
        Sets whether the dependencies of this component are unknown.

        This flag is needed to be able to tell dependencies with unknown dependencies from components without any dependencies.

        Parameters:
        unknownDependencies - whether dependencies are unknown

      • addComponent

        public void addComponent​(Component c)
        Adds a nested component.
        Parameters:
        c - nested component

      • add

        public void add​(ComponentResolver resolver)
        Resolver that uses external data to enrich this component.
        Parameters:
        resolver - the resolver
        Since:
        CycloneDX Antlib 0.2

      • getComponentFile

        public org.apache.tools.ant.types.Resource getComponentFile()
        Gets the resource the component is about.
        Returns:
        the resource holding the component's content - may be null
        Since:
        CycloneDX Antlib 0.2

      • getType

        public ComponentType getType()
        Gets the component type.
        Returns:
        the component type - may be null
        Since:
        CycloneDX Antlib 0.2

      • getName

        public java.lang.String getName()
        Gets the name of the component.
        Returns:
        component name - will not be null on a valid component

      • getGroup

        public java.lang.String getGroup()
        Gets the group of the component.
        Returns:
        component group - may be null

      • getVersion

        public java.lang.String getVersion()
        Gets the version of the component.
        Returns:
        component version - may be null
        Since:
        CycloneDX Antlib 0.2

      • getPurl

        public java.lang.String getPurl()
        Gets the Package-URL (purl) of the component.
        Returns:
        the value set with {@see #setPurl} or a Maven purl derived from name, group and version if all three or set - or null otherwise.

      • getBomRef

        public java.lang.String getBomRef()
        Gets the bom-ref of the component.
        Returns:
        the value set with {@see #setBomRef} or the result of {@see #getPurl}.

      • getDescription

        public java.lang.String getDescription()
        Gets the decription of the component.
        Overrides:
        getDescription in class org.apache.tools.ant.ProjectComponent
        Returns:
        component description - may be null
        Since:
        CycloneDX Antlib 0.2

      • getPublisher

        public java.lang.String getPublisher()
        Gets the publisher of the component.
        Returns:
        component publisher - may be null
        Since:
        CycloneDX Antlib 0.2

      • getCopyright

        public java.lang.String getCopyright()
        Gets the copyright of the component.
        Returns:
        component copyright - may be null
        Since:
        CycloneDX Antlib 0.2

      • getMimeType

        public java.lang.String getMimeType()
        Gets the mime-type of the component.
        Returns:
        component mime-type - may be null
        Since:
        CycloneDX Antlib 0.2

      • getCompositionAggregate

        public CompositionAggregate getCompositionAggregate()
        Gets the composition aggregate of the component.
        Returns:
        composition aggregate - may be null
        Since:
        CycloneDX Antlib 0.2

      • getManufacturer

        public Organization getManufacturer()
        Gets the manufacturer of the component.
        Returns:
        component manufacturer - may be null
        Since:
        CycloneDX Antlib 0.2

      • getSupplier

        public Organization getSupplier()
        Gets the supplier of the component.
        Returns:
        component supplier - may be null
        Since:
        CycloneDX Antlib 0.2

      • getAuthors

        public java.util.Collection<org.cyclonedx.model.OrganizationalContact> getAuthors()
        Gets the authors of the component.
        Returns:
        component authors - will not be null
        Since:
        CycloneDX Antlib 0.2

      • getTags

        public java.util.Collection<Component.Tag> getTags()
        Gets the tags of the component.
        Returns:
        component tags - will not be null
        Since:
        CycloneDX Antlib 0.2

      • getSupplierIsManufacturer

        public boolean getSupplierIsManufacturer()
        Gets whether the supplier shall also be used to provide the manufacturer information.
        Returns:
        whether to use supplier as manufacturer as well
        Since:
        CycloneDX Antlib 0.2

      • getLicenses

        public java.util.Collection<License> getLicenses()
        Gets licenses added to this component.
        Returns:
        component licenses - will not be null
        Since:
        CycloneDX Antlib 0.2

      • getExternalReferences

        public java.util.Collection<org.cyclonedx.model.ExternalReference> getExternalReferences()
        Gets the merged external references added via {@see #addConfiguredExternalReference} or {@see #addConfiguredExternalReferenceSet} to the component.
        Returns:
        component's external references - will not be null
        Since:
        CycloneDX Antlib 0.2

      • getScope

        public ComponentScope getScope()
        Gets the scope of this component.
        Returns:
        component scope - may be null
        Since:
        CycloneDX Antlib 0.2

      • getIsExternal

        public boolean getIsExternal()
        Gets whether the isExternal flag is true.
        Returns:
        whether the isExternal flag is true
        Since:
        CycloneDX Antlib 0.2

      • getNestedComponents

        public java.util.List<Component> getNestedComponents()
        Recursively returns the nested components of this component.
        Returns:
        nested components of this component - will not be null

      • getDependencies

        public java.util.Collection<Component.Dependency> getDependencies()
        Gets the dependencies of the component.
        Returns:
        component's dependencies - will not be null

      • areDependenciesUnknown

        public boolean areDependenciesUnknown()
        Whether dependencies are unknoown.
        Returns:
        the value set with setUnknownDependencies(boolean) or false.

      • resolve

        public java.util.Collection<Component> resolve()
                                        throws java.io.IOException
        Read the linked SBOM (if any) and merge its content with the one already defined for this component.
        Returns:
        the "addtional" components defined in the linked SBOM that are dependencies of this component.
        Throws:
        java.io.IOException - if reading the SBOM links fails

      • createFileComponent

        public static Component createFileComponent​(org.apache.tools.ant.Project project,
                                            org.apache.tools.ant.types.Resource r)
        Creates a new "file" type component for a resource.
        Parameters:
        project - project to use when resolving paths
        r - the resource holding the file
        Returns:
        the component

      • toMainCycloneDxComponent

        public org.cyclonedx.model.Component toMainCycloneDxComponent​(org.cyclonedx.Version bomVersion)
                                                       throws java.io.IOException
        Translates this component to a CycloneDX component suitable for the metadata.component.
        Parameters:
        bomVersion - specification version
        Returns:
        mapped component
        Throws:
        java.io.IOException - if calculating component hashes fails

      • toAdditionalCycloneDxComponent

        public org.cyclonedx.model.Component toAdditionalCycloneDxComponent​(org.cyclonedx.Version bomVersion)
                                                             throws java.io.IOException
        Translates this component to a CycloneDX component suitable for the components.component.
        Parameters:
        bomVersion - specification version
        Returns:
        mapped component
        Throws:
        java.io.IOException - if calculating component hashes fails

      • toCycloneDxComponent

        protected org.cyclonedx.model.Component toCycloneDxComponent​(org.cyclonedx.Version bomVersion)
                                                      throws java.io.IOException
        Maps all common data except for scope and isExternal.
        Parameters:
        bomVersion - specification version
        Returns:
        mapped component
        Throws:
        java.io.IOException - if calculating component hashes fails

      • from

        protected static Component from​(org.cyclonedx.model.Component real,
                                java.util.List<org.cyclonedx.model.Dependency> dependencies)
        Maps from a CycloneDX Component to an incstance of this type.
        Parameters:
        real - the CycloneDX component
        dependencies - list of dependencies of "real"
        Returns:
        a Component matching real and dependencies

      • fillFrom

        protected void fillFrom​(org.cyclonedx.model.Component real,
                        java.util.List<org.cyclonedx.model.Dependency> allDependencies)
        Enriches this instance with data read from a CycloneDX component and its dependencies.

        Any values already set on this component will not be overwritten by "real"'s values.

        +
        Parameters:
        real - the CycloneDX component
        allDependencies - list of dependencies of "real"

      • addHashes

        protected void addHashes​(org.cyclonedx.model.Component component,
                         org.cyclonedx.Version bomVersion)
                  throws java.io.IOException
        If this component has a nested resource child, all hashes supported by the CycloneDX Core library for the spec version are created and added to the given component.
        Parameters:
        component - component to add hashes to
        bomVersion - specification version
        Throws:
        java.io.IOException - if calculating component hashes fails

      • getRef

        protected Component getRef()
        Perform the check for circular references and return the referenced Component.
        Returns:
        Component.

      • dieOnCircularReference

        protected void dieOnCircularReference​(java.util.Stack<java.lang.Object> stk,
                                      org.apache.tools.ant.Project p)
                               throws org.apache.tools.ant.BuildException
        Overrides:
        dieOnCircularReference in class org.apache.tools.ant.types.DataType
        Throws:
        org.apache.tools.ant.BuildException