A prototype space element, or prototype, is the resource oriented computing equivalent of an object-oriented class. A prototype declaration specifies a prototype space element within its hosting space. Within a client space an endpoint specification may refer to the prototype which will result in a physical endpoint being created within the client space that is a (possibly customized with parameters) instance of the prototype.
Typically prototype declarations are exposed by libraries as a way of providing definitions of overlays, transports and sometimes accessors. The result of using a prototype is no different from using a Java class - both create physical endpoints. However the prototype declaration abstracts the client from the implementation class and provides metadata declaration which allows parameters to customise the instantiation.
A prototype is declared in the host space within a library with a <prototype> tag within a space. The prototype tag contains an <id> tag which declares the prototypes unique identity within the host space, a <class> declaration tag which specifies the implementation Java class which will be constructed when a prototype is instantiated. It also contains a list of <parameter> tags which specify construction parameters.
Attributes on the parameter are as follows:
|name||This is the name of the parameter. It must be a suitable for a well formed XML element name as that is how it must be specified when a prototype is instantiated.|
|desc||A short single sentence description of the parameter.|
|type||Type defines how the value specified on instantiation is interpreted. It may have the values string, integer, long, float, double, boolean, element or identifier.|
|min||The minimum number of instances of this parameter. If omitted it defaults to "1".|
|max||The maximum number of instances of this parameter. If omitted it defaults to "1".|
|default||The default value for instances of this parameter. This is only really useful if max="1", min="0".|
The following parameter types deserve special attention:
|element||An XML fragment is expected within the parameter tag. This is passed to the instantiated endpoint as a org.w3c.dom.Document DOM document. The parameter tag itself is considered the document element.|
|identifier||The parameter tag may contain either a resource identifier string or an XML fragment. This makes the specification of parameters in a module definition syntactically equivalent to specifying arguments in declarative requests by allowing both XML literals and resource identifiers. See the Accessing parameter values section below for more details on accessing their values.|
For all other parameter types the text value of the tag element is used and parsed into the required primitive type.
For example, the Groovy language module includes the prototype declaration GroovyPrototype.
The GroovyPrototype defines two required and two optional parameters. The required parameters must be supplied when an endpoint is defined based on this prototype. For example, the following endpoint:
uses GroovyPrototype and specifies the grammar and script parameters as elements. The result is a new physical endpoint that is based on the GroovyPrototype, the specified Groovy script (identified in the script element) and the specified grammar (identified in the grammar element).
The use of a prototype instance will initiate resolution for the prototype declaration starting in the space hosting the instance. It is therefore essential that the host space imports the space that provides the prototype declaration so that it may be resolved.
Special consideration should be taken when instantiating prototypes that themselves have a space as a parameter (for example, they are an overlay which routes requests to a wrapped space). It is important to understand that the space providing the prototype declaration will not be resolvable if it is imported into the wrapped space of the prototype instance - since that space will only come into existence after the prototype is commissioned. Therefore to ensure the prototype boot-straps correctly the prototype declaration space must be imported into the primary host space of the prototype instance.
Inside an endpoint parameters are accessible via two mechanisms:
The parameters are exposed by the
getParametermethod available on all
standard endpoint implementations including accessors, transreptors, transports and overlays.
The class of object returned will depend upon the type specified in the declaration:
public Object getParameter(String aName) throws NKFException
Parameters of type identifier are exposed into the address space inside NKF. This means it is possible to SOURCE parameter and transrept their representations if necessary. The use of identifier parameters is common with configured overlays.
Document config = context.source("param:config", Document.class);
For a prototype to be useful outside the module in which it was defined the Java class which it specifies must be exposed by the classloader of that module. To do this ensure you have a classloader export definition: