edu.washington.cs.sounddetector.server.api
Class SoundDetectorAPI

java.lang.Object
  extended by edu.washington.cs.sounddetector.server.api.SoundDetectorAPI

public class SoundDetectorAPI
extends Object

Class for clients of the API.

SoundDetectorAPI is mutable and not threadsafe.

Author:
the.dylan.price@gmail.com

Constructor Summary
SoundDetectorAPI(URI serverURI, org.apache.http.client.HttpClient httpClient)
          Constructs a new SoundDetectorAPI.
 
Method Summary
 String classify(String detectorId, byte[] sound, SoundFormat soundFormat, List<PeakEvent> peakEvents)
          Notify the server that a sound event was detected.
 org.apache.http.client.HttpClient getHttpClient()
           
 List<Notification> getOldNotifications(String phoneId, Date greaterThanDate, Date lessThanDate)
          Retrieves a list of notifications that have already been seen by the given phone.
 List<Notification> getPendingNotifications(String phoneId)
          Retrieves the latest notifications the given phone has not yet seen from the server.
 URI getServerURI()
           
 byte[] getSound(long soundId)
          Retrieves the given sound from the server.
 Map<SoundClass,List<Long>> getSounds(String detectorId)
          Retrieves all sounds saved to the server (from previous calls to train(java.lang.String, java.util.List, edu.washington.cs.sounddetector.server.api.object.SoundFormat)) for the given detector.
 void registerReceiverPhone(String phoneId, String registrationId)
          Registers a new Receiver Phone with the server.
 void renameDetector(String oldDetectorId, String newDetectorId)
          Rename a detector.
protected
<T extends MethodResult<?>>
T
sendMethod(Method method, Class<T> methodResultClass)
          Sends the given method to the server.
 void setHttpClient(org.apache.http.client.HttpClient httpClient)
           
 void setSoundClassProperties(String detectorId, List<SoundClass> soundClasses)
          Set properties on sound classes.
 void setURI(URI serverURI)
           
 List<Long> train(String detectorId, List<LabeledSound> data, SoundFormat soundFormat)
          Sends training data to the server.
 boolean unregisterReceiverPhone(String phoneId)
          Unregisters the given phone with the server.
 void untrain(List<Long> soundIds)
          Untrains sounds from the server's classifier.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

SoundDetectorAPI

public SoundDetectorAPI(URI serverURI,
                        org.apache.http.client.HttpClient httpClient)
Constructs a new SoundDetectorAPI.

Parameters:
serverURI - the uri of the running sound-detector server
httpClient - an http client that the SoundDetectorAPI will use to make requests
Method Detail

registerReceiverPhone

public void registerReceiverPhone(String phoneId,
                                  String registrationId)
                           throws org.apache.http.client.ClientProtocolException,
                                  IOException,
                                  SoundDetectorInternalErrorException
Registers a new Receiver Phone with the server. If the given phoneId is already registered, then overwrites the entry with the given registrationId.

Parameters:
phoneId - a unique identifier for the phone
registrationId - registration Id obtained from the Android Cloud to Device Messaging framework. May be null if you do not wish to receive push notifications. In this case you can manually poll the server using getPendingNotifications(java.lang.String) .
Throws:
SoundDetectorInternalErrorException - if the server encounters an error that it does not know how to deal with
IOException - if there is a problem communicating with the server
org.apache.http.client.ClientProtocolException - if there is an error in the HTTP protocol

unregisterReceiverPhone

public boolean unregisterReceiverPhone(String phoneId)
                                throws org.apache.http.client.ClientProtocolException,
                                       IOException,
                                       SoundDetectorInternalErrorException
Unregisters the given phone with the server.

Parameters:
phoneId - the phoneId to unregister
Returns:
true if the phone was unregistered, false if the phone did not exist on the server in the first place
Throws:
SoundDetectorInternalErrorException - if the server encounters an error that it does not know how to deal with
IOException - if there is a problem communicating with the server
org.apache.http.client.ClientProtocolException - if there is an error in the HTTP protocol

train

