Name

cx:cache-add — Adds documents to the runtime cache.

Synopsis

XML Calabash maintains a cache of documents. This step adds a document to the cache.

Input portPrimarySequenceContent types
source✔   
Output portPrimarySequenceContent types
result✔   
Option nameTypeDefault value
fail-if-in-cachexs:booleanfalse()
hrefxs:anyURI?()
This is an extension step; to use it, your pipeline must include its declaration. For example, by including the extension library with an import at the top of your pipeline:
<p:import href="https://xmlcalabash.com/ext/library/cache.xpl"/>
Declaration
1 |<p:declare-step xmlns:p="http://www.w3.org/ns/xproc">
  |   <p:option name="href" as="xs:anyURI?" select="()"/>
  |   <p:option name="fail-if-in-cache" as="xs:boolean" select="false()"/>
  |   <p:input port="source"/>
5 |   <p:output port="result"/>
  |</p:declare-step>
Errors
CodeDescription
err:XI0030It is a dynamic error (cxerr:XI0030) if the source document does not have a base URI and the href option is not provided.
err:XI0037It is a dynamic error (cxerr:XI0037) if the fail-if-in-cache option is true and the cache already contains a document with the URI being cached.

Description

XML Calabash maintains a document cache while the pipeline is running. The cx:cache-add allows a pipeline author to explicitly add a document to the cache. Some steps use the cache implicitly (for example, the validate steps update it to hold schema documents). When a request is made for a document (by a step, by one of the URI resolvers, etc.), if it appears in the cache, a cached document will be returned.

The cache has two levels. At the top level, a URI maps to a second level cache that maps from content types to documents. In this way, the cache can contain different representations for the same URI provided that they have different content types.

The processor uses the combination of a URI and a content type to locate documents in the cache. If an exact content type match is found for a URI, that document is returned. If there isn’t an exact match, the cache tries to return a document of the right “type”: an XML document for an XML content type, a text document for a text content type, etc. If there’s no type match at all, an arbitrary document will be returned.

If the href option is provided, it is used as the URI for caching, otherwise the source document URI is used. It is a dynamic error (cxerr:XI0030) if the source document does not have a base URI and the href option is not provided.

Irrespective of the cache URI, the step simply copies its source document to the result port. (It does not change the document’s base URI, even if an href option is provided to the cx:cache-add step.)

It is a dynamic error (cxerr:XI0037) if the fail-if-in-cache option is true and the cache already contains a document with the URI being cached.

A pipeline author can remove documents from the cache with cx:cache-delete.

Options

There are two options.

href

The URI to cache. Defaults to the source document URI.

fail-if-in-cache

Determines whether the URI must not already exist in the cache.

Document properties

No properties are changed.