edu.berkeley.guir.ptk.input
Class InputSource

java.lang.Object
  edu.berkeley.guir.ptk.PTK
      edu.berkeley.guir.ptk.input.InputSource

All Implemented Interfaces:

java.lang.Runnable

Direct Known Subclasses:

AudioInput, BusInput, CameraInput, CNNNewsInput, ContextInput, PhidgetsInterfaceKitInput, StockInput, TestInput, WeatherInput

public abstract class InputSource

extends PTK

implements java.lang.Runnable

Wrapper class for all input that enters the PTK. Application-specific input source classes extend this abstract class. The abstract method that input developers must implement is newInput. This method is responsible for getting the actual input data (i.e., from a sensor, Web page, etc.). The other methods in this class help wrap the input data in PTK objects, set up communication with the PTK server, and dispatch events to the server. Typically in a class that extends this class, you would include a main function that did the following:

1. Called the Input (or Input subclass) parameterized constructor.
2. Repeatedly call getThenSendInputData(), possibly with some specified waiting time in between calls (depending on the nature of the input).

Before running an input, the PTK server (PDiscovery) must be running at the IP address and port number specified in PTKConstants (SERVER_IP and SERVER_PORT). After this input is running, an output that has subscribed to get events with metadata included in this class (specified by the mds data field) will start to receive and handle events this input class provides. You are responsible for setting the Metadata mds field of this class. This is necessary so that outputs can subscribe to receive the input the subclasses of this class generates. They are also necessary because they are used by this class to register to the PTK server.

Author:

tmatthew Created: Mar 1, 2003

Field Summary

protected History	history Used only if there are Abstractors installed to aid in abstraction.
Metadata	mds The MetadataItems of the events this input source creates.
java.lang.String	my_id A unique ID String for this input.
java.lang.String	my_ip This is the IP address for the machine on which this input will run.
protected long	time_between_events

Fields inherited from class edu.berkeley.guir.ptk.PTK

debug, MAX_DEBUG, MED_DEBUG, MIN_DEBUG, NO_DEBUG

Constructor Summary

InputSource(Metadata mds, java.lang.String my_id)
This constructor is used when the input and application are not distributed.

InputSource(Metadata mds, java.lang.String my_id, Abstractor abs)
Use one of the constructors that take an Abstractor or array of Abstractors to do abstraction on the input side.

InputSource(Metadata mds, java.lang.String my_id, Abstractor[] abs)

InputSource(Metadata mds, java.lang.String my_id, java.lang.String my_ip)
Use this constructor whenever you instantiate an Input subclass object.

InputSource(Metadata mds, java.lang.String my_id, java.lang.String my_ip, Abstractor abs)
Use one of the constructors that take an Abstractor or array of Abstractors to do abstraction on the input side.

InputSource(Metadata mds, java.lang.String my_id, java.lang.String my_ip, Abstractor[] abs)

Method Summary

void	addMetadata(Metadata md) Adds the given metadata to this input's metadata, without replacing any of the existing metadata.
void	addMetadataItem(MetadataItem mi)
protected void	addMyMetadataToEvent(Events e) Adds this InputSource's metadata (set in constructor) to this event.
boolean	dispatchEvent(Event e) Dispatches given event to the PTK server, which will make sure any output applications that want the data will get it.
protected void	finalize() Unregisters this input upon Java garbage collection.
boolean	getAbstractThenSendInputEvent() Provides an alternate way of getting input from the input source to the PTK server, that involves abstracting the event first.
Metadata	getMetadata()
MetadataItem[]	getMetadataItemsAsArray()
boolean	getThenSendInputEvent() Provides the main way of getting input from the input source to the PTK server.
abstract Events	newInput() Gets input from the data source and fills a Template with it.
protected void	register(Metadata mds) Register this input source with the PTK Server.
void	run()
void	setMetadata(Metadata md) Replaces this input's metadata with the given metadata.
void	setTimeBetweenEvents(long milliseconds)
void	startInput()

Methods inherited from class edu.berkeley.guir.ptk.PTK

getMAX, getMED, getMIN, getNO, printDebug, printDebug, printError

Methods inherited from class java.lang.Object

clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

my_ip

public java.lang.String my_ip

This is the IP address for the machine on which this input will run.

my_id

public java.lang.String my_id

A unique ID String for this input. This must be unique per PTK server instance (Anind: correct?). Note: How to guarantee this is unique for all inputs?

mds

public Metadata mds

The MetadataItems of the events this input source creates. Each event has an array of MetadataItems that identify the event to other objects. For example, an output will subscribe to input events that a include certain set of MetadataItems. Outputs can subscribe to an events that include MetadataItems, but may also include other MetadataItems. This means that you can include as much detail as you wish in this field and outputs can subscribe to it without specifying all MetadataItems.

