What are resource identifier arguments?

Resource identifiers are treated opaquely by the NetKernel infrastructure but when they are constructed, matched and deconstructed by endpoints their sequence of characters is important. Typically sets of identifiers are handled by one endpoint and parts of the identifiers that are handled are free to vary. Some simple identifiers such as file: have a single degree of freedom which is the appended filesystem path. Other such as http: can several degrees of freedom such as the server, port, path and query parameters. The active URI scheme defines a software function which is passed arbitrary number of function arguments, each argument has a name and a nested resource identifier - each of these is a degree of freedom. We call these degrees of freedom arguments. Arguments are named substrings of a resource identifier.

Defining arguments

Arguments are defined when an identifier grammar is specified for an endpoint. The grammar specifies not only the structure of an identifier but which parts of it consitute it's arguments. Arguments need to be supplied when a request is constructed with declarative request technology and are parsed out by standard module accessors and made available within NKF during the processing of an endpoint.

Arguments as nested identifiers

Active URIs define their arguments as nested identifiers. (It also possible for BNF grammars to do the same though this is not common.) These are in effect resource references and not just substrings. This is called a pass-by-reference argument. Because this is a common pattern NetKernel provides some capabilities to make using arguments in this way easier:

Dereferencing nested identifier arguments in NKF

In the NetKernel Foundation API (NKF) argument substrings are available from from the INKFRequestReadOnly.getArgumentValue() method. However these arguments are also exposed into the local address space of the endpoint such that if a request is issued with the identifier arg:[argument name] then a request is issued with its identifier being the value of that argument.

For example if we create a toUpper endpoint and call it with the following identifier:

active:toUpper+operand@file:/a.txt

then inside the endpoint if we execute the following code:

String operand=context.source("arg:operand",String.class);

then we will retrieve the contents of the file:/a.txt as a string because a request was actually issued for file:/a.txt.

Pass-by-value and pass-by-request arguments

Both NKF and declarative requests support the concepts of pass-by-value and pass-by-request. These concepts built upon the fact that identifier arguments may be nested pass-by-reference identifiers.

Pass-by-value provides a mechanism for passing arguments that have a specific value representation rather than a reference to a resource. When issuing a request with a pass-by-value representation that representation is placed into a dynamically generated address space with a dynamically generated identifier. This space is then injected into the request scope of the issued request and the argument is given the value of the generated identifier. This structure means that when the argument is SOURCEd it retrieves that representation back as the response.

Pass-by-request is quite similar to pass-by-value but rather than putting a representation into the dynamically generated space a request is placed into the dynamically generated address space and referenced with a dynamically generated identifier. In an invoked endpoint, the request wil be executed whenever its argument is SOURCEd. The request that is passed need not be a SOURCE request. This pattern is useful for lazy evaluation patterns because that request will only actually be issued if the argument is SOURCEd.

Primary argument

Request verbs such as SINK, NEW, TRANSREPT and RESOLVE require a primary argument. The primary argument is not to be confused with identifier arguments. It is a representation that is passed inside the request to support the semantics of the request and does not effect the identifier. Declarative requests do support setting of this primary argument.