Skip to content

Commit 0c34285

Browse files
goneallgoneall
authored
Merge pull request #246 from spdx/v3-prototype
Implementation of SPDX version 3.0.0 spec
2 parents 5cbf5b2 + 7dcec9b commit 0c34285

File tree

219 files changed

+13371
-32877
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

219 files changed

+13371
-32877
lines changed

‎GETTING-STARTED.md‎

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
# Getting Started
2+
3+
## SPDX Version 3
4+
5+
### Programmatically Creating SPDX Data
6+
7+
Before executing any of the model class methods, the model versions need to be intialized. This is done by calling:
8+
9+
```
10+
SpdxModelFactory.init();
11+
```
12+
13+
SPDX data is stored in a "model store" and copying between model stores requires a copy manager.
14+
15+
A simple store is provided in the java library. To create the simple in-memory model store and a copy manager, execute the following:
16+
17+
```
18+
InMemSpdxStore modelStore = new InMemSpdxStore();
19+
IModelCopyManager copyManager = new ModelCopyManager();
20+
```
21+
22+
All SPDX elements are required to have a unique SPDX ID which is an Object URI. In the SPDX Java libraries, this is commonly referred to as the `objectUri` to avoid confusion with the SPDX 2.X version short SPDX IDs.
23+
24+
A good practice is to create a common prefix to use for your programatic session. The prefix should be unique to the session. There are convenience methods in the library to append identifiers uniques to the model store.
25+
26+
In these examples, we'll use:
27+
28+
```
29+
String prefix = "https://org.spdx.spdxdata/899b1918-f72a-4755-9215-6262b3c346df/";
30+
```
31+
32+
Since SPDX 3.0 requires creation info on every element, the easiest way to start is to use the SPDX 3 model convenience method `SpdxModelClassFactory.createCreationInfo(...)` which will create the `Agent` and `CreationInfo` classes which can be added to all of the subsequent elements.
33+
34+
For example:
35+
36+
```
37+
CreationInfo creationInfo = SpdxModelClassFactory.createCreationInfo(
38+
modelStore, prefix + "Agent/Gary01123", "Gary O'Neall",
39+
copyManager);
40+
```
41+
42+
We're now ready to create our first SPDX element. You can start anywhere, but let's start with an SBOM element.
43+
44+
There is a factory method you can use to get started:
45+
46+
```
47+
Sbom sbom = SpdxModelClassFactory.getModelObject(modelStore,
48+
prefix + "sbom/mysbom", SpdxConstantsV3.SOFTWARE_SBOM,
49+
copyManager, true, prefix);
50+
```
51+
52+
Let's not forget to add the creation info:
53+
54+
```
55+
sbom.setCreationInfo(creationInfo);
56+
```
57+
58+
From here on, things get easier. We can get and set properties to the sbom we just created.
59+
60+
If we want to create another SPDX object or element, we can use the builder convenience methods available to all SPDX objects. For example, if we want to create a package to add to the SBOM we can call:
61+
62+
```
63+
sbom.getElements().add(
64+
sbom.createSpdxPackage(prefix + "package/mypackage")
65+
.setName("Package Name")
66+
.build()
67+
);
68+
```
69+
70+
The model store, creation info, copy manager, and prefix information will all be copied from the sbom allowing you to focus just on the properties you need to add.

‎README-V3-UPGRADE.md‎

