WARNING: This server provides a static reference view of the NetKernel documentation. Links to dynamic content do not work. For the best experience we recommend you install NetKernel and view the documentation in the live system .

Endpoint
Name:Golden Thread Cut Listener Accessor
Description:listen for golden threads being cut
Id:layer1.GoldenThreadCutListener
Category:accessor
Identifier Syntax

Golden Thread Cut Listener Accessor is an accessor using Active URI syntax with the following base identifiers:

Base
active:addGoldenThreadCutListener
active:removeGoldenThreadCutListener

and the following arguments: (for more details on argument passing details see here)

ArgumentRulesTypingDescription
id
Mandatory
Representation (java.lang.String)Golden thread identifier regular expression
request
Mandatory
Representation (org.netkernel.layer0.nkf.INKFRequest, DOM)declarative request to issue when thread is cut
Request Verbs

The following verb is supported:

Verb
SOURCE
Response

The response representation of this accessor for SOURCE requests is unknown.

This accessor throws no documented exceptions.

Import Requirements

To use Golden Thread Cut Listener Accessor accessor you must import the module urn:com:1060research:www3:

<import>
  <uri>urn:com:1060research:www3</uri>
</import>

This accessor allows endpoints to register an interest in knowing when golden threads get cut. When a golden thread is cut the endpoint will be notified with a request containing the id of the thread that was cut.

Lifecycle

It often makes sense to register a golden thread listener on the postCommission of an endpoint and remove it on the preDecommission. This ensures the listener is always cleaned up and cannot lead to a leak.

It is also possible to add and remove cut listeners ad hoc.

Add returns

a boolean value to indicate the success of the operation.

Remove returns

a boolean value to indicate the success of the operation.

To remove a listener the registering endpoint must issue an active:removeGoldenThreadCutListener with identical arguments to the argument that were specified when it was registered with active:addGoldenThreadCutListener.

Semantics

Listeners can be registered on specific golden threads or on a regular expression that matches multiple golden threads. One synchronous SOURCE request will be issued for each matching thread that is cut.

The regular expression specified is a standard java regular expression as per java.util.regex.Pattern.

Callback request

When a golden thread is cut a request will be constructed using the declarative request specified as the request argument to the active:addGoldenThreadCutListener request. This request is issued into the calling space that is resolved when the request is added.

An optional argument argument can be added to the request which will specify the id of the cut golden thread. This is named as arg:id. For example:

<request>
  <identifier>active:myGoldenThreadCutListener</identifier>
  <argument name="goldenthread">arg:id</argument>
</request>

This declarative request will cause a SOURCE request of active:myGoldenThreadCutListener+goldenthread@<id of thread>