From dc9ec3980df7c65cae466174a147304de0c87042 Mon Sep 17 00:00:00 2001 From: Arthit Suriyawongkul Date: Sat, 10 May 2025 22:47:08 +0100 Subject: [PATCH 1/3] Javadoc: Add javadoc string to ListedLicenses Signed-off-by: Arthit Suriyawongkul --- .../java/org/spdx/library/ListedLicenses.java | 219 +++++++++++++----- 1 file changed, 163 insertions(+), 56 deletions(-) diff --git a/src/main/java/org/spdx/library/ListedLicenses.java b/src/main/java/org/spdx/library/ListedLicenses.java index 04e8bb82..25de73a1 100644 --- a/src/main/java/org/spdx/library/ListedLicenses.java +++ b/src/main/java/org/spdx/library/ListedLicenses.java @@ -73,7 +73,25 @@ private ListedLicenses() { "false")); initializeLicenseModelStore(); } - + + /** + * Initializes the license model store for managing SPDX listed licenses and + * exceptions + *

+ * This method sets up the appropriate model store based on the configuration. + * If the property + * {@code org.spdx.useJARLicenseInfoOnly} is set to {@code true}, it uses the + * locally cached licenses. + * Otherwise, it attempts to fetch the most current listed licenses from the + * SPDX website. + * If the web store is unavailable, it falls back to the locally cached + * licenses. + *

+ *

+ * This method also initializes the SPDX version 2 and version 3 model stores + * for compatibility. + *

+ */ private void initializeLicenseModelStore() { listedLicenseModificationLock.writeLock().lock(); try { @@ -100,10 +118,18 @@ private void initializeLicenseModelStore() { } } - - + /** + * Retrieve the singleton instance of the {@code ListedLicenses} class + *

+ * This method ensures that only one instance of the {@code ListedLicenses} + * class is created and shared + * throughout the application. If the instance does not already exist, it + * initializes it. + *

+ * + * @return The singleton instance of the {@code ListedLicenses} class. + */ public static ListedLicenses getListedLicenses() { - ListedLicenses retval; listedLicenseModificationLock.readLock().lock(); try { @@ -124,12 +150,15 @@ public static ListedLicenses getListedLicenses() { } return retval; } - + /** - * Resets all of the cached license information and reloads the license IDs - * NOTE: This method should be used with caution, it will negatively impact - * performance. - * @return a new instance of this class + * Reset all cached license information and reload the license IDs + *

+ * NOTE: This method should be used with caution as it can negatively + * impact performance due to the reloading process. + *

+ * + * @return A new instance of the {@code ListedLicenses} class. */ public static ListedLicenses resetListedLicenses() { listedLicenseModificationLock.writeLock().lock(); @@ -140,58 +169,86 @@ public static ListedLicenses resetListedLicenses() { listedLicenseModificationLock.writeLock().unlock(); } } - /** - * @param licenseId case insensitive - * @return true if the licenseId belongs to an SPDX listed license + * Check whether the given license ID belongs to an SPDX listed license + * + * @param licenseId The case-insensitive SPDX license ID. + * @return {@code true} if the license ID belongs to an SPDX listed license, + * {@code false} otherwise. */ public boolean isSpdxListedLicenseId(String licenseId) { return baseModelStore.isSpdxListedLicenseId(SpdxConstantsCompatV2.LISTED_LICENSE_NAMESPACE_PREFIX, licenseId); } - - /** - * @param exceptionId case insensitive - * @return true if the exceptionId belongs to an SPDX listed exception - */ + + /** + * Check whether the given exception ID belongs to an SPDX listed exception + * + * @param exceptionId The case-insensitive SPDX exception ID to check. + * @return {@code true} if the exception ID belongs to an SPDX listed exception, + * {@code false} otherwise. + */ public boolean isSpdxListedExceptionId(String exceptionId) { return this.baseModelStore.isSpdxListedExceptionId(SpdxConstantsCompatV2.LISTED_LICENSE_NAMESPACE_PREFIX, exceptionId); } - + /** - * @param licenseId SPDX Listed License ID - * @return an SPDX spec version 2 SPDX listed license or null if the ID is not in the SPDX license list - * @throws InvalidSPDXAnalysisException on SPDX parsing error + * Retrieve an SPDX listed license by its ID + * for SPDX specification version 2 compatibility + * + * @param licenseId The SPDX Listed License ID. + * @return The SPDX specification version 2 listed license, or {@code null} if + * the ID is not in the SPDX License List. + * @throws InvalidSPDXAnalysisException If an error occurs while retrieving the + * license. */ public SpdxListedLicense getListedLicenseByIdCompatV2(String licenseId) throws InvalidSPDXAnalysisException { return getSpdxListedLicensesCompatV2().get(licenseId); } - + /** - * @param exceptionId SPDX Listed License Exception ID - * @return an SPDX spec version 2 SPDX listed license exception or null if the ID is not in the SPDX license list - * @throws InvalidSPDXAnalysisException on SPDX parsing error + * Retrieve an SPDX listed license exception by its ID + * for SPDX specification version 2 compatibility + * + * @param exceptionId The SPDX Listed License Exception ID. + * @return The SPDX specification version 2 listed license exception, or + * {@code null} if the ID is not in the SPDX License List. + * @throws InvalidSPDXAnalysisException If an error occurs while retrieving the + * exception. */ - public org.spdx.library.model.v2.license.ListedLicenseException getListedExceptionByIdCompatV2(String exceptionId) throws InvalidSPDXAnalysisException { + public org.spdx.library.model.v2.license.ListedLicenseException getListedExceptionByIdCompatV2(String exceptionId) + throws InvalidSPDXAnalysisException { return getSpdxListedLicenseExceptionsCompatV2().get(exceptionId); } - + /** - * @param licenseId SPDX Listed License ID - * @return SPDX listed license or null if the ID is not in the SPDX license list - * @throws InvalidSPDXAnalysisException on SPDX parsing error + * Retrieve an SPDX listed license by its ID + * + * @param licenseId The SPDX Listed License ID. + * @return The SPDX listed license, or {@code null} if not in the SPDX License List. + * @throws InvalidSPDXAnalysisException If an error occurs while retrieving the license. */ public ListedLicense getListedLicenseById(String licenseId) throws InvalidSPDXAnalysisException { return getSpdxListedLicenses().get(licenseId); } - + + /** + * Retrieve an SPDX listed license exception by its ID + * + * @param exceptionId The SPDX Listed License Exception ID. + * @return The SPDX listed license exception, or {@code null} if not in the SPDX + * License List. + * @throws InvalidSPDXAnalysisException If an error occurs while retrieving the + * exception. + */ public ListedLicenseException getListedExceptionById(String exceptionId) throws InvalidSPDXAnalysisException { return getSpdxListedLicenseExceptions().get(exceptionId); - } - + /** - * @return List of all SPDX listed license IDs + * Retrieve a list of all SPDX listed license IDs + * + * @return A list of all SPDX Listed License IDs. */ public List getSpdxListedLicenseIds() { listedLicenseModificationLock.readLock().lock(); @@ -203,8 +260,12 @@ public List getSpdxListedLicenseIds() { } /** - * @return a map of SPDX listed license IDs to the SPDX listed license - * @throws InvalidSPDXAnalysisException on errors fetching the licenses + * Retrieve a map of SPDX Listed License IDs to their SPDX listed licenses + * + * @return A map where the keys are SPDX Listed License IDs and the values are + * {@link ListedLicense} objects. + * @throws InvalidSPDXAnalysisException If an error occurs while fetching the + * licenses. */ public Map getSpdxListedLicenses() throws InvalidSPDXAnalysisException { listedLicenseModificationLock.readLock().lock(); @@ -233,8 +294,13 @@ public Map getSpdxListedLicenses() throws InvalidSPDXAnal } /** - * @return a map of SPDX listed license exception IDs to the SPDX listed license exception - * @throws InvalidSPDXAnalysisException on errors fetching the license exceptions + * Retrieve a map of SPDX Listed License Exception IDs to their SPDX listed + * license exceptions + * + * @return A map where the keys are SPDX Listed License Exception IDs + * and the values are {@link ListedLicenseException} objects. + * @throws InvalidSPDXAnalysisException If an error occurs while fetching the + * license exceptions. */ public Map getSpdxListedLicenseExceptions() throws InvalidSPDXAnalysisException { listedLicenseModificationLock.readLock().lock(); @@ -263,8 +329,13 @@ public Map getSpdxListedLicenseExceptions() thro } /** - * @return a map of SPDX listed license IDs to the SPDX Spec version 2 listed license - * @throws InvalidSPDXAnalysisException on errors fetching the licenses + * Retrieve a map of SPDX Listed License IDs to their SPDX listed licenses + * for SPDX specification version 2 compatibility + * + * @return A map where the keys are SPDX Listed License IDs and the values are + * {@link SpdxListedLicense} (SPDX spec version 2) objects. + * @throws InvalidSPDXAnalysisException If an error occurs while fetching the + * licenses. */ protected Map getSpdxListedLicensesCompatV2() throws InvalidSPDXAnalysisException { listedLicenseModificationLock.readLock().lock(); @@ -294,8 +365,16 @@ protected Map getSpdxListedLicensesCompatV2() throws } /** - * @return a map of SPDX listed license exception IDs to the SPDX listed license exception - * @throws InvalidSPDXAnalysisException on errors fetching the license exceptions + * Retrieve a map of SPDX Listed License Exception IDs to their SPDX listed + * license exceptions + * for SPDX specification version 2 compatibility + * + * @return A map where the keys are SPDX Listed License Exception IDs + * and the values are + * {@link org.spdx.library.model.v2.license.ListedLicenseException} + * (SPDX spec version 2) objects. + * @throws InvalidSPDXAnalysisException If an error occurs while fetching the + * license exceptions. */ protected Map getSpdxListedLicenseExceptionsCompatV2() throws InvalidSPDXAnalysisException { listedLicenseModificationLock.readLock().lock(); @@ -323,55 +402,83 @@ protected Map listedLicenseModificationLock.writeLock().unlock(); } } - + /** - * @return The version of the loaded license list in the form M.N, where M is the major release and N is the minor release. - * If no license list is loaded, returns the default license list version. + * Retrieve the version of the loaded SPDX license list + *

+ * The version is returned in the format "M.N", where M is the major release and N is the minor release. + * If no license list is loaded, this method returns the default license list version. + *

+ * + * @return The version of the loaded SPDX license list, or the default version if no license list is loaded. */ public String getLicenseListVersion() { return this.baseModelStore.getLicenseListVersion(); } /** - * @return list of SPDX exception IDs + * Retrieve a list of all SPDX listed exception IDs + * + * @return A list of SPDX listed exception IDs. */ public List getSpdxListedExceptionIds() { return this.baseModelStore.getSpdxListedExceptionIds(); } /** - * @param licenseId case insensitive license ID - * @return the case sensitive license ID + * Retrieve the case-sensitive SPDX license ID for a given case-insensitive + * license ID + * + * @param licenseId The case-insensitive SPDX license ID to look up. + * @return An {@link Optional} containing the case-sensitive license ID if + * found, or an empty {@link Optional} if not found. */ public Optional listedLicenseIdCaseSensitive(String licenseId) { return this.baseModelStore.listedLicenseIdCaseSensitive(licenseId); } /** - * @param exceptionId case insensitive exception ID - * @return case sensitive ID + * Retrieve the case-sensitive SPDX exception ID for a given case-insensitive + * exception ID + * + * @param exceptionId The case-insensitive SPDX exception ID to look up. + * @return An {@link Optional} containing the case-sensitive exception ID if + * found, or an empty {@link Optional} if not found. */ public Optional listedExceptionIdCaseSensitive(String exceptionId) { return this.baseModelStore.listedExceptionIdCaseSensitive(exceptionId); } - + /** - * @return model store for listed licenses using the version 3 SPDX model + * Retrieve the model store for listed licenses using the SPDX version 3 model + * + * @return The {@link IModelStore} for SPDX version 3 listed licenses and + * exceptions. */ public IModelStore getLicenseModelStore() { return this.licenseStoreV3; } - + + /** + * Retrieve the model store for listed licenses using the SPDX version 2 model + * + * @return The {@link IModelStore} for SPDX version 2 listed licenses and + * exceptions. + */ public IModelStore getLicenseModelStoreCompatV2() { return this.licenseStoreV2; } /** - * @return the CreationInfo used for all SPDX listed licenses and listed exceptions - * @throws InvalidSPDXAnalysisException on error inflating the creation info + * Retrieve the creation information for all SPDX listed licenses and exceptions + * + * @return The {@link CreationInfo} used for all SPDX listed licenses and + * exceptions. + * @throws InvalidSPDXAnalysisException If an error occurs while inflating the + * creation information. */ public CreationInfo getListedLicenseCreationInfo() throws InvalidSPDXAnalysisException { return licenseStoreV3.getListedLicenseCreationInfo(); } -} \ No newline at end of file +} From c904f881e57ac1454d4436254b333fdf561243a7 Mon Sep 17 00:00:00 2001 From: Arthit Suriyawongkul Date: Sat, 10 May 2025 22:56:11 +0100 Subject: [PATCH 2/3] Compact javadoc string Signed-off-by: Arthit Suriyawongkul --- src/main/java/org/spdx/library/ListedLicenses.java | 7 ------- 1 file changed, 7 deletions(-) diff --git a/src/main/java/org/spdx/library/ListedLicenses.java b/src/main/java/org/spdx/library/ListedLicenses.java index 25de73a1..e16a219f 100644 --- a/src/main/java/org/spdx/library/ListedLicenses.java +++ b/src/main/java/org/spdx/library/ListedLicenses.java @@ -79,13 +79,6 @@ private ListedLicenses() { * exceptions *

* This method sets up the appropriate model store based on the configuration. - * If the property - * {@code org.spdx.useJARLicenseInfoOnly} is set to {@code true}, it uses the - * locally cached licenses. - * Otherwise, it attempts to fetch the most current listed licenses from the - * SPDX website. - * If the web store is unavailable, it falls back to the locally cached - * licenses. *

*

* This method also initializes the SPDX version 2 and version 3 model stores From e44d1e5c37429a00143ffb8faa0f07c50126f40e Mon Sep 17 00:00:00 2001 From: Arthit Suriyawongkul Date: Sun, 11 May 2025 02:08:56 +0100 Subject: [PATCH 3/3] Update src/main/java/org/spdx/library/ListedLicenses.java Co-authored-by: Gary O'Neall Signed-off-by: Arthit Suriyawongkul --- src/main/java/org/spdx/library/ListedLicenses.java | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/main/java/org/spdx/library/ListedLicenses.java b/src/main/java/org/spdx/library/ListedLicenses.java index e16a219f..070d0013 100644 --- a/src/main/java/org/spdx/library/ListedLicenses.java +++ b/src/main/java/org/spdx/library/ListedLicenses.java @@ -117,7 +117,7 @@ private void initializeLicenseModelStore() { * This method ensures that only one instance of the {@code ListedLicenses} * class is created and shared * throughout the application. If the instance does not already exist, it - * initializes it. + * is initialized. *

* * @return The singleton instance of the {@code ListedLicenses} class.