tools/embedded_probe.html

---
active_crumb: Embedded Probe
layout: documentation
id: embedded_probe
---

<!--
 Licensed to the Apache Software Foundation (ASF) under one or more
 contributor license agreements.  See the NOTICE file distributed with
 this work for additional information regarding copyright ownership.
 The ASF licenses this file to You under the Apache License, Version 2.0
 (the "License"); you may not use this file except in compliance with
 the License.  You may obtain a copy of the License at

      http://www.apache.org/licenses/LICENSE-2.0

 Unless required by applicable law or agreed to in writing, software
 distributed under the License is distributed on an "AS IS" BASIS,
 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 See the License for the specific language governing permissions and
 limitations under the License.
-->

<div class="col-md-8 second-column">
    <section id="overview">
        <h2 class="section-title">Overview</h2>
        <p>
            Embedded probe allows to run data probe in the same JVM process as JVM-based client application.
        </p>
        <p>
            Typically, data probes are launched in their own independent JVMs. However, when a client application is
            itself a JVM-based process, it is sometimes preferable for performance reasons to to host
            a data model - and hence the data probe - in the same "client" JVM.
        </p>
        <p>
            In a standard processing flow, when data probe (with its deployed data models) is hosted in its own independent JVM,
            the request from
            the client application takes 4 network hops to go server, then to the data probe and back to the client application (see fig 1. below):
        </p>
        <figure>
            <img class="img-fluid" src="/images/emb_probe1.png" alt="">
            <figcaption><b>Fig 1.</b> Standard Processing Flow</figcaption>
        </figure>
        <p>
            When performing model unit testing or when client "application" can be combined with the data probe in a single JVM, the
            embedded probe mode provides significant performance advantage. Using embedded probe you can reduce number
            of network hops to 2 in a similar scenario (see fig 2.):
        </p>
        <figure>
            <img class="img-fluid" src="/images/emb_probe2.png" alt="">
            <figcaption><b>Fig 2.</b> Embedded Processing Flow</figcaption>
        </figure>
    </section>
    <section id="usage">
        <h2 class="section-title">Usage</h2>
        <p>
            Embedded probe support consists of the following types in <code>org.apache.nlpcraft.probe.embedded</code> package:
        </p>
        <ul>
            <li>
                <a
                    target="javadoc"
                    href="https://javadoc.io/static/org.apache.nlpcraft/nlpcraft/0.5.0/org/apache/nlpcraft/probe/embedded/NCEmbeddedProbe.html">
                    NCEmbeddedProbe
                </a> - Embedded probe main class.
            </li>
            <li>
                <a
                    target="javadoc"
                    href="https://javadoc.io/static/org.apache.nlpcraft/nlpcraft/0.5.0/org/apache/nlpcraft/probe/embedded/NCEmbeddedResult.html">
                    NCEmbeddedResult
                </a> - Processing result container since result is delivered as a local JVM call.
            </li>
        </ul>
        <p>
            Here's an code snippet from <a href="/examples/alarm_clock.html">Alarm Clock</a>
            example illustrating the usage of embedded probe together with NLPCraft test framework and JUnit 5:
        </p>
        <pre class="brush: java, highlight: [6, 18]">
public class AlarmTest {
    private NCTestClient cli;

    &#64;BeforeEach
    void setUp() throws NCException, IOException {
        NCEmbeddedProbe.start(AlarmModel.class);

        cli = new NCTestClientBuilder().newBuilder().build();

        cli.open("nlpcraft.alarm.ex");
    }

    &#64;AfterEach
    void tearDown() throws NCException, IOException {
        if (cli != null)
            cli.close();

        NCEmbeddedProbe.stop();
    }

    &#64;Test
    public void test() throws NCException, IOException {
        // Should be passed.
        assertTrue(cli.ask("Ping me in 3 minutes").isOk());
        assertTrue(cli.ask("Buzz me in an hour and 15mins").isOk());
        assertTrue(cli.ask("Set my alarm for 30s").isOk());
    }
}
        </pre>
        <p>
            Notes:
        </p>
        <ul>
            <li>
                Lines 6 and 18 show the embedded data probe start and stop as it's used in the unit tests.
            </li>
        </ul>
        <p>
            It's important to note that there are number of inherent limitations associated with embedded probe:
        </p>
        <ul>
            <li>
                Embedded probe is only available for JVM-based applications (and can be used with any JVM languages).
            </li>
            <li>
                There can be only one embedded probe per JVM.
            </li>
            <li>
                Once data probe is stopped and cannot be re-started again in the same JVM.
            </li>
            <li>
                Even though the caller can register local-JVM listener for the query results, these results
                will still be asynchronously delivered to the REST server in the usual manner so that other clients
                could fetch these results to maintain internal logging, tracing and metrics. If the client
                application hosting data model and its probe <i>is the only client</i> for that model it needs to cancel the
                request on the REST server after receiving a local-JVM callback to release associated
                resources on the REST server.
            </li>
        </ul>
    </section>
    <section id="examples">
        <h2 class="section-title">Examples</h2>
        <p>
            All <a target="github" href="https://github.com/apache/incubator-nlpcraft/tree/master/src/main/scala/org/apache/nlpcraft/examples">examples</a>
            shipped with NLPCraft utilize embedded probes in their unit tests.
        </p>
    </section>
</div>
<div class="col-md-2 third-column">
    <ul class="side-nav">
        <li class="side-nav-title">On This Page</li>
        <li><a href="#overview">Overview</a></li>
        <li><a href="#usage">Usage</a></li>
        <li><a href="#examples">Examples</a></li>
        {% include quick-links.html %}
    </ul>
</div>