Multithreading with the Java API

When using the Java API with multiple threads, you should take care to follow the guidelines in this document to help you produce reliable, bug-free programs.

The golden rule of multithreading with the Java API is to make sure that you do not access a DocumentComparator, PipelinedComparatorS9 or DataComparator instance nor their configuration objects from multiple threads at the same time.

If you are using input multithreading (which you are by default unless you have explicitly turned it off) you should also take care to follow the guidelines in the input multithreading guide.

Guidelines for multithreading with the Java API

In the following list of guidelines “comparator” refers to either DocumentComparator, PipelinedComparatorS9 or DataComparator

• You should not share a net.sf.saxon.s9api.Processor between multiple comparator objects.

• You should not interact with a comparator instance from multiple threads simultaneously. This includes any

  • comparator configuration objects such as those from https://apidocs.deltaxml.com/xml-compare/current/docs/api/com/deltaxml/cores9api/config/package-summary.html.

• You should not share pipeline configuration objects between comparators or interact with them from multiple threads simultaneously.

  • Pipeline configuration objects are https://apidocs.deltaxml.com/xml-compare/current/docs/api/com/deltaxml/cores9api/FilterStep.html, https://apidocs.deltaxml.com/xml-compare/current/docs/api/com/deltaxml/cores9api/FilterChain.html and https://apidocs.deltaxml.com/xml-compare/current/docs/api/com/deltaxml/cores9api/FilterStepHelper.html

  • This means that if you wish to have the same input pipeline for multiple comparators, you must create two distinct copies of the input pipeline that do not reference each other.

• If you use the underlying Saxon API, you should make sure to follow Saxon’s rules for multithreading which are detailed throughout their documentation.

• If you share Saxon objects across multiple comparators and then run those comparators from multiple threads simultaneously any behaviour is undefined.

Currently comparator instances may use ‘live references’ to comparator configuration and pipeline configuration objects and so altering the state of one of those objects which is shared between comparators will lead to undefined behaviour if done concurrently.