Compound URI Guide

What is a compound URI?

A compund URI is a URI that contains multiple named inner URIs. It is 100% compatible with the IETF [RFC2396,RFC1738] URI specification and so can be used everywhere a URI can be used. A compound URI has the form

{scheme}:{type}+{arg}@{value}+{arg}@{value}+....

Where {scheme} is the URI scheme of the complete compound URI. {type} is an application specific type declaration and may itself be an escaped URI. {arg} is an argument name. {value} is an escaped inner URI.

Compound URI's can be used to nest URI's to arbitrary depth provided all inner URI's are correctly escaped. Therefore a compound URI can hold another compound URI as an argument value.

Compound URI manipulation

In order to be valid URI's a compound URI must be carefully escaped. The layer1 module provides a utility class org.ten60.netkernel.layer1.util.CompoundURIdentifier which can be used to add, remove and query the parts of a compound URI and which performs all necessary escaping.

Using Compound URI's with URA's

Compound URI's are the primary addressing scheme for invoking Active URA's. The NetKernel uses the URI arguments of a compound URI as the reference to real arguments used in a URA request. A URA request's arguments can be be either by reference or by value. A URA reccieves a compound URI as the primary key to it's invocation request. It queries the compound URI using a set of argument names, defined by convention, to obtain the URI of an argument. The URI of the argument is used to obtain the underlying request argument.

The convention for invoking a URA is to use the active: scheme with a type and proceeded by multiple URI arguments. These active URI's have the following form.

active:{type}+operand@{value}+operator@{value}+param@{value}....

where {type} is the public instruction name. That is {type} is identical to the value of an instr/type element in an idoc executing in the DPML runtime. The convention is to use a small set of standard argument names as follows

• operand - operand
• opt - operator
• param - parameter
• cwu - current working URI

These named arguments are purely a convention. Nothing prevents an accessor from being invoked with arbitrary URI argument names. In addition nothing prevents a URA being invoked with no arguments, so some accessor may us none, some or all of these arguments. The URA development guide explains how a URA can declare which arguments it requires and how the Kernel ensures requests comply with the declared interface of the URA.

URIs with the active: scheme are treated just like any other URI in that they can be cached and are resolved by the Module Manager to invocations of the accessors to process them.