history

protected History history

Used only if there are Abstractors installed to aid in abstraction.

time_between_events

protected long time_between_events

Constructor Detail

InputSource

public InputSource(Metadata mds,
                   java.lang.String my_id,
                   java.lang.String my_ip)

Use this constructor whenever you instantiate an Input subclass object. This constructor registers the input to the PTK Server, which is required for the input to dispatch events. The MetadataItem array passed in includes the MetadataItems of the events created by this input source. The MetadataItems must be set so that outputs can subscribe to receive the input the subclasses of this class generates.

Parameters:

mds - The MetadataItems of the events created by this input source. Used to register to the PTK server and to identify events this class generates.

my_id - A unique id for this input source. Must be unique for all input sources registered to a single PTK Server instance. (Anind: true?)

my_ip - The ip address where this input class is running.

InputSource

public InputSource(Metadata mds,
                   java.lang.String my_id,
                   java.lang.String my_ip,
                   Abstractor abs)

Use one of the constructors that take an Abstractor or array of Abstractors to do abstraction on the input side. The default behavior, implemented by getAbstractThenSendEvent(), is to call each Abstractor to abstract the event and then dispatch one event for each.

InputSource

public InputSource(Metadata mds,
                   java.lang.String my_id,
                   java.lang.String my_ip,
                   Abstractor[] abs)

InputSource

public InputSource(Metadata mds,
                   java.lang.String my_id)

This constructor is used when the input and application are not distributed. No IP address is needed.

Parameters:

mds -

my_id -

InputSource

public InputSource(Metadata mds,
                   java.lang.String my_id,
                   Abstractor abs)

Use one of the constructors that take an Abstractor or array of Abstractors to do abstraction on the input side. The default behavior, implemented by getAbstractThenSendEvent(), is to call each Abstractor to abstract the event and then dispatch one event for each.

InputSource

public InputSource(Metadata mds,
                   java.lang.String my_id,
                   Abstractor[] abs)

Method Detail

run

public void run()

Specified by:

run in interface java.lang.Runnable

startInput

public void startInput()

getThenSendInputEvent

public boolean getThenSendInputEvent()

Provides the main way of getting input from the input source to the PTK server. This method calls newInput() to get new input data, puts the new input in a Template, creates an event that includes the Template by calling createEvent(), and dispatches the event to the PTK server by calling dispathEvent(). Returns true if all of these method calls were successful, false otherwise.

Returns:

boolean true if all this method is successful, false otherwise

getAbstractThenSendInputEvent

public boolean getAbstractThenSendInputEvent()

Provides an alternate way of getting input from the input source to the PTK server, that involves abstracting the event first. Only called if there are Abstractors installed in this.abstractors. Dispatches one event for each Abstractor. Does not allow chaining of Abstractors (i.e., the output from one Abstractor becomes the input of the next in the chain), which is allowed on the output application side. To change this, reimplement this method.

newInput

public abstract Events newInput()

Gets input from the data source and fills a Template with it. When template as full as the application developer wants, return it. The input data source could be a sensor, Web page, etc. This class must be implemented by any (non-abstract) subclass.

dispatchEvent

public boolean dispatchEvent(Event e)

Dispatches given event to the PTK server, which will make sure any output applications that want the data will get it.

Parameters:

e - the event to send to the server

Returns:

boolean true if successful

register

protected void register(Metadata mds)

Register this input source with the PTK Server. Called by the parameterized constructor.

Parameters:

mds - The Metadata of the events created by this input source. Used to register to the PTK server and to identify events this class generates.

finalize

protected void finalize()
                 throws java.lang.Throwable

Unregisters this input upon Java garbage collection. Does not unregister if client is null.

Throws:

java.lang.Throwable

See Also:

Object.finalize()

setTimeBetweenEvents

public void setTimeBetweenEvents(long milliseconds)

setMetadata

public void setMetadata(Metadata md)

Replaces this input's metadata with the given metadata. Performs a deep copy of the MetadataItems in the array passed in to the mds data field. Use this method instead of "=" so that multiple objects are not sharing the same array of MetadataItems.

addMetadata

public void addMetadata(Metadata md)

Adds the given metadata to this input's metadata, without replacing any of the existing metadata. Performs a deep copy of the Metadata passed in to the mds data field.

addMetadataItem

public void addMetadataItem(MetadataItem mi)

getMetadataItemsAsArray

public MetadataItem[] getMetadataItemsAsArray()

getMetadata

public Metadata getMetadata()

addMyMetadataToEvent

protected void addMyMetadataToEvent(Events e)

Adds this InputSource's metadata (set in constructor) to this event. An input calls this when it is creating an event to dispatch; metadata enables the PTK Server and PeripheralDisplay applications to identify the event.

Parameters:

e -