Active Accessor Development

Active accessors provide functions in NetKernel, accepting zero or more parameters and supporting only SOURCE requests. This guides describes how to develop active accessors using Java and the NKF, the NetKernel Foundation API. Many active accessors may be implemented with a scripting language or DPML.

To create an accessor, extend the class org.ten60.netkernel.layer1.nkf.impl.NKFAccessorImpl located in the module urn:org:ten60:netkernel:ext:layer1, and provide implementations for the lifecycle methods.

LifeCycle

NetKernel determines when to load and unload your accessor' class, when to create and destroy instances, and when to call the processRequest(...) service method.

Class Lifecycle

NetKernel loads accessor classes using the accessor's module's classloader. Class loading occurs when NetKernel first determines that the accessor's services are needed. The class will remain in memory until the hosting module is decommissioned. Decommissioning occurs either:

• On hot restart,
• When a module has been modified as is reloaded, or when
• NetKernel terminates.

Class Instance Lifecycle

After NetKernel loads an accessor's class into memory it creates an instance of the accessor's class (an object) and calls methods on the instance based on a well-defined lifecycle. The phases of the lifecycle are:

• Creation,
• Service, and
• Destruction.

Creation

When NetKernel creates an instance of an accessor the no-argument constructor is called followed by a call to the initialise() method. The initialise() method will be allowed to complete before any other methods are called.

Constructor

The no-argument constructor must call super(...) to provide information to NFKAccessorImpl's constructor. Three pieces of information may be provided regarding:

• Creation cost, an integer, a relative value that indicates how expensive it is to create a representation using this accessor. This is used by the cache as a hint to help it determine how long to keep representations in memory.
• Thread Safety, a boolean, indicating if the accessor is capable of servicing concurrent service requests. For this parameter, use the constants SAFE_FOR_CONCURRENT_USE or NOT_SAFE_FOR_CONCURRENT_USE in the class NFKAcessorImpl to indicate the accessor's capabilities.
• Request Types, an integer containing bit-flags, a set of indicators that list the types of requests handled by the accessor (Use the constants RQT_SOURCE, RQT_SINK, RQT_EXISTS, RQT_DELETE, or RQT_NEW in the interface INKFRequestReadOnly to indicate the types of requests the accessor will processes) These constants can be combined with the Java OR operator ("|").

super(5, SAFE_FOR_CONCURRENT_USE, INKFRequestReadOnly.RQT_SOURCE);

super(SAFE_FOR_CONCURRENT_USE, INKFRequestReadOnly.RQT_SOURCE);

super(INKFRequestReadOnly.RQT_SOURCE | INKFRequestReadOnly.RQT_SINK);

initialise()

The initialise(...) is called by NetKernel after the instance is created and before it calls any other method. Use the initialise(...) method to establish operational context such as opening files, etc.

public void initialise(Container aContainer, ModuleDef aModuleDef)
{ ... 
}

Service

NetKernel requests the services of the accessor by calling the processRequest(...) method. For each invocation, NetKernel provides an instance of INKFConvenienceHelper.

public void processRequest(INKFConvenienceHelper context) 
{ ... 
}

The accessor must be coded in a thread-safe manner if it declared support for concurrent use by passing the SAFE_FOR_CONCURRENT_USE constant in the constructor's call to super(...).

Destruction

When NetKernel determines that it no longer wants the accessor class instance in memory, it will allow all requests to processRequest(...) to complete and will then call

public void destroy()
{ ...
}

Accessor Invocation

An active accessor can accept zero or more parameters. For example, an accessor that returns the current date and time requires no information to operate correctly. If parameters are required, they may be coded as fixed and required, fixed and optional, or they may be dynamically discovered at run time.

Parameters are passed in a request by name within the "param" address space. In the active scheme, parameters are segregated by the "+" symbol. For example, the following active URI specifies two parameters, operand and operator:

active:transform+operand@{uri}+operator@{uri}

An accessor may be coded in a way that it requires certain named parameters, will look for optional named parameters, or will request a list of all passed parameters and determine what to do with them at run time.

Fixed Parameters

An accessor that needs specific parameters will ask for them by name through methods on the context parameter. For example, if an accessor requires the operand parameter represented as an IAspectString object, it would use the following code in the processRequest(...) method:

IAspectString operand;
String        operandName = "this:param:operand";
Class         operandClass = IAspectString.class;
operand = (IAspectString)context.sourceAspect(operandName,operandClass);              

If the accessor requires a specific named parameter, it can test for its presence with:

IAspectString operand;
String        operandName = "this:param:operand";
Class         operandClass = IAspectString.class;

if (context.getThisRequest().argumentExists(operandName))
{ operand = (IAspectString)context.sourceAspect(operandName,operandClass);              
}
else
{ throw new Exception("Parameter " + operandName + " required, but not present");
}

Dynamic Parameters

For accessors that do not know the names of parameters that will be passed until runtime, use the context parameter to gather this information. For example, the following code queries the request to find the names of the parameters sent on the request:

Iterator iter = context.getThisRequest().getArguments();
while (iter.hasNext())
{ String operandName = iter.next();
  ...
}

Active accessors are usually mapped to Active URIs, active URIs have a syntax equivalent to a function call with named arguments.