Saxon

Controller.registerDocument() is called from two places: from DocumentFn (implementing doc() and document()) and from Controller.makeSourceTree() which handles the "primary input" to a transformation (to the extent that's still a meaningful concept). The main reason for putting the primary input in the document pool is so that it isn't parsed again if the transformation then uses doc() to access it. Yes, I guess it wouldn't do any harm if we find the document URI is already in use to just skip that: it just means anyone who tries to use document-uri() on the document is going to wonder why it hasn't got one.

Ok, I do not understand this part of what you are saying:

it just means anyone who tries to use document-uri() on the document is going to wonder why it hasn't got one.

so there's a side effect to checking if the document is already in the pool when Controller.registerDocument is called?

document-uri() gives a result only for a document that's in the pool. That's because returning a document-uri() UUU for a document provides a guarantee that doc('UUU') will return that document; and that's why two documents aren't allowed to have the same document URI.

So if the XSLT uses document-uri on a node from the current XML source it would not return anything? Might be a problem. How about auto discard a document if already in the pool and the Controller.registerDocument is called?

          TreeInfo cachedDoc = getDocumentPool().find(uri);
          if(cachedDoc != null) {
            getDocumentPool().discard(cachedDoc);
          }
          sourceDocumentPool.add(doc, uri);
        

We can't do anything that would make the data mutable - the result of document-uri() applied to a node can't change over time.

The problems with this started with fn:transform(), which muddies the scope rules for things like the immutability of the result of doc().

I'm not seeing the entire picture here, you can choose to do what's best, maybe even not fix this issue if it looks like something few people would run into or that we could fix by discarding all documents in the pool when reusing the transformer. How about if in the method "net.sf.saxon.Controller.makeSourceTree(Source, int)" if there is already a DocumentKey for that source in the pool we no longer create a new document from it and just use the document in the pool?

Looking more at what we are doing on our side to cause this problem, we are reusing a Transformer and give it each time a javax.xml.transform.Source which has the same system ID but has a reader with different contents each time. So on our side we can clear the pool every time after transforming. In general on the method "net.sf.saxon.Controller.makeSourceTree(Source, int)" creating a DocumentKey over the "new DocumentKey(source.getSystemId())" will not capture the fact that the source contents (reader or input stream or parser) may be different than what's currently in the pool so in my opinion it would make sense to remove the key from the pool if it exists before adding it.

Is there any good reason to reuse the Transformer rather than creating a new one? I usually recommend creating a new Transformer for every transformation.

I think we might reuse the transformer usually because it has a pre-compiled stylesheet. Other projects like the DITA Open Toolkit may reuse the transformer because it has a document pool and has there are lots of DITA topics, each with links to various targets which may be the same file, once the DITA OT loads a target file using document() it's useful that for another processed topic which refers to the same target, the target file is not loaded again.