Gotchas

This page holds a collection of gotchas, tips and hard won advice when working with NetKernel applications.

Markdown documentation unterminated <element> tags

When writing NetKernel book or endpoint documentation markup files, any xml element tags in the text must be either teminated or `quoted` with backticks.

This markup line:

2. Created a <rootspace> with public="false" (want to hide csv file from rest of system)

will cause the following exception to be reported in the NetKernel system log:

        org.xml.sax.SAXParseException
        The element type "rootspace" must be terminated by the matching end-tag "</rootspace>".

Test xpath expressions with active:fragmentHDS

Use the active:fragmentHDS resource in conjunction with the RequestTrace tool to experiment with xpath expressions (where the expression is supposed to return a single node). You need a org.netkernel.mod.hds space imported into my application space, and then inject a request into an application space, using other resources and test data available:

 <request>
  <identifier>active:fragmentHDS</identifier>
        <argument name="xpath"><literal type="string">/teamResults/teamResult[team='Liverpool']</literal></argument>
  <argument name="operand">
        <request>
          <identifier>active:HomeResults</identifier>
            <argument name="matches">active:MatchResults+season@2014-2015</argument>
        </request>
</argument>
</request>

Endpoint documentation

NetKernel automatically generates a documentation page for every space and endpoint from information provided in the module.xml file. These pages can be enhanced with additional content:

  1. to add a doc (referenced in the module’s etc/system/Docs.xml) for each endpoint you want to document, also specifying <category>doc accessor</category>
  2. adding {endpoint}MyEndpointUri{endpoint} macro to bring in the auto-generated endpoint documentation.

Also, if you add a doc for an endpoint (using the {endpoint .. {/endpoint}) macro, it will not show up properly in the Space Explorer until you rebuild the search index of the NK instance.

XUnit test space endpoints must be public

All endpoints in a NetKernel XUnit unit test space MUST BE PUBLIC! This includes any <import>ed spaces required for the tests. Private endpoints (with <private />) simply cannot be resolved by the external XUnit test manager, and your tests will fail mysteriously with Request Resolution Failure errors.

Exporting classes from a module

Exporting contents of jars from a module using the <system><classpath><export> must specify the correct regex to include all classes and other files you want to expose to other modules. eg:

  1. “com.foo.bar..*” for all java classes in the com.foo.bar package (and sub-packages).
  2. “com/foo/bar/..*” for java resource files of any type under the module file path com/foo/bar

The active:java resource cannot access classes from request superstack

The active:java language runtime endpoint does not get access to Netkernel’s superstack classloader (ie. access to classes via modules imported into the module containing the active:java endpoint). It only gets access to the local module lib/ folder and classes in the module src tree itself (unlike other language runtime endpoints like active:groovy).