Data Accessor Development

Data accessors provide gateway access to a set of resources. Typically a data accessor will implement a full URI scheme and service more than one type of request type.

According to the URI specification, a scheme designates a set of rules that defines the syntax and semantics of valid addresses. When a data accessor implements an entire scheme, it is responsible for parsing and interpreting the URI addresses. {What processing is provided by NetKernel when handling the address portion of the URI address?}

Because it implements an entire scheme, a suitable set of requests types must be supported. Typically, an accessor applies these semantics to the standard NetKernel request types:

• SOURCE: retrieve a representation of the resource at the given address.
• SINK: update the resource to reflect the information contained in the passed representation.
• NEW: create a new (null valued) resource at the location specified by the address. Note that in some cases creating a new resource can be an implicit part of a SINK operation.
• DELETE: remove the underlying resource at the location specified by the address.
• EXISTS: test to see if a resource is located at the specified address, return a boolean indicator.

This guide illustrates how to build a data accessor for a new scheme called transient:. First read the guide to building active accessors to learn how to write an accessor in Java. This guide expands on that material and discusses the enhancements required to create a data accessor.

transient: scheme

The transient: URI scheme provides in-memory storage for representations of resources. The URI address is used as a key to an in-memory cache. The supported logical operations place a representation in memory (SINK), retrieve a representation from memory (SOURCE), delete a representation from memory (DELETE), and determine if a representation is stored in memory (EXISTS). Examples of URI addresses that are supported include:

• transient:myResult.txt
• transient:/sessions/1/data.gif

Implementing transient:

Step 1 - declare class

As with active accessor development, create a subclass of org.ten60.netkernel.layer1.nkf.impl.NKFAccessorImpl located in the module urn:org:ten60:netkernel:ext:layer1, and provide implementations for the lifecycle methods. Because this example accessor implements transient storage, there is no work to be completed in the initialise() and destroy() methods.

package org.myDomain.myApp;
      
import java.util.HashMap;
import java.util.Map;
  
import org.ten60.netkernel.layer1.nkf.INKFConvenienceHelper;
import org.ten60.netkernel.layer1.nkf.INKFRequestReadOnly;
import org.ten60.netkernel.layer1.nkf.INKFResponse;
import org.ten60.netkernel.layer1.nkf.impl.NKFAccessorImpl;
import org.ten60.netkernel.layer1.representation.BooleanAspect;
  
import com.ten60.netkernel.urii.IURAspect;
import com.ten60.netkernel.urii.IURRepresentation;
  
public class TransientDataAccessor extends NKFAccessorImpl
{ private final static Map mResources = new HashMap();
  
  public TransientDataAccessor()
  { super(NOT_SAFE_FOR_CONCURRENT_USE, 
          INKFRequestReadOnly.RQT_SOURCE   | 
          INKFRequestReadOnly.RQT_SINK     | 
          INKFRequestReadOnly.RQT_DELETE   | 
          INKFRequestReadOnly.RQT_EXISTS
         );
  }
  ...
}

Step 2 - implement functionality

The processRequest(...) method is called when a request is received by the accessor. This method test the request type and calls an appropriate method depending on the request verb.

public void processRequest(INKFConvenienceHelper context) throws Exception
{ switch (context.getThisRequest().getRequestType())
  {
  case INKFRequestReadOnly.RQT_SINK:
    sink(context);
    break;
  case INKFRequestReadOnly.RQT_SOURCE:
    source(context);
    break;
  case INKFRequestReadOnly.RQT_DELETE:
    delete(context);
    break;
  case INKFRequestReadOnly.RQT_EXISTS:
    exists(context);
    break;
  default:
    throw new Exception("Unsupported Request Type");
  } 
}
  
protected void sink(INKFConvenienceHelper context) throws Exception
{ IURRepresentation rep = context.source(INKFRequestReadOnly.URI_SYSTEM);
  IURAspect aspect = (IURAspect) rep.getAspects().iterator().next();
  String path = context.getThisRequest().getURIWithoutFragment();
  mResources.put(path, aspect);
}
  
protected void source(INKFConvenienceHelper context) throws Exception
{ String path = context.getThisRequest().getURIWithoutFragment();
  IURAspect aspect = (IURAspect) mResources.get(path);
  if (null == aspect)
  { throw new Exception("Resource " + path + " not found.");
  }   
  else
  { INKFResponse resp = context.createResponseFrom(aspect);
    context.setResponse(resp);
  }
}
  
protected void delete(INKFConvenienceHelper context) throws Exception
{ String path = context.getThisRequest().getURIWithoutFragment();
  mResources.remove(path);
  IURAspect aspect = new BooleanAspect(true);
  INKFResponse resp = context.createResponseFrom(aspect);
  context.setResponse(resp);
}
  
protected void exists(INKFConvenienceHelper context) throws Exception
{ String path = context.getThisRequest().getURIWithoutFragment();
  boolean result = (null != mResources.get(path));
  BooleanAspect ba = new BooleanAspect(result);
  INKFResponse resp = context.createResponseFrom(ba);
  context.setResponse(resp);
}

The source() method uses the request URI as a key to locate a representation in the static map. If it find a representation, it is returned, otherwise an exception is thrown.

The delete() method uses the request URI as a key and asks the static map to delete that entry.

The exists() method uses the request URI as a key and determines if there is an entry in the static map at that key value.

Step 3 - register the accessor

The data accessor must be registered with a module in a manner that directs all requests for the scheme to this new accessor. This is accomplished with the following entry in the mapping section of module.xml: