eeml
Class DataOut

java.lang.Object
  java.lang.Thread
      eeml.DataOut

All Implemented Interfaces:

java.lang.Runnable

public class DataOut

extends java.lang.Thread

This is the class to use for making data available to remote environments/applications. It creates a 'server' object (based on Processing's network library) that sends data to remote clients that request your local EEML data. (See below for instructions on manual updates, in case a 'server' is not possible or desirable -- this is tailored specifically for use with Pachube).

Automatic updates on request

The normal way to use the DataOut object is asynchronous which means that once a DataOut object is constructed it invokes an onReceiveRequest() method every time it receives a request for data. You therefore must have a method void onReceiveRequest(DataOut d) in your application, and you would at this point normally update the values of your individual streamed data with the update() method. The onReceiveRequest method then automatically creates an EEML document with all relevant data and serves it to the requesting client.

 DataOut myDataOut = new DataOut(this, 5210);
 myDataOut.addData(0,"tag1,tag2,tag3");
 
 void onReceiveRequest(DataOut d){ 
    d.update(0, myVariable); // updates stream 0 with the value of myVariable.
 }
 

Manual updates only when required

If you are behind a firewall, don't have an open IP address, or want to update data only when necessary (e.g. only if a datastream state changes) then you can use the alternative form of the DataOut object, to update manually. In this case you would normally update the values of your individual streamed data with the update() method then update the EEML data using the updatePachube() method, which returns 200 unless there was a problem (in which case it returns other status codes (http://www.w3.org/Protocols/HTTP/HTRESP.html) and/or throws an exception).

 DataOut myDataOut = new DataOut(this, "FEED_URL", "API_KEY");  
 myDataOut.addData(0,"tag1,tag2,tag3");
 
 myDataOut.update(0, myVariable); // updates stream 0 with the value of myVariable.
 
 if (myDataOut.updatePachube() == 200){
 		// data was updated successfully.
 }
 

Using Pachube

To register on the Pachube website you would need to know the IP address of your serving machine and you would need to ensure that requests on your selected port are forwarded to the serving machine (unless you are using the manual updates version of the DataOut object, see above).

I.e. if your IP address is 100.100.100.100, and you have selected port 5250, then your serving IP address as registered on Pachube would be http://100.100.100.100:5250/

If your machine is on a local network, with an IP address of, say 192.168.0.5, then you would first have to find out the IP address of your router (as seen by the external world; for example 100.100.100.100), enable port forwarding on the router so that all traffic that comes to port 5250 is forwarded to the machine at 192.168.0.5. Then register the URL as http://100.100.100.100:5250/

 DataOut myDataOut = new DataOut(this, 5210);
 myDataOut.addData(0,"tag1,tag2,tag3");
 
 void onReceiveRequest(DataOut d){ 
 
    d.update(0, myVariable); // updates stream 0 with the value of myVariable.
 
 }
 

See Also:

addData(), update(int id, float value)

Field Summary

Fields inherited from class java.lang.Thread

MAX_PRIORITY, MIN_PRIORITY, NORM_PRIORITY

Constructor Summary

DataOut(processing.core.PApplet parent, int port)
When the object receives a request from a remote client it invokes the onReceiveRequest() method in your application where data streams can be updated prior to serving.

DataOut(processing.core.PApplet parent, java.lang.String updateURL, java.lang.String key)
DataOut object that enables manual updating of EEML data

Method Summary

void	addData(int id, java.lang.String tags) Set up a data stream with a particular id with comma-delimited tags.
void	addData(int id, java.lang.String tags, float min, float max) Set up a data stream with a particular id with comma-delimited tags and minimum and maximum values.
void	quit() Ignore.
void	run() Ignore.
java.lang.String	serverMessage() Returns the last message received from the requesting client.
void	setLocation(float lat, float lon, float ele) Set location data for this environment: ONLY latitude, longitude and elevation.
void	setLocation(java.lang.String exposure, java.lang.String domain, java.lang.String disposition) Sets location data for this environment: ONLY exposure ("outdoor"/"indoor"), domain ("physical"/"virtual"), disposition ("fixed"/"mobile") (See EEML specs for more info).
void	setLocation(java.lang.String exposure, java.lang.String domain, java.lang.String disposition, float lat, float lon, float ele) Sets location data for this environment, including exposure ("outdoor"/"indoor"), domain ("physical"/"virtual"), disposition ("fixed"/"mobile") and latitude, longitude and elevation.
void	setMaximum(int id, float maximum) Sets the "maximum" attribute for a particular data stream's value
void	setMinimum(int id, float minimum) Sets the "minimum" attribute for a particular data stream's value
void	setUnits(int id, java.lang.String unit_, java.lang.String symbol_, java.lang.String type_) Sets the unit element for a particular data stream's value.
void	update(int id, float value) Updates a particular data stream with a float value.
void	update(int id, java.lang.String value) Updates a particular data stream with a String value.
int	updatePachube() Used to PUT data to Pachube in order to update a feed (for example when your IP address is not externally accessible and/or you want to update your datastreams manually).

Methods inherited from class java.lang.Thread

activeCount, checkAccess, countStackFrames, currentThread, destroy, dumpStack, enumerate, getContextClassLoader, getName, getPriority, getThreadGroup, holdsLock, interrupt, interrupted, isAlive, isDaemon, isInterrupted, join, join, join, resume, setContextClassLoader, setDaemon, setName, setPriority, sleep, sleep, start, stop, stop, suspend, toString, yield

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

DataOut

public DataOut(processing.core.PApplet parent,
               int port)

When the object receives a request from a remote client it invokes the onReceiveRequest() method in your application where data streams can be updated prior to serving.

DataOut myDataOut = new DataOut(this, 5210);

Parameters:

parent - usually 'this'

port - port to serve on

DataOut

public DataOut(processing.core.PApplet parent,
               java.lang.String updateURL,
               java.lang.String key)

DataOut object that enables manual updating of EEML data

DataOut myDataOut = new DataOut(this, "URL_TO_UPDATE_TO", "YOUR_API_KEY");

Parameters:

parent - usually 'this'

updateURL - URL that was provided when the feed was registered

key - the Pachube API key used to access Pachube feeds (requires registration at pachube.com)

See Also:

DataOut(PApplet parent, int port)

Method Detail

addData

public void addData(int id,
                    java.lang.String tags)

Set up a data stream with a particular id with comma-delimited tags.

myDataOut.addData(0,"tag1,tag2,tag3");

Parameters:

id -

tags -

addData

public void addData(int id,
                    java.lang.String tags,
                    float min,
                    float max)

Set up a data stream with a particular id with comma-delimited tags and minimum and maximum values.

myDataOut.addData(0,"tag1,tag2,tag3",23.0,100.0);

Parameters:

id -

tags -

update

public void update(int id,
                   float value)

Updates a particular data stream with a float value.

d.update(3, 4.2);

Parameters:

id -

value -

update

public void update(int id,
                   java.lang.String value)

Updates a particular data stream with a String value.

d.update(0, "myName");

Parameters:

id -

value -

updatePachube

public int updatePachube()

Used to PUT data to Pachube in order to update a feed (for example when your IP address is not externally accessible and/or you want to update your datastreams manually). To see typical serve response codes see here: http://www.w3.org/Protocols/HTTP/HTRESP.html (200 is when everything goes right).

if (myDataOut.updatePachube() == 200){
     - server response indicates that the feed was successfully updated
 }

Returns:

See Also:

DataOut(PApplet parent, String updateURL, String key)

setLocation

public void setLocation(java.lang.String exposure,
                        java.lang.String domain,
                        java.lang.String disposition,
                        float lat,
                        float lon,
                        float ele)

Sets location data for this environment, including exposure ("outdoor"/"indoor"), domain ("physical"/"virtual"), disposition ("fixed"/"mobile") and latitude, longitude and elevation. (See EEML specs for more info).

d.setLocation("indoor", "physical", "fixed", 51.566742, -0.099373, 22.4);

Parameters:

exposure -

domain -

disposition -

lat -

lon -

ele -

setLocation

public void setLocation(java.lang.String exposure,
                        java.lang.String domain,
                        java.lang.String disposition)

Sets location data for this environment: ONLY exposure ("outdoor"/"indoor"), domain ("physical"/"virtual"), disposition ("fixed"/"mobile") (See EEML specs for more info).

d.setLocation("indoor", "physical", "fixed");

Parameters:

exposure -

domain -

disposition -

setLocation

public void setLocation(float lat,
                        float lon,
                        float ele)

Set location data for this environment: ONLY latitude, longitude and elevation. (See EEML specs for more info).

Parameters:

lat -

lon -

ele -

setMinimum

public void setMinimum(int id,
                       float minimum)

Sets the "minimum" attribute for a particular data stream's value

Parameters:

id -

minimum -

setMaximum

public void setMaximum(int id,
                       float maximum)

Sets the "maximum" attribute for a particular data stream's value

Parameters:

id -

maximum -

setUnits

public void setUnits(int id,
                     java.lang.String unit_,
                     java.lang.String symbol_,
                     java.lang.String type_)

Sets the unit element for a particular data stream's value.

d.setUnits(0, "Celsius","C","basicSI");

Parameters:

id -

unit_ -

symbol_ -

type_ -

serverMessage

public java.lang.String serverMessage()

Returns the last message received from the requesting client. Useful for parsing for the IP address of the remote client.

Returns:

run

public void run()

Ignore.

quit

public void quit()

Ignore.