= Resource Endpoint =

[[PageOutline(2-3,Table of Contents,inline)]]

== Role of Resource Endpoints ==
The Resource Endpoint (REP) provides a standardised access to the sensors inside the test bed which are exposed as SENSEI Resources. The Resource Access Interface (RAI) is the standard RESTful interface provided to SENSEI users.

[[Image(SENSEI deployment.png)]]

Each sensor of the test bed will have a counterpart on the REP modelled as a Resource. One REP can accommodate more Resources. A router will take care that a REST call will be directed to the Resource the call concerns.

Once a method on a Resource is called, the call will be translated into the proprietary call the sensor island gateway is able to handle. This Gateway inside the test bed will forward the call to the desired sensor. 

[[Image(REP overview.png)]]

== Resource Provider's efforts ==

The REP is basically the **adapter to the SENSEI system that needs to be implemented**.
The Java REP reference implementation provides some help to Resource Providers showing an example using the Restlet framework.

The **REP class** provides a method **createInboundRoot()** in which the routing of REST requests is defined. In the example below all requests issued to **{REP_URL}/s/sensorName** are routed to the handler class **Sensor Type**

{{{
@Override
public synchronized Restlet createInboundRoot() {

	// Create a router Restlet that defines routes.
	Router router = new Router(getContext());
		
	// attach the RAI handler class
	String path = "/s/{sensorName}";
	Class<SensorType> handler = SensorType.class;
	router.attach(path, handler);
		
	return router;
}
}}}

The parameter sensor Name is taken from the URL used for the HTTP request so that the route can be used for temperature values as well as light values. In the first case the request would be http://{REP_URL}/s/temp in the light value case it would be http://{REP_URL}/s/light.

The different handling for temp and light is implemented in the **RAI handler** class called **Sensor Type** in the example code.

=== Resource Access Interface ===

The RAI methods are provided by the **RAI handler** which is attached to the REP. The **RAI handler** presents the Resource the REP exposes to the SENSEI Resource Users. 
In the example project a **com.sensinode.sensei.rep.rest.test.!SensorType.class** is used as an example for a RAI handler attached to the REP.

'''RAI GET''' requests are handled by the method **toXML()** provided by the class **Sensor Type**. This method reads the Observation & Measurement value from a file and returns in XML/RDF format.

{{{
@Get("xml")
public Representation toXml() {
	try {
		DomRepresentation representation = new DomRepresentation(
				MediaType.TEXT_XML);

		// read the Observation & Measurement value from the respective file
		String fileName = "./xml/sensors/" + sensorName + ".rdf";

		File file = new File(fileName);

		DocumentBuilderFactory dbf = DocumentBuilderFactory.newInstance();
		DocumentBuilder db = dbf.newDocumentBuilder();

		// Generate a DOM document
		Document doc = db.parse(file);
		doc.normalize();
		representation.setDocument(doc);

		// Returns the XML representation of this document.
		return representation;

	} catch (IOException e) {
		e.printStackTrace();
	} catch (ParserConfigurationException e) {
		e.printStackTrace();
	} catch (SAXException e) {
		e.printStackTrace();
	}
	return null;
}
}}}
 
For handling POST, PUT, DELETE and OPTION request you need to add methods with arbitrary names and annotate them with the appropriate Java annotations so that the Restlet framework will handle them accordingly. Make sure the method returns a value of type **org.restlet.representation.Representation**!

{{{
/**
 * Handle POST requests
 */
@Post
public Representation acceptItem(Representation entity) {}
}}}

=== Resource Publish Interface ===

Also part of the example code is the class **RPI Client** which provides the methods to publish and unpublish Resource Descriptions to Resource Directories.

*	public List<String> publishResourceDescription(String descriptionString)
*	public List<String> publishResourceDescription(!ResourceDescription desc)
*	public String updateResourceDescription(String resourceID, !ResourceDescription description)
*	public String deleteResourceDescription(List<String> resourceIDs)

On how to write Resource Descriptions please see section [[wiki:RpResDescription]]