From 985286166cd8352f090a0629386efcba3192ceab Mon Sep 17 00:00:00 2001 From: Arthit Suriyawongkul Date: Sat, 10 May 2025 10:54:00 +0100 Subject: [PATCH 1/3] Javadoc: Add

to start of paragraphs To separated the first one-liner summary from the rest of the descriptions. Signed-off-by: Arthit Suriyawongkul --- .../compare/CompareTemplateOutputHandler.java | 83 ++++++++++++++----- .../VerificationCodeGenerator.java | 13 +++ 2 files changed, 75 insertions(+), 21 deletions(-) diff --git a/src/main/java/org/spdx/utility/compare/CompareTemplateOutputHandler.java b/src/main/java/org/spdx/utility/compare/CompareTemplateOutputHandler.java index 7334a371..16590493 100644 --- a/src/main/java/org/spdx/utility/compare/CompareTemplateOutputHandler.java +++ b/src/main/java/org/spdx/utility/compare/CompareTemplateOutputHandler.java @@ -57,7 +57,7 @@ class ParseInstruction { /** * Construct a new {@link ParseInstruction} with the specified rule, text, and parent - * + *

* A parse instruction represents a single unit of parsing logic, which may include a rule, * associated text, and a hierarchical relationship to a parent instruction. * @@ -77,7 +77,7 @@ class ParseInstruction { /** * Return a string representation of this parse instruction - * + *

* If the parse instruction has an associated rule, the rule's string representation is returned. * If the parse instruction has associated text, the first 10 characters of the text are returned. * If neither a rule nor text is associated, "NONE" is returned. @@ -103,7 +103,7 @@ public String toString() { /** * Retrieve the license template rule associated with this parse instruction - * + *

* The rule defines the type of instruction (e.g., variable, optional, etc.) and provides * details about how the instruction should be processed during the comparison. * @@ -116,7 +116,7 @@ public LicenseTemplateRule getRule() { /** * Set the license template rule associated with this parse instruction - * + *

* The rule defines the type of instruction (e.g., variable, optional, etc.) and provides * details about how the instruction should be processed during the comparison. * @@ -129,7 +129,7 @@ public void setRule(LicenseTemplateRule rule) { /** * Retrieve the text associated with this parse instruction - * + *

* The text represents the content of this parse instruction, which may be compared against * other text during the license template matching process. * @@ -142,7 +142,7 @@ public String getText() { /** * Set the text content for this parse instruction - * + *

* The text represents the content of this parse instruction, which may be compared against * other text during the license template matching process. * @@ -198,7 +198,7 @@ public void setParent(ParseInstruction parent) { /** * Retrieve the list of sub-instructions for this parse instruction. - * + *

* Sub-instructions represent the child instructions that are part of this parse * instruction. These can include text, rules, or other nested instructions. * @@ -590,7 +590,7 @@ public void setLastOptionalDifference(DifferenceDescription optionalDifference) * a single token * * @return {@code true} if the instruction following this instruction is a - * {@code BEGIN_OPTIONAL} rule containing text with a single token, {@code false} + * {@code beginOptional} rule containing text with a single token, {@code false} * otherwise. */ public boolean isFollowingInstructionOptionalSingleToken() { @@ -677,11 +677,23 @@ public void skipNextInstruction() { nextInst.setSkip(true); } } - + + /** + * Check whether this parse instruction should be skipped during matching + * + * @return {@code true} if this parse instruction should be skipped; {@code false} + * otherwise. + */ public boolean getSkip() { - return this.skip ; + return this.skip; } - + + /** + * Set whether this parse instruction should be skipped during matching + * + * @param skip {@code true} if this parse instruction should be skipped; {@code false} + * otherwise. + */ public void setSkip(boolean skip) { this.skip = skip; } @@ -728,7 +740,7 @@ public ParseInstruction getNextNormalTextInstruction() { /** * Set whether the first text token of this parse instruction should be skipped during * matching - * + *

* This is useful in cases where the first token of the text is optional or should not be * considered for comparison purposes. * @@ -742,7 +754,7 @@ public void setSkipFirstToken(boolean skipFirstTextToken) { /** * Check whether the first text token of this parse instruction should be skipped during * matching - * + *

* This is useful in cases where the first token of the text is optional or should not be * considered for comparison purposes. * @@ -765,6 +777,7 @@ public static class DifferenceDescription { /** * Creates a difference description + * * @param differenceFound if true, a difference was found * @param differenceMessage Message describing the differences * @param differences list of lines where the difference was found @@ -785,28 +798,39 @@ public DifferenceDescription() { } /** - * @return true if a difference is found + * Check whether a difference was found during the comparison process + * + * @return {@code true} if a difference was found; {@code false} otherwise. */ public boolean isDifferenceFound() { return differenceFound; } /** - * @param differenceFound if true, a difference was found + * Set whether a difference was found during the comparison process + * + * @param differenceFound {@code true} if a difference was found; {@code false} otherwise. */ public void setDifferenceFound(boolean differenceFound) { this.differenceFound = differenceFound; } /** - * @return Message describing the differences + * Retrieve the message describing the differences found during the comparison process + *

+ * The difference message provides details about the nature of the differences, including + * the location, token, and context of the mismatch. + * + * @return A message describing the differences. */ public String getDifferenceMessage() { return differenceMessage; } /** - * @param differenceMessage Message describing the differences + * Set the message describing the differences found during the comparison process. + * + * @param differenceMessage A message describing the differences. */ public void setDifferenceMessage(String differenceMessage) { this.differenceMessage = differenceMessage; @@ -827,6 +851,8 @@ public void setDifferences(List differences) { } /** + * Adds a new difference to the list of differences found during the comparison process + * * @param location Location in the text of the difference * @param token Token causing the difference * @param msg Message for the difference @@ -880,9 +906,15 @@ public void addDifference(LineColumn location, String token, String msg, String DifferenceDescription differences = new DifferenceDescription(); ParseInstruction currentOptionalInstruction = null; boolean parsingComplete = false; - + /** - * @param compareText Text to compare the parsed SPDX license template to + * Construct a new {@link CompareTemplateOutputHandler} with the specified text to compare + *

+ * This handler is used to compare the output of a parsed SPDX license template to the provided + * text. It tokenizes the input text and prepares it for comparison against the parsed license + * template. + * + * @param compareText The text to compare the parsed SPDX license template to. * @throws IOException This is not to be expected since we are using StringReaders */ public CompareTemplateOutputHandler(String compareText) throws IOException { @@ -892,11 +924,14 @@ public CompareTemplateOutputHandler(String compareText) throws IOException { } /** + * Compares the given text tokens against the match tokens starting from a specific token index + * * @param textTokens source for compare * @param matchTokens tokens to match against * @param startToken index for the start token * @param instruction parse instruction - * @return positive index of the next match token after the match or negative index of the token which first failed the match + * @return positive index of the next match token after the match or negative index of the token + * which first failed the match */ private int compareText(String[] textTokens, String[] matchTokens, int startToken, ParseInstruction instruction) { @@ -1023,7 +1058,10 @@ public void endOptional(LicenseTemplateRule rule) { } /** - * Performs the actual parsing if it has not been completed. NOTE: This should only be called after all text has been added. + * Performs the actual parsing if it has not been completed + *

+ * NOTE: This should only be called after all text has been added. + * * @return true if no differences were found * @throws LicenseParserException on license parsing error */ @@ -1035,6 +1073,8 @@ public boolean matches() throws LicenseParserException { } /** + * Retrieve the details of the differences found during the comparison process + * * @return details on the differences found */ public DifferenceDescription getDifferences() { @@ -1057,6 +1097,7 @@ public void completeParsing() throws LicenseParserException { /** * Compares the text against the compareText + * * @param text text to compare * @param startToken token of the compareText to being the comparison * @return next token index (positive) if there is a match, negative first token where this is a miss-match if no match diff --git a/src/main/java/org/spdx/utility/verificationcode/VerificationCodeGenerator.java b/src/main/java/org/spdx/utility/verificationcode/VerificationCodeGenerator.java index 1b182e16..05120302 100644 --- a/src/main/java/org/spdx/utility/verificationcode/VerificationCodeGenerator.java +++ b/src/main/java/org/spdx/utility/verificationcode/VerificationCodeGenerator.java @@ -51,12 +51,22 @@ public class VerificationCodeGenerator { private final IFileChecksumGenerator fileChecksumGenerator; + /** + * Construct a new {@link VerificationCodeGenerator} with the specified file checksum generator + *

+ * The file checksum generator is used to calculate checksums for files during the generation of + * the SPDX Package Verification Code. + * + * @param fileChecksumGenerator An implementation of {@link IFileChecksumGenerator} used to + * calculate file checksums. Must not be {@code null}. + */ public VerificationCodeGenerator(IFileChecksumGenerator fileChecksumGenerator) { this.fileChecksumGenerator = fileChecksumGenerator; } /** * Generate the SPDX Package Verification Code from an array of SPDXFiles + * * @param spdxFiles Files to generate the VerificationCode from * @param skippedFilePaths File path names to not include in the VerificationCode * @param modelStore where the resultant VerificationCode is store @@ -93,6 +103,7 @@ public SpdxPackageVerificationCode generatePackageVerificationCode(SpdxFile[] sp /** * Generate the SPDX Package Verification Code from a directory of files included in the archive + * * @param sourceDirectory source directory for the package verification code * @param modelStore where the resultant VerificationCode is store * @param documentUri document URI where the VerificationCode is stored @@ -184,6 +195,7 @@ private void collectFileData(String prefixForRelative, File sourceDirectory, /** * Normalizes a file path per the SPDX spec + * * @param nonNormalizedFilePath original file path - may be unix or DOS format * @return file path normalized per SPDX spec */ @@ -218,6 +230,7 @@ public static String normalizeFilePath(String nonNormalizedFilePath) { } /** * Convert a byte array SHA-1 digest into a 40 character hex string + * * @param digest message digest from checksum calculation * @return string representation of the checksum */ From 9577f7a80340a4d1ed000ab5b2e7ead23cfdb930 Mon Sep 17 00:00:00 2001 From: Arthit Suriyawongkul Date: Sat, 10 May 2025 12:11:16 +0100 Subject: [PATCH 2/3] Add javadoc to StoredTypedItem Signed-off-by: Arthit Suriyawongkul --- .../spdx/storage/simple/StoredTypedItem.java | 147 ++++++++++++------ 1 file changed, 103 insertions(+), 44 deletions(-) diff --git a/src/main/java/org/spdx/storage/simple/StoredTypedItem.java b/src/main/java/org/spdx/storage/simple/StoredTypedItem.java index a16c7e0e..1b9bb1a0 100644 --- a/src/main/java/org/spdx/storage/simple/StoredTypedItem.java +++ b/src/main/java/org/spdx/storage/simple/StoredTypedItem.java @@ -58,13 +58,32 @@ public class StoredTypedItem extends TypedValue { private int referenceCount = 0; private final ReadWriteLock countLock = new ReentrantReadWriteLock(); - + + /** + * Construct a new {@link StoredTypedItem} with the specified object URI, type, and + * specification version + *

+ * This constructor initializes a stored typed item, which represents an individual item to be + * stored in memory with its associated properties and metadata. + * + * @param objectUri The unique URI identifying this stored item. + * @param type The type of the stored item. + * @param specVersion The version of the SPDX specification associated with this item. + * @throws InvalidSPDXAnalysisException If the provided parameters are invalid or violate SPDX + * constraints. + */ public StoredTypedItem(String objectUri, String type, String specVersion) throws InvalidSPDXAnalysisException { super(objectUri, type, specVersion); } - + /** - * @return property descriptors for all properties having a value + * Retrieve the property descriptors for all properties that have a value + *

+ * This method iterates through the stored properties and collects the descriptors + * for all properties that currently have an associated value. + * + * @return An unmodifiable {@link List} of {@link PropertyDescriptor} objects representing + * the properties that have values. */ public List getPropertyValueDescriptors() { Iterator> iter = this.properties.entrySet().iterator(); @@ -75,9 +94,10 @@ public List getPropertyValueDescriptors() { } return Collections.unmodifiableList(retval); } - + /** * Increment the reference count for this stored type item - the number of times this item is referenced + * * @return new number of times this item is referenced */ @SuppressWarnings("UnusedReturnValue") @@ -93,6 +113,7 @@ public int incReferenceCount() { /** * Decrement the reference count for this stored type item + * * @return new number of times this item is referenced * @throws SpdxInvalidTypeException on invalid type */ @@ -108,9 +129,11 @@ public int decReferenceCount() throws SpdxInvalidTypeException { countLock.writeLock().unlock(); } } - - /** - * @return new number of times this item is referenced + + /** + * Retrieve the current reference count for this stored item + * + * @return The current number of times this item is referenced. */ public int getReferenceCount() { countLock.readLock().lock(); @@ -120,13 +143,16 @@ public int getReferenceCount() { countLock.readLock().unlock(); } } - + /** + * Set the value for the specified property descriptor + * * @param propertyDescriptor Descriptor for the property * @param value Value to be set * @throws SpdxInvalidTypeException on invalid type */ - public void setValue(PropertyDescriptor propertyDescriptor, Object value) throws SpdxInvalidTypeException { + public void setValue(PropertyDescriptor propertyDescriptor, Object value) + throws SpdxInvalidTypeException { Objects.requireNonNull(propertyDescriptor, "Property descriptor can not be null"); Objects.requireNonNull(value, "Value can not be null"); if (value instanceof CoreModelObject) { @@ -145,14 +171,17 @@ public void setValue(PropertyDescriptor propertyDescriptor, Object value) throws } properties.put(propertyDescriptor, value); } - + /** - * Sets the value list for the property to an empty list creating the propertyDescriptor if it does not exist + * Set the value list for the property to an empty list creating the propertyDescriptor if it + * does not exist + * * @param propertyDescriptor descriptor for the property * @throws SpdxInvalidTypeException on invalid type */ - public void clearPropertyValueList(PropertyDescriptor propertyDescriptor) throws SpdxInvalidTypeException { - Objects.requireNonNull(propertyDescriptor, "property descriptor can not be null"); + public void clearPropertyValueList(PropertyDescriptor propertyDescriptor) + throws SpdxInvalidTypeException { + Objects.requireNonNull(propertyDescriptor, "Property descriptor can not be null"); Object value = properties.get(propertyDescriptor); if (value == null) { return; @@ -166,12 +195,15 @@ public void clearPropertyValueList(PropertyDescriptor propertyDescriptor) throws } /** - * Adds a value to a property list for a String or Boolean type of value creating the propertyDescriptor if it does not exist + * Add a value to a property list for a String or Boolean type of value creating the + * propertyDescriptor if it does not exist + * * @param propertyDescriptor Descriptor for the property * @param value Value to be set * @throws SpdxInvalidTypeException on invalid type */ - public boolean addValueToList(PropertyDescriptor propertyDescriptor, Object value) throws SpdxInvalidTypeException { + public boolean addValueToList(PropertyDescriptor propertyDescriptor, Object value) + throws SpdxInvalidTypeException { Objects.requireNonNull(propertyDescriptor, "Property descriptor can not be null"); Objects.requireNonNull(value, "Value can not be null"); if (value instanceof CoreModelObject) { @@ -217,15 +249,17 @@ public boolean addValueToList(PropertyDescriptor propertyDescriptor, Object valu throw new SpdxInvalidTypeException("Invalid list type for "+propertyDescriptor); } } - /** + * Remove a property from a property list if it exists + * * @param propertyDescriptor descriptor for the property * @param value to be removed - * @return true if the value was removed, false if the value did not exist + * @return {@code true} if the value was removed, {@code false} if the value did not exist. * @throws SpdxInvalidTypeException for an invalid type */ - public boolean removeTypedValueFromList(PropertyDescriptor propertyDescriptor, TypedValue value) throws SpdxInvalidTypeException { + public boolean removeTypedValueFromList(PropertyDescriptor propertyDescriptor, TypedValue value) + throws SpdxInvalidTypeException { Object map = properties.get(propertyDescriptor); if (map == null) { return false; @@ -247,13 +281,16 @@ public boolean removeTypedValueFromList(PropertyDescriptor propertyDescriptor, T } /** - * Removes a property from a list if it exists + * Remove a property from a property list if it exists + * * @param propertyDescriptor descriptor for the property * @param value value to remove + * @return {@code true} if the value was removed, {@code false} if the value did not exist. * @throws SpdxInvalidTypeException on invalid type */ - public boolean removeValueFromList(PropertyDescriptor propertyDescriptor, Object value) throws SpdxInvalidTypeException { - Objects.requireNonNull(propertyDescriptor, "property descriptor can not be null"); + public boolean removeValueFromList(PropertyDescriptor propertyDescriptor, Object value) + throws SpdxInvalidTypeException { + Objects.requireNonNull(propertyDescriptor, "Property descriptor can not be null"); Objects.requireNonNull(value, "Value can not be null"); Object map = properties.get(propertyDescriptor); if (map == null) { @@ -280,14 +317,20 @@ public boolean removeValueFromList(PropertyDescriptor propertyDescriptor, Object throw new SpdxInvalidTypeException("Invalid list type for "+propertyDescriptor); } } - + /** + * Retrieve an iterator over the list of values associated with the specified property + * descriptor + * * @param propertyDescriptor Descriptor for the property - * @return List of values associated with the objectUri, propertyDescriptor and document - * @throws SpdxInvalidTypeException on invalid type + * @return An {@link Iterator} over the list of values associated with the property descriptor. + * If no values exist, an empty iterator is returned. + * @throws SpdxInvalidTypeException If the property is not associated with a list or if the type + * is invalid. */ - public Iterator getValueList(PropertyDescriptor propertyDescriptor) throws SpdxInvalidTypeException { - Objects.requireNonNull(propertyDescriptor, "property descriptor can not be null"); + public Iterator getValueList(PropertyDescriptor propertyDescriptor) + throws SpdxInvalidTypeException { + Objects.requireNonNull(propertyDescriptor, "Property descriptor can not be null"); Object list = properties.get(propertyDescriptor); if (list == null) { return Collections.emptyIterator(); @@ -306,29 +349,38 @@ public Iterator getValueList(PropertyDescriptor propertyDescriptor) thro throw new SpdxInvalidTypeException("Trying to get a list for non list type for property "+propertyDescriptor); } } - + /** - * @param propertyDescriptor Descriptor for the property - * @return the single value associated with the objectUri, propertyDescriptor and document + * Retrieve the value associated with the specified property descriptor + * + * @param propertyDescriptor The descriptor for the property. Must not be {@code null}. + * @return The single value associated with the specified property descriptor, or {@code null} + * if no value exists. */ public Object getValue(PropertyDescriptor propertyDescriptor) { - Objects.requireNonNull(propertyDescriptor, "property descriptor can not be null"); + Objects.requireNonNull(propertyDescriptor, "Property descriptor can not be null"); return properties.get(propertyDescriptor); } /** - * Removes a property from the document for the given ID if the property exists. Does not raise any exception if the propertyDescriptor does not exist - * @param propertyDescriptor Descriptor for the property + * Remove a property from the document for the given ID if the property exists. + *

+ * Does not raise any exception if the propertyDescriptor does not exist + * + * @param propertyDescriptor The descriptor for the property. Must not be {@code null}. */ public void removeProperty(PropertyDescriptor propertyDescriptor) { - Objects.requireNonNull(propertyDescriptor, "property descriptor can not be null"); + Objects.requireNonNull(propertyDescriptor, "Property descriptor can not be null"); properties.remove(propertyDescriptor); } /** - * Copy all values for this item from another store - * @param store model store to copy from - * @throws InvalidSPDXAnalysisException on invalid type + * Copy all values for this item from another model store + * + * @param store The {@link IModelStore} from which to copy values. Must not be {@code null}. + * @throws InvalidSPDXAnalysisException If an invalid type is encountered during the copy + * process. This can occur if the values in the source store are not compatible with + * this item's properties. */ public void copyValuesFrom(IModelStore store) throws InvalidSPDXAnalysisException { Objects.requireNonNull(store, "Store can not be null"); @@ -348,7 +400,7 @@ public void copyValuesFrom(IModelStore store) throws InvalidSPDXAnalysisExceptio */ @SuppressWarnings("rawtypes") public int collectionSize(PropertyDescriptor propertyDescriptor) throws SpdxInvalidTypeException { - Objects.requireNonNull(propertyDescriptor, "property descriptor can not be null"); + Objects.requireNonNull(propertyDescriptor, "Property descriptor can not be null"); Object map = properties.get(propertyDescriptor); if (map == null) { properties.putIfAbsent(propertyDescriptor, new ConcurrentHashMap>()); @@ -374,13 +426,20 @@ public int collectionSize(PropertyDescriptor propertyDescriptor) throws SpdxInva } /** - * @param propertyDescriptor descriptor for the property - * @param value value to be checked - * @return true if value is in the list associated with the property descriptor - * @throws SpdxInvalidTypeException on invalid type + * Check whether the specified value exists in the list associated with the given property descriptor. + * + * This method verifies if the provided value is present in the collection of values associated + * with the specified property descriptor. If the property descriptor is not associated with a list, + * an exception is thrown. + * + * @param propertyDescriptor The descriptor for the property. Must not be {@code null}. + * @param value The value to be checked. + * @return {@code true} if the value exists in the list associated with the property descriptor; {@code false} otherwise. + * @throws SpdxInvalidTypeException If the property is not associated with a list or if the type is invalid. */ - public boolean collectionContains(PropertyDescriptor propertyDescriptor, Object value) throws SpdxInvalidTypeException { - Objects.requireNonNull(propertyDescriptor, "property descriptor can not be null"); + public boolean collectionContains(PropertyDescriptor propertyDescriptor, Object value) + throws SpdxInvalidTypeException { + Objects.requireNonNull(propertyDescriptor, "Property descriptor can not be null"); Objects.requireNonNull(value, "Value can not be null"); Object map = properties.get(propertyDescriptor); if (map == null) { @@ -530,4 +589,4 @@ public boolean usesId(String elementId) { } return false; } -} \ No newline at end of file +} From 9d060cf0e384355c47869a12cf271731e66cc957 Mon Sep 17 00:00:00 2001 From: Arthit Suriyawongkul Date: Sat, 10 May 2025 16:35:12 +0100 Subject: [PATCH 3/3] Add "must not be null" Signed-off-by: Arthit Suriyawongkul --- .../spdx/storage/simple/StoredTypedItem.java | 131 +++++++++++------- 1 file changed, 79 insertions(+), 52 deletions(-) diff --git a/src/main/java/org/spdx/storage/simple/StoredTypedItem.java b/src/main/java/org/spdx/storage/simple/StoredTypedItem.java index 1b9bb1a0..9cde8f3b 100644 --- a/src/main/java/org/spdx/storage/simple/StoredTypedItem.java +++ b/src/main/java/org/spdx/storage/simple/StoredTypedItem.java @@ -96,9 +96,10 @@ public List getPropertyValueDescriptors() { } /** - * Increment the reference count for this stored type item - the number of times this item is referenced + * Increment the reference count for this stored type item - the number of times this item is + * referenced * - * @return new number of times this item is referenced + * @return The new number of times this item is referenced. */ @SuppressWarnings("UnusedReturnValue") public int incReferenceCount() { @@ -114,7 +115,7 @@ public int incReferenceCount() { /** * Decrement the reference count for this stored type item * - * @return new number of times this item is referenced + * @return The new number of times this item is referenced. * @throws SpdxInvalidTypeException on invalid type */ public int decReferenceCount() throws SpdxInvalidTypeException { @@ -147,8 +148,8 @@ public int getReferenceCount() { /** * Set the value for the specified property descriptor * - * @param propertyDescriptor Descriptor for the property - * @param value Value to be set + * @param propertyDescriptor The descriptor for the property. Must not be {@code null}. + * @param value The value to be set. Must not be {@code null}. * @throws SpdxInvalidTypeException on invalid type */ public void setValue(PropertyDescriptor propertyDescriptor, Object value) @@ -176,7 +177,7 @@ public void setValue(PropertyDescriptor propertyDescriptor, Object value) * Set the value list for the property to an empty list creating the propertyDescriptor if it * does not exist * - * @param propertyDescriptor descriptor for the property + * @param propertyDescriptor The descriptor for the property. Must not be {@code null}. * @throws SpdxInvalidTypeException on invalid type */ public void clearPropertyValueList(PropertyDescriptor propertyDescriptor) @@ -198,8 +199,8 @@ public void clearPropertyValueList(PropertyDescriptor propertyDescriptor) * Add a value to a property list for a String or Boolean type of value creating the * propertyDescriptor if it does not exist * - * @param propertyDescriptor Descriptor for the property - * @param value Value to be set + * @param propertyDescriptor The descriptor for the property. Must not be {@code null}. + * @param value Th value to be set. Must not be {@code null}. * @throws SpdxInvalidTypeException on invalid type */ public boolean addValueToList(PropertyDescriptor propertyDescriptor, Object value) @@ -253,8 +254,8 @@ public boolean addValueToList(PropertyDescriptor propertyDescriptor, Object valu /** * Remove a property from a property list if it exists * - * @param propertyDescriptor descriptor for the property - * @param value to be removed + * @param propertyDescriptor The descriptor for the property. + * @param value The value to be removed. * @return {@code true} if the value was removed, {@code false} if the value did not exist. * @throws SpdxInvalidTypeException for an invalid type */ @@ -283,8 +284,8 @@ public boolean removeTypedValueFromList(PropertyDescriptor propertyDescriptor, T /** * Remove a property from a property list if it exists * - * @param propertyDescriptor descriptor for the property - * @param value value to remove + * @param propertyDescriptor The descriptor for the property. Must not be {@code null}. + * @param value The value to be removed. Must not be {@code null}. * @return {@code true} if the value was removed, {@code false} if the value did not exist. * @throws SpdxInvalidTypeException on invalid type */ @@ -322,7 +323,7 @@ public boolean removeValueFromList(PropertyDescriptor propertyDescriptor, Object * Retrieve an iterator over the list of values associated with the specified property * descriptor * - * @param propertyDescriptor Descriptor for the property + * @param propertyDescriptor The descriptor for the property. Must not be {@code null}. * @return An {@link Iterator} over the list of values associated with the property descriptor. * If no values exist, an empty iterator is returned. * @throws SpdxInvalidTypeException If the property is not associated with a list or if the type @@ -363,9 +364,9 @@ public Object getValue(PropertyDescriptor propertyDescriptor) { } /** - * Remove a property from the document for the given ID if the property exists. + * Remove a property from the document for the given ID if the property exists *

- * Does not raise any exception if the propertyDescriptor does not exist + * Does not raise any exception if the propertyDescriptor does not exist. * * @param propertyDescriptor The descriptor for the property. Must not be {@code null}. */ @@ -394,9 +395,15 @@ public void copyValuesFrom(IModelStore store) throws InvalidSPDXAnalysisExceptio } /** - * @param propertyDescriptor descriptor for the property - * @return Size of the collection - * @throws SpdxInvalidTypeException on invalid type + * Retrieve the size of the collection associated with the specified property descriptor + *

+ * This method calculates the total number of elements in the collection associated with the + * given property descriptor. + * + * @param propertyDescriptor The descriptor for the property. Must not be {@code null}. + * @return The size of the collection. + * @throws SpdxInvalidTypeException If the type is invalid or if the property is not associated + * with a collection. */ @SuppressWarnings("rawtypes") public int collectionSize(PropertyDescriptor propertyDescriptor) throws SpdxInvalidTypeException { @@ -412,7 +419,7 @@ public int collectionSize(PropertyDescriptor propertyDescriptor) throws SpdxInva } if (map instanceof ConcurrentHashMap) { int count = 0; - for (Object value:((ConcurrentHashMap)map).values()) { + for (Object value : ((ConcurrentHashMap) map).values()) { if (value instanceof Collection) { count = count + ((Collection)value).size(); } else { @@ -426,16 +433,17 @@ public int collectionSize(PropertyDescriptor propertyDescriptor) throws SpdxInva } /** - * Check whether the specified value exists in the list associated with the given property descriptor. - * + * Check whether the specified value exists in the collection associated with the given property + * descriptor + *

* This method verifies if the provided value is present in the collection of values associated - * with the specified property descriptor. If the property descriptor is not associated with a list, - * an exception is thrown. - * + * with the specified property descriptor. + * * @param propertyDescriptor The descriptor for the property. Must not be {@code null}. - * @param value The value to be checked. - * @return {@code true} if the value exists in the list associated with the property descriptor; {@code false} otherwise. - * @throws SpdxInvalidTypeException If the property is not associated with a list or if the type is invalid. + * @param value The value to be checked. Must not be {@code null}. + * @return {@code true} if the value exists in the collection; {@code false} otherwise. + * @throws SpdxInvalidTypeException If the type is invalid or if the property is not associated + * with a collection. */ public boolean collectionContains(PropertyDescriptor propertyDescriptor, Object value) throws SpdxInvalidTypeException { @@ -470,12 +478,17 @@ public boolean collectionContains(PropertyDescriptor propertyDescriptor, Object } /** - * @param propertyDescriptor descriptor for the property - * @param clazz class to test against - * @return true if the property with the propertyDescriptor can be assigned to clazz - * @throws ModelRegistryException On registry exception - check that it is initialized + * Check whether all members of the collection associated with the specified property descriptor + * can be assigned to the specified class + * + * @param propertyDescriptor The descriptor for the property. Must not be {@code null}. + * @param clazz The class to test against. Must not be {@code null}. + * @return {@code true} if the property with the {@code propertyDescriptor} can be assigned to + * {@code clazz}; {@code false} otherwise. + * @throws ModelRegistryException If the model registry is not properly initialized. */ - public boolean isCollectionMembersAssignableTo(PropertyDescriptor propertyDescriptor, Class clazz) throws ModelRegistryException { + public boolean isCollectionMembersAssignableTo(PropertyDescriptor propertyDescriptor, + Class clazz) throws ModelRegistryException { Objects.requireNonNull(propertyDescriptor, "Property descriptor can not be null"); Objects.requireNonNull(clazz, "Class can not be null"); Object map = properties.get(propertyDescriptor); @@ -488,8 +501,8 @@ public boolean isCollectionMembersAssignableTo(PropertyDescriptor propertyDescri } @SuppressWarnings("unchecked") ConcurrentHashMap> idValueMap = (ConcurrentHashMap>)map; - for (List valueList:idValueMap.values()) { - for (Object value:valueList) { + for (List valueList : idValueMap.values()) { + for (Object value : valueList) { if (!isAssignableTo(value, clazz, getSpecVersion())) { return false; } @@ -497,15 +510,18 @@ public boolean isCollectionMembersAssignableTo(PropertyDescriptor propertyDescri } return true; } - + /** - * @param value value to test - * @param clazz class to see if the value can be assigned to - * @param specVersion version of the spec - * @return true if value can be assigned to clazz - * @throws ModelRegistryException if the model registry is not property initialized + * Check whether the given value can be assigned to the specified class + * + * @param value The value to test. + * @param clazz The class to check if the value can be assigned to. + * @param specVersion The SPDX specification version to use for type resolution. + * @return {@code true} if the value can be assigned to {@code clazz}; {@code false} otherwise. + * @throws ModelRegistryException If the model registry is not properly initialized. */ - private boolean isAssignableTo(Object value, Class clazz, String specVersion) throws ModelRegistryException { + private boolean isAssignableTo(Object value, Class clazz, String specVersion) + throws ModelRegistryException { if (clazz.isAssignableFrom(value.getClass())) { return true; } @@ -538,15 +554,20 @@ private boolean isAssignableTo(Object value, Class clazz, String specVersion) return false; } } - + /** - * @param propertyDescriptor descriptor for the property - * @param clazz class to test against - * @param specVersion Version of the spec to test for - * @return true if the property can be assigned to type clazz for the latest SPDX spec version - * @throws ModelRegistryException if the registry is not property initialized + * Check whether the value associated with the specified property descriptor can be assigned to + * the specified class + * + * @param propertyDescriptor The descriptor for the property. Must not be {@code null}. + * @param clazz The class to test against. Must not be {@code null}. + * @param specVersion The SPDX specification version to use for type resolution. + * @return {@code true} if the property value can be assigned to type {@code clazz} for the + * latest SPDX spec version; {@code false} otherwise. + * @throws ModelRegistryException If the model registry is not properly initialized. */ - public boolean isPropertyValueAssignableTo(PropertyDescriptor propertyDescriptor, Class clazz, String specVersion) throws ModelRegistryException { + public boolean isPropertyValueAssignableTo(PropertyDescriptor propertyDescriptor, + Class clazz, String specVersion) throws ModelRegistryException { Objects.requireNonNull(propertyDescriptor, "Property descriptor can not be null"); Objects.requireNonNull(clazz, "Class can not be null"); Object value = properties.get(propertyDescriptor); @@ -557,8 +578,11 @@ public boolean isPropertyValueAssignableTo(PropertyDescriptor propertyDescriptor } /** - * @param propertyDescriptor property descriptor - * @return true if there is a list associated with the property descriptor + * Check whether the specified property descriptor is associated with a collection + * + * @param propertyDescriptor The property descriptor to check. Must not be {@code null}. + * @return {@code true} if the property descriptor is associated with a collection; + * {@code false} otherwise. */ public boolean isCollectionProperty(PropertyDescriptor propertyDescriptor) { Objects.requireNonNull(propertyDescriptor, "Property descriptor can not be null"); @@ -567,8 +591,11 @@ public boolean isCollectionProperty(PropertyDescriptor propertyDescriptor) { } /** - * @param elementId objectUri for the element to check - * @return true if an element using the objectUri is used as a value in a collection + * Check whether the specified element ID is used as a value in any collection or property + * + * @param elementId The object URI of the element to check. + * @return {@code true} if the element using the object URI is used as a value in a collection; + * {@code false} otherwise. */ public boolean usesId(String elementId) { if (Objects.isNull(elementId)) {