Skip to content
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

Bulletizes README #267

Merged
merged 1 commit into from
Dec 22, 2024
Merged

Bulletizes README #267

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
87 changes: 69 additions & 18 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,9 +5,15 @@

Java library which implements the Java object model for SPDX and provides useful helper functions.

The API documentation is available at:
<https://spdx.github.io/Spdx-Java-Library/>

## Code quality badges

| [![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) |
[![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)

## Library Version Compatibility

Expand All @@ -19,17 +25,44 @@ See the [README-V3-UPGRADE.md](README-V3-UPGRADE.md) file for information on how

## Storage Interface

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.

Most common use of the library would de-serialize an existing SPDX document using one of the supported formats and model stores. To create SPDX objects from scratch, simply create the Java objects found in the org.spdx.library.model package. The model follows the [SPDX Object Model](https://github.com/spdx/spdx-spec/blob/2a7aff7afa089a774916bd5c64fc2cb83637ea07/model/SPDX-UML-Class-Diagram.jpg). The model objects themselves are stateless and do not store information. All information is retrieved from the model store when properties are access. Storage to the classes will store the updates through the use of the storage interface.
- 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.

### Storage Interface Usage

- Most common use of the library would de-serialize an existing SPDX document
using one of the supported formats and model stores.
- To create SPDX objects from scratch, simply create the Java objects found in
the `org.spdx.library.model` package.
- The model follows the [SPDX Object Model][spdx-object-model].
- The model objects themselves are stateless and do not store information.
- All information is retrieved from the model store when properties are access.
- Storage to the classes will store the updates through the use of the storage
interface.

[spdx-object-model]: https://github.com/spdx/spdx-spec/blob/2a7aff7afa089a774916bd5c64fc2cb83637ea07/model/SPDX-UML-Class-Diagram.jpg

## Multi-Threaded Considerations

The methods enterCriticalSection and leaveCriticalSection are available to support multi-threaded applications. These methods serialize access to the model store for the specific SPDX document used for the SPDX model object.
The methods `enterCriticalSection` and `leaveCriticalSection` are available to
support multi-threaded applications.

These methods serialize access to the model store for the specific SPDX
document used for the SPDX model object.

## Getting Started

The library is available in [Maven Central org.spdx:java-spdx-library](https://search.maven.org/artifact/org.spdx/java-spdx-library).
The library is available in Maven Central as
[`org.spdx:java-spdx-library`](https://search.maven.org/artifact/org.spdx/java-spdx-library)
(note the order of the word "java-spdx").

If you are using Maven, you can add the following dependency in your POM file:

Expand All @@ -41,12 +74,15 @@ If you are using Maven, you can add the following dependency in your POM file:
</dependency>
```

[API JavaDocs are available here](https://spdx.github.io/Spdx-Java-Library/).
The API documentation is available at:
<https://spdx.github.io/Spdx-Java-Library/>

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

- org.spdx.library.SpdxModelFactory supports the creation of specific model objects
- org.spdx.library.model.license.LicenseInfoFactory supports the parsing of SPDX license expressions, creation, and comparison of SPDX licenses
- `org.spdx.library.SpdxModelFactory` supports the creation of specific
model objects
- `org.spdx.library.model.license.LicenseInfoFactory` supports the parsing of
SPDX license expressions, creation, and comparison of SPDX licenses

## Configuration options

Expand All @@ -58,26 +94,41 @@ The library has these configuration options:
2. `org.spdx.downloadCacheEnabled` - a boolean that enables or disables the download cache. Defaults to `false` (the cache is disabled). The cache location is determined as per the [XDG Base Directory Specification](https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html) (i.e. `${XDG_CACHE_HOME}/Spdx-Java-Library` or `${HOME}/.cache/Spdx-Java-Library`).
3. `org.spdx.downloadCacheCheckIntervalSecs` - a long that controls how often each cache entry is rechecked for staleness, in units of seconds. Defaults to 86,400 seconds (24 hours). Set to 0 (zero) to have each cache entry checked every time (note: this will result in a lot more network I/O and negatively impact performance, albeit there is still a substantial performance saving vs not using the cache at all).

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.
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.*

## Initialization

The first thing that needs to be done in your implementation is call `SpdxModelFactory.init()` - this will load all the supported versions.

If you are programmatically 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()`.
If you are programmatically 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()`.

The first object you create will depend on the major version:

- 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(...)`);
- 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.
- 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(...)`);
- 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.

## Update for new versions of the spec

To update Spdx-Java-Library, the following is a very brief checklist:

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.
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.
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.
4. Update SpdxModelFactory unit test for the highest version check
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.
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.
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.
4. Update SpdxModelFactory unit test for the highest version check

## Development Status

Note: This library is currently unstable, and under development. Reviews, suggestions are welcome. Please enter an issue with any suggestions.
Note: This library is currently unstable, and under development.
Reviews, suggestions are welcome.
Please enter an issue with any suggestions.
Loading