public List<Long> train(String detectorId,
                        List<LabeledSound> data,
                        SoundFormat soundFormat)
                 throws org.apache.http.client.ClientProtocolException,
                        IOException,
                        SoundDetectorInternalErrorException,
                        CantBuildClassifierException
Sends training data to the server.

Parameters:
detectorId - the location of the phone that detected the sound
data - a list of sound samples labeled with sound class names
soundFormat - the format of the sound samples
Returns:
a list of ids corresponding to the LabeledSounds sent to the server. Use these ids to identify the sounds to the server in other API calls.
Throws:
CantBuildClassifierException - if the classifier can't be built. Known reasons this may happen:
  • all of the data you have ever sent up has been labeled 'unknown'--the classifier must have at least two sound classes to work with
SoundDetectorInternalErrorException - if the server encounters an error that it does not know how to deal with
IOException - if there is a problem communicating with the server
org.apache.http.client.ClientProtocolException - if there is an error in the HTTP protocol

untrain

public void untrain(List<Long> soundIds)
             throws org.apache.http.client.ClientProtocolException,
                    IOException,
                    SoundDetectorInternalErrorException,
                    CantBuildClassifierException
Untrains sounds from the server's classifier.

Parameters:
soundIds - the ids returned by a call to train(java.lang.String, java.util.List, edu.washington.cs.sounddetector.server.api.object.SoundFormat), identifying sounds which are to be deleted from the server and removed from the server's classifier.
Throws:
CantBuildClassifierException - if after deleting the sounds the server could not build the classifier. In this case the server is in the same state it was before the call to untrain.
SoundDetectorInternalErrorException - if the server encounters an error that it does not know how to deal with
IOException - if there is a problem communicating with the server
org.apache.http.client.ClientProtocolException - if there is an error in the HTTP protocol

classify

public String classify(String detectorId,
                       byte[] sound,
                       SoundFormat soundFormat,
                       List<PeakEvent> peakEvents)
                throws org.apache.http.client.ClientProtocolException,
                       IOException,
                       SoundDetectorInternalErrorException
Notify the server that a sound event was detected.

Parameters:
detectorId - the location of the phone that detected the sound
sound - the audio event that was detected
soundFormat - the format of the sound sample
peakEvents - a list of peak events for the audio event
Returns:
the most likely class of the sound
Throws:
SoundDetectorInternalErrorException - if the server encounters an error that it does not know how to deal with
IOException - if there is a problem communicating with the server
org.apache.http.client.ClientProtocolException - if there is an error in the HTTP protocol

getPendingNotifications

public List<Notification> getPendingNotifications(String phoneId)
                                           throws org.apache.http.client.ClientProtocolException,
                                                  IOException,
                                                  SoundDetectorInternalErrorException,
                                                  PhoneDoesNotExistException
Retrieves the latest notifications the given phone has not yet seen from the server.

Parameters:
phoneId - the id of the phone which has been registered with registerReceiverPhone(java.lang.String, java.lang.String).
Returns:
a list of notifications this phone has not yet seen
Throws:
PhoneDoesNotExistException - if no phone with phoneId has been registered with a call to registerReceiverPhone(java.lang.String, java.lang.String).
SoundDetectorInternalErrorException - if the server encounters an error that it does not know how to deal with
IOException - if there is a problem communicating with the server
org.apache.http.client.ClientProtocolException - if there is an error in the HTTP protocol

getOldNotifications

public List<Notification> getOldNotifications(String phoneId,
                                              Date greaterThanDate,
                                              Date lessThanDate)
                                       throws PhoneDoesNotExistException,
                                              org.apache.http.client.ClientProtocolException,
                                              IOException,
                                              SoundDetectorInternalErrorException
Retrieves a list of notifications that have already been seen by the given phone.

Parameters:
phoneId - the id of the phone which has been registered with registerReceiverPhone(java.lang.String, java.lang.String).
greaterThanDate - retrieve notifications which were created after this date
lessThanDate - retrieve notifications which were created before this date
Returns:
a list of notifications
Throws:
PhoneDoesNotExistException - if no phone with phoneId has been registered with a call to registerReceiverPhone(java.lang.String, java.lang.String).
SoundDetectorInternalErrorException - if the server encounters an error that it does not know how to deal with
IOException - if there is a problem communicating with the server
org.apache.http.client.ClientProtocolException - if there is an error in the HTTP protocol