Lines changed: 78 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,78 @@
1+
# Upgrading from version 2 to version 3
2+
3+
With the support of SPDX 3.0, several changes have been made to the library codebase that will break previous API's.
4+
Although we tried to keep breaking changes to a minimum, some of the changes were necessary due to breaking changes in the spec. itself.
5+
We also took advantage of the changes to fix some annoying design flaws in the previous implementation of the library.
6+
7+
## Classes and Methods moved to SPDX Java Core library
8+
9+
The SPDX Java Core Library is in a separate repository and jar file.
10+
11+
The following classes and methods are moved from `org.spdx.library` to `org.spdx.core`:
12+
13+
- `DefaultModelStore`
14+
- Most exception classes including `InvalidSPDXAnalysisException`
15+
- `ModelCollection`
16+
- `ModelSet`
17+
- `SimpleUriValue`
18+
- `TypedValue`
19+
20+
The packages in `org.spdx.licenseTemplates` are now in the `java-spdx-core` repository.
21+
22+
A new class `LicenseTextHelper` was added and the method `isLicenseTextEquivalent(String, String)` along with many supporting methods were moved to `LicenseTextHelper` from `org.spdx.utility.compare.LicenseCompareHelper`.
23+
24+
## Changes to SPDX version 2 package, class, and method names
25+
To support accessing SPDX 2.X model object while updating the library for SPDX 3.0 support, the package names for the SPDX 2.X model objects are now named `org.spdx.library.model.v2.[package]`.
26+
27+
Many of the class and property names have been changed to append `CompatV2` to clearly designate a compatible object is being referenced.
28+
29+
Also note that the model classes are now stored in a separate repository `spdx-java-model-2_X`.
30+
31+
## Changes to ExternalElement and ExternalExtractedLicenseInfo (SPDX Version 2.X classes)
32+
33+
- Constructors changed to take the document URI for the document containing the external element or license. This is different from the previous constructor which took the document URI of the document containing the reference and an ID of the form `DocumentRef-XX:[ID]` To accomodate compatibility, the constructors
34+
will check for the old DocumentRef format and attempt a conversion.
35+
- Added a method `referenceElementId(SpdxDocument documentReferencingExternal)` which will convert return the `DocumentRef-XX:[ID]`. This should be used in place of the getId which previously returned this format.
36+
37+
Note that this incompatibility was introduced due to using a common mode store API which in some cases will not have the documentUri as a required parameter
38+
39+
## Changes to deserialize interface
40+
Since SPDX documents are not generally required in SPDX spec version 3.0, the SPDX namespace was removed from the return value for deserialized and also removed as a parameter for the serialize method. Serialize will now serialize all objects - which may be multiple SPDX documents.
41+
42+
To find all the SPDX documents in a serialization, you can execute:
43+
44+
```
45+
List<SpdxDocument> docs = (List<SpdxDocument>)SpdxModelFactory.getSpdxObjects(store, null, SpdxConstantsCompatV2.CLASS_SPDX_DOCUMENT, null, null)
46+
.collect(Collectors.toList());
47+
```
48+
after deserialization to get a list of all SPDX documents.
49+
50+
For the RDF store, to keep compatible with the SPDX 2.X requirements, it now only supports a single document namespace.
51+
52+
## Changes to the SPI for the Model Store
53+
54+
### Change propertyName to propertyDescriptor
55+
56+
One significant change to the model store which impacts most of the API's.
57+
All `String` `propertyName` properties are replaced by a `propertyDescriptor` of type `ProperyDescriptor`.
58+
The `PropertyDescriptor` has a `name` property and a `nameSpace` property.
59+
The property constants defined in `org.spdx.library.SpdxConstants` have all been changed to use constant `PropertyDescriptor`s.
60+
If you're using the constants, you may not need to change much beyond the method signatures for anything that was passing along the `propertyName`.
61+
62+
### Make DocumentNamespace Optional
63+
64+
In SPDX 3.0, not all elements are contained within an SPDX document and we can't be guaranteed that a namespace is available for all `TypedValue` typed properties. Methods that are passed a `DocumentNamespace` and an `id` now are passed a URI.
65+
66+
To translate from SPDX 2.X, the `DocumentNamespace` concatenated with the `id` can be used for the URI.
67+
68+
### Change TypedValue structure
69+
70+
`TypedValue` now takes an ObjectURI rather than an ID.
71+
Note that the method signature has not changed, so you may need to manually search for usage in order to change.
72+
There is a convenience helper method `CompatibleModelStoreWrapper.typedValueFromDocUri(String documentUri, String id, boolean anonymous, String type)` that will convert from the SPDX V2 TypedValue to the current version.
73+
74+
### CompatibleModelStoreWrapper
75+
76+
To help with the migration, the `CompatibleModelStoreWrapper` class was introduced supporting the `IModelStore` interface taking a base store as a parameter in the constructor. This class "wraps" the base store and supports the SPDX 2 methods which take the document namespace parameters.
77+
78+
There is also a convenience static method to convert a namespace and ID to an Object URI.

