Add examples

[goneall]

It would help first time users to create some examples for common library usage.

Some ideas for different examples:

• Creating a document, adding a few files using the SPDX Model Factory
• Parsing license expressions using the SPDX license parser
• Comparing SPDX documents using the SPDX Document Comparer

[goneall]

If anyone would like to take just one of these issues, add a comment here as to which example you are adding and create a Pull Request with the example implementation.

[AnishaSrivastava1411]

I am on it.

[AnishaSrivastava1411]

Hi @goneall,
Please guide me how should to start contributing from the git branch.
I am taking third, SPDX Document Comparer to implement.

[goneall]

@AnishaSrivastava1411 Thanks for taking this on - I would clone this repo to your local repo. Make the changes there, then create a pull request. See the CONTRIBUTING.md file for more info. If the Contributing file isn't clear, feel free to open an issue with any suggestions.

[goneall]

One more helpful tip on creating the examples - I am currently porting the old spdx tools over to use this new library. The code may provide some ideas for creating the examples. Since it is under development, it is in my personal repo at https://github.com/goneall/Spdx-Tools-Java.

Once it is stable enough, I'll move it to the SPDX repo.

[stevespringett]

Is it possible to parse an SPDX document and create an object model from it?

I'm looking for a lightweight alternative to SPDX Tools to do this as SPDX Tools has too many dependencies for my liking - many of which are brought in through various command line options or through RDF support.

If and when possible, it would be great to get an example of how to do it with this library.

[goneall]

Is it possible to parse an SPDX document and create an object model from it?

@stevespringett This is a primary objective for this library. It is a redesign of the original SPDX libraries intended to reduce the dependencies to a minimum and refactor the code into a number of separate java libraries.

You can find an implementation of XML, JSON, and YAML SPDX parsers in my personal repo at https://github.com/goneall/Spdx-Java-Json-Store - once it is more tested and stable, I plan to transfer it to SPDX. Review, comments, and contributions welcome.

You can find an RDF/XML parser at https://github.com/goneall/Spdx-Java-Json-Store.

[stevespringett]

Fantastic Gary. I'll be checking it out in the next few weeks.

[rpavlik]

For what it's worth, I recently pushed a little app I hacked together (in Kotlin) to parse a tag-value formatted SPDX file and extract filenames whose license data matched a predicate of interest. Worked pretty well once I found the entry points I wanted. Even works with graalvm "native-image" for building a native binary rather than a jar that needs a JRE. https://github.com/rpavlik/khronos-dual-license-finder

[rremer]

Will be using this library soon and can document a few flows. You want me to put some markdown in src/site and configure the maven-site-plugin against github pages, or how are we publishing documentation?

[goneall]

You want me to put some markdown in src/site and configure the maven-site-plugin against github pages, or how are we publishing documentation?

@rremer adding to src/site with the maven-site-plugin sounds good - thanks!

[Mariuxdeangelo]

Hey, sorry for possibly asking stupid questions. I'm not really sure if this is still an active issue, but I'm currently trying to read some SPDX JSON files and wanted to use this library. However, it seems that the object 'SpdxDocument' doesn't contain a 'SpdxPackage' or any sort of list or collection. Unfortunately, there isn't much documentation or examples available. Maybe someone here could give me a hint?

For a simple snipped how i read the file:

    private void readSpdxFile(File file) throws InvalidSPDXAnalysisException, IOException, SpdxCompareException {
        MultiFormatStore inputStore = new MultiFormatStore(new InMemSpdxStore(), MultiFormatStore.Format.JSON);

        try (InputStream input = new FileInputStream(file)) {
            inputStore.deSerialize(input, false);
        }

        String documentUri = inputStore.getDocumentUris().get(0);
        SpdxDocument inputDocument = new SpdxDocument(inputStore, documentUri, null, false);
        System.out.println(inputDocument.getCreationInfo().getCreated());
        
//        inputDocument.getPackages();  // Would expect something like this. 

        Iterator<SpdxElement> spdxElementIterator = inputDocument.getDocumentDescribes().iterator();
        while (spdxElementIterator.hasNext()) {
            System.out.println(spdxElementIterator.next().getName());
        }
    }

[goneall]

@Mariuxdeangelo - very reasonable question.

The SPDX 2.X model doesn't have packages as a direct property of the SPDX Document. It is more of a graph of SPDX Elements. The SPDX Element may be of type SpdxPackage, SpdxFile, or SpdxSnippet.

The code while (spdxElementIterator.hasNext()) { ... will iterate through the roots of the SPDX Document, but won't do the entire graph. If you want to produce the entire graph, you can follow the relationships in the root elements.

However, there are some helper methods that can retrieve all of the elements of a specific type from the document giving you something similar to inputDocument.getPackages();:

Spdx-Java-Library/src/main/java/org/spdx/library/model/SpdxModelFactory.java

Line 248 in 96bdc3a

public static Stream<?> getElements(IModelStore store, String documentUri, ModelCopyManager copyManager,

Here's an example of it's use from the compare utility code:

	protected List<SpdxPackage> collectAllPackages(SpdxDocument spdxDocument) throws InvalidSPDXAnalysisException {
		Stream<SpdxPackage> packageStream = (Stream<SpdxPackage>) SpdxModelFactory.getElements(
                spdxDocument.getModelStore(), spdxDocument.getDocumentUri(), 
                null, SpdxPackage.class);	
	    List<SpdxPackage> retval = packageStream.collect(Collectors.toList());
	    packageStream.close();
	    return retval;
	}

Feel free to post any additional questions. Once we have a volunteer to code up some examples, it will make a good guide.