68 lines
No EOL
9.3 KiB
HTML
68 lines
No EOL
9.3 KiB
HTML
<!DOCTYPE html
|
||
SYSTEM "about:legacy-compat">
|
||
<html lang="en"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><meta charset="UTF-8"><meta name="copyright" content="(C) Copyright 2020"><meta name="generator" content="DITA-OT"><meta name="description" content="DITA-OT originally assumed resources would be available on disk and available from file paths. Recent versions added URI input, so HTTPS resources could be used, but temporary and output resources were still file-based. DITA-OT 3.6 introduces a new Store API that can process temporary resources in memory instead of writing them to disk."><meta name="keywords" content="Store API, in-memory processing"><link rel="stylesheet" type="text/css" href="../css/commonltr.css"><link rel="stylesheet" type="text/css" href="../css/dita-ot-doc.css"><title>Store API – Processing in memory</title></head><body id="store-api"><header role="banner"><div class="header">
|
||
<p>DITA Open Toolkit</p>
|
||
<hr>
|
||
</div></header><nav role="toc"><ul><li><a href="../index.html">DITA Open Toolkit 3.6</a></li><li><a href="../release-notes/index.html">Release Notes</a></li><li><a href="../topics/installing-client.html">Installing DITA-OT</a></li><li><a href="../topics/building-output.html">Building output</a></li><li><a href="../topics/input-formats.html">Authoring formats</a></li><li><a href="../topics/output-formats.html">Output formats</a></li><li><a href="../parameters/index.html">Parameters</a></li><li><a href="../topics/html-customization.html">Customizing HTML</a></li><li><a href="../topics/pdf-customization.html">Customizing PDF</a></li><li><a href="../topics/adding-plugins.html">Adding plug-ins</a></li><li><a href="../topics/custom-plugins.html">Creating plug-ins</a></li><li><a href="../topics/troubleshooting-overview.html">Troubleshooting</a></li><li><a href="../reference/index.html">Reference</a><ul><li><a href="../reference/architecture.html">DITA-OT architecture</a><ul><li><a href="../reference/processing-structure.html">Processing structure</a></li><li><a href="../reference/map-first-preprocessing.html">Map-first preprocessing</a></li><li><a href="../reference/processing-pipeline-modules.html">Processing modules</a></li><li><a href="../reference/processing-order.html">Processing order</a></li><li class="active"><a href="../reference/store-api.html">Store API</a></li><li><a href="../reference/preprocessing.html">Pre-processing modules</a></li><li><a href="../reference/html-based-processing.html">HTML-based processing modules</a></li><li><a href="../reference/pdf-transform.html">PDF processing modules</a></li></ul></li><li><a href="../reference/dita-spec-support.html">DITA specification support</a></li><li><a href="../extension-points/plugin-extension-points.html">Extension points</a></li><li><a href="../reference/license.html">License</a></li><li><a href="../reference/glossary.html#glossary">Glossary</a></li></ul></li><li><a href="../topics/dita-and-dita-ot-resources.html">Resources</a></li></ul></nav><main role="main"><article role="article" aria-labelledby="ariaid-title1">
|
||
<h1 class="title topictitle1" id="ariaid-title1">Store API – Processing in memory</h1>
|
||
|
||
|
||
|
||
<div class="body"><p class="shortdesc">DITA-OT originally assumed resources would be available on disk and available from file paths. Recent
|
||
versions added URI input, so HTTPS resources could be used, but temporary and output resources were still
|
||
file-based. DITA-OT 3.6 introduces a new Store API that can process temporary resources in memory instead of writing
|
||
them to disk.</p>
|
||
<p class="p">The Store API (<code class="ph codeph">org.dita.dost.store.Store</code>) is a Java abstraction over temporary file operations.
|
||
So for example instead of reading resources directly with <code class="ph codeph">FileInputStream</code>, the Store API provides
|
||
operations for this. This abstraction allows implementations of the Store API to choose how they handle resources,
|
||
enables optimizations or non–file-based storage. Since DITA-OT processes a lot of XML data, the Store API offers
|
||
operations for XML processing directly. For example, a read method to directly get a DOM
|
||
<code class="ph codeph">Document</code>, instead of opening a file stream manually, parsing it with an XML parser, and getting
|
||
the <code class="ph codeph">Document</code> instance from the parser.</p>
|
||
<p class="p">The Store API is extendable using Java’s
|
||
<a class="xref" href="https://docs.oracle.com/javase/9/docs/api/java/util/ServiceLoader.html" target="_blank" rel="external noopener">Resource Loader</a> with the <code class="ph codeph">org.dita.dost.store.StoreBuilder</code> service. This is a builder
|
||
interface to get named <code class="ph codeph">Store</code> instances (“a Store”).</p>
|
||
<section class="section" id="store-api__stream-store"><h2 class="title sectiontitle">Stream Store for file-based processing</h2>
|
||
|
||
<p class="p">This Store could also be a File Store, since it uses disk and local files for temporary resources. This is the
|
||
traditional DITA-OT implementation, where temporary XML files are stored under the
|
||
<code class="ph codeph">dita.temp.dir</code> path.</p>
|
||
<p class="p">The Stream Store is activated by setting the <span class="keyword parmname">store-type</span> parameter to
|
||
<span class="keyword option">file</span>.</p>
|
||
<div class="note note note_note"><span class="note__title">Note:</span> To ensure backwards compatibility, the <span class="keyword option">file</span> Store is the default setting in DITA-OT
|
||
3.6.</div>
|
||
</section>
|
||
<section class="section" id="store-api__cache-store"><h2 class="title sectiontitle">Cache Store for in-memory processing</h2>
|
||
|
||
<p class="p">This Store is an in-memory Store, that keeps all temporary resources in memory. The name comes from the feature
|
||
of the Store, that it caches the parsed XML after reading. That is, instead of storing XML as a byte array, it
|
||
keeps it as a DOM <code class="ph codeph">Document</code> or <span class="keyword apiname">S9api</span> <code class="ph codeph">XdmNode</code>. When the same
|
||
resource is re-read later, it doesn't have to parse it again, only return the parsed document. Resources that
|
||
are not available in the temporary directory are handled with the Stream Store.</p>
|
||
<p class="p">While the Store doesn't write anything to the temporary directory, it will still use URIs where the resources
|
||
are under the temporary directory. The URIs are simply used for addressing, similarly to URNs. Future releases
|
||
of DITA-OT may use some other method of addressing, such as a <code class="ph codeph">tmp</code> URI scheme.</p>
|
||
<div class="note tip note_tip"><span class="note__title">Tip:</span> As of DITA-OT 3.6, the Cache Store can be activated by setting the
|
||
<span class="keyword parmname">store-type</span> parameter to <span class="keyword option">memory</span>.</div>
|
||
</section>
|
||
<section class="section" id="store-api__benefits"><h2 class="title sectiontitle">Benefits</h2>
|
||
|
||
<p class="p">The initial implementation of the Cache Store is provided in DITA-OT 3.6 as a preview to allow integration
|
||
partners to test this new feature.</p>
|
||
<p class="p">
|
||
<span class="ph">In-memory processing provides performance advantages in I/O bound environments such as cloud
|
||
computing platforms, where processing time depends primarily on how long it takes to read and write temporary
|
||
files.</span></p>
|
||
<p class="p">The Store API also makes the Saxon <span class="keyword apiname">S9api</span> easier to use. It offers an XML document model that
|
||
is in most cases easier to work with than DOM. The abstraction Store makes it easier to work with XML, so
|
||
various modules don’t need to repeat the same type of XML processing code.</p></section>
|
||
<section class="section" id="store-api__caveats"><h2 class="title sectiontitle">Caveats</h2>
|
||
|
||
<p class="p">Not all custom plug-ins will work with the Cache Store, because they may assume files are used and expect direct file
|
||
access for resource operations.</p>
|
||
<div class="note important note_important"><span class="note__title">Important:</span> To take advantage of the Store API, custom plug-ins must use DITA-OT XSLT modules in custom
|
||
<code class="keyword markupname xmlelement"><pipeline></code> elements instead of Ant’s built-in <code class="keyword markupname xmlelement"><xslt></code> tasks as
|
||
recommended in <a class="xref" href="../topics/plugin-coding-conventions.html" title="To ensure custom plug-ins work well with the core toolkit code and remain compatible with future releases, the DITA Open Toolkit project recommends that plug-ins use modern development practices and common coding patterns.">Plug-in coding conventions</a>.</div>
|
||
</section>
|
||
</div>
|
||
<nav role="navigation" class="related-links"><div class="familylinks"><div class="parentlink"><strong>Parent topic:</strong> <a class="link" href="../reference/architecture.html" title="DITA Open Toolkit is an open-source implementation of the OASIS specification for the Darwin Information Typing Architecture. The toolkit uses Ant, XSLT, and Java to transform DITA content (maps and topics) into different deliverable formats.">DITA Open Toolkit Architecture</a></div></div></nav></article></main></body></html> |