Transreptor Development Guide

Transreptor- what and why?

Accessors are free to create the simplest/easiest aspect of a URI in any representations that they create. If a client process of that representation wants it in a specialised form that it must be transrepresented, its representation must be changed. A Transreptor takes on representation of a resource and converts it into another representation with the desired aspect. See the URII package design for the class model behind these terms.

It is important that transreptors do not change the content or semantics of the resource but just the aspect/API that its in-memory representation exhibits.

Transreptors are invoked automatically by the NetKernel when the desired aspect in the result of a request isn't what an accessor produces. They can also be invoked when an explicit transpresententation is required by making a RQT_TRANSREPRESENT request.

Creating a Transreptor

Transreptors are created by implementing interface com.ten60.netkernel.urii.ITransrepresentor.

The supports method should be implemented to only return true when the transreptor is capable of transrepresenting aFrom to a representation that has an aspect which implements aTo.

The transrepresent method will only be invoked after the transreptor has declared it can support the operation. Implementation is obviously transreptor specific but but the once a result has been obtained the usual pattern is to create a org.ten60.netkernel.layer1.meta.DependencyMeta that has a dependency on aFrom and a cost. Then use an Aspect factory method to create a representation for the result:

    DependencyMeta meta = new DependencyMeta(aFrom,COST);
    return BooleanAspect.create(meta,bool);

Take a look at some of the shipped transreptors for examples.

Out of the Box

The transreptors that come shipped with Salisbury are:

org.ten60.netkernel.layer1.transrepresentation.BooleanSerializer from layer1 Takes a com.ten60.netkernel.urii.aspect.IAspectBoolean (an native java boolean) and converts it to a com.ten60.netkernel.urii.aspect.IAspectString (a java.lang.String)

org.ten60.netkernel.xml.transrepresentation.DOMXDAParser from ext_xml Parses XML into DOM Takes a com.ten60.netkernel.urii.aspect.IAspectBinaryStream (an native byte array or java.io.InputStream) and converts it to a com.ten60.netkernel.xml.representation.IXAspect (an org.w3c.dom and XDA)

org.ten60.netkernel.xml.transrepresentation.DOMXDASerializer from ext_xml Serializes DOM Takes a org.ten60.netkernel.xml.representation.IAspectDOM (an org.w3c.dom) and converts it to a com.ten60.netkernel.urii.aspect.IAspectReadableBinaryStream (an native byte array and java.io.InputStream)

org.ten60.netkernel.xml.transrepresentation.BinaryStreamToSAX from ext_xml Parses XML into SAX Events Takes a com.ten60.netkernel.urii.aspect.IAspectBinaryStream (an native byte array or java.io.InputStream) and converts it to a com.ten60.netkernel.xml.representation.IAspectSAX (an org.xml.sax.ContentHandler)

org.ten60.netkernel.xml.transrepresentation.SAXToBinaryStream from ext_xml Serializes SAX Events Takes a org.ten60.netkernel.xml.representation.IAspectSAX (an org.w3c.sax.ContentHandler) and converts it to a com.ten60.netkernel.urii.aspect.IAspectReadableBinaryStream (an native java.io.InputStream)

org.ten60.netkernel.xml.transrepresentation.CanonicalBooleanToBoolean from ext_xml Converts a Canonical Boolean XML Document into a native boolean Takes an org.ten60.netkernel.xml.representation.IAspectXDA (an XDA interface) and converts it to a com.ten60.netkernel.urii.aspect.IAspectBoolean (an native boolean)

org.ten60.netkernel.xml.transrepresentation.NVPToXML from ext_xml Builds a DOM from a Name Value Pair List Takes a org.ten60.netkernel.layer1.representation.IAspectNVP ( a set of name and value pairs ) and converts it to a com.ten60.netkernel.xml.representation.IXAspect (an org.w3c.dom and XDA)

org.ten60.transport.http.cookie.transrepresentation.CookieToXMLTransrepresentor from tpt_http Builds a DOM from a HTTP Cookie Takes a org.ten60.transport.http.cookie.representation.IAspectCookie (a javax.servlet.http.Cookie) and converts it to a org.ten60.netkernel.xml.representation.IXAspect (an org.w3c.dom and XDA)

org.ten60.transport.http.cookie.transrepresentation.XMLToCookieTransrepresentor from tpt_http Builds a HTTP Cookie from DOM Takes an org.ten60.netkernel.xml.representation.IAspectXDA (an XDA interface) and converts it to a org.ten60.transport.http.cookie.representation.IAspectCookie (a javax.servlet.http.Cookie)

org.ten60.transport.http.request.transrepresentation.HeaderToXMLTransrepresentor from tpt_http Builds a DOM from a HTTP Request Header Takes a org.ten60.transport.http.request.representation.IAspectRequestHeader (a org.mortbay.http.RequestHeader) and converts it to a org.ten60.netkernel.xml.representation.IXAspect (an org.w3c.dom and XDA)