Merge pull request #216 from jkrae-metaeffekt/issue215

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

Author: goneall

src/main/java/org/spdx/library/model/ModelObject.java

@@ -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.*;
 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;
@@ -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() {

src/main/java/org/spdx/library/model/SpdxDocument.java

@@ -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");
@@ -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");

src/main/java/org/spdx/library/model/license/ExtractedLicenseInfo.java

@@ -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);
@@ -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 {