getSounds

public Map<SoundClass,List<Long>> getSounds(String detectorId)
                                     throws org.apache.http.client.ClientProtocolException,
                                            IOException,
                                            SoundDetectorInternalErrorException,
                                            DetectorDoesNotExistException
Retrieves all sounds saved to the server (from previous calls to train(java.lang.String, java.util.List, edu.washington.cs.sounddetector.server.api.object.SoundFormat)) for the given detector.

Parameters:
detectorId - the id of the detector
Returns:
a map from sound classes to a list of sound ids. You can retrieve the actual sound using getSound(long).
Throws:
DetectorDoesNotExistException - if there are no sounds with the given detectorId
SoundDetectorInternalErrorException - if the server encounters an error that it does not know how to deal with
IOException - if there is a problem communicating with the server
org.apache.http.client.ClientProtocolException - if there is an error in the HTTP protocol

getSound

public byte[] getSound(long soundId)
                throws org.apache.http.client.ClientProtocolException,
                       IOException,
                       SoundDetectorInternalErrorException,
                       SoundDoesNotExistException
Retrieves the given sound from the server.

Parameters:
soundId - the identifier of the sound, from a previous call to train(java.lang.String, java.util.List, edu.washington.cs.sounddetector.server.api.object.SoundFormat) or getSounds(java.lang.String).
Returns:
the sound as a byte array
Throws:
SoundDoesNotExistException - if there is no such sound with the given soundId
SoundDetectorInternalErrorException - if the server encounters an error that it does not know how to deal with
IOException - if there is a problem communicating with the server
org.apache.http.client.ClientProtocolException - if there is an error in the HTTP protocol

setSoundClassProperties

public void setSoundClassProperties(String detectorId,
                                    List<SoundClass> soundClasses)
                             throws DetectorDoesNotExistException,
                                    org.apache.http.client.ClientProtocolException,
                                    IOException,
                                    SoundDetectorInternalErrorException,
                                    SoundClassDoesNotExistException
Set properties on sound classes.

Parameters:
detectorId - the detector
soundClasses - a list of sound classes and properties for the detector
Throws:
DetectorDoesNotExistException - if no detector with detectorId exists
SoundClassDoesNotExistException - if one of the sound classes does not exist
SoundDetectorInternalErrorException - if the server encounters an error that it does not know how to deal with
IOException - if there is a problem communicating with the server
org.apache.http.client.ClientProtocolException - if there is an error in the HTTP protocol

renameDetector

public void renameDetector(String oldDetectorId,
                           String newDetectorId)
                    throws org.apache.http.client.ClientProtocolException,
                           IOException,
                           SoundDetectorInternalErrorException,
                           DetectorDoesNotExistException
Rename a detector.

Parameters:
oldDetectorId - the old detector id
newDetectorId - the new detector id
Throws:
DetectorDoesNotExistException - if no detector with detectorId exists
SoundDetectorInternalErrorException - if the server encounters an error that it does not know how to deal with
IOException - if there is a problem communicating with the server
org.apache.http.client.ClientProtocolException - if there is an error in the HTTP protocol

getServerURI

public URI getServerURI()
Returns:
the server URI

setURI

public void setURI(URI serverURI)
Parameters:
serverURI - the server URI to set

getHttpClient

public org.apache.http.client.HttpClient getHttpClient()
Returns:
the http client

setHttpClient

public void setHttpClient(org.apache.http.client.HttpClient httpClient)
Parameters:
httpClient - the HttpClient to use for API calls

sendMethod

protected <T extends MethodResult<?>> T sendMethod(Method method,
                                                   Class<T> methodResultClass)
                                        throws org.apache.http.client.ClientProtocolException,
                                               IOException,
                                               SoundDetectorInternalErrorException
Sends the given method to the server.

Parameters:
method - the API method to call
Returns:
the result from the command.
Throws:
org.apache.http.client.ClientProtocolException
IOException
SoundDetectorInternalErrorException


Copyright © 2012. All Rights Reserved.