mirror of
https://github.com/NetherlandsForensicInstitute/hansken-extraction-plugin-sdk-documentation.git
synced 2026-08-24 20:17:16 +00:00
0.6.3
This commit is contained in:
remco
@@ -0,0 +1,346 @@
|
||||
<!DOCTYPE html>
|
||||
<html class="writer-html5" lang="en" >
|
||||
<head>
|
||||
<meta charset="utf-8" /><meta name="generator" content="Docutils 0.18.1: http://docutils.sourceforge.net/" />
|
||||
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
|
||||
<title>Java API Changelog — Hansken Extraction Plugins for plugin developers 0.6.3
|
||||
documentation</title>
|
||||
<link rel="stylesheet" href="../../_static/pygments.css" type="text/css" />
|
||||
<link rel="stylesheet" href="../../_static/css/theme.css" type="text/css" />
|
||||
<link rel="stylesheet" href="../../_static/wider_pages.css" type="text/css" />
|
||||
<!--[if lt IE 9]>
|
||||
<script src="../../_static/js/html5shiv.min.js"></script>
|
||||
<![endif]-->
|
||||
|
||||
<script data-url_root="../../" id="documentation_options" src="../../_static/documentation_options.js"></script>
|
||||
<script src="../../_static/doctools.js"></script>
|
||||
<script src="../../_static/sphinx_highlight.js"></script>
|
||||
<script src="../../_static/js/theme.js"></script>
|
||||
<link rel="index" title="Index" href="../../genindex.html" />
|
||||
<link rel="search" title="Search" href="../../search.html" />
|
||||
<link rel="next" title="Prerequisites" href="prerequisites.html" />
|
||||
<link rel="prev" title="Java" href="../java.html" />
|
||||
</head>
|
||||
|
||||
<body class="wy-body-for-nav">
|
||||
<div class="wy-grid-for-nav">
|
||||
<nav data-toggle="wy-nav-shift" class="wy-nav-side">
|
||||
<div class="wy-side-scroll">
|
||||
<div class="wy-side-nav-search" >
|
||||
|
||||
|
||||
|
||||
<a href="../../index.html" class="icon icon-home">
|
||||
Hansken Extraction Plugins for plugin developers
|
||||
</a>
|
||||
<div class="version">
|
||||
0.6.3
|
||||
|
||||
</div>
|
||||
<div role="search">
|
||||
<form id="rtd-search-form" class="wy-form" action="../../search.html" method="get">
|
||||
<input type="text" name="q" placeholder="Search docs" aria-label="Search docs" />
|
||||
<input type="hidden" name="check_keywords" value="yes" />
|
||||
<input type="hidden" name="area" value="default" />
|
||||
</form>
|
||||
</div>
|
||||
</div><div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu">
|
||||
<p class="caption" role="heading"><span class="caption-text">Contents:</span></p>
|
||||
<ul class="current">
|
||||
<li class="toctree-l1"><a class="reference internal" href="../introduction.html">Introduction</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../concepts.html">General concepts</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../spec.html">Extraction Plugin specifications</a></li>
|
||||
<li class="toctree-l1 current"><a class="reference internal" href="../java.html">Java</a><ul class="current">
|
||||
<li class="toctree-l2 current"><a class="current reference internal" href="#">Java API Changelog</a><ul>
|
||||
<li class="toctree-l3"><a class="reference internal" href="#id1">0.6.1</a></li>
|
||||
<li class="toctree-l3"><a class="reference internal" href="#id2">0.6.0</a></li>
|
||||
<li class="toctree-l3"><a class="reference internal" href="#id3">0.5.0</a></li>
|
||||
<li class="toctree-l3"><a class="reference internal" href="#id4">0.4.13</a></li>
|
||||
<li class="toctree-l3"><a class="reference internal" href="#id5">0.4.7</a></li>
|
||||
<li class="toctree-l3"><a class="reference internal" href="#id6">0.4.6</a></li>
|
||||
<li class="toctree-l3"><a class="reference internal" href="#id7">0.4.0</a></li>
|
||||
<li class="toctree-l3"><a class="reference internal" href="#id8">0.3.0</a></li>
|
||||
<li class="toctree-l3"><a class="reference internal" href="#id9">0.2.0</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="prerequisites.html">Prerequisites</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="packaging.html">Packaging</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="snippets.html">Java code snippets</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="testing.html">Using the Test Framework in Java</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="debugging.html">How to debug an Extraction Plugin</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="javadoc.html">Javadoc</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../python.html">Python</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../examples.html">Examples</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../faq.html">Frequently Asked Questions</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../../contact.html">Contact</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../../changes.html">Changelog</a></li>
|
||||
</ul>
|
||||
|
||||
</div>
|
||||
</div>
|
||||
</nav>
|
||||
|
||||
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"><nav class="wy-nav-top" aria-label="Mobile navigation menu" >
|
||||
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
|
||||
<a href="../../index.html">Hansken Extraction Plugins for plugin developers</a>
|
||||
</nav>
|
||||
|
||||
<div class="wy-nav-content">
|
||||
<div class="rst-content">
|
||||
<div role="navigation" aria-label="Page navigation">
|
||||
<ul class="wy-breadcrumbs">
|
||||
<li><a href="../../index.html" class="icon icon-home" aria-label="Home"></a></li>
|
||||
<li class="breadcrumb-item"><a href="../java.html">Java</a></li>
|
||||
<li class="breadcrumb-item active">Java API Changelog</li>
|
||||
<li class="wy-breadcrumbs-aside">
|
||||
<a href="../../_sources/dev/java/api_changelog.md.txt" rel="nofollow"> View page source</a>
|
||||
</li>
|
||||
</ul>
|
||||
<hr/>
|
||||
</div>
|
||||
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
|
||||
<div itemprop="articleBody">
|
||||
|
||||
<section id="java-api-changelog">
|
||||
<h1>Java API Changelog<a class="headerlink" href="#java-api-changelog" title="Permalink to this heading"></a></h1>
|
||||
<p>This document summarizes all important API changes in the Extraction Plugin API. This document only shows changes that
|
||||
are important to plugin developers. For a full list of changes per version, please refer to the general
|
||||
<a class="reference internal" href="../../changes.html#changelog"><span class="std std-ref">changelog</span></a>.</p>
|
||||
<section id="id1">
|
||||
<h2>0.6.1<a class="headerlink" href="#id1" title="Permalink to this heading"></a></h2>
|
||||
<ul class="simple">
|
||||
<li><p>The JAVA SDK is now distributed through maven central instead of the Hansken community.</p></li>
|
||||
</ul>
|
||||
</section>
|
||||
<section id="id2">
|
||||
<h2>0.6.0<a class="headerlink" href="#id2" title="Permalink to this heading"></a></h2>
|
||||
<div class="admonition warning">
|
||||
<p class="admonition-title">Warning</p>
|
||||
<p>It is highly recommended to upgrade your plugin to this new version.
|
||||
See the migration steps below.</p>
|
||||
</div>
|
||||
<ul>
|
||||
<li><p>Extraction plugin container images are now labeled with PluginInfo. This
|
||||
allows Hansken to efficiently load extraction plugins.</p></li>
|
||||
<li><p>By default, extraction plugin version is managed in the plugin’s <code class="docutils literal notranslate"><span class="pre">pom.xml</span></code>.
|
||||
The <code class="docutils literal notranslate"><span class="pre">.pluginVersion(..)</span></code> can be removed from the PluginInfo builder.</p></li>
|
||||
<li><p><strong>Migration steps from earlier versions</strong> – for plugins that use the Java
|
||||
extraction plugin SuperPOM:</p>
|
||||
<ol class="arabic">
|
||||
<li><p>Update the SDK version in your <code class="docutils literal notranslate"><span class="pre">pom.xml</span></code></p></li>
|
||||
<li><p>If you come from a version prior to <code class="docutils literal notranslate"><span class="pre">0.4.0</span></code>, or if you use a plugin name
|
||||
instead of a plugin id in your <code class="docutils literal notranslate"><span class="pre">pluginInfo()</span></code>, switch to the plugin id style
|
||||
(read instructions for version <code class="docutils literal notranslate"><span class="pre">0.4.0</span></code>)</p></li>
|
||||
<li><p>Set your plugin version in your project’s <code class="docutils literal notranslate"><span class="pre">pom.xml</span></code>, and remove the
|
||||
following from your <code class="docutils literal notranslate"><span class="pre">PluginInfo.Builder</span></code>:</p>
|
||||
<div class="highlight-java notranslate"><div class="highlight"><pre><span></span><span class="p">.</span><span class="na">pluginVersion</span><span class="p">(...)</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
</li>
|
||||
<li><p>Update your build scripts to build your plugin (Docker) container image.
|
||||
You should build your plugin container image with the following command:</p>
|
||||
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>mvn<span class="w"> </span>package<span class="w"> </span>docker:build<span class="sb">`</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>This will generate a plugin image:</p>
|
||||
<ul class="simple">
|
||||
<li><p>The extraction plugin is added to your local image registry
|
||||
(<code class="docutils literal notranslate"><span class="pre">docker</span> <span class="pre">images</span></code>),</p></li>
|
||||
<li><p>The image name is <code class="docutils literal notranslate"><span class="pre">extraction-plugin/PLUGINID</span></code>, e.g.
|
||||
<code class="docutils literal notranslate"><span class="pre">extraction-plugin/nfi.nl/extract/chat/whatsapp</span></code>,</p></li>
|
||||
<li><p>The image is tagged with two tags: <code class="docutils literal notranslate"><span class="pre">latest</span></code>, and your plugin version.</p></li>
|
||||
</ul>
|
||||
<p>Nb. If Docker is not available in your environment, <code class="docutils literal notranslate"><span class="pre">podman</span></code> can be used
|
||||
as an alternative. See <a class="reference internal" href="packaging.html#java-superpom-podman"><span class="std std-ref">packaging</span></a> for more
|
||||
details.</p>
|
||||
</li>
|
||||
</ol>
|
||||
</li>
|
||||
</ul>
|
||||
</section>
|
||||
<section id="id3">
|
||||
<h2>0.5.0<a class="headerlink" href="#id3" title="Permalink to this heading"></a></h2>
|
||||
<ul>
|
||||
<li><p>Add new tracelet api <code class="docutils literal notranslate"><span class="pre">Trace.addTracelet(type,</span> <span class="pre">consumer)</span></code>.
|
||||
It can be used like this:</p>
|
||||
<div class="highlight-java notranslate"><div class="highlight"><pre><span></span><span class="n">trace</span><span class="p">.</span><span class="na">addTracelet</span><span class="p">(</span><span class="s">"prediction"</span><span class="p">,</span><span class="w"> </span><span class="n">tracelet</span><span class="w"> </span><span class="o">-></span><span class="w"> </span><span class="n">tracelet</span>
|
||||
<span class="w"> </span><span class="p">.</span><span class="na">set</span><span class="p">(</span><span class="s">"type"</span><span class="p">,</span><span class="w"> </span><span class="s">"classification"</span><span class="p">)</span>
|
||||
<span class="w"> </span><span class="p">.</span><span class="na">set</span><span class="p">(</span><span class="s">"label"</span><span class="p">,</span><span class="w"> </span><span class="s">"label"</span><span class="p">)</span>
|
||||
<span class="w"> </span><span class="p">.</span><span class="na">set</span><span class="p">(</span><span class="s">"confidence"</span><span class="p">,</span><span class="w"> </span><span class="mf">0.8f</span><span class="p">)</span>
|
||||
<span class="w"> </span><span class="p">.</span><span class="na">set</span><span class="p">(</span><span class="s">"embedding"</span><span class="p">,</span><span class="w"> </span><span class="n">Vector</span><span class="p">.</span><span class="na">of</span><span class="p">(</span><span class="mi">1</span><span class="p">,</span><span class="mi">2</span><span class="p">,</span><span class="mi">3</span><span class="p">))</span>
|
||||
<span class="w"> </span><span class="p">.</span><span class="na">set</span><span class="p">(</span><span class="s">"modelName"</span><span class="p">,</span><span class="w"> </span><span class="s">"yolo"</span><span class="p">)</span>
|
||||
<span class="w"> </span><span class="p">.</span><span class="na">set</span><span class="p">(</span><span class="s">"modelVersion"</span><span class="p">,</span><span class="w"> </span><span class="s">"2.0"</span><span class="p">));</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
</li>
|
||||
<li><p>Deprecate Trace.addTracelet(Trace)</p></li>
|
||||
<li><p>Support vector data type in trace properties.</p></li>
|
||||
</ul>
|
||||
</section>
|
||||
<section id="id4">
|
||||
<h2>0.4.13<a class="headerlink" href="#id4" title="Permalink to this heading"></a></h2>
|
||||
<ul class="simple">
|
||||
<li><p>When writing input search traces for tests, it is no longer required to explicitly set an <code class="docutils literal notranslate"><span class="pre">id</span></code> property.
|
||||
These are automatically generated when executing tests.</p></li>
|
||||
</ul>
|
||||
</section>
|
||||
<section id="id5">
|
||||
<h2>0.4.7<a class="headerlink" href="#id5" title="Permalink to this heading"></a></h2>
|
||||
<ul>
|
||||
<li><p>A new convenience method <code class="docutils literal notranslate"><span class="pre">id(String,</span> <span class="pre">String,</span> <span class="pre">String)</span></code> is added to the PluginInfo builder. This removes some
|
||||
boilerplate code when setting the pluginId. More details on the plugin naming conventions can be found at the
|
||||
<a class="reference internal" href="../concepts/plugin_naming_convention.html"><span class="doc">Plugin naming convention</span></a> section.</p>
|
||||
<div class="highlight-java notranslate"><div class="highlight"><pre><span></span><span class="n">PluginInfo</span><span class="p">.</span><span class="na">builderFor</span><span class="p">(</span><span class="k">this</span><span class="p">)</span>
|
||||
<span class="w"> </span><span class="p">.</span><span class="na">id</span><span class="p">(</span><span class="s">"nfi.nl"</span><span class="p">,</span><span class="w"> </span><span class="s">"extract"</span><span class="p">,</span><span class="w"> </span><span class="s">"TestPlugin"</span><span class="p">)</span><span class="w"> </span><span class="c1">// new style</span>
|
||||
<span class="w"> </span><span class="p">.</span><span class="na">id</span><span class="p">(</span><span class="k">new</span><span class="w"> </span><span class="n">PluginId</span><span class="p">(</span><span class="s">"nfi.nl"</span><span class="p">,</span><span class="w"> </span><span class="s">"extract"</span><span class="p">,</span><span class="w"> </span><span class="s">"TestPlugin"</span><span class="p">))</span><span class="w"> </span><span class="c1">// old style, but also works</span>
|
||||
<span class="w"> </span><span class="p">...</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
</li>
|
||||
</ul>
|
||||
</section>
|
||||
<section id="id6">
|
||||
<h2>0.4.6<a class="headerlink" href="#id6" title="Permalink to this heading"></a></h2>
|
||||
<ul>
|
||||
<li><p>It is now possible to specify maximum system resources in the <code class="docutils literal notranslate"><span class="pre">PluginInfo</span></code>. To run a plugin with 0.5 cpu (= 0.5
|
||||
vCPU/Core/hyperthread) and 1 gb memory, for example, the following configuration can be added to <code class="docutils literal notranslate"><span class="pre">PluginInfo</span></code>:</p>
|
||||
<div class="highlight-java notranslate"><div class="highlight"><pre><span></span><span class="n">PluginInfo</span><span class="p">.</span><span class="na">builderFor</span><span class="p">(</span><span class="k">this</span><span class="p">)</span>
|
||||
<span class="w"> </span><span class="p">...</span>
|
||||
<span class="w"> </span><span class="p">.</span><span class="na">pluginResources</span><span class="p">(</span><span class="n">PluginResources</span><span class="p">.</span><span class="na">builder</span><span class="p">()</span>
|
||||
<span class="w"> </span><span class="p">.</span><span class="na">maximumCpu</span><span class="p">(</span><span class="mf">0.5f</span><span class="p">)</span>
|
||||
<span class="w"> </span><span class="p">.</span><span class="na">maximumMemory</span><span class="p">(</span><span class="mi">1000</span><span class="p">)</span>
|
||||
<span class="w"> </span><span class="p">.</span><span class="na">build</span><span class="p">())</span>
|
||||
<span class="w"> </span><span class="p">.</span><span class="na">build</span><span class="p">();</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
</li>
|
||||
</ul>
|
||||
</section>
|
||||
<section id="id7">
|
||||
<h2>0.4.0<a class="headerlink" href="#id7" title="Permalink to this heading"></a></h2>
|
||||
<ul>
|
||||
<li><p>Extraction Plugins are now identified with a <code class="docutils literal notranslate"><span class="pre">PluginInfo.PluginId</span></code> containing a domain, category and name. The
|
||||
method <code class="docutils literal notranslate"><span class="pre">PluginInfo.name(pluginName)</span></code> has been replaced by <code class="docutils literal notranslate"><span class="pre">PluginInfo.id(new</span> <span class="pre">PluginId(domain,</span> <span class="pre">category,</span> <span class="pre">name)</span></code>. More
|
||||
details on the plugin naming conventions can be found at the <a class="reference internal" href="../concepts/plugin_naming_convention.html"><span class="doc">Plugin naming convention</span></a> section.</p></li>
|
||||
<li><p><code class="docutils literal notranslate"><span class="pre">PluginInfo.name()</span></code> is now deprecated (but will still work for backwards compatibility).</p></li>
|
||||
<li><p>A new license field <code class="docutils literal notranslate"><span class="pre">PluginInfo.license</span></code> has also been added in this release.</p></li>
|
||||
<li><p>The following example creates a PluginInfo for a plugin with the name <code class="docutils literal notranslate"><span class="pre">TestPlugin</span></code>, licensed under
|
||||
the <code class="docutils literal notranslate"><span class="pre">Apache</span> <span class="pre">License</span> <span class="pre">2.0</span></code> license:</p>
|
||||
<div class="highlight-java notranslate"><div class="highlight"><pre><span></span><span class="n">PluginInfo</span><span class="p">.</span><span class="na">builderFor</span><span class="p">(</span><span class="k">this</span><span class="p">)</span>
|
||||
<span class="w"> </span><span class="p">.</span><span class="na">id</span><span class="p">(</span><span class="k">new</span><span class="w"> </span><span class="n">PluginId</span><span class="p">(</span><span class="s">"nfi.nl"</span><span class="p">,</span><span class="w"> </span><span class="s">"extract"</span><span class="p">,</span><span class="w"> </span><span class="s">"TestPlugin"</span><span class="p">))</span><span class="w"> </span><span class="c1">// id.domain: nfi.nl, id.category: extract, id.name: TestPlugin</span>
|
||||
<span class="w"> </span><span class="c1">// .name("TestPlugin") // no longer supported</span>
|
||||
<span class="w"> </span><span class="p">.</span><span class="na">pluginVersion</span><span class="p">(</span><span class="s">"0.4.1"</span><span class="p">)</span>
|
||||
<span class="w"> </span><span class="p">.</span><span class="na">author</span><span class="p">(</span><span class="n">Author</span><span class="p">.</span><span class="na">builder</span><span class="p">()...</span><span class="na">build</span><span class="p">())</span>
|
||||
<span class="w"> </span><span class="p">.</span><span class="na">description</span><span class="p">(</span><span class="s">"A plugin for testing."</span><span class="p">)</span>
|
||||
<span class="w"> </span><span class="p">.</span><span class="na">maturityLevel</span><span class="p">(</span><span class="n">MaturityLevel</span><span class="p">.</span><span class="na">PROOF_OF_CONCEPT</span><span class="p">)</span>
|
||||
<span class="w"> </span><span class="p">.</span><span class="na">hqlMatcher</span><span class="p">(</span><span class="s">"*"</span><span class="p">)</span>
|
||||
<span class="w"> </span><span class="p">.</span><span class="na">webpageUrl</span><span class="p">(</span><span class="s">"https://www.hansken.org"</span><span class="p">)</span>
|
||||
<span class="w"> </span><span class="p">.</span><span class="na">license</span><span class="p">(</span><span class="s">"Apache License 2.0"</span><span class="p">)</span>
|
||||
<span class="w"> </span><span class="p">.</span><span class="na">build</span><span class="p">();</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
</li>
|
||||
</ul>
|
||||
</section>
|
||||
<section id="id8">
|
||||
<h2>0.3.0<a class="headerlink" href="#id8" title="Permalink to this heading"></a></h2>
|
||||
<ul>
|
||||
<li><p>Extraction Plugins can now create new datastreams on a Trace through data transformations. Data transformations
|
||||
describe how data can be obtained from a source.</p>
|
||||
<p>An example case is an extraction plugin that processes an archive file. The plugin creates a child trace per entry in
|
||||
the archive file. Each child trace will have a datastream that is a transformation that marks the start and length of
|
||||
the entry in the original archive data. By just describing the data instead of specifying the actual data, a lot of
|
||||
space is saved.</p>
|
||||
<p>Although Hansken supports various transformations, the Extraction Plugins SDK for now only supports ranged data
|
||||
transformations. Ranged data transformations define data as a list of ranges, each range with an offset and length in
|
||||
a bytearray.</p>
|
||||
<p>The following example sets a new datastream with dataType <code class="docutils literal notranslate"><span class="pre">html</span></code> on a trace, by setting a ranged data transformation:</p>
|
||||
<div class="highlight-java notranslate"><div class="highlight"><pre><span></span><span class="n">trace</span><span class="p">.</span><span class="na">setData</span><span class="p">(</span><span class="s">"html"</span><span class="p">,</span><span class="w"> </span><span class="n">RangedDataTransformation</span><span class="p">.</span><span class="na">builder</span><span class="p">().</span><span class="na">addRange</span><span class="p">(</span><span class="n">offset</span><span class="p">,</span><span class="w"> </span><span class="n">length</span><span class="p">).</span><span class="na">build</span><span class="p">());</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>The following example creates a child trace and sets a new datastream with dataType <code class="docutils literal notranslate"><span class="pre">raw</span></code> on it, by setting a ranged
|
||||
data transformation with two ranges:</p>
|
||||
<div class="highlight-java notranslate"><div class="highlight"><pre><span></span><span class="n">trace</span><span class="p">.</span><span class="na">newChild</span><span class="p">(</span><span class="n">format</span><span class="p">(</span><span class="s">"lineNumber %d"</span><span class="p">,</span><span class="w"> </span><span class="n">lineNumber</span><span class="p">),</span><span class="w"> </span><span class="n">child</span><span class="w"> </span><span class="o">-></span><span class="w"> </span><span class="p">{</span>
|
||||
<span class="w"> </span><span class="n">child</span><span class="p">.</span><span class="na">setData</span><span class="p">(</span><span class="s">"raw"</span><span class="p">,</span><span class="w"> </span><span class="n">RangedDataTransformation</span><span class="p">.</span><span class="na">builder</span><span class="p">()</span>
|
||||
<span class="w"> </span><span class="p">.</span><span class="na">addRange</span><span class="p">(</span><span class="mi">10</span><span class="p">,</span><span class="w"> </span><span class="mi">20</span><span class="p">)</span>
|
||||
<span class="w"> </span><span class="p">.</span><span class="na">addRange</span><span class="p">(</span><span class="mi">50</span><span class="p">,</span><span class="w"> </span><span class="mi">30</span><span class="p">)</span>
|
||||
<span class="w"> </span><span class="p">.</span><span class="na">build</span><span class="p">());</span>
|
||||
<span class="p">});</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>More detailed documentation will follow in an upcoming SDK release.</p>
|
||||
</li>
|
||||
</ul>
|
||||
</section>
|
||||
<section id="id9">
|
||||
<h2>0.2.0<a class="headerlink" href="#id9" title="Permalink to this heading"></a></h2>
|
||||
<div class="admonition warning">
|
||||
<p class="admonition-title">Warning</p>
|
||||
<p>This is an API breaking change. Plugins created with an earlier version of the extraction plugin SDK are
|
||||
not compatible with Hansken that uses <cite>0.2.0</cite> or later.</p>
|
||||
</div>
|
||||
<ul>
|
||||
<li><p>Introduced a new extraction plugin type <code class="docutils literal notranslate"><span class="pre">DeferredExtractioPlugin</span></code>. Deferred Extraction plugins can be run at a
|
||||
different extraction stage. This type of plugin also allows accessing other traces using the searcher.</p></li>
|
||||
<li><p>The class <code class="docutils literal notranslate"><span class="pre">ExtractionContext</span></code> has been renamed to <code class="docutils literal notranslate"><span class="pre">DataContext</span></code>. The new name <code class="docutils literal notranslate"><span class="pre">DataContext</span></code> represents the class
|
||||
contents better. Plugins have to update matching import statements and the type in <code class="docutils literal notranslate"><span class="pre">ExtractionPlugin.process()</span></code>
|
||||
implementation in the same way. This change has no functional side effects.</p>
|
||||
<p>Old:</p>
|
||||
<div class="highlight-java notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span><span class="w"> </span><span class="nn">org.hansken.plugin.extraction.api.ExtractionContext</span><span class="p">;</span>
|
||||
|
||||
<span class="nd">@Override</span>
|
||||
|
||||
<span class="kd">public</span><span class="w"> </span><span class="kt">void</span><span class="w"> </span><span class="nf">process</span><span class="p">(</span><span class="kd">final</span><span class="w"> </span><span class="n">Trace</span><span class="w"> </span><span class="n">trace</span><span class="p">,</span><span class="w"> </span><span class="kd">final</span><span class="w"> </span><span class="n">ExtractionContext</span><span class="w"> </span><span class="n">context</span><span class="p">)</span><span class="w"> </span><span class="kd">throws</span><span class="w"> </span><span class="n">IOException</span><span class="w"> </span><span class="p">{</span>
|
||||
|
||||
<span class="p">}</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>New:</p>
|
||||
<div class="highlight-java notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span><span class="w"> </span><span class="nn">org.hansken.plugin.extraction.api.DataContext</span><span class="p">;</span>
|
||||
|
||||
<span class="nd">@Override</span>
|
||||
<span class="kd">public</span><span class="w"> </span><span class="kt">void</span><span class="w"> </span><span class="nf">process</span><span class="p">(</span><span class="kd">final</span><span class="w"> </span><span class="n">Trace</span><span class="w"> </span><span class="n">trace</span><span class="p">,</span><span class="w"> </span><span class="kd">final</span><span class="w"> </span><span class="n">DataContext</span><span class="w"> </span><span class="n">dataContext</span><span class="p">)</span><span class="w"> </span><span class="kd">throws</span><span class="w"> </span><span class="n">IOException</span><span class="w"> </span><span class="p">{</span>
|
||||
|
||||
<span class="p">}</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
</li>
|
||||
</ul>
|
||||
</section>
|
||||
</section>
|
||||
|
||||
|
||||
</div>
|
||||
</div>
|
||||
<footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer">
|
||||
<a href="../java.html" class="btn btn-neutral float-left" title="Java" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
|
||||
<a href="prerequisites.html" class="btn btn-neutral float-right" title="Prerequisites" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
|
||||
</div>
|
||||
|
||||
<hr/>
|
||||
|
||||
<div role="contentinfo">
|
||||
<p>© Copyright 2020-2023 Netherlands Forensic Institute.</p>
|
||||
</div>
|
||||
|
||||
Built with <a href="https://www.sphinx-doc.org/">Sphinx</a> using a
|
||||
<a href="https://github.com/readthedocs/sphinx_rtd_theme">theme</a>
|
||||
provided by <a href="https://readthedocs.org">Read the Docs</a>.
|
||||
|
||||
|
||||
</footer>
|
||||
</div>
|
||||
</div>
|
||||
</section>
|
||||
</div>
|
||||
<script>
|
||||
jQuery(function () {
|
||||
SphinxRtdTheme.Navigation.enable(true);
|
||||
});
|
||||
</script>
|
||||
|
||||
</body>
|
||||
</html>
|
||||
@@ -0,0 +1,273 @@
|
||||
<!DOCTYPE html>
|
||||
<html class="writer-html5" lang="en" >
|
||||
<head>
|
||||
<meta charset="utf-8" /><meta name="generator" content="Docutils 0.18.1: http://docutils.sourceforge.net/" />
|
||||
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
|
||||
<title>How to debug an Extraction Plugin — Hansken Extraction Plugins for plugin developers 0.6.3
|
||||
documentation</title>
|
||||
<link rel="stylesheet" href="../../_static/pygments.css" type="text/css" />
|
||||
<link rel="stylesheet" href="../../_static/css/theme.css" type="text/css" />
|
||||
<link rel="stylesheet" href="../../_static/wider_pages.css" type="text/css" />
|
||||
<!--[if lt IE 9]>
|
||||
<script src="../../_static/js/html5shiv.min.js"></script>
|
||||
<![endif]-->
|
||||
|
||||
<script data-url_root="../../" id="documentation_options" src="../../_static/documentation_options.js"></script>
|
||||
<script src="../../_static/doctools.js"></script>
|
||||
<script src="../../_static/sphinx_highlight.js"></script>
|
||||
<script src="../../_static/js/theme.js"></script>
|
||||
<link rel="index" title="Index" href="../../genindex.html" />
|
||||
<link rel="search" title="Search" href="../../search.html" />
|
||||
<link rel="next" title="Javadoc" href="javadoc.html" />
|
||||
<link rel="prev" title="Using the Test Framework in Java" href="testing.html" />
|
||||
</head>
|
||||
|
||||
<body class="wy-body-for-nav">
|
||||
<div class="wy-grid-for-nav">
|
||||
<nav data-toggle="wy-nav-shift" class="wy-nav-side">
|
||||
<div class="wy-side-scroll">
|
||||
<div class="wy-side-nav-search" >
|
||||
|
||||
|
||||
|
||||
<a href="../../index.html" class="icon icon-home">
|
||||
Hansken Extraction Plugins for plugin developers
|
||||
</a>
|
||||
<div class="version">
|
||||
0.6.3
|
||||
|
||||
</div>
|
||||
<div role="search">
|
||||
<form id="rtd-search-form" class="wy-form" action="../../search.html" method="get">
|
||||
<input type="text" name="q" placeholder="Search docs" aria-label="Search docs" />
|
||||
<input type="hidden" name="check_keywords" value="yes" />
|
||||
<input type="hidden" name="area" value="default" />
|
||||
</form>
|
||||
</div>
|
||||
</div><div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu">
|
||||
<p class="caption" role="heading"><span class="caption-text">Contents:</span></p>
|
||||
<ul class="current">
|
||||
<li class="toctree-l1"><a class="reference internal" href="../introduction.html">Introduction</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../concepts.html">General concepts</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../spec.html">Extraction Plugin specifications</a></li>
|
||||
<li class="toctree-l1 current"><a class="reference internal" href="../java.html">Java</a><ul class="current">
|
||||
<li class="toctree-l2"><a class="reference internal" href="api_changelog.html">Java API Changelog</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="prerequisites.html">Prerequisites</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="packaging.html">Packaging</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="snippets.html">Java code snippets</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="testing.html">Using the Test Framework in Java</a></li>
|
||||
<li class="toctree-l2 current"><a class="current reference internal" href="#">How to debug an Extraction Plugin</a><ul>
|
||||
<li class="toctree-l3"><a class="reference internal" href="#locally">Locally</a><ul>
|
||||
<li class="toctree-l4"><a class="reference internal" href="#logging">Logging</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
<li class="toctree-l3"><a class="reference internal" href="#locally-with-docker">Locally with Docker</a><ul>
|
||||
<li class="toctree-l4"><a class="reference internal" href="#build-a-docker-image">Build a Docker image</a></li>
|
||||
<li class="toctree-l4"><a class="reference internal" href="#run-the-docker-image-with-specific-java-tool-options">Run the Docker image with specific Java tool options</a></li>
|
||||
<li class="toctree-l4"><a class="reference internal" href="#setting-breakpoints-in-the-code">Setting breakpoints in the code</a></li>
|
||||
<li class="toctree-l4"><a class="reference internal" href="#logging-in-docker">Logging in Docker</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
<li class="toctree-l3"><a class="reference internal" href="#kubernetes">Kubernetes</a><ul>
|
||||
<li class="toctree-l4"><a class="reference internal" href="#logging-in-kubernetes">Logging in Kubernetes</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
<li class="toctree-l3"><a class="reference internal" href="#debug-hql">Debug HQL</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="javadoc.html">Javadoc</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../python.html">Python</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../examples.html">Examples</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../faq.html">Frequently Asked Questions</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../../contact.html">Contact</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../../changes.html">Changelog</a></li>
|
||||
</ul>
|
||||
|
||||
</div>
|
||||
</div>
|
||||
</nav>
|
||||
|
||||
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"><nav class="wy-nav-top" aria-label="Mobile navigation menu" >
|
||||
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
|
||||
<a href="../../index.html">Hansken Extraction Plugins for plugin developers</a>
|
||||
</nav>
|
||||
|
||||
<div class="wy-nav-content">
|
||||
<div class="rst-content">
|
||||
<div role="navigation" aria-label="Page navigation">
|
||||
<ul class="wy-breadcrumbs">
|
||||
<li><a href="../../index.html" class="icon icon-home" aria-label="Home"></a></li>
|
||||
<li class="breadcrumb-item"><a href="../java.html">Java</a></li>
|
||||
<li class="breadcrumb-item active">How to debug an Extraction Plugin</li>
|
||||
<li class="wy-breadcrumbs-aside">
|
||||
<a href="../../_sources/dev/java/debugging.md.txt" rel="nofollow"> View page source</a>
|
||||
</li>
|
||||
</ul>
|
||||
<hr/>
|
||||
</div>
|
||||
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
|
||||
<div itemprop="articleBody">
|
||||
|
||||
<section id="how-to-debug-an-extraction-plugin">
|
||||
<h1>How to debug an Extraction Plugin<a class="headerlink" href="#how-to-debug-an-extraction-plugin" title="Permalink to this heading"></a></h1>
|
||||
<p>Debugging is the art of removing bugs — hopefully quickly.</p>
|
||||
<section id="locally">
|
||||
<h2>Locally<a class="headerlink" href="#locally" title="Permalink to this heading"></a></h2>
|
||||
<p>To debug a plugin locally, it is recommended to start the plugin via the IDE by running the integration test. This has
|
||||
the advantage that breakpoints can easily be put in the code instead of printing log statements, for example.</p>
|
||||
<section id="logging">
|
||||
<h3>Logging<a class="headerlink" href="#logging" title="Permalink to this heading"></a></h3>
|
||||
<p>The logging of the extraction plugin is displayed in the console.</p>
|
||||
</section>
|
||||
</section>
|
||||
<section id="locally-with-docker">
|
||||
<h2>Locally with Docker<a class="headerlink" href="#locally-with-docker" title="Permalink to this heading"></a></h2>
|
||||
<p>Debugging an extraction plugin via docker is a bit trickier. Java has the advantage that remote debugging is already
|
||||
baked in.</p>
|
||||
<p>Using Java Remote Debug with Docker containers requires 3 distinct steps:</p>
|
||||
<ol class="arabic simple">
|
||||
<li><p>Build a Docker image</p></li>
|
||||
<li><p>Run the Docker image with specific Java tool options</p></li>
|
||||
<li><p>Setting breakpoints in your code</p></li>
|
||||
</ol>
|
||||
<section id="build-a-docker-image">
|
||||
<h3>Build a Docker image<a class="headerlink" href="#build-a-docker-image" title="Permalink to this heading"></a></h3>
|
||||
<p>If the Docker image is not built, run the following command to build the Docker image:</p>
|
||||
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>mvn<span class="w"> </span>package<span class="w"> </span>docker:build
|
||||
</pre></div>
|
||||
</div>
|
||||
</section>
|
||||
<section id="run-the-docker-image-with-specific-java-tool-options">
|
||||
<h3>Run the Docker image with specific Java tool options<a class="headerlink" href="#run-the-docker-image-with-specific-java-tool-options" title="Permalink to this heading"></a></h3>
|
||||
<p>In Java, the remote debug functionality is not enabled by default. To enable the remote debug functionality, the
|
||||
following environments variable must be set in the Docker container:</p>
|
||||
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span><span class="nv">JAVA_TOOL_OPTIONS</span><span class="o">=</span><span class="s2">"-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=*:5005"</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>This environment variable allows the debugger to connect to the debuggee (application being debugged). To start the
|
||||
Docker image with the <code class="docutils literal notranslate"><span class="pre">JAVA_TOOL_OPTIONS</span></code> environment variable, the following command can be used:</p>
|
||||
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>docker<span class="w"> </span>run<span class="w"> </span>-p<span class="w"> </span><span class="m">5005</span>:5005<span class="w"> </span>-e<span class="w"> </span><span class="nv">JAVA_TOOL_OPTIONS</span><span class="o">=</span><span class="s2">"-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=*:5005"</span><span class="w"> </span>your_extraction_plugin_name
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>The next step is to attach the debugger to the debuggee.
|
||||
For Intellij, the instructions are clearly described on the following
|
||||
page: <a class="reference external" href="https://www.jetbrains.com/help/idea/tutorial-remote-debug.html#49be7f04">Tutorial: Remote debug</a></p>
|
||||
</section>
|
||||
<section id="setting-breakpoints-in-the-code">
|
||||
<h3>Setting breakpoints in the code<a class="headerlink" href="#setting-breakpoints-in-the-code" title="Permalink to this heading"></a></h3>
|
||||
<p>The last step is to add breakpoints in the code.</p>
|
||||
</section>
|
||||
<section id="logging-in-docker">
|
||||
<h3>Logging in Docker<a class="headerlink" href="#logging-in-docker" title="Permalink to this heading"></a></h3>
|
||||
<p>The logging of the extraction plugin is displayed in the console after running the <code class="docutils literal notranslate"><span class="pre">docker</span> <span class="pre">run</span></code> command. In addition,
|
||||
the logging is also displayed in the IntelliJ console while debugging.</p>
|
||||
</section>
|
||||
</section>
|
||||
<section id="kubernetes">
|
||||
<h2>Kubernetes<a class="headerlink" href="#kubernetes" title="Permalink to this heading"></a></h2>
|
||||
<p>In kubernetes it is currently <em>not</em> possible to debug via Java Remote Debug because:</p>
|
||||
<ul class="simple">
|
||||
<li><p>no debug ports are published;</p></li>
|
||||
<li><p>the container was not started with the environment variable <code class="docutils literal notranslate"><span class="pre">JAVA_TOOL_OPTIONS</span></code> so debugging is not enabled.</p></li>
|
||||
</ul>
|
||||
<section id="logging-in-kubernetes">
|
||||
<h3>Logging in Kubernetes<a class="headerlink" href="#logging-in-kubernetes" title="Permalink to this heading"></a></h3>
|
||||
<p>If there is authorization to the kubernetes cluster, the logging can be viewed with the following command:</p>
|
||||
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>kubectl<span class="w"> </span>logs<span class="w"> </span>-f<span class="w"> </span>hansken-extraction-plugins/your_extraction_plugin_pod
|
||||
</pre></div>
|
||||
</div>
|
||||
</section>
|
||||
</section>
|
||||
<section id="debug-hql">
|
||||
<h2>Debug HQL<a class="headerlink" href="#debug-hql" title="Permalink to this heading"></a></h2>
|
||||
<p>An HQL query can be debugged by overriding the <code class="docutils literal notranslate"><span class="pre">isVerboseLoggingEnabled()</span></code> method of the <code class="docutils literal notranslate"><span class="pre">ExtractionPluginFlits</span></code> class.
|
||||
The example below shows an example of an embedded FLITS test with verbose logging enabled.</p>
|
||||
<div class="highlight-java notranslate"><div class="highlight"><pre><span></span><span class="kd">public</span><span class="w"> </span><span class="kd">class</span> <span class="nc">TestPluginFlitsIT</span><span class="w"> </span><span class="kd">extends</span><span class="w"> </span><span class="n">EmbeddedExtractionPluginFlits</span><span class="w"> </span><span class="p">{</span>
|
||||
|
||||
<span class="w"> </span><span class="nd">@Override</span>
|
||||
<span class="w"> </span><span class="kd">public</span><span class="w"> </span><span class="n">Path</span><span class="w"> </span><span class="nf">testPath</span><span class="p">()</span><span class="w"> </span><span class="p">{</span>
|
||||
<span class="w"> </span><span class="k">return</span><span class="w"> </span><span class="n">srcPath</span><span class="p">(</span><span class="s">"integration/inputs/plugin"</span><span class="p">);</span>
|
||||
<span class="w"> </span><span class="p">}</span>
|
||||
|
||||
<span class="w"> </span><span class="nd">@Override</span>
|
||||
<span class="w"> </span><span class="kd">public</span><span class="w"> </span><span class="n">Path</span><span class="w"> </span><span class="nf">resultPath</span><span class="p">()</span><span class="w"> </span><span class="p">{</span>
|
||||
<span class="w"> </span><span class="k">return</span><span class="w"> </span><span class="n">srcPath</span><span class="p">(</span><span class="s">"integration/results/embedded/plugin"</span><span class="p">);</span>
|
||||
<span class="w"> </span><span class="p">}</span>
|
||||
|
||||
<span class="w"> </span><span class="nd">@Override</span>
|
||||
<span class="w"> </span><span class="kd">protected</span><span class="w"> </span><span class="n">ExtractionPlugin</span><span class="w"> </span><span class="nf">pluginToTest</span><span class="p">()</span><span class="w"> </span><span class="p">{</span>
|
||||
<span class="w"> </span><span class="k">return</span><span class="w"> </span><span class="k">new</span><span class="w"> </span><span class="n">TestPlugin</span><span class="p">();</span>
|
||||
<span class="w"> </span><span class="p">}</span>
|
||||
|
||||
<span class="w"> </span><span class="nd">@Override</span>
|
||||
<span class="w"> </span><span class="kd">public</span><span class="w"> </span><span class="kt">boolean</span><span class="w"> </span><span class="nf">regenerate</span><span class="p">()</span><span class="w"> </span><span class="p">{</span>
|
||||
<span class="w"> </span><span class="k">return</span><span class="w"> </span><span class="kc">true</span><span class="p">;</span>
|
||||
<span class="w"> </span><span class="p">}</span>
|
||||
|
||||
<span class="w"> </span><span class="nd">@Override</span>
|
||||
<span class="w"> </span><span class="kd">protected</span><span class="w"> </span><span class="kt">boolean</span><span class="w"> </span><span class="nf">isVerboseLoggingEnabled</span><span class="p">()</span><span class="w"> </span><span class="p">{</span>
|
||||
<span class="w"> </span><span class="k">return</span><span class="w"> </span><span class="kc">true</span><span class="p">;</span>
|
||||
<span class="w"> </span><span class="p">}</span>
|
||||
<span class="p">}</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>The following output will then be displayed in the console:</p>
|
||||
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>HQL match found for:
|
||||
$data.type=jpg
|
||||
With trace:
|
||||
dataType=jpg
|
||||
types={file, data}
|
||||
properties={data.raw.mimeType=image/jpg, path=/test-input-trace, file.name=image.jpg, name=test-input-trace, id=0}
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>If the HQL query contains an error, it will be shown in the generated test results. An example of an invalid query
|
||||
is <code class="docutils literal notranslate"><span class="pre">$data.mimeType=image/jpg</span></code> (slash not escaped). This query will produce an error like the one shown below.</p>
|
||||
<div class="highlight-json notranslate"><div class="highlight"><pre><span></span><span class="p">{</span>
|
||||
<span class="w"> </span><span class="nt">"class"</span><span class="p">:</span><span class="w"> </span><span class="s2">"org.hansken.plugin.extraction.hql_lite.lang.ParseException"</span><span class="p">,</span>
|
||||
<span class="w"> </span><span class="nt">"message"</span><span class="p">:</span><span class="w"> </span><span class="s2">"HqlLiteHumanQueryParser: line 1:20 token recognition error at: '/jpg'"</span>
|
||||
<span class="p">}</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<div class="admonition note">
|
||||
<p class="admonition-title">Note</p>
|
||||
<p>The error is only shown in the generated trace, so to find out the <cite>ParseException</cite> override
|
||||
the <code class="docutils literal notranslate"><span class="pre">regenerate()</span></code> method from <code class="docutils literal notranslate"><span class="pre">Flits</span></code> and then let this method return <code class="docutils literal notranslate"><span class="pre">true</span></code>.</p>
|
||||
</div>
|
||||
</section>
|
||||
</section>
|
||||
|
||||
|
||||
</div>
|
||||
</div>
|
||||
<footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer">
|
||||
<a href="testing.html" class="btn btn-neutral float-left" title="Using the Test Framework in Java" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
|
||||
<a href="javadoc.html" class="btn btn-neutral float-right" title="Javadoc" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
|
||||
</div>
|
||||
|
||||
<hr/>
|
||||
|
||||
<div role="contentinfo">
|
||||
<p>© Copyright 2020-2023 Netherlands Forensic Institute.</p>
|
||||
</div>
|
||||
|
||||
Built with <a href="https://www.sphinx-doc.org/">Sphinx</a> using a
|
||||
<a href="https://github.com/readthedocs/sphinx_rtd_theme">theme</a>
|
||||
provided by <a href="https://readthedocs.org">Read the Docs</a>.
|
||||
|
||||
|
||||
</footer>
|
||||
</div>
|
||||
</div>
|
||||
</section>
|
||||
</div>
|
||||
<script>
|
||||
jQuery(function () {
|
||||
SphinxRtdTheme.Navigation.enable(true);
|
||||
});
|
||||
</script>
|
||||
|
||||
</body>
|
||||
</html>
|
||||
@@ -0,0 +1,132 @@
|
||||
<!DOCTYPE html>
|
||||
<html class="writer-html5" lang="en" >
|
||||
<head>
|
||||
<meta charset="utf-8" /><meta name="generator" content="Docutils 0.18.1: http://docutils.sourceforge.net/" />
|
||||
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
|
||||
<title>Javadoc — Hansken Extraction Plugins for plugin developers 0.6.3
|
||||
documentation</title>
|
||||
<link rel="stylesheet" href="../../_static/pygments.css" type="text/css" />
|
||||
<link rel="stylesheet" href="../../_static/css/theme.css" type="text/css" />
|
||||
<link rel="stylesheet" href="../../_static/wider_pages.css" type="text/css" />
|
||||
<!--[if lt IE 9]>
|
||||
<script src="../../_static/js/html5shiv.min.js"></script>
|
||||
<![endif]-->
|
||||
|
||||
<script data-url_root="../../" id="documentation_options" src="../../_static/documentation_options.js"></script>
|
||||
<script src="../../_static/doctools.js"></script>
|
||||
<script src="../../_static/sphinx_highlight.js"></script>
|
||||
<script src="../../_static/js/theme.js"></script>
|
||||
<link rel="index" title="Index" href="../../genindex.html" />
|
||||
<link rel="search" title="Search" href="../../search.html" />
|
||||
<link rel="next" title="Python" href="../python.html" />
|
||||
<link rel="prev" title="How to debug an Extraction Plugin" href="debugging.html" />
|
||||
</head>
|
||||
|
||||
<body class="wy-body-for-nav">
|
||||
<div class="wy-grid-for-nav">
|
||||
<nav data-toggle="wy-nav-shift" class="wy-nav-side">
|
||||
<div class="wy-side-scroll">
|
||||
<div class="wy-side-nav-search" >
|
||||
|
||||
|
||||
|
||||
<a href="../../index.html" class="icon icon-home">
|
||||
Hansken Extraction Plugins for plugin developers
|
||||
</a>
|
||||
<div class="version">
|
||||
0.6.3
|
||||
|
||||
</div>
|
||||
<div role="search">
|
||||
<form id="rtd-search-form" class="wy-form" action="../../search.html" method="get">
|
||||
<input type="text" name="q" placeholder="Search docs" aria-label="Search docs" />
|
||||
<input type="hidden" name="check_keywords" value="yes" />
|
||||
<input type="hidden" name="area" value="default" />
|
||||
</form>
|
||||
</div>
|
||||
</div><div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu">
|
||||
<p class="caption" role="heading"><span class="caption-text">Contents:</span></p>
|
||||
<ul class="current">
|
||||
<li class="toctree-l1"><a class="reference internal" href="../introduction.html">Introduction</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../concepts.html">General concepts</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../spec.html">Extraction Plugin specifications</a></li>
|
||||
<li class="toctree-l1 current"><a class="reference internal" href="../java.html">Java</a><ul class="current">
|
||||
<li class="toctree-l2"><a class="reference internal" href="api_changelog.html">Java API Changelog</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="prerequisites.html">Prerequisites</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="packaging.html">Packaging</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="snippets.html">Java code snippets</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="testing.html">Using the Test Framework in Java</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="debugging.html">How to debug an Extraction Plugin</a></li>
|
||||
<li class="toctree-l2 current"><a class="current reference internal" href="#">Javadoc</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../python.html">Python</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../examples.html">Examples</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../faq.html">Frequently Asked Questions</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../../contact.html">Contact</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../../changes.html">Changelog</a></li>
|
||||
</ul>
|
||||
|
||||
</div>
|
||||
</div>
|
||||
</nav>
|
||||
|
||||
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"><nav class="wy-nav-top" aria-label="Mobile navigation menu" >
|
||||
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
|
||||
<a href="../../index.html">Hansken Extraction Plugins for plugin developers</a>
|
||||
</nav>
|
||||
|
||||
<div class="wy-nav-content">
|
||||
<div class="rst-content">
|
||||
<div role="navigation" aria-label="Page navigation">
|
||||
<ul class="wy-breadcrumbs">
|
||||
<li><a href="../../index.html" class="icon icon-home" aria-label="Home"></a></li>
|
||||
<li class="breadcrumb-item"><a href="../java.html">Java</a></li>
|
||||
<li class="breadcrumb-item active">Javadoc</li>
|
||||
<li class="wy-breadcrumbs-aside">
|
||||
<a href="../../_sources/dev/java/javadoc.md.txt" rel="nofollow"> View page source</a>
|
||||
</li>
|
||||
</ul>
|
||||
<hr/>
|
||||
</div>
|
||||
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
|
||||
<div itemprop="articleBody">
|
||||
|
||||
<section id="javadoc">
|
||||
<h1>Javadoc<a class="headerlink" href="#javadoc" title="Permalink to this heading"></a></h1>
|
||||
<p>Visit the <a class="reference external" href="../../_static/javadoc/index.html">Javadoc of the Extraction Plugins SDK API</a>.</p>
|
||||
</section>
|
||||
|
||||
|
||||
</div>
|
||||
</div>
|
||||
<footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer">
|
||||
<a href="debugging.html" class="btn btn-neutral float-left" title="How to debug an Extraction Plugin" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
|
||||
<a href="../python.html" class="btn btn-neutral float-right" title="Python" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
|
||||
</div>
|
||||
|
||||
<hr/>
|
||||
|
||||
<div role="contentinfo">
|
||||
<p>© Copyright 2020-2023 Netherlands Forensic Institute.</p>
|
||||
</div>
|
||||
|
||||
Built with <a href="https://www.sphinx-doc.org/">Sphinx</a> using a
|
||||
<a href="https://github.com/readthedocs/sphinx_rtd_theme">theme</a>
|
||||
provided by <a href="https://readthedocs.org">Read the Docs</a>.
|
||||
|
||||
|
||||
</footer>
|
||||
</div>
|
||||
</div>
|
||||
</section>
|
||||
</div>
|
||||
<script>
|
||||
jQuery(function () {
|
||||
SphinxRtdTheme.Navigation.enable(true);
|
||||
});
|
||||
</script>
|
||||
|
||||
</body>
|
||||
</html>
|
||||
@@ -0,0 +1,162 @@
|
||||
<!DOCTYPE html>
|
||||
<html class="writer-html5" lang="en" >
|
||||
<head>
|
||||
<meta charset="utf-8" /><meta name="generator" content="Docutils 0.18.1: http://docutils.sourceforge.net/" />
|
||||
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
|
||||
<title>Packaging — Hansken Extraction Plugins for plugin developers 0.6.3
|
||||
documentation</title>
|
||||
<link rel="stylesheet" href="../../_static/pygments.css" type="text/css" />
|
||||
<link rel="stylesheet" href="../../_static/css/theme.css" type="text/css" />
|
||||
<link rel="stylesheet" href="../../_static/wider_pages.css" type="text/css" />
|
||||
<!--[if lt IE 9]>
|
||||
<script src="../../_static/js/html5shiv.min.js"></script>
|
||||
<![endif]-->
|
||||
|
||||
<script data-url_root="../../" id="documentation_options" src="../../_static/documentation_options.js"></script>
|
||||
<script src="../../_static/doctools.js"></script>
|
||||
<script src="../../_static/sphinx_highlight.js"></script>
|
||||
<script src="../../_static/js/theme.js"></script>
|
||||
<link rel="index" title="Index" href="../../genindex.html" />
|
||||
<link rel="search" title="Search" href="../../search.html" />
|
||||
<link rel="next" title="Java code snippets" href="snippets.html" />
|
||||
<link rel="prev" title="Prerequisites" href="prerequisites.html" />
|
||||
</head>
|
||||
|
||||
<body class="wy-body-for-nav">
|
||||
<div class="wy-grid-for-nav">
|
||||
<nav data-toggle="wy-nav-shift" class="wy-nav-side">
|
||||
<div class="wy-side-scroll">
|
||||
<div class="wy-side-nav-search" >
|
||||
|
||||
|
||||
|
||||
<a href="../../index.html" class="icon icon-home">
|
||||
Hansken Extraction Plugins for plugin developers
|
||||
</a>
|
||||
<div class="version">
|
||||
0.6.3
|
||||
|
||||
</div>
|
||||
<div role="search">
|
||||
<form id="rtd-search-form" class="wy-form" action="../../search.html" method="get">
|
||||
<input type="text" name="q" placeholder="Search docs" aria-label="Search docs" />
|
||||
<input type="hidden" name="check_keywords" value="yes" />
|
||||
<input type="hidden" name="area" value="default" />
|
||||
</form>
|
||||
</div>
|
||||
</div><div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu">
|
||||
<p class="caption" role="heading"><span class="caption-text">Contents:</span></p>
|
||||
<ul class="current">
|
||||
<li class="toctree-l1"><a class="reference internal" href="../introduction.html">Introduction</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../concepts.html">General concepts</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../spec.html">Extraction Plugin specifications</a></li>
|
||||
<li class="toctree-l1 current"><a class="reference internal" href="../java.html">Java</a><ul class="current">
|
||||
<li class="toctree-l2"><a class="reference internal" href="api_changelog.html">Java API Changelog</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="prerequisites.html">Prerequisites</a></li>
|
||||
<li class="toctree-l2 current"><a class="current reference internal" href="#">Packaging</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="snippets.html">Java code snippets</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="testing.html">Using the Test Framework in Java</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="debugging.html">How to debug an Extraction Plugin</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="javadoc.html">Javadoc</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../python.html">Python</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../examples.html">Examples</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../faq.html">Frequently Asked Questions</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../../contact.html">Contact</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../../changes.html">Changelog</a></li>
|
||||
</ul>
|
||||
|
||||
</div>
|
||||
</div>
|
||||
</nav>
|
||||
|
||||
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"><nav class="wy-nav-top" aria-label="Mobile navigation menu" >
|
||||
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
|
||||
<a href="../../index.html">Hansken Extraction Plugins for plugin developers</a>
|
||||
</nav>
|
||||
|
||||
<div class="wy-nav-content">
|
||||
<div class="rst-content">
|
||||
<div role="navigation" aria-label="Page navigation">
|
||||
<ul class="wy-breadcrumbs">
|
||||
<li><a href="../../index.html" class="icon icon-home" aria-label="Home"></a></li>
|
||||
<li class="breadcrumb-item"><a href="../java.html">Java</a></li>
|
||||
<li class="breadcrumb-item active">Packaging</li>
|
||||
<li class="wy-breadcrumbs-aside">
|
||||
<a href="../../_sources/dev/java/packaging.md.txt" rel="nofollow"> View page source</a>
|
||||
</li>
|
||||
</ul>
|
||||
<hr/>
|
||||
</div>
|
||||
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
|
||||
<div itemprop="articleBody">
|
||||
|
||||
<section id="packaging">
|
||||
<h1>Packaging<a class="headerlink" href="#packaging" title="Permalink to this heading"></a></h1>
|
||||
<p>Extraction plugins are packaged as OCI images (also known as Docker images).
|
||||
The OCI images are labeled with the PluginInfo.
|
||||
To automate packaging of a Java plugin and labeling the OCI image, the Extraction Plugin SuperPom has been configured to automate this for you.</p>
|
||||
<p>If your project uses the Extraction Plugin SuperPom (see <a class="reference internal" href="prerequisites.html"><span class="doc">Prerequisites</span></a>), Packaging an extraction plugin is handled by Maven.
|
||||
To package your plugin into a container image, the following command can be used:</p>
|
||||
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>mvn<span class="w"> </span>package<span class="w"> </span>docker:build
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>This will generate a plugin image:</p>
|
||||
<ul class="simple">
|
||||
<li><p>The extraction plugin is added to your local image registry
|
||||
(<code class="docutils literal notranslate"><span class="pre">docker</span> <span class="pre">images</span></code>),</p></li>
|
||||
<li><p>The image name is <code class="docutils literal notranslate"><span class="pre">extraction-plugin/PLUGINID</span></code>, e.g.
|
||||
<code class="docutils literal notranslate"><span class="pre">extraction-plugin/nfi.nl/extract/chat/whatsapp</span></code>,</p></li>
|
||||
<li><p>The image is labeled with two tags: <code class="docutils literal notranslate"><span class="pre">latest</span></code>, and your plugin version.</p></li>
|
||||
</ul>
|
||||
<p>It is possible to apply extra arguments to the docker command <a class="reference external" href="http://dmp.fabric8.io/#docker:build">as described here</a>.
|
||||
For example, to specify a proxy, use the following command:</p>
|
||||
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>mvn<span class="w"> </span>package<span class="w"> </span>docker:build<span class="w"> </span>-Ddocker.buildArg.https_proxy<span class="o">=</span>https://proxy:8001
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>Once your plugin is packaged, it can be published or ‘uploaded’ to Hansken.
|
||||
See “<a class="reference internal" href="../concepts/extraction_plugins.html#upload-plugin"><span class="std std-ref">Upload the plugin to Hansken</span></a>” for instructions.</p>
|
||||
<p id="java-superpom-podman">Note: if your build environment does not have Docker available, you can use
|
||||
<a class="reference external" href="https://podman.io/">podman</a> as an alternative. Install podman on your machine
|
||||
or build agent, and run the following commands <em>before</em> invoking the
|
||||
<code class="docutils literal notranslate"><span class="pre">mvn</span> <span class="pre">package</span> <span class="pre">docker:build</span></code> command:</p>
|
||||
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>podman<span class="w"> </span>system<span class="w"> </span>service<span class="w"> </span>--time<span class="o">=</span><span class="m">0</span><span class="w"> </span>unix:/run/user/<span class="k">$(</span>id<span class="w"> </span>-u<span class="k">)</span>/podman/podman.sock<span class="w"> </span><span class="p">&</span>
|
||||
<span class="nb">export</span><span class="w"> </span><span class="nv">DOCKER_HOST</span><span class="o">=</span><span class="s2">"unix:/run/user/</span><span class="k">$(</span>id<span class="w"> </span>-u<span class="k">)</span><span class="s2">/podman/podman.sock"</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
</section>
|
||||
|
||||
|
||||
</div>
|
||||
</div>
|
||||
<footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer">
|
||||
<a href="prerequisites.html" class="btn btn-neutral float-left" title="Prerequisites" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
|
||||
<a href="snippets.html" class="btn btn-neutral float-right" title="Java code snippets" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
|
||||
</div>
|
||||
|
||||
<hr/>
|
||||
|
||||
<div role="contentinfo">
|
||||
<p>© Copyright 2020-2023 Netherlands Forensic Institute.</p>
|
||||
</div>
|
||||
|
||||
Built with <a href="https://www.sphinx-doc.org/">Sphinx</a> using a
|
||||
<a href="https://github.com/readthedocs/sphinx_rtd_theme">theme</a>
|
||||
provided by <a href="https://readthedocs.org">Read the Docs</a>.
|
||||
|
||||
|
||||
</footer>
|
||||
</div>
|
||||
</div>
|
||||
</section>
|
||||
</div>
|
||||
<script>
|
||||
jQuery(function () {
|
||||
SphinxRtdTheme.Navigation.enable(true);
|
||||
});
|
||||
</script>
|
||||
|
||||
</body>
|
||||
</html>
|
||||
@@ -0,0 +1,173 @@
|
||||
<!DOCTYPE html>
|
||||
<html class="writer-html5" lang="en" >
|
||||
<head>
|
||||
<meta charset="utf-8" /><meta name="generator" content="Docutils 0.18.1: http://docutils.sourceforge.net/" />
|
||||
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
|
||||
<title>Prerequisites — Hansken Extraction Plugins for plugin developers 0.6.3
|
||||
documentation</title>
|
||||
<link rel="stylesheet" href="../../_static/pygments.css" type="text/css" />
|
||||
<link rel="stylesheet" href="../../_static/css/theme.css" type="text/css" />
|
||||
<link rel="stylesheet" href="../../_static/wider_pages.css" type="text/css" />
|
||||
<!--[if lt IE 9]>
|
||||
<script src="../../_static/js/html5shiv.min.js"></script>
|
||||
<![endif]-->
|
||||
|
||||
<script data-url_root="../../" id="documentation_options" src="../../_static/documentation_options.js"></script>
|
||||
<script src="../../_static/doctools.js"></script>
|
||||
<script src="../../_static/sphinx_highlight.js"></script>
|
||||
<script src="../../_static/js/theme.js"></script>
|
||||
<link rel="index" title="Index" href="../../genindex.html" />
|
||||
<link rel="search" title="Search" href="../../search.html" />
|
||||
<link rel="next" title="Packaging" href="packaging.html" />
|
||||
<link rel="prev" title="Java API Changelog" href="api_changelog.html" />
|
||||
</head>
|
||||
|
||||
<body class="wy-body-for-nav">
|
||||
<div class="wy-grid-for-nav">
|
||||
<nav data-toggle="wy-nav-shift" class="wy-nav-side">
|
||||
<div class="wy-side-scroll">
|
||||
<div class="wy-side-nav-search" >
|
||||
|
||||
|
||||
|
||||
<a href="../../index.html" class="icon icon-home">
|
||||
Hansken Extraction Plugins for plugin developers
|
||||
</a>
|
||||
<div class="version">
|
||||
0.6.3
|
||||
|
||||
</div>
|
||||
<div role="search">
|
||||
<form id="rtd-search-form" class="wy-form" action="../../search.html" method="get">
|
||||
<input type="text" name="q" placeholder="Search docs" aria-label="Search docs" />
|
||||
<input type="hidden" name="check_keywords" value="yes" />
|
||||
<input type="hidden" name="area" value="default" />
|
||||
</form>
|
||||
</div>
|
||||
</div><div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu">
|
||||
<p class="caption" role="heading"><span class="caption-text">Contents:</span></p>
|
||||
<ul class="current">
|
||||
<li class="toctree-l1"><a class="reference internal" href="../introduction.html">Introduction</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../concepts.html">General concepts</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../spec.html">Extraction Plugin specifications</a></li>
|
||||
<li class="toctree-l1 current"><a class="reference internal" href="../java.html">Java</a><ul class="current">
|
||||
<li class="toctree-l2"><a class="reference internal" href="api_changelog.html">Java API Changelog</a></li>
|
||||
<li class="toctree-l2 current"><a class="current reference internal" href="#">Prerequisites</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="packaging.html">Packaging</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="snippets.html">Java code snippets</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="testing.html">Using the Test Framework in Java</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="debugging.html">How to debug an Extraction Plugin</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="javadoc.html">Javadoc</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../python.html">Python</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../examples.html">Examples</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../faq.html">Frequently Asked Questions</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../../contact.html">Contact</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../../changes.html">Changelog</a></li>
|
||||
</ul>
|
||||
|
||||
</div>
|
||||
</div>
|
||||
</nav>
|
||||
|
||||
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"><nav class="wy-nav-top" aria-label="Mobile navigation menu" >
|
||||
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
|
||||
<a href="../../index.html">Hansken Extraction Plugins for plugin developers</a>
|
||||
</nav>
|
||||
|
||||
<div class="wy-nav-content">
|
||||
<div class="rst-content">
|
||||
<div role="navigation" aria-label="Page navigation">
|
||||
<ul class="wy-breadcrumbs">
|
||||
<li><a href="../../index.html" class="icon icon-home" aria-label="Home"></a></li>
|
||||
<li class="breadcrumb-item"><a href="../java.html">Java</a></li>
|
||||
<li class="breadcrumb-item active">Prerequisites</li>
|
||||
<li class="wy-breadcrumbs-aside">
|
||||
<a href="../../_sources/dev/java/prerequisites.md.txt" rel="nofollow"> View page source</a>
|
||||
</li>
|
||||
</ul>
|
||||
<hr/>
|
||||
</div>
|
||||
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
|
||||
<div itemprop="articleBody">
|
||||
|
||||
<section id="prerequisites">
|
||||
<h1>Prerequisites<a class="headerlink" href="#prerequisites" title="Permalink to this heading"></a></h1>
|
||||
<p>Required software:</p>
|
||||
<ul class="simple">
|
||||
<li><p>Java 11 or higher</p></li>
|
||||
<li><p>Docker for <a class="reference internal" href="packaging.html"><span class="doc">packaging</span></a> and publishing plugins<span class="raw-html-m2r"><br></span>
|
||||
(or use a Docker alternative such as <code class="docutils literal notranslate"><span class="pre">podman</span></code>)</p></li>
|
||||
<li><p>Maven (recommended, build automation tool)</p></li>
|
||||
</ul>
|
||||
<p>Required dependencies:</p>
|
||||
<ul>
|
||||
<li><p>All required project dependencies to build extraction plugins are published on the public Maven Central, under <code class="docutils literal notranslate"><span class="pre">org.hansken.plugin.extraction:plugin-super-pom</span></code>.
|
||||
For maven based extraction plugins, the following <code class="docutils literal notranslate"><span class="pre">pom.xml</span></code> snippet can be used as basis of a plugin:</p>
|
||||
<div class="highlight-xml notranslate"><div class="highlight"><pre><span></span><span class="cp"><?xml version="1.0" encoding="UTF-8"?></span>
|
||||
<span class="nt"><project</span><span class="w"> </span><span class="na">xmlns=</span><span class="s">"http://maven.apache.org/POM/4.0.0"</span>
|
||||
<span class="w"> </span><span class="na">xmlns:xsi=</span><span class="s">"http://www.w3.org/2001/XMLSchema-instance"</span>
|
||||
<span class="w"> </span><span class="na">xsi:schemaLocation=</span><span class="s">"http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd"</span><span class="nt">></span>
|
||||
<span class="w"> </span><span class="nt"><modelVersion></span>4.0.0<span class="nt"></modelVersion></span>
|
||||
|
||||
<span class="w"> </span><span class="nt"><parent></span>
|
||||
<span class="w"> </span><span class="nt"><groupId></span>org.hansken.plugin.extraction<span class="nt"></groupId></span>
|
||||
<span class="w"> </span><span class="nt"><artifactId></span>plugin-super-pom<span class="nt"></artifactId></span>
|
||||
<span class="w"> </span><span class="nt"><version></span>SET_THE_SDK_VERSION_HERE<span class="nt"></version></span>
|
||||
<span class="w"> </span><span class="nt"></parent></span>
|
||||
|
||||
<span class="w"> </span><span class="nt"><artifactId></span>CHOOSE_YOUR_ARTIFACTID_HERE<span class="nt"></artifactId></span>
|
||||
<span class="w"> </span><span class="nt"><version></span>SET_THE_PLUGIN_VERSION_HERE<span class="nt"></version></span>
|
||||
|
||||
<span class="w"> </span><span class="nt"><licenses></span>
|
||||
<span class="w"> </span><span class="nt"><license></span>
|
||||
<span class="w"> </span><span class="nt"><name></span>The<span class="w"> </span>Apache<span class="w"> </span>Software<span class="w"> </span>License,<span class="w"> </span>Version<span class="w"> </span>2.0<span class="nt"></name></span>
|
||||
<span class="w"> </span><span class="nt"><url></span>http://www.apache.org/licenses/LICENSE-2.0.txt<span class="nt"></url></span>
|
||||
<span class="w"> </span><span class="nt"><distribution></span>repo<span class="nt"></distribution></span>
|
||||
<span class="w"> </span><span class="nt"></license></span>
|
||||
<span class="w"> </span><span class="nt"></licenses></span>
|
||||
|
||||
<span class="w"> </span><span class="nt"><properties></span>
|
||||
<span class="w"> </span><span class="nt"><mainClass></span>SET_THE_PLUGIN_MAIN_CLASS_HERE<span class="nt"></mainClass></span>
|
||||
<span class="w"> </span><span class="nt"></properties></span>
|
||||
<span class="nt"></project></span>
|
||||
</pre></div>
|
||||
</div>
|
||||
</li>
|
||||
</ul>
|
||||
</section>
|
||||
|
||||
|
||||
</div>
|
||||
</div>
|
||||
<footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer">
|
||||
<a href="api_changelog.html" class="btn btn-neutral float-left" title="Java API Changelog" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
|
||||
<a href="packaging.html" class="btn btn-neutral float-right" title="Packaging" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
|
||||
</div>
|
||||
|
||||
<hr/>
|
||||
|
||||
<div role="contentinfo">
|
||||
<p>© Copyright 2020-2023 Netherlands Forensic Institute.</p>
|
||||
</div>
|
||||
|
||||
Built with <a href="https://www.sphinx-doc.org/">Sphinx</a> using a
|
||||
<a href="https://github.com/readthedocs/sphinx_rtd_theme">theme</a>
|
||||
provided by <a href="https://readthedocs.org">Read the Docs</a>.
|
||||
|
||||
|
||||
</footer>
|
||||
</div>
|
||||
</div>
|
||||
</section>
|
||||
</div>
|
||||
<script>
|
||||
jQuery(function () {
|
||||
SphinxRtdTheme.Navigation.enable(true);
|
||||
});
|
||||
</script>
|
||||
|
||||
</body>
|
||||
</html>
|
||||
@@ -0,0 +1,372 @@
|
||||
<!DOCTYPE html>
|
||||
<html class="writer-html5" lang="en" >
|
||||
<head>
|
||||
<meta charset="utf-8" /><meta name="generator" content="Docutils 0.18.1: http://docutils.sourceforge.net/" />
|
||||
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
|
||||
<title>Java code snippets — Hansken Extraction Plugins for plugin developers 0.6.3
|
||||
documentation</title>
|
||||
<link rel="stylesheet" href="../../_static/pygments.css" type="text/css" />
|
||||
<link rel="stylesheet" href="../../_static/css/theme.css" type="text/css" />
|
||||
<link rel="stylesheet" href="../../_static/wider_pages.css" type="text/css" />
|
||||
<!--[if lt IE 9]>
|
||||
<script src="../../_static/js/html5shiv.min.js"></script>
|
||||
<![endif]-->
|
||||
|
||||
<script data-url_root="../../" id="documentation_options" src="../../_static/documentation_options.js"></script>
|
||||
<script src="../../_static/doctools.js"></script>
|
||||
<script src="../../_static/sphinx_highlight.js"></script>
|
||||
<script src="../../_static/js/theme.js"></script>
|
||||
<link rel="index" title="Index" href="../../genindex.html" />
|
||||
<link rel="search" title="Search" href="../../search.html" />
|
||||
<link rel="next" title="Using the Test Framework in Java" href="testing.html" />
|
||||
<link rel="prev" title="Packaging" href="packaging.html" />
|
||||
</head>
|
||||
|
||||
<body class="wy-body-for-nav">
|
||||
<div class="wy-grid-for-nav">
|
||||
<nav data-toggle="wy-nav-shift" class="wy-nav-side">
|
||||
<div class="wy-side-scroll">
|
||||
<div class="wy-side-nav-search" >
|
||||
|
||||
|
||||
|
||||
<a href="../../index.html" class="icon icon-home">
|
||||
Hansken Extraction Plugins for plugin developers
|
||||
</a>
|
||||
<div class="version">
|
||||
0.6.3
|
||||
|
||||
</div>
|
||||
<div role="search">
|
||||
<form id="rtd-search-form" class="wy-form" action="../../search.html" method="get">
|
||||
<input type="text" name="q" placeholder="Search docs" aria-label="Search docs" />
|
||||
<input type="hidden" name="check_keywords" value="yes" />
|
||||
<input type="hidden" name="area" value="default" />
|
||||
</form>
|
||||
</div>
|
||||
</div><div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu">
|
||||
<p class="caption" role="heading"><span class="caption-text">Contents:</span></p>
|
||||
<ul class="current">
|
||||
<li class="toctree-l1"><a class="reference internal" href="../introduction.html">Introduction</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../concepts.html">General concepts</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../spec.html">Extraction Plugin specifications</a></li>
|
||||
<li class="toctree-l1 current"><a class="reference internal" href="../java.html">Java</a><ul class="current">
|
||||
<li class="toctree-l2"><a class="reference internal" href="api_changelog.html">Java API Changelog</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="prerequisites.html">Prerequisites</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="packaging.html">Packaging</a></li>
|
||||
<li class="toctree-l2 current"><a class="current reference internal" href="#">Java code snippets</a><ul>
|
||||
<li class="toctree-l3"><a class="reference internal" href="#randomaccessdata-as-inputstream">RandomAccessData as InputStream</a></li>
|
||||
<li class="toctree-l3"><a class="reference internal" href="#adding-tracelets">Adding tracelets</a></li>
|
||||
<li class="toctree-l3"><a class="reference internal" href="#adding-data-to-a-trace">Adding data to a trace</a><ul>
|
||||
<li class="toctree-l4"><a class="reference internal" href="#data-transformations">Data Transformations</a></li>
|
||||
<li class="toctree-l4"><a class="reference internal" href="#blobs">Blobs</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
<li class="toctree-l3"><a class="reference internal" href="#specifying-system-resources">Specifying system resources</a></li>
|
||||
<li class="toctree-l3"><a class="reference internal" href="#deferred-extraction-plugins">Deferred Extraction Plugins</a></li>
|
||||
<li class="toctree-l3"><a class="reference internal" href="#logging">Logging</a><ul>
|
||||
<li class="toctree-l4"><a class="reference internal" href="#usage">Usage</a></li>
|
||||
<li class="toctree-l4"><a class="reference internal" href="#customize-logging">Customize logging</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
<li class="toctree-l3"><a class="reference internal" href="#experimental-feature-adding-previews-to-a-trace">[EXPERIMENTAL FEATURE] Adding previews to a trace</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="testing.html">Using the Test Framework in Java</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="debugging.html">How to debug an Extraction Plugin</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="javadoc.html">Javadoc</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../python.html">Python</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../examples.html">Examples</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../faq.html">Frequently Asked Questions</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../../contact.html">Contact</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../../changes.html">Changelog</a></li>
|
||||
</ul>
|
||||
|
||||
</div>
|
||||
</div>
|
||||
</nav>
|
||||
|
||||
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"><nav class="wy-nav-top" aria-label="Mobile navigation menu" >
|
||||
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
|
||||
<a href="../../index.html">Hansken Extraction Plugins for plugin developers</a>
|
||||
</nav>
|
||||
|
||||
<div class="wy-nav-content">
|
||||
<div class="rst-content">
|
||||
<div role="navigation" aria-label="Page navigation">
|
||||
<ul class="wy-breadcrumbs">
|
||||
<li><a href="../../index.html" class="icon icon-home" aria-label="Home"></a></li>
|
||||
<li class="breadcrumb-item"><a href="../java.html">Java</a></li>
|
||||
<li class="breadcrumb-item active">Java code snippets</li>
|
||||
<li class="wy-breadcrumbs-aside">
|
||||
<a href="../../_sources/dev/java/snippets.md.txt" rel="nofollow"> View page source</a>
|
||||
</li>
|
||||
</ul>
|
||||
<hr/>
|
||||
</div>
|
||||
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
|
||||
<div itemprop="articleBody">
|
||||
|
||||
<section id="java-code-snippets">
|
||||
<h1>Java code snippets<a class="headerlink" href="#java-code-snippets" title="Permalink to this heading"></a></h1>
|
||||
<p>This page contains Java code snippets for common patterns that will be used when writing a plugin.</p>
|
||||
<section id="randomaccessdata-as-inputstream">
|
||||
<h2>RandomAccessData as InputStream<a class="headerlink" href="#randomaccessdata-as-inputstream" title="Permalink to this heading"></a></h2>
|
||||
<p>In Java, <code class="docutils literal notranslate"><span class="pre">InputStream</span></code> is a common type to pass data to another class or method. The SDK provides a simple utility to
|
||||
use a <code class="docutils literal notranslate"><span class="pre">RandomAccessData</span></code> as <code class="docutils literal notranslate"><span class="pre">InputStream</span></code>.</p>
|
||||
<p>Add the following import to your code:</p>
|
||||
<div class="highlight-java notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span><span class="w"> </span><span class="nn">org.hansken.plugin.extraction.core.data.RandomAccessDatas</span><span class="p">;</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>Next we can create an <code class="docutils literal notranslate"><span class="pre">InputStream</span></code> from the <code class="docutils literal notranslate"><span class="pre">RandomAccessData</span></code> as shown in the following snippet. Note that the
|
||||
<code class="docutils literal notranslate"><span class="pre">InputStream</span></code> is created using a <code class="docutils literal notranslate"><span class="pre">try-with-resources</span></code>-statement. This ensures that the <code class="docutils literal notranslate"><span class="pre">InputStream</span></code> is correctly closed
|
||||
when the <code class="docutils literal notranslate"><span class="pre">InputStream</span></code> is no longer required.</p>
|
||||
<div class="highlight-java notranslate"><div class="highlight"><pre><span></span><span class="n">RandomAccessData</span><span class="w"> </span><span class="n">traceData</span><span class="o">=</span><span class="p">...;</span>
|
||||
<span class="w"> </span><span class="k">try</span><span class="p">(</span><span class="n">InputStream</span><span class="w"> </span><span class="n">asInputStream</span><span class="o">=</span><span class="n">RandomAccessDatas</span><span class="p">.</span><span class="na">asInputStream</span><span class="p">(</span><span class="n">traceData</span><span class="p">)){</span>
|
||||
<span class="w"> </span><span class="c1">// use the InputStream here</span>
|
||||
<span class="w"> </span><span class="p">}</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>Notes:</p>
|
||||
<ul class="simple">
|
||||
<li><p>the created <code class="docutils literal notranslate"><span class="pre">InputStream</span></code> is <em>not</em> thread-safe,</p></li>
|
||||
<li><p>the created <code class="docutils literal notranslate"><span class="pre">InputStream</span></code> changes state in the provided <code class="docutils literal notranslate"><span class="pre">RandomAccessData</span></code>
|
||||
(e.g. when data is read, the position updated in both the <code class="docutils literal notranslate"><span class="pre">InputStream</span></code> <em>and</em>
|
||||
the <code class="docutils literal notranslate"><span class="pre">RandomAccessData</span></code> instances),</p></li>
|
||||
<li><p>for more details on the implementation of the <code class="docutils literal notranslate"><span class="pre">InputStream</span></code>, refer to the <code class="docutils literal notranslate"><span class="pre">RandomAccessDataInputStream</span></code> JavaDoc.</p></li>
|
||||
</ul>
|
||||
</section>
|
||||
<section id="adding-tracelets">
|
||||
<span id="tracelets-java"></span><h2>Adding tracelets<a class="headerlink" href="#adding-tracelets" title="Permalink to this heading"></a></h2>
|
||||
<p>In the following Java example, a “classification” <a class="reference internal" href="../concepts/traces.html#tracelets"><span class="std std-ref">tracelet</span></a> is added to a trace. The tracelet consists
|
||||
of a list of four properties, namely “class”, “confidence”, “modelName” and “modelVersion”.</p>
|
||||
<div class="highlight-java notranslate"><div class="highlight"><pre><span></span><span class="n">trace</span><span class="p">.</span><span class="na">addTracelet</span><span class="p">(</span><span class="s">"prediction"</span><span class="p">,</span><span class="w"> </span><span class="n">tracelet</span><span class="w"> </span><span class="o">-></span><span class="w"> </span><span class="n">tracelet</span>
|
||||
<span class="w"> </span><span class="p">.</span><span class="na">set</span><span class="p">(</span><span class="s">"type"</span><span class="p">,</span><span class="w"> </span><span class="s">"classification"</span><span class="p">)</span>
|
||||
<span class="w"> </span><span class="p">.</span><span class="na">set</span><span class="p">(</span><span class="s">"class"</span><span class="p">,</span><span class="w"> </span><span class="s">"telephone"</span><span class="p">)</span>
|
||||
<span class="w"> </span><span class="p">.</span><span class="na">set</span><span class="p">(</span><span class="s">"label"</span><span class="p">,</span><span class="w"> </span><span class="s">"label"</span><span class="p">)</span>
|
||||
<span class="w"> </span><span class="p">.</span><span class="na">set</span><span class="p">(</span><span class="s">"confidence"</span><span class="p">,</span><span class="w"> </span><span class="mf">0.8f</span><span class="p">)</span>
|
||||
<span class="w"> </span><span class="p">.</span><span class="na">set</span><span class="p">(</span><span class="s">"embedding"</span><span class="p">,</span><span class="w"> </span><span class="n">Vector</span><span class="p">.</span><span class="na">of</span><span class="p">(</span><span class="mi">1</span><span class="p">,</span><span class="mi">2</span><span class="p">,</span><span class="mi">3</span><span class="p">))</span>
|
||||
<span class="w"> </span><span class="p">.</span><span class="na">set</span><span class="p">(</span><span class="s">"modelName"</span><span class="p">,</span><span class="w"> </span><span class="s">"yolo"</span><span class="p">)</span>
|
||||
<span class="w"> </span><span class="p">.</span><span class="na">set</span><span class="p">(</span><span class="s">"modelVersion"</span><span class="p">,</span><span class="w"> </span><span class="s">"2.0"</span><span class="p">));</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>or</p>
|
||||
<div class="highlight-java notranslate"><div class="highlight"><pre><span></span><span class="n">trace</span><span class="p">.</span><span class="na">addTracelet</span><span class="p">(</span><span class="k">new</span><span class="w"> </span><span class="n">Tracelet</span><span class="p">(</span><span class="s">"prediction"</span><span class="p">,</span><span class="w"> </span><span class="n">List</span><span class="p">.</span><span class="na">of</span><span class="p">(</span>
|
||||
<span class="w"> </span><span class="k">new</span><span class="w"> </span><span class="n">TraceletProperty</span><span class="p">(</span><span class="s">"prediction.type"</span><span class="p">,</span><span class="s">"classification"</span><span class="p">),</span>
|
||||
<span class="w"> </span><span class="k">new</span><span class="w"> </span><span class="n">TraceletProperty</span><span class="p">(</span><span class="s">"prediction.class"</span><span class="p">,</span><span class="s">"telephone"</span><span class="p">),</span>
|
||||
<span class="w"> </span><span class="k">new</span><span class="w"> </span><span class="n">TraceletProperty</span><span class="p">(</span><span class="s">"prediction.label"</span><span class="p">,</span><span class="s">"label"</span><span class="p">),</span>
|
||||
<span class="w"> </span><span class="k">new</span><span class="w"> </span><span class="n">TraceletProperty</span><span class="p">(</span><span class="s">"prediction.confidence"</span><span class="p">,</span><span class="mf">0.8f</span><span class="p">))),</span>
|
||||
<span class="w"> </span><span class="k">new</span><span class="w"> </span><span class="n">TraceletProperty</span><span class="p">(</span><span class="s">"prediction.embedding"</span><span class="p">,</span><span class="w"> </span><span class="n">Vector</span><span class="p">.</span><span class="na">of</span><span class="p">(</span><span class="mi">1</span><span class="p">,</span><span class="mi">2</span><span class="p">,</span><span class="mi">3</span><span class="p">)),</span>
|
||||
<span class="w"> </span><span class="k">new</span><span class="w"> </span><span class="n">TraceletProperty</span><span class="p">(</span><span class="s">"prediction.modelName"</span><span class="p">,</span><span class="s">"yolo"</span><span class="p">),</span>
|
||||
<span class="w"> </span><span class="k">new</span><span class="w"> </span><span class="n">TraceletProperty</span><span class="p">(</span><span class="s">"prediction.modelVersion"</span><span class="p">,</span><span class="s">"2.0"</span><span class="p">));</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
</section>
|
||||
<section id="adding-data-to-a-trace">
|
||||
<span id="datastreams-java"></span><h2>Adding data to a trace<a class="headerlink" href="#adding-data-to-a-trace" title="Permalink to this heading"></a></h2>
|
||||
<p>Traces can have data attatched to them. See <a class="reference internal" href="../concepts/traces.html#datastreams"><span class="std std-ref">Data streams</span></a> for more information.
|
||||
The following two snippets demonstrate how to add data to a trace.</p>
|
||||
<p>It is currently not possible to verify that a specific data stream is already set or not.</p>
|
||||
<section id="data-transformations">
|
||||
<h3>Data Transformations<a class="headerlink" href="#data-transformations" title="Permalink to this heading"></a></h3>
|
||||
<p>The most efficient way to add data to a trace is using data transformations.
|
||||
See <a class="reference internal" href="../concepts/data_transformations.html"><span class="doc">Data Transformations</span></a> for more details.</p>
|
||||
<p>The following example sets a new data stream with dataType <code class="docutils literal notranslate"><span class="pre">html</span></code> on a trace, by setting a ranged data transformation:</p>
|
||||
<div class="highlight-java notranslate"><div class="highlight"><pre><span></span><span class="n">trace</span><span class="p">.</span><span class="na">setData</span><span class="p">(</span><span class="s">"html"</span><span class="p">,</span><span class="w"> </span><span class="n">RangedDataTransformation</span><span class="p">.</span><span class="na">builder</span><span class="p">().</span><span class="na">addRange</span><span class="p">(</span><span class="n">offset</span><span class="p">,</span><span class="w"> </span><span class="n">length</span><span class="p">).</span><span class="na">build</span><span class="p">());</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>The following example creates a child trace and sets a new datastream with dataType <code class="docutils literal notranslate"><span class="pre">raw</span></code> on it, by setting a ranged
|
||||
data transformation with two ranges:</p>
|
||||
<div class="highlight-java notranslate"><div class="highlight"><pre><span></span><span class="n">trace</span><span class="p">.</span><span class="na">newChild</span><span class="p">(</span><span class="n">format</span><span class="p">(</span><span class="s">"lineNumber %d"</span><span class="p">,</span><span class="w"> </span><span class="n">lineNumber</span><span class="p">),</span><span class="w"> </span><span class="n">child</span><span class="w"> </span><span class="o">-></span><span class="w"> </span><span class="p">{</span>
|
||||
<span class="w"> </span><span class="n">child</span><span class="p">.</span><span class="na">setData</span><span class="p">(</span><span class="s">"raw"</span><span class="p">,</span><span class="w"> </span><span class="n">RangedDataTransformation</span><span class="p">.</span><span class="na">builder</span><span class="p">()</span>
|
||||
<span class="w"> </span><span class="p">.</span><span class="na">addRange</span><span class="p">(</span><span class="mi">10</span><span class="p">,</span><span class="w"> </span><span class="mi">20</span><span class="p">)</span>
|
||||
<span class="w"> </span><span class="p">.</span><span class="na">addRange</span><span class="p">(</span><span class="mi">50</span><span class="p">,</span><span class="w"> </span><span class="mi">30</span><span class="p">)</span>
|
||||
<span class="w"> </span><span class="p">.</span><span class="na">build</span><span class="p">());</span>
|
||||
<span class="p">});</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
</section>
|
||||
<section id="blobs">
|
||||
<h3>Blobs<a class="headerlink" href="#blobs" title="Permalink to this heading"></a></h3>
|
||||
<p>It is not always possible to create a transormation for the data that has to be
|
||||
added to a trace. For example the data is a result of a computation, and not
|
||||
a direct subset of another data stream..</p>
|
||||
<p>The following examples show how to creates a new data stream of dataType <code class="docutils literal notranslate"><span class="pre">raw</span></code> on a trace.</p>
|
||||
<p>In case all data is stored in a <code class="docutils literal notranslate"><span class="pre">byte[]</span></code>, we can add the byte array to the data stream with:</p>
|
||||
<div class="highlight-java notranslate"><div class="highlight"><pre><span></span><span class="kd">final</span><span class="w"> </span><span class="kt">byte</span><span class="o">[]</span><span class="w"> </span><span class="n">rawBytes</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="p">{.....};</span>
|
||||
<span class="n">trace</span><span class="p">.</span><span class="na">setData</span><span class="p">(</span><span class="s">"raw"</span><span class="p">,</span><span class="w"> </span><span class="n">writer</span><span class="w"> </span><span class="o">-></span><span class="w"> </span><span class="n">writer</span><span class="p">.</span><span class="na">write</span><span class="p">(</span><span class="n">rawBytes</span><span class="p">));</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>Alternatively, if the data is available in an <code class="docutils literal notranslate"><span class="pre">InputStream</span></code> the data can be added with:</p>
|
||||
<div class="highlight-java notranslate"><div class="highlight"><pre><span></span><span class="kd">final</span><span class="w"> </span><span class="n">InputStream</span><span class="w"> </span><span class="n">inputStream</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="p">...;</span>
|
||||
<span class="n">trace</span><span class="p">.</span><span class="na">setData</span><span class="p">(</span><span class="s">"raw"</span><span class="p">,</span><span class="w"> </span><span class="n">inputStream</span><span class="p">);</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
</section>
|
||||
</section>
|
||||
<section id="specifying-system-resources">
|
||||
<h2>Specifying system resources<a class="headerlink" href="#specifying-system-resources" title="Permalink to this heading"></a></h2>
|
||||
<p>In the <code class="docutils literal notranslate"><span class="pre">PluginInfo</span></code> you can specify <strong>maximum</strong> system resource metrics for a plugin. These are used for scaling the
|
||||
number of pods as described <a class="reference internal" href="../concepts/kubernetes_autoscaling.html"><span class="doc">here</span></a>. To run a plugin with 0.5 cpu (=
|
||||
0.5 vCPU/Core/hyperthread) and 1 gb memory, for example, the following configuration can be added to <code class="docutils literal notranslate"><span class="pre">PluginInfo</span></code>:</p>
|
||||
<div class="highlight-java notranslate"><div class="highlight"><pre><span></span><span class="n">PluginInfo</span><span class="p">.</span><span class="na">builderFor</span><span class="p">(</span><span class="k">this</span><span class="p">)</span>
|
||||
<span class="w"> </span><span class="p">...</span>
|
||||
<span class="w"> </span><span class="p">.</span><span class="na">pluginResources</span><span class="p">(</span><span class="n">PluginResources</span><span class="p">.</span><span class="na">builder</span><span class="p">()</span>
|
||||
<span class="w"> </span><span class="p">.</span><span class="na">maximumCpu</span><span class="p">(</span><span class="mf">0.5f</span><span class="p">)</span>
|
||||
<span class="w"> </span><span class="p">.</span><span class="na">maximumMemory</span><span class="p">(</span><span class="mi">1000</span><span class="p">)</span>
|
||||
<span class="w"> </span><span class="p">.</span><span class="na">build</span><span class="p">())</span>
|
||||
<span class="w"> </span><span class="p">.</span><span class="na">build</span><span class="p">();</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
</section>
|
||||
<section id="deferred-extraction-plugins">
|
||||
<span id="java-snippets-deferred"></span><h2>Deferred Extraction Plugins<a class="headerlink" href="#deferred-extraction-plugins" title="Permalink to this heading"></a></h2>
|
||||
<p>Using a deferred plugin requires inheriting the <code class="docutils literal notranslate"><span class="pre">DeferredExtractionPlugin</span></code> base class. This allows access to
|
||||
a <code class="docutils literal notranslate"><span class="pre">TraceSearcher</span></code> object in the process function to search for traces.</p>
|
||||
<div class="highlight-java notranslate"><div class="highlight"><pre><span></span><span class="kd">public</span><span class="w"> </span><span class="kd">class</span> <span class="nc">ExampleDeferred</span><span class="w"> </span><span class="kd">extends</span><span class="w"> </span><span class="n">DeferredExtractionPlugin</span><span class="w"> </span><span class="p">{</span>
|
||||
<span class="w"> </span><span class="nd">@Override</span>
|
||||
<span class="w"> </span><span class="kd">public</span><span class="w"> </span><span class="n">PluginInfo</span><span class="w"> </span><span class="nf">pluginInfo</span><span class="p">();</span>
|
||||
|
||||
<span class="w"> </span><span class="nd">@Override</span>
|
||||
<span class="w"> </span><span class="kd">public</span><span class="w"> </span><span class="kt">void</span><span class="w"> </span><span class="nf">process</span><span class="p">(</span><span class="kd">final</span><span class="w"> </span><span class="n">Trace</span><span class="w"> </span><span class="n">trace</span><span class="p">,</span><span class="w"> </span><span class="kd">final</span><span class="w"> </span><span class="n">ExtractionContext</span><span class="w"> </span><span class="n">context</span><span class="p">,</span>
|
||||
<span class="w"> </span><span class="kd">final</span><span class="w"> </span><span class="n">TraceSearcher</span><span class="w"> </span><span class="n">searcher</span><span class="p">)</span><span class="w"> </span><span class="p">{</span>
|
||||
<span class="w"> </span><span class="kd">final</span><span class="w"> </span><span class="n">SearchResult</span><span class="w"> </span><span class="n">result</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">searcher</span><span class="p">.</span><span class="na">search</span><span class="p">(</span><span class="s">"file.extension=asc"</span><span class="p">,</span><span class="w"> </span><span class="mi">10</span><span class="p">);</span>
|
||||
<span class="w"> </span><span class="p">}</span>
|
||||
<span class="p">}</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>The <code class="docutils literal notranslate"><span class="pre">search</span></code> method accepts a HQL query and a count, which represents the maximum number of traces to return. It may
|
||||
be useful to specifically search for traces from the image being extracted. Add <code class="docutils literal notranslate"><span class="pre">"image:"</span> <span class="pre">+</span> <span class="pre">trace.get("image")</span></code> to
|
||||
your query. The query of the provided example could be extended like this:
|
||||
<code class="docutils literal notranslate"><span class="pre">"file.extension</span> <span class="pre">=</span> <span class="pre">asc</span> <span class="pre">AND</span> <span class="pre">image:"</span> <span class="pre">+</span> <span class="pre">trace.get("image")</span></code>.</p>
|
||||
<p>The traces contained in the <code class="docutils literal notranslate"><span class="pre">SearchResult</span></code> are returned as a stream.</p>
|
||||
<div class="highlight-java notranslate"><div class="highlight"><pre><span></span><span class="kd">final</span><span class="w"> </span><span class="n">Stream</span><span class="o"><</span><span class="n">Trace</span><span class="o">></span><span class="w"> </span><span class="n">stream</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">result</span><span class="p">.</span><span class="na">getTraces</span><span class="p">();</span>
|
||||
<span class="n">stream</span><span class="p">.</span><span class="na">limit</span><span class="p">(</span><span class="mi">5</span><span class="p">);</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
</section>
|
||||
<section id="logging">
|
||||
<h2>Logging<a class="headerlink" href="#logging" title="Permalink to this heading"></a></h2>
|
||||
<p>The logging is provided by Log4j 2 with a SLF4J binding. The Log4j 2 SLF4J binding allows applications coded to the
|
||||
SLF4J API to use Log4j 2 as the implementation.</p>
|
||||
<section id="usage">
|
||||
<h3>Usage<a class="headerlink" href="#usage" title="Permalink to this heading"></a></h3>
|
||||
<p>Here is an example illustrating how to log something with SLF4J. It begins by getting a logger with the name “LOG”. This
|
||||
logger is in turn used to log the message <code class="docutils literal notranslate"><span class="pre">I'm</span> <span class="pre">logging</span> <span class="pre">a</span> <span class="pre">variable</span> <span class="pre">1234!</span></code>.</p>
|
||||
<div class="highlight-java notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span><span class="w"> </span><span class="nn">org.slf4j.Logger</span><span class="p">;</span>
|
||||
<span class="kn">import</span><span class="w"> </span><span class="nn">org.slf4j.LoggerFactory</span><span class="p">;</span>
|
||||
|
||||
<span class="kd">public</span><span class="w"> </span><span class="kd">class</span> <span class="nc">Example</span><span class="w"> </span><span class="p">{</span>
|
||||
<span class="w"> </span><span class="kd">private</span><span class="w"> </span><span class="kd">static</span><span class="w"> </span><span class="kd">final</span><span class="w"> </span><span class="n">Logger</span><span class="w"> </span><span class="n">LOG</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">LoggerFactory</span><span class="p">.</span><span class="na">getLogger</span><span class="p">(</span><span class="n">Example</span><span class="p">.</span><span class="na">class</span><span class="p">);</span>
|
||||
|
||||
<span class="w"> </span><span class="kd">public</span><span class="w"> </span><span class="kt">void</span><span class="w"> </span><span class="nf">example</span><span class="p">()</span><span class="w"> </span><span class="p">{</span>
|
||||
<span class="w"> </span><span class="kd">final</span><span class="w"> </span><span class="kt">int</span><span class="w"> </span><span class="n">aNumber</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">1234</span><span class="p">;</span>
|
||||
<span class="w"> </span><span class="c1">// logs to console: I'm logging a variable 1234!</span>
|
||||
<span class="w"> </span><span class="n">LOG</span><span class="p">.</span><span class="na">info</span><span class="p">(</span><span class="s">"I'm logging a variable {}!"</span><span class="p">,</span><span class="w"> </span><span class="n">aNumber</span><span class="p">);</span>
|
||||
<span class="w"> </span><span class="p">}</span>
|
||||
<span class="p">}</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
</section>
|
||||
<section id="customize-logging">
|
||||
<h3>Customize logging<a class="headerlink" href="#customize-logging" title="Permalink to this heading"></a></h3>
|
||||
<p>It’s easy to change the logging format with a file called <code class="docutils literal notranslate"><span class="pre">log4j2.xml</span></code>. If desired, this file must be in the <code class="docutils literal notranslate"><span class="pre">resources</span></code>
|
||||
folder, for example <code class="docutils literal notranslate"><span class="pre">src/main/resources/log4j2.xml</span></code></p>
|
||||
<div class="highlight-xml notranslate"><div class="highlight"><pre><span></span><span class="cp"><?xml version="1.0" encoding="UTF-8"?></span>
|
||||
<span class="nt"><configuration></span>
|
||||
<span class="w"> </span><span class="nt"><appenders></span>
|
||||
<span class="w"> </span><span class="nt"><console</span><span class="w"> </span><span class="na">name=</span><span class="s">"stdout"</span><span class="w"> </span><span class="na">target=</span><span class="s">"SYSTEM_OUT"</span><span class="nt">></span>
|
||||
<span class="w"> </span><span class="nt"><patternLayout</span>
|
||||
<span class="w"> </span><span class="na">pattern=</span><span class="s">"%-5p|%d{yyyy-MM-dd HH:mm:ss}|%-20.20t|%-32.32c{1}|%m%n"</span><span class="nt">/></span>
|
||||
<span class="w"> </span><span class="nt"></console></span>
|
||||
<span class="w"> </span><span class="nt"></appenders></span>
|
||||
<span class="w"> </span><span class="nt"><loggers></span>
|
||||
<span class="w"> </span><span class="nt"><root</span><span class="w"> </span><span class="na">level=</span><span class="s">"info"</span><span class="nt">></span>
|
||||
<span class="w"> </span><span class="nt"><appenderRef</span><span class="w"> </span><span class="na">ref=</span><span class="s">"stdout"</span><span class="nt">/></span>
|
||||
<span class="w"> </span><span class="nt"></root></span>
|
||||
<span class="w"> </span><span class="nt"></loggers></span>
|
||||
<span class="nt"></configuration></span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<div class="admonition warning">
|
||||
<p class="admonition-title">Warning</p>
|
||||
<p>Be careful with logging sensitive information.</p>
|
||||
</div>
|
||||
<div class="admonition note">
|
||||
<p class="admonition-title">Note</p>
|
||||
<p>More information about customizing the logging can be found <a class="reference external" href="https://logging.apache.org/log4j/2.x">here</a>.</p>
|
||||
</div>
|
||||
<div class="admonition note">
|
||||
<p class="admonition-title">Note</p>
|
||||
<p>The default logger is pre-configured to log <cite>INFO</cite> to <cite>STDOUT</cite> (see the configuration above)</p>
|
||||
</div>
|
||||
<div class="admonition note">
|
||||
<p class="admonition-title">Note</p>
|
||||
<p>Log4j 2 supports various logging formats, including xml, yaml, json, properties, etc.
|
||||
Currently, only the xml format is supported.</p>
|
||||
</div>
|
||||
<div class="admonition note">
|
||||
<p class="admonition-title">Note</p>
|
||||
<p>Contact your Hansken administrator for more information on where to find logs for your Hansken environment.</p>
|
||||
</div>
|
||||
</section>
|
||||
</section>
|
||||
<section id="experimental-feature-adding-previews-to-a-trace">
|
||||
<h2>[EXPERIMENTAL FEATURE] Adding previews to a trace<a class="headerlink" href="#experimental-feature-adding-previews-to-a-trace" title="Permalink to this heading"></a></h2>
|
||||
<div class="admonition warning">
|
||||
<p class="admonition-title">Warning</p>
|
||||
<p>This is an experimental feature, which might change or get removed in future releases.</p>
|
||||
</div>
|
||||
<p>Example:</p>
|
||||
<div class="highlight-java notranslate"><div class="highlight"><pre><span></span><span class="kd">public</span><span class="w"> </span><span class="kd">class</span> <span class="nc">ExamplePlugin</span><span class="w"> </span><span class="kd">extends</span><span class="w"> </span><span class="n">ExtractionPlugin</span><span class="w"> </span><span class="p">{</span>
|
||||
<span class="w"> </span><span class="nd">@Override</span>
|
||||
<span class="w"> </span><span class="kd">public</span><span class="w"> </span><span class="n">PluginInfo</span><span class="w"> </span><span class="nf">pluginInfo</span><span class="p">();</span>
|
||||
|
||||
<span class="w"> </span><span class="nd">@Override</span>
|
||||
<span class="w"> </span><span class="kd">public</span><span class="w"> </span><span class="kt">void</span><span class="w"> </span><span class="nf">process</span><span class="p">(</span><span class="kd">final</span><span class="w"> </span><span class="n">Trace</span><span class="w"> </span><span class="n">trace</span><span class="p">,</span><span class="w"> </span><span class="kd">final</span><span class="w"> </span><span class="n">DataContext</span><span class="w"> </span><span class="n">context</span><span class="p">)</span><span class="w"> </span><span class="p">{</span>
|
||||
<span class="w"> </span><span class="kd">final</span><span class="w"> </span><span class="kt">byte</span><span class="o">[]</span><span class="w"> </span><span class="n">previewData</span><span class="p">;</span>
|
||||
<span class="w"> </span><span class="c1">// set the preview data for the image/png MIME-type</span>
|
||||
<span class="w"> </span><span class="n">trace</span><span class="p">.</span><span class="na">set</span><span class="p">(</span><span class="s">"preview.image/png"</span><span class="p">,</span><span class="w"> </span><span class="n">previewData</span><span class="p">);</span>
|
||||
<span class="w"> </span><span class="n">trace</span><span class="p">.</span><span class="na">set</span><span class="p">(</span><span class="s">"preview.image/png"</span><span class="p">,</span><span class="w"> </span><span class="n">previewData</span><span class="p">);</span>
|
||||
<span class="w"> </span><span class="p">}</span>
|
||||
<span class="p">}</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
</section>
|
||||
</section>
|
||||
|
||||
|
||||
</div>
|
||||
</div>
|
||||
<footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer">
|
||||
<a href="packaging.html" class="btn btn-neutral float-left" title="Packaging" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
|
||||
<a href="testing.html" class="btn btn-neutral float-right" title="Using the Test Framework in Java" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
|
||||
</div>
|
||||
|
||||
<hr/>
|
||||
|
||||
<div role="contentinfo">
|
||||
<p>© Copyright 2020-2023 Netherlands Forensic Institute.</p>
|
||||
</div>
|
||||
|
||||
Built with <a href="https://www.sphinx-doc.org/">Sphinx</a> using a
|
||||
<a href="https://github.com/readthedocs/sphinx_rtd_theme">theme</a>
|
||||
provided by <a href="https://readthedocs.org">Read the Docs</a>.
|
||||
|
||||
|
||||
</footer>
|
||||
</div>
|
||||
</div>
|
||||
</section>
|
||||
</div>
|
||||
<script>
|
||||
jQuery(function () {
|
||||
SphinxRtdTheme.Navigation.enable(true);
|
||||
});
|
||||
</script>
|
||||
|
||||
</body>
|
||||
</html>
|
||||
@@ -0,0 +1,289 @@
|
||||
<!DOCTYPE html>
|
||||
<html class="writer-html5" lang="en" >
|
||||
<head>
|
||||
<meta charset="utf-8" /><meta name="generator" content="Docutils 0.18.1: http://docutils.sourceforge.net/" />
|
||||
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
|
||||
<title>Using the Test Framework in Java — Hansken Extraction Plugins for plugin developers 0.6.3
|
||||
documentation</title>
|
||||
<link rel="stylesheet" href="../../_static/pygments.css" type="text/css" />
|
||||
<link rel="stylesheet" href="../../_static/css/theme.css" type="text/css" />
|
||||
<link rel="stylesheet" href="../../_static/wider_pages.css" type="text/css" />
|
||||
<!--[if lt IE 9]>
|
||||
<script src="../../_static/js/html5shiv.min.js"></script>
|
||||
<![endif]-->
|
||||
|
||||
<script data-url_root="../../" id="documentation_options" src="../../_static/documentation_options.js"></script>
|
||||
<script src="../../_static/doctools.js"></script>
|
||||
<script src="../../_static/sphinx_highlight.js"></script>
|
||||
<script src="../../_static/js/theme.js"></script>
|
||||
<link rel="index" title="Index" href="../../genindex.html" />
|
||||
<link rel="search" title="Search" href="../../search.html" />
|
||||
<link rel="next" title="How to debug an Extraction Plugin" href="debugging.html" />
|
||||
<link rel="prev" title="Java code snippets" href="snippets.html" />
|
||||
</head>
|
||||
|
||||
<body class="wy-body-for-nav">
|
||||
<div class="wy-grid-for-nav">
|
||||
<nav data-toggle="wy-nav-shift" class="wy-nav-side">
|
||||
<div class="wy-side-scroll">
|
||||
<div class="wy-side-nav-search" >
|
||||
|
||||
|
||||
|
||||
<a href="../../index.html" class="icon icon-home">
|
||||
Hansken Extraction Plugins for plugin developers
|
||||
</a>
|
||||
<div class="version">
|
||||
0.6.3
|
||||
|
||||
</div>
|
||||
<div role="search">
|
||||
<form id="rtd-search-form" class="wy-form" action="../../search.html" method="get">
|
||||
<input type="text" name="q" placeholder="Search docs" aria-label="Search docs" />
|
||||
<input type="hidden" name="check_keywords" value="yes" />
|
||||
<input type="hidden" name="area" value="default" />
|
||||
</form>
|
||||
</div>
|
||||
</div><div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu">
|
||||
<p class="caption" role="heading"><span class="caption-text">Contents:</span></p>
|
||||
<ul class="current">
|
||||
<li class="toctree-l1"><a class="reference internal" href="../introduction.html">Introduction</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../concepts.html">General concepts</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../spec.html">Extraction Plugin specifications</a></li>
|
||||
<li class="toctree-l1 current"><a class="reference internal" href="../java.html">Java</a><ul class="current">
|
||||
<li class="toctree-l2"><a class="reference internal" href="api_changelog.html">Java API Changelog</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="prerequisites.html">Prerequisites</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="packaging.html">Packaging</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="snippets.html">Java code snippets</a></li>
|
||||
<li class="toctree-l2 current"><a class="current reference internal" href="#">Using the Test Framework in Java</a><ul>
|
||||
<li class="toctree-l3"><a class="reference internal" href="#prerequisites">Prerequisites</a></li>
|
||||
<li class="toctree-l3"><a class="reference internal" href="#embedded-testing-versus-remote-testing">Embedded Testing versus Remote Testing</a><ul>
|
||||
<li class="toctree-l4"><a class="reference internal" href="#embedded-testing-example">Embedded Testing example</a></li>
|
||||
<li class="toctree-l4"><a class="reference internal" href="#remote-testing-example">Remote Testing example</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
</ul>
|
||||
</li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="debugging.html">How to debug an Extraction Plugin</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="javadoc.html">Javadoc</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../python.html">Python</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../examples.html">Examples</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../faq.html">Frequently Asked Questions</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../../contact.html">Contact</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="../../changes.html">Changelog</a></li>
|
||||
</ul>
|
||||
|
||||
</div>
|
||||
</div>
|
||||
</nav>
|
||||
|
||||
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"><nav class="wy-nav-top" aria-label="Mobile navigation menu" >
|
||||
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
|
||||
<a href="../../index.html">Hansken Extraction Plugins for plugin developers</a>
|
||||
</nav>
|
||||
|
||||
<div class="wy-nav-content">
|
||||
<div class="rst-content">
|
||||
<div role="navigation" aria-label="Page navigation">
|
||||
<ul class="wy-breadcrumbs">
|
||||
<li><a href="../../index.html" class="icon icon-home" aria-label="Home"></a></li>
|
||||
<li class="breadcrumb-item"><a href="../java.html">Java</a></li>
|
||||
<li class="breadcrumb-item active">Using the Test Framework in Java</li>
|
||||
<li class="wy-breadcrumbs-aside">
|
||||
<a href="../../_sources/dev/java/testing.md.txt" rel="nofollow"> View page source</a>
|
||||
</li>
|
||||
</ul>
|
||||
<hr/>
|
||||
</div>
|
||||
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
|
||||
<div itemprop="articleBody">
|
||||
|
||||
<section id="using-the-test-framework-in-java">
|
||||
<h1>Using the Test Framework in Java<a class="headerlink" href="#using-the-test-framework-in-java" title="Permalink to this heading"></a></h1>
|
||||
<p id="java-testing">This section assumes you use the same setup as is used in the
|
||||
<a class="reference external" href="https://git.eminjenv.nl/hanskaton/hansken-extraction-plugin-sdk/examples">Extraction Plugin Examples</a>.</p>
|
||||
<section id="prerequisites">
|
||||
<h2>Prerequisites<a class="headerlink" href="#prerequisites" title="Permalink to this heading"></a></h2>
|
||||
<p>Java Plugins can use the <code class="docutils literal notranslate"><span class="pre">plugin-super-pom</span></code> as maven parent, which makes sure the
|
||||
FLITS <a class="reference internal" href="../concepts/test_framework.html"><span class="doc">Test Framework</span></a> is included in the build.</p>
|
||||
<div class="highlight-xml notranslate"><div class="highlight"><pre><span></span><span class="nt"><parent></span>
|
||||
<span class="w"> </span><span class="nt"><groupId></span>org.hansken.plugin.extraction<span class="nt"></groupId></span>
|
||||
<span class="w"> </span><span class="nt"><artifactId></span>plugin-super-pom<span class="nt"></artifactId></span>
|
||||
<span class="w"> </span><span class="nt"><version></span>0.4.3<span class="nt"></version></span>
|
||||
<span class="nt"></parent></span>
|
||||
</pre></div>
|
||||
</div>
|
||||
</section>
|
||||
<section id="embedded-testing-versus-remote-testing">
|
||||
<h2>Embedded Testing versus Remote Testing<a class="headerlink" href="#embedded-testing-versus-remote-testing" title="Permalink to this heading"></a></h2>
|
||||
<p>There are ways of integration testing a plugin with the Test Framework:</p>
|
||||
<ul class="simple">
|
||||
<li><p><strong>Embedded testing</strong>: Here the plugin is run directly from a JUnit test without using the gRPC layer.</p></li>
|
||||
<li><p><strong>Remote testing</strong>: Here the test will start an ExtractionPluginServer that will serve the plugin. All communication
|
||||
is between server and plugin is done using gRPC.</p></li>
|
||||
</ul>
|
||||
<p>See below for an example of each way of testing.
|
||||
The <a class="reference external" href="https://git.eminjenv.nl/hanskaton/hansken-extraction-plugin-sdk/examples">Extraction Plugin Examples</a> contains many
|
||||
more examples.</p>
|
||||
<section id="embedded-testing-example">
|
||||
<h3>Embedded Testing example<a class="headerlink" href="#embedded-testing-example" title="Permalink to this heading"></a></h3>
|
||||
<p>Embedded tests can be run as a unit test.</p>
|
||||
<div class="highlight-java notranslate"><div class="highlight"><pre><span></span><span class="kn">import static</span><span class="w"> </span><span class="nn">nl.minvenj.nfi.flits.util.FlitsUtil.srcPath</span><span class="p">;</span>
|
||||
|
||||
<span class="kn">import</span><span class="w"> </span><span class="nn">java.nio.file.Path</span><span class="p">;</span>
|
||||
|
||||
<span class="kn">import</span><span class="w"> </span><span class="nn">org.hansken.plugin.extraction.api.ExtractionPlugin</span><span class="p">;</span>
|
||||
<span class="kn">import</span><span class="w"> </span><span class="nn">org.hansken.plugin.extraction.test.EmbeddedExtractionPluginFlits</span><span class="p">;</span>
|
||||
|
||||
<span class="cm">/**</span>
|
||||
<span class="cm"> * An integration test for MyPlugin.</span>
|
||||
<span class="cm"> */</span>
|
||||
<span class="kd">class</span> <span class="nc">MyPluginIT</span><span class="w"> </span><span class="kd">extends</span><span class="w"> </span><span class="n">EmbeddedExtractionPluginFlits</span><span class="w"> </span><span class="p">{</span>
|
||||
|
||||
<span class="w"> </span><span class="nd">@Override</span>
|
||||
<span class="w"> </span><span class="kd">protected</span><span class="w"> </span><span class="n">ExtractionPlugin</span><span class="w"> </span><span class="nf">pluginToTest</span><span class="p">()</span><span class="w"> </span><span class="p">{</span>
|
||||
<span class="w"> </span><span class="c1">// MyPlugin is a class implementing the ExtractionPlugin interface,</span>
|
||||
<span class="w"> </span><span class="c1">// with pluginInfo() and process() methods.</span>
|
||||
<span class="w"> </span><span class="k">return</span><span class="w"> </span><span class="k">new</span><span class="w"> </span><span class="n">MyPlugin</span><span class="p">();</span>
|
||||
<span class="w"> </span><span class="p">}</span>
|
||||
|
||||
<span class="w"> </span><span class="nd">@Override</span>
|
||||
<span class="w"> </span><span class="kd">public</span><span class="w"> </span><span class="n">Path</span><span class="w"> </span><span class="nf">testPath</span><span class="p">()</span><span class="w"> </span><span class="p">{</span>
|
||||
<span class="w"> </span><span class="c1">// Provide the folder containing input files. For examples, see</span>
|
||||
<span class="w"> </span><span class="c1">// https://git.eminjenv.nl/hanskaton/hansken-extraction-plugin-sdk/examples.</span>
|
||||
<span class="w"> </span><span class="k">return</span><span class="w"> </span><span class="n">srcPath</span><span class="p">(</span><span class="s">"integration/inputs"</span><span class="p">);</span>
|
||||
<span class="w"> </span><span class="p">}</span>
|
||||
|
||||
<span class="w"> </span><span class="nd">@Override</span>
|
||||
<span class="w"> </span><span class="kd">public</span><span class="w"> </span><span class="n">Path</span><span class="w"> </span><span class="nf">resultPath</span><span class="p">()</span><span class="w"> </span><span class="p">{</span>
|
||||
<span class="w"> </span><span class="c1">// Provide the folder containing result files. For examples, see</span>
|
||||
<span class="w"> </span><span class="c1">// https://git.eminjenv.nl/hanskaton/hansken-extraction-plugin-sdk/examples.</span>
|
||||
<span class="w"> </span><span class="k">return</span><span class="w"> </span><span class="n">srcPath</span><span class="p">(</span><span class="s">"integration/results"</span><span class="p">);</span>
|
||||
<span class="w"> </span><span class="p">}</span>
|
||||
|
||||
<span class="w"> </span><span class="nd">@Override</span>
|
||||
<span class="w"> </span><span class="kd">public</span><span class="w"> </span><span class="kt">boolean</span><span class="w"> </span><span class="nf">regenerate</span><span class="p">()</span><span class="w"> </span><span class="p">{</span>
|
||||
<span class="w"> </span><span class="c1">// Returning false means the test will fail if the result files don't</span>
|
||||
<span class="w"> </span><span class="c1">// match the outcome of the=++ test. Returning true means the test create</span>
|
||||
<span class="w"> </span><span class="c1">// new result files .</span>
|
||||
<span class="w"> </span><span class="k">return</span><span class="w"> </span><span class="kc">false</span><span class="p">;</span>
|
||||
<span class="w"> </span><span class="p">}</span>
|
||||
<span class="p">}</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
</section>
|
||||
<section id="remote-testing-example">
|
||||
<h3>Remote Testing example<a class="headerlink" href="#remote-testing-example" title="Permalink to this heading"></a></h3>
|
||||
<p>Note that the following example serves the plugin by using <code class="docutils literal notranslate"><span class="pre">ExtractionServer</span></code>.</p>
|
||||
<div class="highlight-java notranslate"><div class="highlight"><pre><span></span><span class="kn">import static</span><span class="w"> </span><span class="nn">nl.minvenj.nfi.flits.util.FlitsUtil.srcPath</span><span class="p">;</span>
|
||||
|
||||
<span class="kn">import</span><span class="w"> </span><span class="nn">java.nio.file.Path</span><span class="p">;</span>
|
||||
|
||||
<span class="kn">import</span><span class="w"> </span><span class="nn">org.hansken.plugin.extraction.runtime.grpc.client.ExtractionPluginClient</span><span class="p">;</span>
|
||||
<span class="kn">import</span><span class="w"> </span><span class="nn">org.hansken.plugin.extraction.runtime.grpc.server.ExtractionPluginServer</span><span class="p">;</span>
|
||||
<span class="kn">import</span><span class="w"> </span><span class="nn">org.hansken.plugin.extraction.test.plugins.DataTransformationsPlugin</span><span class="p">;</span>
|
||||
<span class="kn">import</span><span class="w"> </span><span class="nn">org.junit.jupiter.api.AfterAll</span><span class="p">;</span>
|
||||
<span class="kn">import</span><span class="w"> </span><span class="nn">org.junit.jupiter.api.BeforeAll</span><span class="p">;</span>
|
||||
|
||||
<span class="kd">public</span><span class="w"> </span><span class="kd">class</span> <span class="nc">RemoteTransformationPluginFlitsIT</span><span class="w"> </span><span class="kd">extends</span><span class="w"> </span><span class="n">RemoteExtractionPluginFlits</span><span class="w"> </span><span class="p">{</span>
|
||||
|
||||
<span class="w"> </span><span class="kd">private</span><span class="w"> </span><span class="kd">static</span><span class="w"> </span><span class="n">ExtractionPluginServer</span><span class="w"> </span><span class="n">_server</span><span class="p">;</span>
|
||||
<span class="w"> </span><span class="kd">private</span><span class="w"> </span><span class="kd">static</span><span class="w"> </span><span class="n">ExtractionPluginClient</span><span class="w"> </span><span class="n">_client</span><span class="p">;</span>
|
||||
|
||||
<span class="w"> </span><span class="nd">@BeforeAll</span>
|
||||
<span class="w"> </span><span class="kd">public</span><span class="w"> </span><span class="kd">static</span><span class="w"> </span><span class="kt">void</span><span class="w"> </span><span class="nf">init</span><span class="p">()</span><span class="w"> </span><span class="kd">throws</span><span class="w"> </span><span class="n">Exception</span><span class="w"> </span><span class="p">{</span>
|
||||
<span class="w"> </span><span class="kd">final</span><span class="w"> </span><span class="kt">int</span><span class="w"> </span><span class="n">port</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">8999</span><span class="p">;</span>
|
||||
|
||||
<span class="w"> </span><span class="c1">// Serve MyPlugin.</span>
|
||||
<span class="w"> </span><span class="c1">// MyPlugin is a class implementing the ExtractionPlugin interface, with PluginInfo and Process methods.</span>
|
||||
<span class="w"> </span><span class="n">_server</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">ExtractionPluginServer</span><span class="p">.</span><span class="na">serve</span><span class="p">(</span><span class="n">port</span><span class="p">,</span><span class="w"> </span><span class="n">MyPlugin</span><span class="p">::</span><span class="k">new</span><span class="p">);</span>
|
||||
|
||||
<span class="w"> </span><span class="c1">// Create an ExtractionPluginClient</span>
|
||||
<span class="w"> </span><span class="n">_client</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="k">new</span><span class="w"> </span><span class="n">ExtractionPluginClient</span><span class="p">(</span><span class="s">"localhost"</span><span class="p">,</span><span class="w"> </span><span class="n">_server</span><span class="p">.</span><span class="na">getListeningPort</span><span class="p">());</span>
|
||||
<span class="w"> </span><span class="p">}</span>
|
||||
|
||||
<span class="w"> </span><span class="nd">@AfterAll</span>
|
||||
<span class="w"> </span><span class="kd">public</span><span class="w"> </span><span class="kd">static</span><span class="w"> </span><span class="kt">void</span><span class="w"> </span><span class="nf">destruct</span><span class="p">()</span><span class="w"> </span><span class="p">{</span>
|
||||
<span class="w"> </span><span class="c1">// At the end of the test, make sure the server and client are closed.</span>
|
||||
<span class="w"> </span><span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="n">_server</span><span class="w"> </span><span class="o">!=</span><span class="w"> </span><span class="kc">null</span><span class="p">)</span><span class="w"> </span><span class="p">{</span>
|
||||
<span class="w"> </span><span class="n">_server</span><span class="p">.</span><span class="na">close</span><span class="p">();</span>
|
||||
<span class="w"> </span><span class="p">}</span>
|
||||
<span class="w"> </span><span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="n">_client</span><span class="w"> </span><span class="o">!=</span><span class="w"> </span><span class="kc">null</span><span class="p">)</span><span class="w"> </span><span class="p">{</span>
|
||||
<span class="w"> </span><span class="n">_client</span><span class="p">.</span><span class="na">close</span><span class="p">();</span>
|
||||
<span class="w"> </span><span class="p">}</span>
|
||||
<span class="w"> </span><span class="p">}</span>
|
||||
|
||||
<span class="w"> </span><span class="nd">@Override</span>
|
||||
<span class="w"> </span><span class="kd">public</span><span class="w"> </span><span class="n">Path</span><span class="w"> </span><span class="nf">testPath</span><span class="p">()</span><span class="w"> </span><span class="p">{</span>
|
||||
<span class="w"> </span><span class="c1">// Provide the folder containing input files. For examples, see https://git.eminjenv.nl/hanskaton/hansken-extraction-plugin-sdk/examples.</span>
|
||||
<span class="w"> </span><span class="k">return</span><span class="w"> </span><span class="n">srcPath</span><span class="p">(</span><span class="s">"integration/inputs"</span><span class="p">);</span>
|
||||
<span class="w"> </span><span class="p">}</span>
|
||||
|
||||
<span class="w"> </span><span class="nd">@Override</span>
|
||||
<span class="w"> </span><span class="kd">public</span><span class="w"> </span><span class="n">Path</span><span class="w"> </span><span class="nf">resultPath</span><span class="p">()</span><span class="w"> </span><span class="p">{</span>
|
||||
<span class="w"> </span><span class="c1">// Provide the folder containing result files. For examples, see https://git.eminjenv.nl/hanskaton/hansken-extraction-plugin-sdk/examples.</span>
|
||||
<span class="w"> </span><span class="k">return</span><span class="w"> </span><span class="n">srcPath</span><span class="p">(</span><span class="s">"integration/results"</span><span class="p">);</span>
|
||||
<span class="w"> </span><span class="p">}</span>
|
||||
|
||||
<span class="w"> </span><span class="nd">@Override</span>
|
||||
<span class="w"> </span><span class="kd">protected</span><span class="w"> </span><span class="n">ExtractionPluginClient</span><span class="w"> </span><span class="nf">pluginToTest</span><span class="p">()</span><span class="w"> </span><span class="p">{</span>
|
||||
<span class="w"> </span><span class="c1">// For Remote testing, the test won't talk directly to the plugin, but to the client.</span>
|
||||
<span class="w"> </span><span class="c1">// The client will use gRPC to communicate with the served plugin.</span>
|
||||
<span class="w"> </span><span class="k">return</span><span class="w"> </span><span class="n">_client</span><span class="p">;</span>
|
||||
<span class="w"> </span><span class="p">}</span>
|
||||
|
||||
<span class="w"> </span><span class="nd">@Override</span>
|
||||
<span class="w"> </span><span class="kd">public</span><span class="w"> </span><span class="kt">boolean</span><span class="w"> </span><span class="nf">regenerate</span><span class="p">()</span><span class="w"> </span><span class="p">{</span>
|
||||
<span class="w"> </span><span class="c1">// Returning false means the test will fail if the result files don't match the outcome of the test.</span>
|
||||
<span class="w"> </span><span class="c1">// Returning true means the test create new result files.</span>
|
||||
<span class="w"> </span><span class="k">return</span><span class="w"> </span><span class="kc">false</span><span class="p">;</span>
|
||||
<span class="w"> </span><span class="p">}</span>
|
||||
<span class="p">}</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<div class="admonition note">
|
||||
<p class="admonition-title">Note</p>
|
||||
<p>Note that with a <cite>RemoteTransformationPluginFlitsIT</cite> it is possible to start a docker image of a plugin and
|
||||
run remote tests against it using your own testdata. To do this, simply remove all <code class="docutils literal notranslate"><span class="pre">_server</span></code> code and manually start
|
||||
your plugin in a docker container. Then run the test against the docker container by setting the correct url and
|
||||
port, presumably <code class="docutils literal notranslate"><span class="pre">new</span> <span class="pre">ExtractionPluginClient("localhost",</span> <span class="pre">8999)</span></code>.</p>
|
||||
</div>
|
||||
</section>
|
||||
</section>
|
||||
</section>
|
||||
|
||||
|
||||
</div>
|
||||
</div>
|
||||
<footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer">
|
||||
<a href="snippets.html" class="btn btn-neutral float-left" title="Java code snippets" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
|
||||
<a href="debugging.html" class="btn btn-neutral float-right" title="How to debug an Extraction Plugin" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
|
||||
</div>
|
||||
|
||||
<hr/>
|
||||
|
||||
<div role="contentinfo">
|
||||
<p>© Copyright 2020-2023 Netherlands Forensic Institute.</p>
|
||||
</div>
|
||||
|
||||
Built with <a href="https://www.sphinx-doc.org/">Sphinx</a> using a
|
||||
<a href="https://github.com/readthedocs/sphinx_rtd_theme">theme</a>
|
||||
provided by <a href="https://readthedocs.org">Read the Docs</a>.
|
||||
|
||||
|
||||
</footer>
|
||||
</div>
|
||||
</div>
|
||||
</section>
|
||||
</div>
|
||||
<script>
|
||||
jQuery(function () {
|
||||
SphinxRtdTheme.Navigation.enable(true);
|
||||
});
|
||||
</script>
|
||||
|
||||
</body>
|
||||
</html>
|
||||
Reference in New Issue
Block a user