If an endpoint has information within a local variable and needs
to pass that in a request then it cannot use the
addArgument(...) method because it has an
physical/object reference to the information, not a logical/URI reference.
In this case the endpoint should use the
method which creates and inserts a value-space,
containing the local variable, into the request context.
The use of a value-space to convert pass-by-value into pass-by-reference is best described by using an example. Again using the toUpper service, the following code:
String message = "Hi, this is a message"; request = context.createRequest("active:toUpper"); request.addArgumentByValue("operand", message);
results in the creation of a new transient space into which the
message is placed.
The space is told to resolve the identifier,
pbv:operand, and return the contents of the
variable when SOURCEd.
This means that a SOURCE request for the resource identified by
that enters this space will return the information in the endpoint's variable
The NKF takes two more steps. It adds a pass-by-reference argument name "operand" to the request and uses the identifier "pbv:operand" as the value. Second it inserts the value-space into the request context before issuing the request.
When the resolved endpoint requests the operand argument with the following code:
String text = context.source("arg:operand", String.class);
several levels of indirection are handled. As discussed in request assessment, when an endpoint uses the arg URI scheme the request actually uses the identifier that is the value of the named argument. Since this value is "pbv:operand" the SOURCE request will resolve in the transient value-space and the representation returned will be the object originally use in the requesting endpoint.
In summary, the SOURCE request for "arg:operand" is converted into a SOURCE request for "pbv:operand" which is resolved in the injected value-space to the inserted representation.
Because NetKernel converts pass-by-value into pass-by-reference then the result is cacheable and any descendent requests issued by the resolved endpoint can use the cached value.