Skip to content

A canonical way to create ExtractedLicenseInfo (Helper method and documentation, Issue #215) #216

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Nov 24, 2023
Merged

A canonical way to create ExtractedLicenseInfo (Helper method and documentation, Issue #215) #216

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
2048e75
add helper method in ModelObject to create ExtractedLicenseInfo corre…
jkrae-metaeffekt Nov 10, 2023
fbfd9ac
improve documentation surrounding ExtractedLicenseInfo use and creation
jkrae-metaeffekt Nov 10, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 19 additions & 6 deletions src/main/java/org/spdx/library/model/ModelObject.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -40,13 +40,8 @@
import org.spdx.library.model.enumerations.ReferenceCategory;
import org.spdx.library.model.enumerations.RelationshipType;
import org.spdx.library.model.enumerations.SpdxEnumFactory;
import org.spdx.library.model.license.AnyLicenseInfo;
import org.spdx.library.model.license.ConjunctiveLicenseSet;
import org.spdx.library.model.license.*;
Copy link
Collaborator

@pmonks pmonks Nov 10, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Based on the existing codebase, I think @goneall prefers explicit imports, rather than wildcard imports. FWIW I'd be in favour of using wildcard imports though, if he's open to that.

Copy link
Contributor Author

@jkrae-metaeffekt jkrae-metaeffekt Nov 13, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fair point about keeping style with the imports. Do you reckon I should just change history and force-push this fix?

Copy link
Member

@goneall goneall Nov 24, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm OK with the wildcards and the minor style inconsistency in using a mix of specific imports and wildcard. I have my IDE set to generate the specific imports - mainly to avoid possible conflicts but in this case the public classes shouldn't create any conflicts.

import org.spdx.library.model.license.CrossRef.CrossRefBuilder;
import org.spdx.library.model.license.DisjunctiveLicenseSet;
import org.spdx.library.model.license.ListedLicenses;
import org.spdx.library.model.license.SpdxNoAssertionLicense;
import org.spdx.library.model.license.SpdxNoneLicense;
import org.spdx.library.model.pointer.ByteOffsetPointer;
import org.spdx.library.model.pointer.LineCharPointer;
import org.spdx.library.model.pointer.SinglePointer;
Expand Down Expand Up @@ -1418,6 +1413,24 @@ public CrossRefBuilder createCrossRef(String url) throws InvalidSPDXAnalysisExce
return new CrossRefBuilder(this.modelStore, this.documentUri,
this.modelStore.getNextId(IdType.Anonymous, this.documentUri), this.copyManager, url);
}

/**
* Constructs {@link ExtractedLicenseInfo} with text set.
*
* <p> Note that object construction has side-effects relating to a document and modelStore,
* requiring document context.
* This may bind usage of {@link ExtractedLicenseInfo} instances to the document that they were created by!
*
* @param id id that the text relates to
* @param text license text corresponding to the id
* @return returns a constructed object
* @throws InvalidSPDXAnalysisException
*/
public ExtractedLicenseInfo createExtractedLicense(String id, String text) throws InvalidSPDXAnalysisException {
ExtractedLicenseInfo eli = new ExtractedLicenseInfo(modelStore, documentUri, id, copyManager, true);
eli.setExtractedText(text);
return eli;
}

@Override
public String toString() {
Expand Down
17 changes: 11 additions & 6 deletions src/main/java/org/spdx/library/model/SpdxDocument.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -184,11 +184,15 @@ public Collection<ExternalDocumentRef> getExternalDocumentRefs() throws InvalidS
public Collection<ExtractedLicenseInfo> getExtractedLicenseInfos() throws InvalidSPDXAnalysisException {
return this.extractedLicenseInfos;
}

/**
* Add a license info to the collection of extracted license infos
* @param licenseInfo
* @return
* Add a license info to the collection of extracted license infos.
*
* <p> Useful for adding license texts for licenseRefs.
*
* @param licenseInfo object containing license information
* @return true if the underlying collection changed due to this call
* @see SpdxDocument#createExtractedLicense(String, String)
*/
public boolean addExtractedLicenseInfos(ExtractedLicenseInfo licenseInfo) {
Objects.requireNonNull(licenseInfo, "License info can not be null");
Expand All @@ -197,8 +201,9 @@ public boolean addExtractedLicenseInfos(ExtractedLicenseInfo licenseInfo) {

/**
* Clear the extractedLicenseInfos and add all elements from extractedLicenseInfos
* @param extractedLicenseInfos
* @return this to enable chaining of sets
*
* @param extractedLicenseInfos the new list of license infos
* @return this to enable chaining of setter calls
*/
public SpdxDocument setExtractedLicenseInfos(List<ExtractedLicenseInfo> extractedLicenseInfos) {
Objects.requireNonNull(extractedLicenseInfos, "Extracted license infos can not be null");
Expand Down
61 changes: 50 additions & 11 deletions src/main/java/org/spdx/library/model/license/ExtractedLicenseInfo.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -44,35 +44,72 @@
*
*/
public class ExtractedLicenseInfo extends AbstractExtractedLicenseInfo {


/**
* Create a new ExtractedLicenseInfo object
*
* <p> Users of the library should not call this constructor directly but use
* {@link org.spdx.library.model.SpdxDocument#createExtractedLicense SpdxDocument#createExtractedLicense}.
* This ensures correct behaviour between that document and its {@link ExtractedLicenseInfo} instance.
*
* <p> Otherwise, the object may misbehave, such as with
* {@link org.spdx.library.model.SpdxDocument#addExtractedLicenseInfos SpdxDocument#addExtractedLicenseInfos}.
*
* @throws InvalidSPDXAnalysisException
*/
public ExtractedLicenseInfo() throws InvalidSPDXAnalysisException {
super(DefaultModelStore.getDefaultModelStore().getNextId(IdType.LicenseRef, DefaultModelStore.getDefaultDocumentUri()));
}


/**
* Create a new ExtractedLicenseInfo object
*
* <p> Users of the library should not call this constructor directly but use
* {@link org.spdx.library.model.SpdxDocument#createExtractedLicense SpdxDocument#createExtractedLicense}.
* This ensures correct behaviour between that document and its {@link ExtractedLicenseInfo} instance.
*
* <p> Otherwise, the object may misbehave, such as with
* {@link org.spdx.library.model.SpdxDocument#addExtractedLicenseInfos SpdxDocument#addExtractedLicenseInfos}.
*
* @param id identifier for the license
* @throws InvalidSPDXAnalysisException
*/
public ExtractedLicenseInfo(String id) throws InvalidSPDXAnalysisException {
super(id);
}

/**
* Create a new ExtractedLicenseInfo object
* @param modelStore container which includes the license
*
* <p> Users of the library should prefer
* {@link org.spdx.library.model.SpdxDocument#createExtractedLicense SpdxDocument#createExtractedLicense}.
*
* @param modelStore container which includes the license
* @param documentUri URI for the SPDX document containing the license
* @param id identifier for the license
* @param id identifier for the license
* @param copyManager if non-null, allows for copying of any properties set which use other model stores or document URI's
* @param create if true, create the license if it does not exist
* @throws InvalidSPDXAnalysisException
* @param create if true, create the license if it does not exist
* @throws InvalidSPDXAnalysisException
*/
public ExtractedLicenseInfo(IModelStore modelStore, String documentUri, String id,
@Nullable ModelCopyManager copyManager, boolean create)
throws InvalidSPDXAnalysisException {
super(modelStore, documentUri, id, copyManager, create);
}

/**
* Create a new ExtractedLicenseInfo using the ID and text
* @param id
* @param text
* @throws InvalidSPDXAnalysisException
*
* <p> Users of the library should not call this constructor directly but use
* {@link org.spdx.library.model.SpdxDocument#createExtractedLicense SpdxDocument#createExtractedLicense}.
* This ensures correct behaviour between that document and its {@link ExtractedLicenseInfo} instance.
*
* <p> Otherwise, the object may misbehave, such as with
* {@link org.spdx.library.model.SpdxDocument#addExtractedLicenseInfos SpdxDocument#addExtractedLicenseInfos}.
*
* @param id identifier for the license
* @param text text to associate with the license
* @throws InvalidSPDXAnalysisException
*/
public ExtractedLicenseInfo(String id, String text) throws InvalidSPDXAnalysisException {
super(id);
Expand Down Expand Up @@ -101,7 +138,9 @@ public String getExtractedText() throws InvalidSPDXAnalysisException {
}

/**
* @param text the text to set
* Sets the license text.
* <p> Affects both this object and the underlying store.
* @param text text to associate with the license
* @throws InvalidSPDXAnalysisException
*/
public void setExtractedText(String text) throws InvalidSPDXAnalysisException {
Expand Down