Creating a new SPDX from Java

[maxbrito500]

Hello,

On the previous code version was possible to call "SPDXDocument" and create a new SPDX doc from scratch.

On the current releases this class is no longer present, I'm only seeing code for directly converting from one format to another but without any mechanism to create them from scratch.

Is this correct and intentional? If not, how would go about to create a new package and fill it up with information?

Thanks.

[goneall]

@maxbrito500 The interface for creating documents has changed from the SPDX tools version, but it is still supported.

Most of the interfaces are in the SPDX Java Library.

The closest interface to SPDXDocument is the SpdxModelFactory.createSpdxDocument. For the modelStore parameter, you can pass in the defaultModelStore. You can pass in null for the copyManager parameter, unless you are copying objects from one store to another - in which case you can just create a new ModelCopyManager.

There are several other interfaces and ways to create and populate SpdxDocuments - best starting point is the SpdxModelFactory if you want to explore more.

[maxbrito500]

Hello Gary, thank you for the detailed explanation.

I've went throught the mentioned classes, installed the packages and started to use the code. Unfortunately the code base is confusing and over-complicated. Despite almost 20 years of programming, 12 of those in Java I'm still not understanding why such a complicated implementation.

Getting the package builder to create the initial document had to be asked through this ticket since it was wrongly documented. After struggle, I've began adding the per-package information but when wanting to output this data to a tag/value or XML document then how to proceed? Again stopped.

I've looked over the past days on different code portions how this was being handled, just to find counter-intuitive class names. For example a class named "Read" is used for the action of writing: https://github.com/spdx/Spdx-Java-Library/blob/master/src/main/java/org/spdx/library/Read.java#L124 and then alas, is used a class named "Write" for the act of reading files: https://github.com/spdx/Spdx-Java-Library/blob/master/src/main/java/org/spdx/library/Write.java#L97

I'm left wondering how many projects you find with such reversed names for read/write operations, and yet this is the only such project I've ever found like this. It's been several days going through the code. I know this is open source, that I can submit improvements but seriously doubt at this point that it is worth doing it.

Before this activity I've implemented CycloneDX output and it literally needed only 10 minutes to have it working. From the main repo there is a test unit showing clearly how to get this working: https://github.com/CycloneDX/cyclonedx-core-java/blob/master/src/test/java/org/cyclonedx/BomJsonGeneratorTest.java and worked right on the first try.

For the sake of SPDX, please consider decomplicating this experience for java developers. An example for writing SPDX documents is an essential functionality and this should be obvious without apologies, we (developers) just need simple examples that work.

Thanks.

[goneall]

@maxbrito500 Sorry to hear you are finding it this difficult to get started.

This could definitely use better documentation. I would propose adding an examples folder with a few use cases implemented and a "getting started" section in the README file.

I'll add a CreatingSpdxDocument.java file in a separate PR.

[goneall]

@maxbrito500 I added an example in PR #42

Please review and let me know if this is what you are looking for.

If you see an opportunity to improve the documentation, feel free to create a PR against the addexample branch.

[maxbrito500]

Gary, thank you for the quick reaction.

That example file made a huge difference. Well explained on each step, and working right out of the box.

Truly appreciated, thanks.

[goneall]

@maxbrito500 Glad to hear the examples helped.

I've merged in the PR and I'll close this issue as resolved.

If you see any other opportunity for better documentation or other issues, please feel free to created another issue or pull request.