Class SpdxComparer

java.lang.Object
org.spdx.utility.compare.SpdxComparer
public class SpdxComparer extends Object
Performs a comparison between two or more SPDX documents and holds the results of the comparison

The main function to perform the comparison is compare(spdxdoc1, spdxdoc2)

For files, the comparison results are separated into unique files based on the file names which can be obtained by the method getUniqueFiles(index1, index2). If two documents contain files with the same name, but different data, the differences for these files can be obtained through the method getFileDifferences(index1, index2)

Multi-threading considerations: This class is "mostly" threadsafe in that the calls to perform the comparison are synchronized and a flag is used to throw an error for any calls to getters when a compare is in progress. There is a small theoretical window in the getters where the compare operation is started in the middle of a get operation.

Author:
Gary O'Neall

  • Constructor Details

    • SpdxComparer

      public SpdxComparer()

  • Method Details

    • compare

      public void compare(org.spdx.library.model.v2.SpdxDocument spdxDoc1, org.spdx.library.model.v2.SpdxDocument spdxDoc2) throws org.spdx.core.InvalidSPDXAnalysisException, SpdxCompareException
      Compares 2 SPDX documents
      Parameters:
      spdxDoc1 - first doc
      spdxDoc2 - second doc
      Throws:
      org.spdx.core.InvalidSPDXAnalysisException - on SPDX parsing errors
      SpdxCompareException - Customize Toolbar…

    • compare

      public void compare(List<org.spdx.library.model.v2.SpdxDocument> spdxDocuments) throws org.spdx.core.InvalidSPDXAnalysisException, SpdxCompareException
      Compares multiple SPDX documents
      Parameters:
      spdxDocuments - documents to compare
      Throws:
      SpdxCompareException - on SPDX parsing errors
      org.spdx.core.InvalidSPDXAnalysisException - on SPDX parsing errors

    • collectAllPackages

      protected List<org.spdx.library.model.v2.SpdxPackage> collectAllPackages(org.spdx.library.model.v2.SpdxDocument spdxDocument) throws org.spdx.core.InvalidSPDXAnalysisException
      Collect all of the packages present in the SPDX document including packages embedded in other relationships within documents
      Parameters:
      spdxDocument - document containing packages
      Returns:
      list of packages
      Throws:
      org.spdx.core.InvalidSPDXAnalysisException - on SPDX parsing errors

    • collectAllFiles

      public List<org.spdx.library.model.v2.SpdxFile> collectAllFiles(org.spdx.library.model.v2.SpdxDocument spdxDocument) throws org.spdx.core.InvalidSPDXAnalysisException
      Collect all of the files present in the SPDX document including files within documents and files embedded in packages
      Parameters:
      spdxDocument - document containing files
      Returns:
      files collected
      Throws:
      org.spdx.core.InvalidSPDXAnalysisException - on SPDX parsing errors

    • compareLicense

      public boolean compareLicense(int doc1, org.spdx.library.model.v2.license.AnyLicenseInfo license1, int doc2, org.spdx.library.model.v2.license.AnyLicenseInfo license2) throws SpdxCompareException
      Compares two licenses from two different SPDX documents taking into account the extracted license infos whose ID's may be different between the two documents Note: The ExtractedLicenseIDMap must be initialized before this method is invoked
      Parameters:
      doc1 - Index of the SPDX document for license1
      license1 - license to compare
      doc2 - Index of the SPDX document for license2
      license2 - license to compare
      Returns:
      true if the licenses are equivalent
      Throws:
      SpdxCompareException - on compare errors

    • stringCollectionsEqual

      public static boolean stringCollectionsEqual(Collection<String> stringsA, Collection<String> stringsB)
      Compares 2 collections and returns true if the contents are equal ignoring order and trimming strings. Nulls are also considered as equal to other nulls.
      Parameters:
      stringsA - string to compare
      stringsB - string to compare
      Returns:
      true if the contents are equal ignoring order and trimming strings

    • objectsEqual

      public static boolean objectsEqual(Object o1, Object o2)
      returns true if the two objects are equal considering nulls
      Parameters:
      o1 - object to compare
      o2 - object to compare
      Returns:
      true if the two objects are equal considering nulls

    • elementsEquivalent

      public static boolean elementsEquivalent(Optional<? extends org.spdx.library.model.v2.ModelObjectV2> elementA, Optional<? extends org.spdx.library.model.v2.ModelObjectV2> elementB) throws org.spdx.core.InvalidSPDXAnalysisException
      Parameters:
      elementA - element to compare
      elementB - element to compare
      Returns:
      true of the elements are present and equivalent
      Throws:
      org.spdx.core.InvalidSPDXAnalysisException - on SPDX parsing errors

    • collectionsEquivalent

      public static boolean collectionsEquivalent(Collection<? extends org.spdx.library.model.v2.ModelObjectV2> collectionA, Collection<? extends org.spdx.library.model.v2.ModelObjectV2> collectionB) throws org.spdx.core.InvalidSPDXAnalysisException
      Parameters:
      collectionA - collection
      collectionB - collection
      Returns:
      true if the collections all contain equivalent items
      Throws:
      org.spdx.core.InvalidSPDXAnalysisException - on SPDX parsing errors

    • listsEquals

      public static boolean listsEquals(List<?> a1, List<?> a2)
      Compare two object lists
      Parameters:
      a1 - list
      a2 - list
      Returns:
      true if 2 lists are equal

    • collectionsEquals

      public static boolean collectionsEquals(Collection<?> a1, Collection<?> a2)
      Compare two object lists
      Parameters:
      a1 - collection
      a2 - collection
      Returns:
      true of the collections are equal

    • stringsEqual

      public static boolean stringsEqual(String stringA, String stringB)
      Compares two strings returning true if they are equal considering null values and trimming the strings. and normalizing linefeeds. Empty strings are treated as the same as null values.
      Parameters:
      stringA - first string to compare
      stringB - second string to compare
      Returns:
      same result as compareTo

    • stringsEqual

      public static boolean stringsEqual(Optional<String> stringA, Optional<String> stringB)
      Compares two strings returning true if they are equal considering null values and trimming the strings. and normalizing linefeeds. Empty strings are treated as the same as null values.
      Parameters:
      stringA - first string to compare
      stringB - second string to compare
      Returns:
      same result as compareTo

    • compareStrings

      public static int compareStrings(String stringA, String stringB)
      Compares two strings including trimming the string and taking into account they may be null. Null is considered a smaller value
      Parameters:
      stringA - first string to compare
      stringB - second string to compare
      Returns:
      same result as compareTo

    • compareStrings

      public static int compareStrings(Optional<String> stringA, Optional<String> stringB)
      Compares two strings including trimming the string and taking into account they may be null. Null is considered a smaller value
      Parameters:
      stringA - first string to compare
      stringB - second string to compare
      Returns:
      same result as compareTo

    • isDifferenceFound

      public boolean isDifferenceFound()
      Returns:
      true if any difference is found

    • isSpdxVersionEqual

      public boolean isSpdxVersionEqual() throws SpdxCompareException
      Returns:
      true if the SPDX spec versions are equal
      Throws:
      SpdxCompareException - on compare errors

    • getSpdxDoc

      public org.spdx.library.model.v2.SpdxDocument getSpdxDoc(int docIndex) throws SpdxCompareException
      Parameters:
      docIndex - Reference to which document number - 0 is the first document parameter in compare
      Returns:
      the SPDX document at the index
      Throws:
      SpdxCompareException - on compare errors

    • isDataLicenseEqual

      public boolean isDataLicenseEqual() throws SpdxCompareException
      Returns:
      true if the data licenses are equals
      Throws:
      SpdxCompareException - on compare errors

    • isDocumentCommentsEqual

      public boolean isDocumentCommentsEqual() throws SpdxCompareException
      Returns:
      true if the document comments are equal
      Throws:
      SpdxCompareException - on compare errors

    • isExternalDocumentRefsEquals

      public boolean isExternalDocumentRefsEquals() throws SpdxCompareException
      Returns:
      true if the external document refs are equal
      Throws:
      SpdxCompareException - on compare errors

    • isExternalDcoumentRefsEquals

      @Deprecated public boolean isExternalDcoumentRefsEquals() throws SpdxCompareException
      Deprecated.
      Returns:
      true if the external document refs are equal
      Throws:
      SpdxCompareException - on compare errors

    • isExtractedLicensingInfosEqual

      public boolean isExtractedLicensingInfosEqual() throws SpdxCompareException
      Returns:
      true if the extracted licensing infos are equal
      Throws:
      SpdxCompareException - on compare errors

    • getUniqueExtractedLicenses

      public List<org.spdx.library.model.v2.license.ExtractedLicenseInfo> getUniqueExtractedLicenses(int docIndexA, int docIndexB) throws SpdxCompareException
      Retrieves any unique extracted licenses from the first SPDX document index relative to the second - unique is determined by the license text matching
      Parameters:
      docIndexA - source document index
      docIndexB - index of the compare document
      Returns:
      ny unique extracted licenses fromt the first SPDX document index relative to the second - unique is determined by the license text matching
      Throws:
      SpdxCompareException - on compare errors

    • getExtractedLicenseDifferences

      public List<SpdxLicenseDifference> getExtractedLicenseDifferences(int docIndexA, int docIndexB) throws SpdxCompareException
      Retrieves any licenses which where the text matches in both documents but other fields are different
      Parameters:
      docIndexA - source document index
      docIndexB - index of the compare document
      Returns:
      any creators which are in the SPDX document 1 which are not in document 2
      Throws:
      SpdxCompareException - on compare errors

    • isCreatorInformationEqual

      public boolean isCreatorInformationEqual() throws SpdxCompareException
      Returns:
      true if all creation information fields equals
      Throws:
      SpdxCompareException - on compare errors

    • isCreatorCommentsEqual

      public boolean isCreatorCommentsEqual() throws SpdxCompareException
      Returns:
      true all creator comments equal
      Throws:
      SpdxCompareException - on compare errors

    • isCreatorDatesEqual

      public boolean isCreatorDatesEqual() throws SpdxCompareException
      Returns:
      true if all creation information fields equals
      Throws:
      SpdxCompareException - on compare errors

    • getUniqueCreators

      public List<String> getUniqueCreators(int doc1index, int doc2index) throws SpdxCompareException
      Returns any creators which are in the SPDX document 1 which are not in document 2
      Parameters:
      doc1index - source document index
      doc2index - index of the compare document
      Returns:
      any creators which are in the SPDX document 1 which are not in document 2
      Throws:
      SpdxCompareException - on compare errors

    • isFilesEquals

      public boolean isFilesEquals() throws SpdxCompareException
      Returns:
      true if the files are equal
      Throws:
      SpdxCompareException - on compare errors

    • isfilesEquals

      @Deprecated public boolean isfilesEquals() throws SpdxCompareException
      Deprecated.
      Returns:
      true if the files are equal
      Throws:
      SpdxCompareException - on compare errors

    • isPackagesEquals

      public boolean isPackagesEquals() throws SpdxCompareException
      Returns:
      true if the packages are equal
      Throws:
      SpdxCompareException - on compare errors

    • isDocumentAnnotationsEquals

      public boolean isDocumentAnnotationsEquals() throws SpdxCompareException
      Returns:
      true if the document annotations are equal
      Throws:
      SpdxCompareException - on compare errors

    • isDocumentRelationshipsEquals

      public boolean isDocumentRelationshipsEquals() throws SpdxCompareException
      Returns:
      true if the document relationships are equal
      Throws:
      SpdxCompareException - on compare errors

    • getUniqueFiles

      public List<org.spdx.library.model.v2.SpdxFile> getUniqueFiles(int docindex1, int docindex2) throws SpdxCompareException
      Return any files which are in spdx document index 1 but not in spdx document index 2
      Parameters:
      docindex1 - index of source document
      docindex2 - index of document to compare
      Returns:
      any files which are in spdx document index 1 but not in spdx document index 2
      Throws:
      SpdxCompareException - on errors doing compare

    • getFileDifferences

      public List<SpdxFileDifference> getFileDifferences(int docindex1, int docindex2) throws SpdxCompareException
      Returns any file differences found between the first and second SPDX documents as specified by the document index
      Parameters:
      docindex1 - index of source document
      docindex2 - index of document to compare
      Returns:
      any file differences found between the first and second SPDX documents as specified by the document index
      Throws:
      SpdxCompareException - on errors doing compare

    • getUniquePackages

      public List<org.spdx.library.model.v2.SpdxPackage> getUniquePackages(int docindex1, int docindex2) throws SpdxCompareException
      Return any files which are in spdx document index 1 but not in spdx document index 2
      Parameters:
      docindex1 - index of source document
      docindex2 - index of document to compare
      Returns:
      any files which are in spdx document index 1 but not in spdx document index 2
      Throws:
      SpdxCompareException - on errors doing compare

    • getUniqueExternalDocumentRefs

      public List<org.spdx.library.model.v2.ExternalDocumentRef> getUniqueExternalDocumentRefs(int docindex1, int docindex2) throws SpdxCompareException
      Return any external document references which are in spdx document index 1 but not in spdx document index 2
      Parameters:
      docindex1 - index of source document
      docindex2 - index of document to compare
      Returns:
      any external document references which are in spdx document index 1 but not in spdx document index 2
      Throws:
      SpdxCompareException - on errors doing compare

    • getUniqueDocumentAnnotations

      public List<org.spdx.library.model.v2.Annotation> getUniqueDocumentAnnotations(int docindex1, int docindex2) throws SpdxCompareException
      Return any document annotations which are in spdx document index 1 but not in spdx document index 2
      Parameters:
      docindex1 - index of source document
      docindex2 - index of document to compare
      Returns:
      any document annotations which are in spdx document index 1 but not in spdx document index 2
      Throws:
      SpdxCompareException - on errors doing compare

    • getUniqueDocumentRelationship

      public List<org.spdx.library.model.v2.Relationship> getUniqueDocumentRelationship(int docindex1, int docindex2) throws SpdxCompareException
      Return any document annotations which are in spdx document index 1 but not in spdx document index 2
      Parameters:
      docindex1 - index of first document to compare
      docindex2 - index of second document to compare
      Returns:
      document annotations in spdx document index 1 but not in spdx document index 2
      Throws:
      SpdxCompareException - On error in comparison

    • getPackageDifferences

      public List<SpdxPackageComparer> getPackageDifferences() throws SpdxCompareException
      Returns:
      Package comparers where there is at least one difference
      Throws:
      SpdxCompareException - On error in comparison

    • getPackageComparers

      public SpdxPackageComparer[] getPackageComparers()
      Returns:
      all package comparers

    • getNumSpdxDocs

      public int getNumSpdxDocs()
      Returns:
      the number of documents being compared

    • isLicenseListVersionEqual

      public boolean isLicenseListVersionEqual() throws SpdxCompareException
      Returns:
      true if the license list version is equal
      Throws:
      SpdxCompareException - On error in comparison

    • findUniqueChecksums

      public static List<org.spdx.library.model.v2.Checksum> findUniqueChecksums(Collection<org.spdx.library.model.v2.Checksum> checksumsA, Collection<org.spdx.library.model.v2.Checksum> checksumsB) throws org.spdx.core.InvalidSPDXAnalysisException
      Find any SPDX checksums which are in checksumsA but not in checksumsB
      Parameters:
      checksumsA - checksum to compare
      checksumsB - checksum to compare
      Returns:
      any SPDX checksums which are in checksumsA but not in checksumsB
      Throws:
      org.spdx.core.InvalidSPDXAnalysisException - on SPDX parsing errors

    • findUniqueAnnotations

      public static List<org.spdx.library.model.v2.Annotation> findUniqueAnnotations(Collection<org.spdx.library.model.v2.Annotation> annotationsA, Collection<org.spdx.library.model.v2.Annotation> annotationsB) throws org.spdx.core.InvalidSPDXAnalysisException
      Find any SPDX annotations which are in annotationsA but not in annotationsB
      Parameters:
      annotationsA - source annotations
      annotationsB - annotations to be compared against
      Returns:
      list of unique annotations in annotationsB
      Throws:
      org.spdx.core.InvalidSPDXAnalysisException - On SPDX parsing errors

    • findUniqueRelationships

      public static List<org.spdx.library.model.v2.Relationship> findUniqueRelationships(Collection<org.spdx.library.model.v2.Relationship> relationshipsA, Collection<org.spdx.library.model.v2.Relationship> relationshipsB) throws org.spdx.core.InvalidSPDXAnalysisException
      Find unique relationships that are present in relationshipsA but not relationshipsB
      Parameters:
      relationshipsA - relationship to compare
      relationshipsB - relationship to compare
      Returns:
      unique relationships that are present in relationshipsA but not relationshipsB
      Throws:
      org.spdx.core.InvalidSPDXAnalysisException - on SPDX parsing errors

    • findUniqueExternalDocumentRefs

      public static List<org.spdx.library.model.v2.ExternalDocumentRef> findUniqueExternalDocumentRefs(Collection<org.spdx.library.model.v2.ExternalDocumentRef> externalDocRefsA, Collection<org.spdx.library.model.v2.ExternalDocumentRef> externalDocRefsB) throws org.spdx.core.InvalidSPDXAnalysisException
      Find unique relationships that are present in relationshipsA but not relationshipsB
      Parameters:
      externalDocRefsA - doc ref to compare
      externalDocRefsB - doc ref to compare
      Returns:
      list of unique relationship
      Throws:
      org.spdx.core.InvalidSPDXAnalysisException - On error in comparison

    • getSpdxDocuments

      public List<org.spdx.library.model.v2.SpdxDocument> getSpdxDocuments()
      Returns:
      list of SPDX documents

    • isDocumentContentsEquals

      public boolean isDocumentContentsEquals() throws SpdxCompareException
      Returns:
      true if the document contents are equals
      Throws:
      SpdxCompareException - On error in comparison

    • isSnippetsEqual

      public boolean isSnippetsEqual() throws SpdxCompareException
      Returns:
      true if the snippets are equals
      Throws:
      SpdxCompareException - On error in comparison

    • getSnippetComparers

      public SpdxSnippetComparer[] getSnippetComparers()
      Returns:
      all snippet comparers