Project

Profile

Help

Bug #5493

closed

Problems with transform result output.resultDocuments

Added by Debbie Lockett over 2 years ago. Updated about 2 years ago.

Status:
Closed
Priority:
High
Category:
API
Sprint/Milestone:
Start date:
2022-05-17
Due date:
% Done:

100%

Estimated time:
Applies to JS Branch:
2, Trunk
Fix Committed on JS Branch:
2, Trunk
Fixed in JS Release:
SEF Generated with:
Platforms:
Company:
-
Contact person:
-
Additional contact persons:
-

Description

As raised by Martin in the forum (see resultDocuments property of transform call result not pop...), the transform results object resultDocuments property is not being populated as intended when deliverResultDocument requests the destination to be serialized.

There is some confusion in the documentation as to whether the transform options properties destination and resultForm affect secondary result documents, or just the principal result document. The destination info at https://www.saxonica.com/saxon-js/documentation2/index.html#!api/transform says it "Determines what happens to the principal result tree from the transformation" and does not mention secondary results (except for updating the HTML page in the browser); and it is clear that deliverResultDocument determines what happens to secondary results, with its own destination defined in the function return object. However https://www.saxonica.com/saxon-js/documentation2/index.html#!api/transform/results says:

As with the principal result document, the way in which secondary result documents are returned is determined by the options supplied to the transformation, in particular options.destination and options.resultForm

I think this statement is wrong for destination, I'm not sure about resultForm.

So when deliverResultDocument is not supplied, I don't think options.destination has any influence for the secondary results, and the default action in Node.js is to write to file. See the documentation for deliverResultDocument:

In the absence of the deliverResultDocument option, SaxonJS effectively uses a default in which:

  • destination is "html-page" if running in the browser, or "file" in Node.js;
  • save places the value in output.resultDocuments[URI], unless destination="file", in which case the value is written to filestore.

But it should be possible to supply a function for deliverResultDocument which returns an object with "destination" : "serialized", and no save property; to request that the secondary result documents should populate output.resultDocuments (by the default save function); but this currently fails.

Actions #2

Updated by Debbie Lockett over 2 years ago

  • Status changed from New to In Progress
  • Fix Committed on JS Branch 2, Trunk added

Added nodejs unit tests saxonapi async-trans-031 and async-trans-032.

Code fixes committed on saxonjs2 and main branches, to use default save function which saves to output.resultDocuments when the deliverResultDocument function specifies destination is serialized, raw or document, but no save function is supplied.

Still to do: improve documentation - clarify as necessary, and add some examples. It would also be good to add more deliverResultDocument tests, since we only have a couple.

Actions #3

Updated by Debbie Lockett over 2 years ago

I've added/reinstated some nodejs unit tests (saxonapi sync-trans-021, sync-trans-031 and sync-trans-032) to test synchronous transforms with secondary result documents. Note that a synchronous transform returns when the principal result has been produced, but secondary results may still be being written (as documented at https://www.saxonica.com/saxon-js/documentation2/index.html#!api/transform/execution). So it is necessary to use a timeout before checking these.

Actions #4

Updated by Debbie Lockett over 2 years ago

I'm moving the "Writing to ..." processing message for secondary results which is currently output when the destination is "file" or "serialized". If the deliverResultDocument save function is not writing to file store, I find this message confusing. So I'm moving it to the actual save methods which do save to file store (the message is "Promising to write to ..." for asynchronous transforms, and "Writing to ..." for synchronous). Plus updating relevant unit tests accordingly.

Actions #5

Updated by Debbie Lockett over 2 years ago

I've added nodejs unit tests for destination document. Currently this returns each secondary result document wrapped in an array (the result sequence from the builder), rather than just the document node directly. So that should be fixed.

For secondary results, destination raw is documented but not implemented. I'm going to remove it from the documentation.

Actions #6

Updated by Norm Tovey-Walsh over 2 years ago

  • Priority changed from Normal to High
  • Sprint/Milestone set to SaxonJS 3.0
Actions #7

Updated by Debbie Lockett over 2 years ago

Destination raw is now implemented for secondary results, and the documentation has been reinstated. xslt30 test transform-008 expects to use "raw" destination for result documents; this test is now passing.

Actions #8

Updated by Norm Tovey-Walsh about 2 years ago

  • Sprint/Milestone changed from SaxonJS 3.0 to SaxonJS 2.5
Actions #9

Updated by Debbie Lockett about 2 years ago

  • Status changed from In Progress to Resolved

Further documentation updates committed (including adding a simple example using deliverResultDocument).

Actions #10

Updated by Norm Tovey-Walsh about 2 years ago

  • Status changed from Resolved to Closed
  • % Done changed from 0 to 100
  • Fixed in JS Release set to SaxonJS 2.5

Fixed in SaxonJS 2.5.

Please register to edit this issue

Also available in: Atom PDF Tracking page