‎README.md‎

Lines changed: 26 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,14 @@ Java library which implements the Java object model for SPDX and provides useful
88

99
| [![Bugs](https://sonarcloud.io/api/project_badges/measure?project=java-spdx-library&metric=bugs)](https://sonarcloud.io/dashboard?id=java-spdx-library) | [![Security Rating](https://sonarcloud.io/api/project_badges/measure?project=java-spdx-library&metric=security_rating)](https://sonarcloud.io/dashboard?id=java-spdx-library) | [![Maintainability Rating](https://sonarcloud.io/api/project_badges/measure?project=java-spdx-library&metric=sqale_rating)](https://sonarcloud.io/dashboard?id=java-spdx-library) | [![Technical Debt](https://sonarcloud.io/api/project_badges/measure?project=java-spdx-library&metric=sqale_index)](https://sonarcloud.io/dashboard?id=java-spdx-library) |
1010

11+
## Library Version Compatibility
12+
13+
Library version 2.0.0 and higher is not compatible with previous versions of the library due to breaking changes introduced in SPDX 3.0.
14+
15+
The library does support the spec versions 2.X and 3.X.
16+
17+
See the [README-V3-UPGRADE.md](README-V3-UPGRADE.md) file for information on how to upgrade from earlier versions of the library.
18+
1119
## Storage Interface
1220
The Spdx-Java-Library allows for different implementations of SPDX object storage. The storage facility implements the org.spdx.storage.IModelStore interface. This is a low level Service Provider Interface (SPI). The ISerializableModelStore extends the IModelStore and supports serializing and de-serializing the store to an I/O Stream. This interface is currently used to implement JSON, XML, YAML, and RDF/XML formats. The default storage interface is an in-memory Map which should be sufficient for light weight usage of the library.
1321

@@ -24,16 +32,17 @@ If you are using Maven, you can add the following dependency in your POM file:
2432
<dependency>
2533
<groupId>org.spdx</groupId>
2634
<artifactId>java-spdx-library</artifactId>
27-
<version>(,1.0]</version>
35+
<version>(,2.0]</version>
2836
</dependency>
2937
```
3038

3139
[API JavaDocs are available here](https://spdx.github.io/Spdx-Java-Library/).
3240

3341
There are a couple of static classes that help common usage scenarios:
3442

35-
- `org.spdx.library.SPDXModelFactory` supports the creation of specific model objects
36-
- `org.spdx.library.model.license.LicenseInfoFactory` supports the parsing of SPDX license expressions, creation, and comparison of SPDX licenses
43+
- org.spdx.library.SpdxModelFactory supports the creation of specific model objects
44+
- org.spdx.library.model.license.LicenseInfoFactory supports the parsing of SPDX license expressions, creation, and comparison of SPDX licenses
45+
3746

3847
## Configuration options
3948

@@ -46,13 +55,21 @@ The library has these configuration options:
4655

4756
Note that these configuration options can only be modified prior to first use of Spdx-Java-Library. Once the library is initialized, subsequent changes will have no effect.
4857

49-
## Update for new properties or classes
58+
The first thing that needs to be done in your implementation is call `SpdxModelFactory.init()` - this will load all the supported versions.
59+
60+
If you are programatically creating SPDX data, you will start by creating a model store. The simplest model store is an in-memory model store which can be created with `store = new InMemSpdxStore()`. A copy manager will be needed if you are working with more than one store (e.g. a serialized format of SPDX data and in memory). If you're not sure, you should just create one. This can be done with `copyManager = new ModelCopyManager()`.
61+
62+
The first object you create will depend on the major version:
63+
- For SPDX 2.X, you would start by creating an SpdxDocument. The factory method `SpdxDocument document = SpdxModelFactory.createSpdxDocumentV2(IModelStore modelStore, String documentUri, IModelCopyManager copyManager)` will create a new SPDX document. Once created, you can use the setters to set the specific fields. You can then use the convenience create methods on the document to create additional SPDX objects (e.g. `document.createSpdxFile(...)`);
64+
- For SPDX 3.X, you will start with a CreationInfo class. The factory method `CreationInfo creationInfo = SpdxModelClassFactory.createCreationInfo(IModelStore modelStore, String createdByUri,String createdByName, @Nullable IModelCopyManager copyManager)` will create and initialize a CreationInfo with today's date and the Agent information. To create any additional objects, you can use the builder convenience methods from the creationInfo (or any Elements created by the creationInfo) (e.g. `creationInfo.createSoftwareSpdxFile(String spdxFileObjectUri)`. The created objects will copy the creationInfo.
65+
66+
## Update for new versions of the spec
5067
To update Spdx-Java-Library, the following is a very brief checklist:
5168

52-
1. Update the SpdxContants with any new or changed properties and classes
53-
2. Update the Java code representing the model
54-
3. Update the SpdxComparer/SpdxFileComparer in the org.spdx.compare package
55-
4. Update unit tests
69+
1. Create a Java .jar file for the new version which contains an implementation of `ISpdxModelInfo` - typically named SpdxModelInfoVXXX - where XXX is the version of the spec.
70+
2. Update the SpdxModelFactory source file to load the model info by adding the line `ModelRegistry.getModelRegistry().registerModel(new SpdxModelInfoVXXX());` in the static block at the very beginning of the class.
71+
3. If there are any conversions that are needed when copying to or from the new model version, add conversion code to the `ModelCopyConverter` class.
72+
4. Update SpdxModelFactory unit test for the highest version check
5673

5774
## Development Status
58-
Note: This library is mostly stable, but and contains some defects. Reviews, suggestions are welcome. Please enter an issue with any suggestions.
75+
Note: This library is currently unstable, and under development. Reviews, suggestions are welcome. Please enter an issue with any suggestions.

‎pom.xml‎

Lines changed: 63 additions & 58 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,9 @@
11
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
22
<modelVersion>4.0.0</modelVersion>
3-
4-
<groupId>org.spdx</groupId>
5-
<artifactId>java-spdx-library</artifactId>
6-
<version>1.1.13-SNAPSHOT</version>
7-
<packaging>jar</packaging>
8-
3+
<groupId>org.spdx</groupId>
4+
<artifactId>java-spdx-library</artifactId>
5+
<version>2.0.0-SNAPSHOT</version>
6+
<packaging>jar</packaging>
97
<name>java-spdx-library</name>
108
<url>https://github.com/spdx/Spdx-Java-Library</url>
119
<licenses>
@@ -69,15 +67,6 @@
6967
</dependency>
7068
</dependencies>
7169
</profile>
72-
<profile>
73-
<id>doclint-java8-disable</id>
74-
<activation>
75-
<jdk>[1.8,)</jdk>
76-
</activation>
77-
<properties>
78-
<javadoc.opts>-Xdoclint:none</javadoc.opts>
79-
</properties>
80-
</profile>
8170
<profile>
8271
<id>release</id>
8372
<build>
@@ -118,48 +107,63 @@
118107
</build>
119108
</profile>
120109
</profiles>
121-
<dependencies>
122-
<dependency>
123-
<groupId>junit</groupId>
124-
<artifactId>junit</artifactId>
125-
<version>4.13.1</version>
126-
<scope>test</scope>
127-
</dependency>
128-
<dependency>
129-
<groupId>org.slf4j</groupId>
130-
<artifactId>slf4j-api</artifactId>
131-
<version>2.0.7</version>
132-
</dependency>
133-
<dependency>
134-
<groupId>org.apache.commons</groupId>
135-
<artifactId>commons-lang3</artifactId>
136-
<version>3.5</version>
137-
</dependency>
138-
<dependency>
139-
<groupId>org.jsoup</groupId>
140-
<artifactId>jsoup</artifactId>
141-
<version>1.15.3</version>
142-
</dependency>
143-
<dependency>
144-
<groupId>com.google.code.gson</groupId>
145-
<artifactId>gson</artifactId>
146-
<version>2.8.9</version>
147-
</dependency>
148-
<dependency>
149-
<groupId>net.jodah</groupId>
150-
<artifactId>concurrentunit</artifactId>
151-
<version>0.4.6</version>
152-
<scope>test</scope>
153-
</dependency>
154-
<dependency>
155-
<groupId>com.google.code.findbugs</groupId>
156-
<artifactId>jsr305</artifactId>
157-
<version>3.0.2</version>
158-
</dependency>
159-
</dependencies>
160-
161-
<build>
162-
<resources>
110+
<dependencies>
111+
<dependency>
112+
<groupId>junit</groupId>
113+
<artifactId>junit</artifactId>
114+
<version>4.13.1</version>
115+
<scope>test</scope>
116+
</dependency>
117+
<dependency>
118+
<groupId>org.slf4j</groupId>
119+
<artifactId>slf4j-api</artifactId>
120+
<version>2.0.7</version>
121+
</dependency>
122+
<dependency>
123+
<groupId>org.apache.commons</groupId>
124+
<artifactId>commons-lang3</artifactId>
125+
<version>3.5</version>
126+
</dependency>
127+
<dependency>
128+
<groupId>org.jsoup</groupId>
129+
<artifactId>jsoup</artifactId>
130+
<version>1.15.3</version>
131+
</dependency>
132+
<dependency>
133+
<groupId>com.google.code.gson</groupId>
134+
<artifactId>gson</artifactId>
135+
<version>2.8.9</version>
136+
</dependency>
137+
<dependency>
138+
<groupId>net.jodah</groupId>
139+
<artifactId>concurrentunit</artifactId>
140+
<version>0.4.6</version>
141+
<scope>test</scope>
142+
</dependency>
143+
<dependency>
144+
<groupId>com.google.code.findbugs</groupId>
145+
<artifactId>jsr305</artifactId>
146+
<version>3.0.2</version>
147+
</dependency>
148+
<dependency>
149+
<groupId>org.spdx</groupId>
150+
<artifactId>spdx-java-model-2_X</artifactId>
151+
<version>0.1.0-Alpha</version>
152+
</dependency>
153+
<dependency>
154+
<groupId>org.spdx</groupId>
155+
<artifactId>spdx-java-core</artifactId>
156+
<version>0.1.0-Alpha</version>
157+
</dependency>
158+
<dependency>
159+
<groupId>org.spdx</groupId>
160+
<artifactId>spdx-java-model-3_0</artifactId>
161+
<version>0.1.0-Alpha</version>
162+
</dependency>
163+
</dependencies>
164+
165+
<build>
166+
<resources>
163167
<resource>
164168
<targetPath>resources</targetPath>
165169
<filtering>false</filtering>
@@ -183,6 +187,7 @@
183187
</excludes>
184188
</resource>
185189
</resources>
190+
<sourceDirectory>src/main/java</sourceDirectory>
186191
<testResources>
187192
<testResource>
188193
<directory>src/test</directory>
@@ -223,7 +228,7 @@
223228
<configuration>
224229
<quiet>true</quiet>
225230
<notimestamp>true</notimestamp>
226-
<additionalparam>-Xdoclint:none</additionalparam>
231+
<doclint>all,-missing</doclint>
227232
</configuration>
228233
<executions>
229234
<execution>

‎resources/listedexternaltypes/listedreferencetypes.properties‎

Lines changed: 0 additions & 4 deletions
This file was deleted.

0 commit comments

Comments
 (0)