Docstoc

ADD

Document Sample
ADD Powered By Docstoc
					Multi-criteria infrastructure for location-based
                   applications
              Shortly known as:

            Localization Platform


   Application Design Document




                   Ronen Abraham
                      Ido Cohen
                     Yuval Efrati
                     Tomer Sole'


                     April 2010
Table Of Contents
1.      Use Cases………………………………………………………………………………………………………4
1.1. The Actors……………………………………………………………………………………………………..4
1.2. Use-Cases………………………………………………………………………………………………………5
2.      Data Model…………………………………………………………………………………………………10
2.1. Android API…………………………………………………………………………………………………10
2.1.1. Description of Data Objects…………………………………………………………………………10
2.1.2. Data Objects Relationships………………………………………………………………………….11
2.2. Storage Server……………………………………………………………………………………….……12
2.2.1. Description of Data Objects…………………………………………………………………………12
2.2.2. Data Objects Relationships………………………………………………………………………….11
2.3. Prediction Server (a registered service) ………………………………………………………13
2.3.1. Description of Data Objects…………………………………………………………………………13
2.3.2. Data Objects Relationships……………………………………………………………………….…14
2.4. Databases……………………………………………………………………………………………………15
2.4.1. Storage Server…………………………………………………………………………………………….15
2.4.1.1. ERD Diagram………………………………………………………………………………………………15
2.4.1.2. Main Tables……………………………………………………………………………………………..…15
2.4.1.3. Main Transactions………………………………………………………………………………………16
2.4.2. Prediction Server…………………………………………………………………………………………18
2.4.2.1. ERD Diagram………………………………………………………………………………………………18
2.4.2.2. Main Tables………………………………………………………………………………………………..18
2.4.2.3. Main Transactions………………………………………………………………………………………19
3.      Behavioral Analysis……………………………………………………………………………………..20
3.1     Sequence Diagrams……………………………………………………………………………………..20
3.1.1 Storage server – add location………………………………………………………………………21
3.1.2 Storage server – get user's last locations…………………………………………………….22
3.1.3 Storage server – Register user……………………………………………………………………..23
3.1.4 Storage server – Unregister user…………………………………………………………………24
3.1.5 Prediction server – add user's location………………..………………………………………25
3.1.6 Prediction server – predict location………………………………….…………………………26
3.2     Events………………………………………………………………………………….………………………28
3.3     States……………………………………………………………………………………….…………………29
3.3.1 Localization server state chart………………………………………………………………….…29
3.3.2 Prediction server state chart ….…………………………………………………………………..30
3.3.3. Localization Client Android state chart………………………………………………………..30
4.      Object-Oriented Analysis…………………………………………………………………………….32
4.1. Android API…………………………………………………………………………………………………32
4.1.1. Class Diagrams……………………………………………………………………………………….…...32
4.1.2. Class Descriptions………………………………………………………………………………………..32
4.2. Storage Server…………………………………………………………………………………………….36
4.2.1. Class Diagrams…………………………………………………………………………………………….36
4.2.2. Class Descriptions………………………………………………………………………………………..39
4.3. Prediction Server…………………………………………………………………………………………41
4.3.1. Class Diagrams…………………………………………………………………………………………….41
4.3.2. Class Descriptions………………………………………………………………………………………..43
4.4. Packages……………………………………………………………………………………………………..45
4.4.1.   Android Client……………………………………………………………………………………………..45
4.4.2.   Server – General………………………………………………………………………………………….45
4.4.3.   Storage Server…………………………………………………………………………………………….45
4.4.4.   Prediction Server………………………………………………………………………………………...46
4.4.5.   Other…………………………………………………………………………………………………………..46
4.5      Unit Testing…………………………………………………………………………………………………47
4.5.1    Basic Operations Testing……………………………………………………………………………..47
4.5.2    Framework Extensions Testing…………………………………………………………………….49
4.5.3    Framework Monitoring and Learning Testing……………………………………………...50
4.5.4    Server Requirements Testing………………………………………………………………………51
5.       System Architecture…………………………………………………………………………………...53
6.       User Interface Draft…………………………………………………………………………………….56
7.       Testing………………………………………………………………………………………………………..57
7.1      Performance Constraints…………………………………………………………………………….57
8.       Task List……………………………………………………………………………………………………….60
1. Use Cases
1.1 The Actors
1.1.1 Location-based application
An application installed on the client mobile device, which uses the "localization
client" to take advantage of the framework's features. This will be developed by
the consumer of our framework.

1.1.2 Registered service client
An application that interacts with a "registered localization service", to take
advantage of the framework's features. This will be developed by the consumer of
our framework.

1.1.3 User
Any person that tests the "mock application" – an application that demonstrates the
usage of the localization platform. Typically a developer who is interested with
using the localization platform and wants to be sure of its capacities.

1.1.4 Administrator
Uses the server GUI to monitor and audit the action on the storage server.
1.2 Use-Cases
ID:                  1. Register user
Primary actors:      Location-based application, user
Description:         The user adds himself to the system.
Trigger:              In the mock application, the user clicks on the "Register" button.
                      Location-based application calls the "register user" function.
Pre-conditions:      Storage server is up
                     The location-based application knows the path to the storage server.
                     The location-based application is running.
Post-conditions:     The identifier of the user is saved in the DB.
Flow of events:      1. A unique identifier taken from the hardware of the client device
                     (IMEI, MAC address..) is sent to the system.
                     2. The server generates a system ID for this user, and returns to the user
                     this new ID.
Alternative flows:   Case: the user already exists in the DB
                     Action: the system returns the system ID that was already allocated to
                     that user

ID:                  2. Unregister user
Primary actors:      User, Location-based application
Description:         The user removes himself from the system.
Trigger:              In the mock application, the user clicks on the "Unregister" button.
                      Location-based application calls the "unregister user" function.
Pre-conditions:      Storage server is up
                     The location-based application knows the path to the storage server.
                     The location-based application is running.
Post-conditions:     The storage server sets the user's unregistration date.
Flow of events:      1. The user's system ID is sent to the server.
                     2. The server sets the current date and time as the user's unregistration
                     date.
                     3. The system returns a success message.
Alternative flows:   Case: user does not exist in the system
                     Action: the system returns a success message anyway

ID:                  3. Add user location
Primary actors:      User, Location-based application
Description:         The user informs the system about his current location.
Trigger:              In the mock application, the user clicks on the "Add new location"
                         button.
                      Location-based application calls the "add new location" function.
Pre-conditions:      Storage server is up
                     The location-based application knows the path to the storage server.
                     The location-based application is running.
                     The current user is registered.
Post-conditions:     The new location coordinates had been saved in the DB.
Flow of events:      The system takes the user's current location, either by the GPS service
                     or by some prepared optimizations.
                     The system sends the taken location sent to the server.
                     The storage server updates the DB with the user's new location
Alternative flows:   none
ID:                  4. Get last user locations
Primary actors:      User, Location-based application
Description:         An application needs the last user locations
Trigger:              In the mock application, the user clicks on the "get last user
                         locations" button.
                      Location-based application calls the "get last user locations"
                         function.
Pre-conditions:      Storage server is up
                     The location-based application knows the path to the storage server.
                     The location-based application is running.
                     The current user is registered.
Post-conditions:     The function returns all the past locations of a specific user
Flow of events:      1. The getLastUserLocations methods has been called
                     2. The function returns a list of all the past locations of a specific user
Alternative flows:   None.

ID:                  5. Register service
Primary actors:      Registered service
Description:         A service adds itself to the storage server, to be notified on events
Trigger:             The service calls the "register service" method
Pre-conditions:      Storage server is up
                     The service knows the path to the storage server
Post-conditions:     The service is saved in the storage server's DB
Flow of events:      The service sends its identity, and the list of events to be notified with
                     when the occur.
                     The storage server saves those choices in the DB and generates a system
                     ID to that service
                     The storage server returns the system ID to the service
Alternative flows:   Case: the service is already registered with the server
                     Action: the storage server updates the list of events the service is
                     interested with, and returns its existing system ID.

ID:                  6. Unregister service
Primary actors:      Registered service
Description:         A service disconnects itself from the storage server.
Trigger:             The service calls the "unregister service" method
Pre-conditions:      Storage server is up
                     The service knows the path to the storage server
Post-conditions:     The storage server updates the service's "unregistration date" field.
Flow of events:      The service sends its system ID to the storage server.
                     The storage server updates the service's "unregistration date" field in
                     the DB.
Alternative flows:   None.
ID:                    7. Predict location
Primary actors:        User, Location-based application
Description:           The client asks for its most predicted location.
Trigger:                In the mock application, the user clicks on the "predict location"
                           button.
                        Location-based application calls the "predict location" function.
Pre-conditions:        The recommendation service is up
                       The location-based application knows the path to the recommendation
                       service.
                       The location-based application is running.
                       The current user is registered and posted more locations than the
                       minimum required by the recommendation service.
Post-conditions:       The client application gets the coordinate of the most predicted
                       location.
Flow of events:        1. The recommendation service runs its internal algorithm and gets the
                       most predicted location for the given user
                       2. The client application gets the result.
Alternative flows:     Case: not enough data / cannot predict a location for the user
                       Action: a constant result will be returned: the unexisting coordinate
                       [200,200].

ID:                   8. Monitor server data
Main actors:          Administrator
Short description;    View the storage server data via server GUI, exposed as web pages.
Trigger:              The admin browses the server web GUI.
Pre-conditions:         Storage server (and its database) is up
                        Administrator has logged in successfully to the web system
Post-conditions:        A web page with the desired data is displayed to the administrator.
Flow of events:        1. Admin chooses a database table to view
                       2. The system displays the table elegantly.

ID:                  9. Audit server data
Main actors:         Administrator
Short                Edit the storage server data via server GUI, exposed as web pages.
description:
Trigger:             The admin pressed the "edit" button when viewing the server web GUI.
Pre-conditions:        Administrator is viewing the server data that he wants to change
                       Administrator is logged into the system
                       Storage server is up
Post-conditions:       The storage server has changed according to the administrator's
                         changes.
                       A web page containing the changed data is displayed to the
                         administrator.
Flow of events:       1. The system displays the database table with editable fields.
                      2. Administrator changes columns, adds or deletes rows, and finally
                         presses "done"
                      3. The system changes the database accordingly.
                      4. The system displays the changed data to the administrator via server
                         web GUI.
2. Data Model
2.1. Android API
2.1.1. Description of Data Objects
LocaManager – the main interface for the localization framework. Implemented as an
abstract class. Responsible for interacting with the Localization server by the REST protocol.
LocaManagerConfig – holds a configuration file, with parameters that the application
developer can change before using the application.
BestManager – an implementation of the efficient location management in the client side.
Instead of asking the GPS for the exact user location, which is the heavy operation we are
trying to narrow to the minimum, it combines other methods to save energy and
communication.
AcademicManager – an alternative implementation of the location management in the
client side. The application developer can choose which concrete LocaManager he wants to
use.
BestManagerConfig – extends LocaManagerConfig with more parameters inside the same
configuration file. These extra parameters are relevant only to BestManager.
LocationSource – an interface for every input source to calculate the client's current
location.
Coordinate – the most basic description for a location: latitude and longitude.
LocationState – a client location report, consisting of a location (Coordinate) and the
accuracy of that report – in meters.
GPSSynchronizer – implements LocationSource by asking the GPS for the current client
location. The actual call to the GPS is specified by BestManager, which initializes it.
StayPolicy – another LocationSource implementation. Works with the device accelerometer
and compass this way: if the client hasn't moved since the last known location, or barely
moved, it returns the last location with a good accuracy of some meters. Else, it returns the
last location with a "bad accuracy".
GAC – GPS, Accelerometer, Compass. Combines the three to determine the client's current
location. GAC will not call the GPS to calculate the location but rather only consider last
locations given from the GPS, not from any other source. It uses Newton's laws of motion
and earth geometry model to calculate the new location.
LocationManager – an Android class which gives details about the user's location by using
the internal GPS, or the wireless IP.
Accelerometer – an Android class which manages the accelerometer sensor.
Compass – an Android class which manages the compass sensor.
2.1.2. Data Objects Relationships

   a. Managers and Location Providers




   b. Location Providers, states and resources
2.2. Storage Server
2.2.1. Description of Data Objects
Our data classes are automatically generated from the database schema, using an
automated tool. Therefore, you won't be able to see the direct relationships between the
objects. The relationships will be managed by the algorithm classes. Also, that's why the
class names are in plural, even though it should have been in singular – because the
automated tool took it from the database table names.
Users – manages a user in the application. The user has a unique ID (managed by the
database), and is mapped to his mobile ID - the 'International Mobile Equipment Identity'
(IMEI) used to identify the user's smartphone device. A user also holds the time where he
registered to the localization platform and, if he is a past user, the time when he
unregistered. The system does not delete old users data but rather keep them as "past
users".
UsersLocations + UsersLocationsId – represents a user that has been to a location at some
point in time. The location is identified by longitude and latitude lines.
RegisteredServices – represents an external application that wishes to be notified of
application events, such as: adding a new user location, getting past locations, etc. The
registered application has to have a REST URL, where the localization server will send
updates on the events this application was registered to. Also, the database gives every
service a unique ID.
RegisteredServicesEvents – connects between a registered service (represented by the
service ID) and the event/s it wants to connect to.


2.2.2. Data Objects Relationships
2.3. Prediction Server (a registered service)
2.3.1. Description of Data Objects
The same comment about our auto-generated data classes from the "storage server" section
also holds here.
UsersLocations + UsersLocationsId – represents a user that has been to a location at some
point in time. The location is identified by longitude and latitude lines, and also by a "sector
ID" – a String representation of the Google tile this location is at.
UsersCluster – A cluster is a group of users who have something in common. This algorithm
groups the users by their most X frequent locations. So every cluster has, besides its
automated unique ID, the "build up sequence" – the Google tile ID's (represented as Strings)
that are required for a user to be in this cluster.
UsersProfile – connects between a user (represented by his unique ID) and a cluster (also
represented by his unique ID).
UsersClusterRules - A rule is a sequence that represents the movement of a single user.
Every user has a rule, a movement-path. This path consists of the sectors the user has visited
historically. When a user is in a cluster, this rule becomes a cluster-rule, so a cluster has as
much rules as it has members. A rule will also have a database-generated unique ID.
UsersClusterCandidates – Candidate is a sequence that represents the movement-pattern of
a single cluster. The candidate of a cluster is used for predicting the next step of a user in
this cluster by combining it with the rule of the cluster-member. It's composed of a unique
ID of that candidate, of the cluster, and a sequence of Google tiles.
Tile – the only class that wasn't auto-generated from the database, as we store tiles in
strings and only here we open them up. A tile is a "square" on the map for a certain zoom
level. It is represented by the coordinates which define the north-east and the south-west
latitude and longitude, and begin-end range which represent the zoom level. Unlike
localization "storage" server, the prediction server only works with Google tiles because it's
easier to associate a group of users to a square of locations instead of one specific
coordinate. It is also good for future consideration of data security, which is another factor
that this service was designed according to.
2.3.2. Data Objects Relationships
2.4 Databases
The framework we have developed consists of the main localization "storage server", and a
"location prediction server". They have two completely separate database schemas as they
represent completely different servers.
Explanation to why our DB is not identical to our ERD:

1. In some cases we didn't want to normalize the database just to have a table of 1 field
(clusters in prediction server).

2. MySQL database efficiencies: In some cases we decided to go with a different definition of
primary keys, foreign keys and tables than what is defined in the ERD. This came after
dealing with hundred thousands of rows of fake locations that took a long time to process, and
not in our algorithmic processing side: but in the database "execute query" side. So we
decided to set the database schemas a little different.


2.4.1. Storage Server
2.4.1.1. ER Diagram




2.4.1.2. Main Tables
Users: id, mobileId, registrationTime, unregistrationTime
The 'Users' table holds the information for the registered users. Mainly it uses by the
prediction system during the clusters-dividing process.
Id (Number) - Contains a unique id for each user.
MobileId (Number) - Contains a unique IMEI for each user. The 'International Mobile
Equipment Identity' used to identify the user's smartphone-device.
RegistrationTime (Timestamp) - Contains the date and time of the user registration.
UnregistrationTime (Timestamp) - Contains the date and time of the user un-registration.
This field is updated when the user is unregistering.

Users_Locations: userId, time, longitude, latitude
The 'Users_Locations' table holds a map of all the users and their locations history. This table
saves all the locations (past and present) of the users and allows setting information and
getting existing information from it.
userId (Number) - Contains the id of the user's location.
time (Timestamp) - Contains the date and time of which this user has been at the specfic
location.
longitude (Number) - Specifies the longitude of the location.
latitude (Number) - Specifies the latitude of the location.

Registered_Services: id, url
The 'Registered_Services' table holds services which added themselves to the storage server,
to be notified on events. All those services will be exposed into a larger set of operations
with the server.
id (Number) - Contains a unique id of the service.
url (String) - Contains a unique REST address to which the update will send.


Registered_Services_Events: id, event
The 'Registered_Services_Events' table holds a map of all the services and their related
events. Once an event occurs, an update will be sent to the registered service through his
url.
id (Number) - Contains the id of the service.
event (String) - The specific event which this id has signed for.


2.4.1.3. Main Transactions
Name: Location Addition
Description: Adding a new Location to the system.
Affected Table: users_locations
Added Fields: userId, time, longitude, latitude
Deleted Fields: None
Updated Fields: None

Name: Last User Locations Receiving
Description: Getting the last locations of a user.
Affected Table: None
Added Fields: None
Deleted Fields: None
Updated Fields: None

Name: User Registration
Description: Adding a new User to the system.
Affected Table: users
Added Fields: id, mobileId, registrationTime, unregistrationTime
Deleted Fields: None
Updated Fields: None

Name: User Removal
Description: Removing an User from the system.
Affected Table: users
Added Fields: None
Deleted Fields: id, mobileId, registrationTime, unregistrationTime
Updated Fields: None

Name: Service Registration
Description: Adding a new Service to the system.
Affected Table: registered_services
Added Fields: id, url
Deleted Fields: None
Updated Fields: None
Affected Table: registered_services_events
Added Fields: id, event
Deleted Fields: None
Updated Fields: None

Name: Service Removal
Description: Removing an existing Service from the system.
Affected Table: registered_services
Added Fields: None
Deleted Fields: id, url
Updated Fields: None
Affected Table: registered_services_events
Added Fields: None
Deleted Fields: id, event
Updated Fields: None
2.4.2. Prediction Server
2.4.2.1. ER Diagram




2.4.2.2. Main Tables
Users_Profile: userId, clusterId, contribution
The 'Users_Profile' table holds a map of all the users and their related clusters. Within every
user there is a specific attributes that make him a member of a specific cluster. The
prediction process will use this table for getting the specific users of a given cluster as a step
in the way of finding the next location.
userId (Number) - Contains the id of the user.
clusterId (Number) - Contains the id of the cluster which contain this user.
Users_Cluster: clusterId, clusterBuildupLocationSequence
The 'Users_Cluster' table holds the information for every cluster. For getting the essence of
many moving-patterns, we need the user's friends. That is the only way to make it useful. To
abstract a group of friends, we put them into a cluster: A group of people that is built up by
different attributes of cluster’s members.
clusterId (Number)- Contains the id of the cluster which contain this group of friends.
clusterBuildupLocationSequence (String) - Threshold condition. Only those who were the
most in these locations can enter the cluster.

Users_Cluster_Rules: clusterId , ruleId, rule
The 'users_cluster_rules' table holds a map of all the clusters and their related rules. A rule is
a sequence that represents the movement of a single user. Every user has a rule, a
movement-path. This path consists of the sectors the user has visited historically. When a
user is in a cluster, this rule becomes a cluster-rule, so a cluster has as much rules as it has
members.
clusterId (Number)- Contains the id of the cluster.
ruleId (number) - Contains the id of the cluster which contain this group of friends.
rule (String) - Contains a sequence that represents the movement of a single user.

Users_Cluster_Candidates: candidateId, candidate, clusterId
The 'users_cluster_rules' table holds a map of all the clusters and their related candidate.
Candidate is a sequence that represents the movement-pattern of a single cluster. The
candidate of a cluster is used for predicting the next step of a user in this cluster by
combining it with the rule of the cluster-member.
candidateId (Number) - Contains the id of the candidate.
candidate (String) - Contains a sequence that represents the movement of a single cluster.
clusterId (Number) - Contains the id of the cluster.




2.4.2.3. Main Transactions
Name: Location Addition
Description: Adding a new Location to the system.
Affected Table: users_locations
Added Fields: userId, time, longitude, latitude, sectorId
Deleted Fields: None
Updated Fields: None
Affected Table: users_profiles
Added Fields: userId
Deleted Fields: None
Updated Fields: None
Affected Table: location_frequencies
Added Fields: sectorId, numOfUsers
Deleted Fields: None
Updated Fields: numOfUsers
(* could be either adding a sector that has never been visited before, or just incrementing
the number of users that went to that location).

Name: Location prediction
Description: Predicting a location using prediction algorithm and database
Affected Table: users_profile
Added Fields: userId, clusterId, contribution
Deleted Fields: userId, clusterId, contribution
Updated Fields: userId, clusterId, contribution
(*Because ' Location prediction' is a big transection, we can meet various of cases: It is
possible that after a calculation we'll need to create a new / remove an old user. Another
case can be in which user has moved to another cluster so after the calculation we'll need to
update).
Affected Table: users_cluster
Added Fields: clusterId, clusterBuildupLocationSequence
Deleted Fields: clusterId, clusterBuildupLocationSequence
Updated Fields: None
(*For a set of clusters we must delete all of them and then to create new clusters for
updating the set).
Affected Table: users_cluster_rules
Added Fields: ruleId, rule, clusterId
Deleted Fields: ruleId, rule, clusterId
Updated Fields: None
(* Same for this table, for a set of rules we must delete all of them and then to create new
rules for updating the set).
Affected Table: users_cluster_candidates
Added Fields: candidateId, candidate, clusterId
Deleted Fields: candidateId, candidate, clusterId
Updated Fields: None
(* Same for this table, for a set of candidates we must delete all of them and then to create
new candidates for updating the set).
3. Behavioral Analysis
3.1 Sequence Diagrams
3.1.1 Storage server – add location
3.1.2 Storage server – get user's last locations
3.1.3 Storage server – Register user
3.1.4 Storage server – Unregister user
3.1.5 Prediction server – add user's location
3.1.6 Prediction server – predict location




The sequence continues on next page
3.2 Events
The general client-server event in our application is:
Name                      Initiated By           Description            Action
A server operation        System, triggered by   The server             When the server is
was made                  the application        communicates           triggered, depending
                          developer (or the      through REST           on the operation it
                          user in the mock       protocol. The user     initiates a database
                          application)           can either use Loca    session, and uses the
                                                 API to call a client   database to
                                                 operation which will   read/write relevant
                                                 call the server via    data. If the caller was
                                                 REST, or call the      a client application
                                                 server himself by      and the function has
                                                 entering the right     an output, it is
                                                 parameters in a REST   returned via REST
                                                 call, or press a       protocol.
                                                 button in the mock
                                                 application.



The Android API has more events to follow. Note that the application developer can be
replaced by a user who uses the demo "mock" application:
Name             Initiated By    Description                   Action
User registers   Application     The user has to register      After notifying Loca Server
                 developer       itself before starting to     with the user's phone
                                 track locations.              identifier (IMEI), a unique user
                                 LocaManager has a function    ID is returned and saved. From
                                 for that.                     now on, the system can start
                                                               tracking locations.
User starts      Application     The user initiates the        Concrete LocaManager starts
tracking         developer       location collection process   managing the user's locations.
location                                                       In BestManager's case, it starts
                                                               listening to signals from each
                                                               of the LocationSource classes.
Location         System          Sometimes, we wish to         Concrete LocaManager asks
polling                          query the location sources    the specified LocationSource
interval                         every X seconds for the       for the current location, gets
passed                           current location, just to     it, and continues its
                                 ensure we're synced and a     calculations.
                                 little more accurate
GPS signal is    System          The system asks GPS for the   If BestManager is selected to
received                         current user location, or     manage locations, it sends the
                                 receives an event from the    new location with its accuracy
                                 GPSSynchronizer               to all the other LocationSource
                                                               classes, and they synchronize
                                                               accordingly.
Accelerator /    System          The system asks an internal   StayPolicy calculates whether
Compass                          sensor for some input, or     the user has moved
signal is                       receives an event from it.     significantly from the last
received                                                       location he was at.
                                                               GAC calculates the user's new
                                                               location based on his internal
                                                               algorithms, and returns the
                                                               new location and the expected
                                                               accuracy.
User stops      Application     The user asks LocaManager      If BestManager is selected to
tracking        developer       to stop the location           manage locations, it turns off
location                        tracking.                      its input Location Sources
                                                               (GPSSync, GAC, Stay) which
                                                               turn off Android's internal
                                                               location sources (GPS,
                                                               compass, accelerometer).

3.3 States
3.3.1. Localization server state chart:




Initialize server: Upon server startup, few components get initialized: the Hibernate
management, which wraps our database tables with objects (instead of us sending SQL
commands), get initialized. Also, startup processes may be executed, such as the initial
locations data import, which is defined to be done or not in a configuration file.
REST request received: The server splits in two: a background thread to handle the request
is made (automatically, through Java REST protocol handling) so that the main thread is still
open for new requests, while that background thread processes the incoming request, let it
be a new location, new user, a user asking for his past locations, user unregisters, or another
server registers for events.
REST processing complete: Any database session that was opened during the process gets
committed. If the server needs to return a value to the caller, Java handles that. Java also
automatically shuts down the processing thread.
Shutdown server: any running objects are freed, and the server is not reachable for calls
anymore.
3.3.2. Prediction server state chart:




Initialize server: Same as localization storage server initialization.
Predict Location request: The way the prediction server is set up at the moment, and,
according to our clients also the way it should be, handling location prediction is sequential.
That means, until one request is finished the other requests are pending. The algorithm
clusters users into groups of their most commons visited locations, and until all that is done,
no other request can interfere.
Clustering complete: After the clustering of users gets done, prediction server returns the
most likely next location of the current user, and lets other prediction requests pass.
Shutdown server: any running objects are freed, and the server is not reachable for calls
anymore.


3.3.3. Localization Client Android state chart:




Register user: Localization Client API can't work without a user ID. Therefore the application
developer must call the "register" function, which ensures that the storage server recognizes
this user. Only after that it is possible to start tracking the user's location.
Start tracking location: When the application developer calls that function, the selected
concrete LocaManager initializes all his LocationSources. If BestManager is selected, GAC,
StayPolicy and GPSSynchronizer are opened and running.
Location update received: The system works on a reacting model. That means, when one
location provider sends a location update, objects that registered to receive those updates
check that location and handle accordingly. For example, BestLocation wires up GAC so that
whenever GPSSynchronizer notifies it with a new location, GAC will update its current
location to the one given, to ensure the correctness of his algorithm (GPS is considered the
most accurate sensor, but also the heaviest one on resources).
Time trigger: Sometimes the location updates are selected to be polled after X seconds pass.
When that happens, the selected LocationSource returns the current location, and the rest
of the system updates itself accordingly.
Stop tracking location: Once the application developer calls this method, the
LocationSources are disconnected and closed.
Unregister user: LocaManager updates the localization storage server that the user doesn't
wish to be a part of this service anymore.
4. Object-Oriented Analysis
4.1. Android API
4.1.1. Class Diagrams




4.1.2. Class Descriptions
LocaManager – the main interface for the localization framework. Implemented as an
abstract class. Its public methods are the entry point for all the use-cases made by the
application developer, as he should work with a class that extends this class.
       register() : takes the user's mobile ID (his IMEI), sends it to the server via
        RestServiceClient, receives the user ID and keeps it. User can't register again if he is
        already registered, unless he un-registered.
       unregister(): calls the server-side "unregister" method via RestServiceClient. The
        user has to be a registered user, meaning, he already registered before.
       startTrackingLocation(): only available if the user has called register() before.
       stopTrackingLocation(): only available if the user has called register() before. Stops
        any resources associated with tracking the location of the user. If the user hasn't
        called startTrackingLocation() before, this method will do nothing.
       getLocation(): the only abstract method in this class. The concrete LocaManager has
        to implement it.
       getPastLocations(from: Date, to: Date, maxLocations: int) : Coordinate[] - calls the
        server-side "getPastLocations" method via RestServiceClient. The user has to be a
        registered user, meaning, he already registered before. It's optional to enter filtering
        parameters: maximum backward locations count, and a date range. The returned
        value is the array of locations of this user.
       sendCurrentLocation(): explicitally calls the "sendLocation" method of
        RestServiceClient. LocaManager will also do that periodically according to a
        configuration parameter, but the user can ask the class to do it again.
LocaManagerConfig – holds a configuration file, with parameters that the application
developer can change before using the application. An example of the available parameters:
       getSendLocationInterval() : long - the fixed interval of milliseconds to send the
        current location of the user to the server. Read from a line in the configuration file.
RestServiceClient – interacts with the Localization Server for the operations that should
involve the server. It has the URL of the server to connect to. Implemented as a "proxy" – it
represents all the available server operations, with the exact input types and return types,
only what it does is passing them on to the server using REST protocol, waiting for a
response and parsing the result to the desired return data type.
BestManager – an implementation of the efficient location management in the client side.
Instead of asking the GPS for the exact user location, which is the heavy operation we are
trying to narrow to the minimum, it combines other methods to save energy and
communication. It has references to all the currently implemented location sources: GAC,
GPSSynchronizer, and StayPolicy.
       onNewLocation(subject: LocationSource, data: LocationState) : BestManager listens
        to "events" from all the LocationSources, and decides what to do when a new
        location is notified from each one of them. If GPSSync sent a new location, it also
        updates all the other LocationSource's. If it received a poor accurate of the location
        from GAC, it checks the time for the next call for the GPS, and if it's too long, it calls
        GPSSynchronizer to ask the GPS for the current coordinate. Other improvements will
        be implemented as time goes on after measuring results from experiments.
AcademicManager – an alternative implementation of the location management in the
client side. The application developer can choose which concrete LocaManager he wants to
use. Currently this is a place holder for an implementation from other people.
BestManagerConfig – extends LocaManagerConfig with more parameters inside the same
configuration file. These extra parameters are relevant only to BestManager. Examples of
parameters necessary for BestManager:
       getGpsSyncInterval() : long – the fixed interval of milliseconds to ask the GPS of the
        device for the current location. Read from a line in the configuration file.
LocationSource – an interface for every input source to calculate the client's current
location.
       getLocation() : LocationState – asks the concrete LocationSource for the known
        current location of the user. The returned location is composed of the location and
        an error estimate.
       getObservable() : Observable – a client can be subscribe to receive location updates
        from a LocationSource, using Java "observer" design pattern.
Coordinate – the most basic description for a location: latitude and longitude.
LocationState – a client location report, consisting of a location (Coordinate) and the
accuracy of that report – in meters.
GPSSynchronizer – implements LocationSource by asking the GPS for the current client
location. The actual call to the GPS is specified by BestManager, which initializes it. Also
extends Java Observable for the observable design pattern. It also subscribes for the GPS for
updates in time and distance.
       getLocation() : LocationState – inherited from LocationSource, asks the GPS
        ingredient of the device for the current location of the user. The device GPS also
        returns an estimation of the error and that will be returned as well. We assume that
        most results here are very accurate.
       notifyObservers() – inherited from Observable, notifies the new GPS location of the
        user.
StayPolicy – another LocationSource implementation. Works with the device accelerometer
and compass this way: if the client hasn't moved since the last known location, or barely
moved, it returns the last location with a good accuracy of some meters. Else, it returns the
last location with a "bad accuracy". Also extends Java Observable for the observable design
pattern.
       notifyObservers() – inherited from Observable, notifies current estimated location of
        the user.
GAC – GPS, Accelerometer, Compass. Combines the three to determine the client's current
location. GAC will not call the GPS to calculate the location but rather only consider last
locations given from the GPS, not from any other source. It uses Newton's laws of motion
and earth geometry model to calculate the new location. Also extends Java Observable for
the observable design pattern.
       getLocation(): LocationState – inherited from LocationSource. Since this class always
        keeps track of the current estimated location of the user based on the motion
        sensors, it simply returns the current location known to the system. No other
        calculation is required. The accuracy estimation is received from its internal
        calculators along with the location updates.
       notifyObservers() – inherited from Observable, notifies current estimated location of
        the user.
LocationManager – an Android class which gives details about the user's location by using
the internal GPS, or the wireless IP.
Accelerometer – an Android class which manages the accelerometer sensor.
Compass – an Android class which manages the compass sensor.
MotionCalculator – uses Newton's laws of motion to try and calculate the new location,
based on a past location, speeds and accelerations.
       calculateNewLocation(from: LocationState, speed: Movement, direction:
        Movement) : LocationState – uses the basic Newton laws of movement to
        determine a new location based on a past location, starting speed (strength and
        direction), the change in acceleration in all three directions, and the change in the
        movement direction. We don't assume that the acceleration is constant but rather
        use the derivative-based formulas for speed and acceleration. Returns a location and
        an error estimation in meters.
GeodesyCalculator – uses a geometry representation of earth to calculate a new coordinate
based on a previous coordinate and a distance. As you know, Euclidian distance it not so
accurate for those things. We use a given package for geodesy calculations which was
already tested and proved.
       calculateNewLocation(from: LocationState, direction: Movement, movement: int) :
        LocationState – calculates a new coordinate from an old coordinate, a change in the
        movement direction and the movement in meters. Returns a location and an error
        estimation in meters.
Observable – a Java class which supports "push" updates for changes in those who extend it.
For us, every LocationSource has to be connected to an observable, in order to get other
clients connect to it and receive location updates. So far, we implemented that connection
through inheritance – each of the 3 LocationSources extends Java Observable and
implement LocationSource interface.
Observer – a Java class which supports receiving "push" updates by those who extend it, for
changes in "Observable"s. So far, BestManager serves as the client to receive updates about
the observables – the LocationSources.
4.2. Storage Server
4.2.1. Class Diagrams
4.2.2. Class Descriptions
LocationsRestAPI – an interface for the server entry point for all the possible operations. All
its functions are the user cases available for the application developer, or the registered
service, and we talked about them in chapter 1.
LocationsRest – implements that interface using REST. Mostly delegates the work to the
"logic" package. The "services" package is doing more things with putting the server online
and registering for REST protocol queries, and the actual work is delegated to the next
package. Whether to use this class or another implementation is specified in a configuration
file and loaded through ReflectionUtils, so that we don't need to recompile to use a different
implementor.
BaseContextListener – handles the start-up of the server. Initializes the database with input
data (if specified in the configuration). Also handles the shut-down of the server.
LocationsManager – contains all the algorithms that are related to the locations, user
management, storage and retrieval of locations. On each REST call regarding locations
management, one of the operations from LocationsManager is called.
       addLocation – checks if the user exists, and if so, adds the new location to the
        database in the proper table structure.
       getLastUserLocations – according to the given parameters (amount of last locations
        to return, starting/ending date), queries the database and returns an appropriate
        array of coordinates.
       registerUser – if the user already exists, just returns its existing user ID. Else, it adds
        the user to the database. The user is identified here by his mobile ID and this
        function returns the new ID from the "users" database table.
       unregisterUser – sets the user's "unregistration time". This indicates that the user
        doesn't use our service anymore; however we still own the past data of him.
ServicesManager – contains all the algorithms that are related to registering external
services to the localization server on some events. On each REST call regarding registering
and unregistering services from events, one of the operations from ServicesManager is
called.
       registerService – adds the URL of that external REST service to the database table,
        according to the given events that this service wants to register to.
       unregisterService – removes the URL's of the external REST service from the
        database tables.
       triggerEvent – for the given event, this function gets the REST URL's of all the
        registered external services, and sends them the new information via REST protocol.
ReflectionUtils – manages our most common use for configuration files – determining which
interface implementation to use. In the server we use many interfaces, and we set the
concrete class in external configuration files, so that we can change it without re-compiling
the code. This class takes the data type defined in the configuration file and turns it into an
actual class, using reflection.
ExceptionKeeper – a utility class to pass an exception object between anonymous
implementations of classes. Since we can't override a function and add a "throws" to the
concrete method only, we use this class to hold the exception and check later if there was
one thrown.
LocationsDao – an interface for the database-related operations (DAO = Data Access
Objects) about locations, user management, storage and retrieval of locations. All its
operations involve holding a Hibernate Session. Works mostly with the data classes, which
are automatically generated from the SQL schema. In section (2) data model we specified
that there were no real connections between the data classes, since they were auto-
generated. The connection takes place here – Hibernate will throw an exception if a
database constraint is violated, and this exception will continue as LocaException and bubble
up to the caller of the methods here.
LocationsDaoImpl – a MySQL implementation of LocationsDao. Whether to use this class or
another implementation is specified in a configuration file and loaded through
ReflectionUtils.
ServicesDao – an interface for the database-related operations about registering and
unregistering services to the different server events. Works mostly with the data classes,
which are automatically generated from the SQL schema.
ServicesDaoImpl – a MySQL implementation of ServicesDao. Whether to use this class or
another implementation is specified in a configuration file and loaded through
ReflectionUtils.
4.3. Prediction Server
4.3.1. Class Diagrams
4.3.2. Class Descriptions
Some of the classes here are very similar in their roles to the ones in "storage server", so we
will mostly focus on the new concepts of classes and methods here.

PredictionRestAPI – an interface for the server entry point for all the possible operations.
PredictionRest – implements that interface using REST. Mostly delegates the work to the
"logic" package.
BaseContextListener – handles the start-up and shut-down of the server. Initializes the
database with input data (if specified in the configuration).
IClusterer – an interface for the "clustering" operations, which are mandatory to be created
before doing the actual location prediction. There can be many ways to implement that
interface due to efficiency and handling lots of data on the way. Therefore we chose to
expose it as an interface.
       createAndPersistClusters – divides the users into cluster groups. Every user's X most
        frequent visited locations (X is configurable) represent his cluster. For each cluster,
        its entrance rule ("build up sequence") is calculated. If that cluster representation
        already exists, the user is added to that cluster; otherwise a new cluster is created.
       createAndPersistUsers – updates the users' profiles to their given clusters
       createAndPersistCandidates – for each cluster, calculates the "candidate" – the next
        best location/s to predict for anyone in that cluster.
Clusterer – currently the only implementation of IClusterer. Implements all the operations
for clustering the users and the locations in groups, which has to happen before doing the
actual prediction of the next location.
IPredictor – an interface for predicting the next location, based on existing clustering of the
users to groups.
       getPredictedUsers – given a location (a Google tile ID named here as "sector ID"),
        this function uses the prediction algorithm to return a "feasibility map" – for each
        user (key = user ID), the probability that that user is expected to visit that location,
        for all users but the asking user. This function was written in the original location
        prediction package by a Deutsche Telekom intern, and we inherited that function. In
        our application we will use a simpler method.
Predictor – an implementation of IPredictor to predict the next location of a user, based on
past locations and clustering of all the users to groups.
LocaPredictor – during the implementation process we found out that the interface is not
exactly what we need, and we really want a simpler function with different input and output
variables. However, we wanted to reuse the helper methods from the original Predictor. So
we chose to extend Predictor with the input and output variables that we needed, and called
some of the functions in Predictor (which were originally private, now protected).
       predictNextBestLocation – given a user ID, this function uses the location prediction
        algorithm, to find the most likely location that this user will visit next. The returned
        data a representation of a coordinate on the map. On every "predict next location"
        REST call, PredictionRest calls LocaPredictor and asks it to do the actual prediction
        algorithm.
MitToUsersLocations – to simulate large data, we have an input database table from an MIT
simulation. No data of real users is kept there, only their ID's and past locations. This class
takes the input table and adds the information to our database. Whether to operate it or not
is saved in a configuration file and loaded (or not) in the start of the server.
Tile – represents a Google Tile. A tile is a "square" on the map for a certain zoom level. It is
represented by the coordinates which define the north-east and the south-west latitude and
longitude, and begin-end range which represent the zoom level. Unlike localization "storage"
server, the prediction server only works with Google tiles because it's easier to associate a
group of users to a square of locations instead of one specific coordinate. It is also good for
future consideration of data security, which is another factor that this service was designed
according to.
GoogleTileUtils – conversions and measurements of google tiles to other external location
data types.
CoordinateUtils – utility class of calculations for Euclidian distance and earth distance
between places.
       euclidianDistance – calculates the "blind" distance of a straight line between two
        coordinates.
       earchSurfaceDistance – calculates the distance between two coordinates on Earth.
        For example, the distance between Alaska and Russia will be very big on
        euclidianDistance, because the longitudes are very different from each other, but
        here, the distance will be relatively small, as expected.
ReflectionUtils – manages our most common use for configuration files – determining which
interface implementation to use. In the server we use many interfaces, and we set the
concrete class in external configuration files, so that we can change it without re-compiling
the code. This class takes the data type defined in the configuration file and turns it into an
actual class, using reflection.
PredictionDao – an interface for the database-related operations (DAO = Data Access
Objects). The operations there are very simple and either query or command, not both.
Every function basically wraps an SQL query. The calls to those functions are usually through
the "logic" package.
PredictionDaoImpl – a MySQL implementation of PredictionDao. The determination to use
this class as the implementer or another class is defined in a textual configuration file.
4.4. Packages
4.4.1. Android Client
loca.client: consists of the main application objects: LocaManager, LocaManagerConfig and
the implementers of them.
loca.client.communication: classes which deal with communicating to the storage server.
loca.client.locationSources: the classes which can provide the user's current location.
loca.client.processing: calculators and different algorithms which will be used for internal
calculation of the user's location, and similar things.
loca.client.utils: Utility classes with no specific reference to this project but more general
methods to solve common problems.



4.4.2. Server – general
We have divided our server into several subprojects (not packages, different JAR's), so that
we can work in tiers:
dao: stands for Data Access Objects. Contains classes for Database access, and also for
retrieving information from other external input sources such as files.
logic: contains the main algorithms of the project. Handles the processing of operations.
Depends on "dao".
services: entry points for the server to operate. The service project only deals with tasks of
initiating a service and running it. When a request is made, the first thing it does is passing it
on to "logic". Depends on "logic".
commons-loca: cross-project classes, including: the data classes automatically generated
from the database schemas, and utility classes. All the other subprojects depend on this one.



4.4.3. Storage Server
loca.dao: general things like constants, and interfaces for all the database operations.
loca.dao.impl.mysql: a MySQL implementation for all the database-related operations.
loca.commons: general cross-project things like database constants and customized
exceptions.
loca.commons.vo.db: data classes that are automatically generated from the database
schema by a tool.
loca.logic: all the storage server algorithms for dealing with users, locations, and registered
services.
loca.services: general services operating classes such as the startup listener, constants and
configurations reader.
loca.services.locations: interfaces for all the server operations.
loca.services.locations.rest: an implementation of the interface from the above package in
REST protocol.
4.4.4. Prediction Server
loca.prediction.dao: general things like constants, and interfaces for all the database
operations.
loca.prediction.dao.impl.mysql: a MySQL implementation for all the database-related
operations.
loca.prediction.commons: general cross-project things like database constants and
customized exceptions.
loca.prediction.commons.vo.db: data classes that are automatically generated from the
database schema by a tool.
loca.prediction.logic.dataGeneration: algorithms and processes for creating fake input data,
loading new data, initiating a new location row, and displaying that data on the screen for
auditing.
loca.prediction.logic.clustering: algorithms for grouping the users based on common
behavior.
loca.prediction.logic.findCandidates: algorithms for processing the clusters and finding the
most likely next locations for a given user, or group of users.
loca.prediction.logic.prediction: algorithms for predicting the next location. Also initiating
the previous algorithms of clustering and finding candidates.
loca.prediction.services: general services operating classes such as the startup listener,
constants and configurations reader.
loca.prediction.services.prediction: interfaces for all the server operations.
loca.prediction.services.prediction.rest: an implementation of the interface from the above
package in REST protocol.



4.4.5. Other
commons: some classes may be useful for both servers and the Android client. One example
is "reflection utils" to read from a configuration file and create an instance from it.
4.5 Unit Testing
4.5.1. Basic Operations Testing
Functionality                     Description               Tests                Comments
  Add user                Localization client /    Test that Localization
  location         registered service send to       client can add a valid
                the storage server a location       location.
                      update, about a user, a      Test that a client can’t
                  specific time, and location       add a non existing
                                  coordinate.       location.
                                                   Test that a non-
                                                    registered client can’t
                                                    add new location
                                                   Verify that added
                                                    locations are stored in
                                                    the DB

Get last user            Localization client /     Test that the
 locations      registered service query the        Localization client can
                        storage server about        query for single user
                      locations of a group of       last location
                     users. Optional filtering     Test that the
                    parameters: date range,         Localization client can
                      max results to return.        query for a group of
                                                    users last location
                                                   Test filtering by date
                                                    on a query
                                                   Test filtering by max
                                                    results query
                                                   Test that a non-
                                                    registered client can’t
                                                    get user locations

    Start          Localization client begins      Test that starting the     This is mainly a
 localization        getting user's locations       client does add             timed call to
    client         every period of time, and        location periodically      “add location”
                     sending updates to the        Test that the location     and so its tests
                                     server.        sent are saved in the      are covered by
                                                    right order in the DB              it
    Stop        Localization client stops the      Test that after
 localization       process of requirement          stopping, no new
    client                                          locations are added
                                                    for the client

  Register            A service adds itself to     Test that a service can
  service        receive event notifications        register to receive
                    from the storage server         notifications from the
                                   ("push").        server.
                  This also gives the service      Test that a service
                permission to ask the server        can’t register itself
                   for past locations and add        more than one time
                          new user locations.       Test that a registered
                                                     service does get
                                                     notifications when
                                                     relevant events
                                                     happen (relevant
                                                     locations are added)


 Unregister      Removes a service from the         Test that a service can
  service          list of known clients from        un-register itself from
                           the storage server.       the server.
                                                    Test that an
                                                     unregistered service
                                                     doesn’t get
                                                     notifications for any
                                                     event

Register user      Localization client sends a      Test that a user can
                 unique identifier of the user       register from a client
                     ("strong identity") to the      and get an ID from the
                  storage server. The storage        server
                   server returns an ID of the      Test that if an existing
                      user, and that's how the       user tries to register
                 user is recognized from now         again he will get his
                 on. If the user already exists,     stored ID (same one as
                          the server returns its     the first time)
                                    existing ID.    Test the two different
                                                     registering users get
                                                     different IDs
 Unregister        Localization client lets the     Test that a user can
   user          server know that a user has         unregister.
                       unregistered from the        Test that the server
                 platform. The server simply         reply an unregistering
                 mentions the unregistration         user with the current
                               date and time.        time
                                                    Test that the user is
                                                     removed from the DB
Events for the             Previous Functional      Test that a registered
  registered         requirements can trigger        service gets events for
    service          events for any registered       every update – add
                     service that registered to      location, get last
                 accept them. Whenever one           location, register a
                  of those functions happens,        user and unregister a
                   the storage server triggers       user.
                    the following event in the
                       registered services that
                  requested to be notified on
                                    that event.
4.5.2. Framework Extensions Testing
Functionality                      Description           Tests                 Comments
  Location                Three algorithms for                                  Evaluating the
 prediction           recommending the next                                       quality of the
                   movement of a user in the                                         prediction
                system will be implemented                                 algorithms is not a
                     by a "registered service".                                      functional
                 That service will register for                                    requirement
                        the event of "add user                             itself. Deciding the
                location", so that every time                                     quality of the
                 a new location is added, the                                prediction will be
                  recommendation service is                                done later by beta
                                       notified.                                         tester.
Predict next                  A function of the    Test that Prediction
  location          recommendation service.         for a registered
                              Returns the next      return a location.
                   recommended location of         Test that the
                 the given user based on the        locations returned
                            algorithm inside it.    are valid
                                                    coordinates
                                                   Test the a non-
                                                    registered user
                                                    trying to use
                                                    prediction get an
                                                    error message

  Mock              A demonstrator for the         Test that Users can
application       localization client and the       register and
                  registered service will be        unregister using the
                              Implemented.          demo client
                                                   Test that Users can
                                                    add and get
                                                    location using the
                                                    demo client.
                                                   Test that it is
                                                    possible to start
                                                    and stop periodic
                                                    location sending.
                                                   Test that registered
                                                    service gets all 4
                                                    types of updates
4.5.3. Framework Monitoring and Learning Testing
Functionality           Description                      Tests            Comments
Configuration        The framework should          Test that the
management       provide the user the ability       default
                               to control the       configurations
                            configuration of        work smoothly
                the data usage frequency:          Change the
                 Duration between the              frequency of
                    location updates a              sending locations
                    localization client             using the demo
                    sends.                          client UI
                 If using the location            Change the
                    prediction service,             update
                    frequency of calling            frequency using
                    that service.                   the demo client
                And additional parameters,          UI
                                     such as:      Test the ability to
                 Address of the storage            change the
                    server                          location storage
                                                    server
                                                   Test that after
                                                    changing the
                                                    location server
                                                    location are still
                                                    saved
  Security       The framework should not          Test that the user
                expose the entire database          can’t get
                        to one user, only the       prediction for
                  information that relevant         other users
                    for him. The localization      Test that a user
                  client will get information       can’t add
                 only relevant to the user it       location for
                                   represents.      another user
                                                   Test that a user
                                                    cant register
                                                    without its
                                                    unique ID
   Logger           The system shall have a        Test that it’s
                     logging mechanism, to          possible to
                           view all the user        change log level
                                commands            from info to
                                                    debug and error
                                                   Test that all
                                                    added location
                                                    are accounted
                                                    for in the log.
                                                   Test that all user
                                                    logins and
                                                    logouts are
                                                    accounted for in
                                                  the log.



 Deployment      The localization client will    Test that the
                   be a code library, to be       localization client
                  used as reference inside        can be imported
                        the location-based        and added to a
                   application that will be       new project
                         developed by the        Test run the
                           platform's user.       client with the
                                                  imported project


4.5.4. Server Requirements Testing
Functionality            Description                  Tests             Comments
   Server           The storage server shall
  Database      hold a database with all the
                  users, the users' locations,
                 registered services and the
                     events the services are
                               registered to.
   Server           The storage server shall     Test that all
  sessions         manage a log file that will    connections to
 monitoring     indicate who contacted the        the server are
                            server, when the      logged
                connection occurred and all      Test that failed
                           the data transfer.     connections
                                                  attempt are
                                                  logged
                                                 Test that all
                                                  location data
                                                  transfers are
                                                  logged
 Server GUI     The storage server will have     Test that the
                 basic GUI, exposed via web       server GUI can
                pages, with a pleasant view       be logged in with
                   of the database and past       valid admin
                   operations. Access to the      credentials
                       pages will require the    Test that the
                   username & password of         server GUI can’t
                          the storage server      be access
                              administrator.      without logging
                                                  in
                                                 Test that it is
                                                  possible to get a
                                                  specific User
                                                  location via the
                                                  server GUI
                                                 Test that it is
                                          possible to
                                          unregister and
                                          delete a user
                                          using the GUI
                                         Test that it is
                                          possible
  Server     An installation guide on    Verify that
Deployment      how to set up a new       Server is
               storage server will be     installed and
                             provided     working after
                                          following the
                                          steps described
                                          in the manual
5. System Architecture
5.1. Components
"Localization Platform" is composed of:

The "storage server" -
saves all the locations (past and present) of the users (registered, past, online and offline) in
the application. That server will expose different interfaces for setting information and
getting existing information from it.

"Localization clients" –
client-side code packages that handle the interaction with the storage server. We will
provide localization clients for Android platforms. In addition to triggering the logics in the
server, the clients will also handle the device's own localization data, starting/stopping it,
reading from it, etc., leaving the consumer the simple option to turn the localization usage
on and off. One of the key limitations of the localization clients is that they only manage one
user's localization data. This is a security requirement in order not to take advantage of the
sensitive data.

"Registered service" –
another way of interacting with the storage server, is by letting the server know about the
presence of the client. The service will register itself in the server, and as a result will be
exposed into a larger set of operations with the server. The consumer will use this when he
needs to manage localization data of more than one user. The server can trigger events on
the registered services, instead of the services checking the server every now and then
("push" instead of "pull").

"Location recommendation" –
an example of a registered service that will be provided with the framework. This contains
an algorithm that based on the users' past locations, can try to recommend their upcoming
movement. The storage server will push new data to it, so when a client asks to recommend
his next movement, the service will be ready to solve it quickly.

"Location-based application" –
uses the "localization client" or interacts with a "registered localization service", to take
advantage of the framework's features. This will be developed by the consumer of our
framework. We will provide a "mock application" that takes use of every feature in the
localization framework, as a placeholder for the real application.
5.2. Architecture Diagram


             Storage server                                           Registered service




                                                                    Location recommendation


            Localization client




               Location-based                 Mock application      Legend:
                   application                                                    Communication
                                                                                     Inheritance




5.3. Configuration
The Android client configuration uses an XML file of configuration parameters, and lets
Android transform it into hard-coded variables when the code compiles. This mechanism is
built-in from the Android SDK. Some of the configuration parameters are:
   The URL of the storage server (and the external services)
   The fixed duration (milliseconds) for polling the GPS for location
   The fixed duration (milliseconds) for getting the location with the accelerometer
The server configuration is written in textual .properties files. Those files are made of
key=value lines, and we use an API for this type of files to get values from the keys. The
parameters can be changed only when the server is down, and after we put the server up
again, the new values are used.
The most common use for configuration in our architecture is when using interfaces, such as
the data access interface or the service interface. We don't want to hard-code construct the
concrete class in our code, so we use reflection, to take the package and name of the
concrete class from the configuration file and work with it as the interface.
Another common configuration parameters group in the servers is the databases URL paths,
schema names, username and password.
In the prediction server, we have a few more configuration parameters:
        The X most-frequent locations to define a new cluster
        The minimum support for apriori candidate generation (between 0.0 and 1.0),
         defines the threshold for the candidate-generation. e.g. 40 means 2 of 5 users have
         to support the sequence.
        The zoom level needed for all the locations being represented in Google Tiles. A
         Google tile consists of X, Y (identifiers) and a zoom level. The bigger the zoom, the
         smaller the square on the map.
The servers also have other files for configuration:
        An SQL file that represents the database schema. Hibernate-friendly data classes are
         automatically generated from it using a script.
        Hibernate configuration files.
        Web.XML – a file required for the server to know which classes to run, and special
         mechanisms like the REST protocol facades.


5.4. Server GUI
The localization framework will typically need a server administrator. To make his life easier,
we put together an HTML file for basic viewing and editing operations on the system. That
page allows him to:
        Look at the current database tables
        Edit some of the database tables' data, such as: users past locations, registration and
         unregistration times, and mostly things that are not primary key or constraint-
         related.
        Import new data of users locations into the system
        Register and unregister external services to the storage server
Of course, this page can only be accessed from inside the server computer and no external
user is given access. We also use that page to debug our application more carefully.



5.5. Deployment
The Android client is compiled very easily: the API compiles into JAR, and if there's a
location-based application like our Mock Application, it imports that JAR and compiles using
Android SDK or the Eclipse plugin. For the server/s, we use a big ant file for the deployment
of the different components. The automatic ant deployment consists of a few steps, and
both are the same in the storage server and the prediction server. Right now we use an
Apache Tomcat server and the deployment fits it and no other server:
    1. Compile the SQL schema into automatic classes (the commons.loca package).
    2. Import external JARs and libraries to use by the server.
    3. Copy all the JARs, libraries and projects, into the server "shared\lib" folder.
    4. Compile the server "services" project into a "war" file, which is a file that the Apache
       Tomcat server can handle.
    5. Copy the "war" file into the server "webapps" folder.
A "war" file is basically a zip of all the classes and references. When the server gets up, it
takes all the "war" files from its "webapps" folder, unzips them, and calls start-up classes it
recognizes (they have to inherit a superclass of Apache, we have BaseContextListener for
that). It also reads web.xml and finds out that we have REST protocol entry points, and the
classes that correspond to them.
The server can be deployed in any computer that's connected to the internet. The only thing
is that the Android client will have to know the server's IP address to connect to its REST
functions.
6. User Interface Draft
Our application is mostly a framework for other developers, but we did make a mock
application to demonstrate the capabilities of the application. Here are a few screens from
our demo "mock" application:
7. Testing
7.1. Performance Constraints
In order to check the most of the constraints, we will use a cluster of computers to set a
large array of android systems emulators each one running a client (About 150 emulators).
We will perform the following tests:
 Functionality                Constraints                        Tests             Comments
     Speed         The connection with the           In order to test the speed
                      storage server should take          constraint We will use
                      less than 5 seconds.               the emulator array to -
                   The location update from          Connecting to the
                      the client to the server            server
                      should take less than 5         Adding a new
                      seconds.                            location
                   The location prediction           Getting a prediction
                      should take less than 10
                      seconds.
    Capacity       The number of users that          Test that it is possible
                      can access the storage              to add 999 users to
                      server simultaneously will          the system
                      not exceed 999(TCP/IP           We will use the
                      capabilities).                      emulator array to
                   The number of active users            check that it is
                      can the storage server can          possible to connect
                      handle will not exceed 999          with up to 80 client
                                                          simultaneously
                                                      A higher capacity test
                                                          will be performed at
                                                          the beta testing
                                                          stage
  Throughput  The storage server should              We will use the
                      handle as many as 150               emulator array to
                      requests simultaneously             send 150 prediction
                      (The server is available to         requests
                      max. 999 users                      simultaneously.
                      simultaneously, although        We will verify that
                      some of them might wait             the 150 request got a
                      until a thread becomes              location prediction as
                      available).                         an answer
                   The predication server
                      should handle as many as
                      150 requests simultaneously
   Reliability     In 100% of the cases when         Legal and illegal
                      an unregistered client              registration requests
                      makes a request, the                will be sent to test
                      operation fails.                    durability of the
                   Each registration that is             system. Simulation of
                      supposed to succeed shall           a
                      take place.                     Registered and
                   Each request of a register            unregistered users
                    client should be succeeded,         will send prediction
                    in case the server is online.       request, all
                   Each request for location           registered should get
                    update should be                    a prediction and all
                    succeeded, in case the              unregistered should
                    server is online.                   get an error message
                   Each request for location
                    prediction should be
                    succeeded, in case the
                    server is online.
  Safety &         When a user sends a                We will use the
  Security          location update the storage         emulator array to
                    server will update only this        simulate a state
                    specific user's data                where many users
                   When a user sends a                 are adding different
                    location prediction request,        locations, and check
                    he will get the correct             that for each user it
                    information only about him          own unique location
                                                        was added
                                                       We will create a state
                                                        where each user has
                                                        a different unique
                                                        prediction, and then
                                                        check that each user
                                                        gets its own specific
                                                        unique prediction.
Portability &      The system works on the            All of the client teat
 Reliability        Android mobile operating            will be performed on
                   The server GUI web                  Android OS.
                    interface will be 100%              (Emulators and real
                    compatible with HTML                phones)
                    standards and therefore be         Test that it is possible
                    available to every standards-       to install the
                    compatible web browser.             application on the
                    The following web browsers          last version of the
                    are expected to be fully            Android OS
                    supported: Google Chrome,          We will perform the
                    and Firefox.                        server GUI functional
                   The system should support           test on the three
                    only in an English text             web browsers
                   In case of a network failure        mentioned above to
                    any connection between              make sure that the
                    client and server will be           application is not
                    disconnected.                       failing on them.
                   When the server crashes,           Test that it is possible
                    whether it is its software          to restore the system
                    crashing or its hardware            from a daily backup
                    crashing, it is supposed to         dump - To verify
                    go back up restoring above          support of restoring
                    90% of the data it previously       in case of the server
                    acquired.                           crushing.
 Usability        The API documentation will          Test that the javadoc
                   be available as static stand         is accessible via the
                   alone web pages                      internet
                   ("Javadoc").                        Functional testing of
                  The mock application will            the mock application
                   provide a way to check the           will cover the
                   following functions:                 usability test of the
                        o Registration.                 application
                        o Send current
                            location.
                        o Predict next location
                  The client will be able to
                   configure the sending
                   current location frequency
                   and the prediction
                   frequency
Availability      The database server and             This will have to
                   prediction server shall run at       tested over a long
                   least 95% of the time, and           period of running
                   listen to requests from              time. Mainly in the
                   clients.                             beta testing stage.
                  On the client side, the             Test that the android
                   application can be shut              application is starting
                   down and the client decides          smoothly
                   when to turn it on.                 Test that the android
                                                        application shutting
                                                        down gracefully on
                                                        the users command
8. Task List
        Period      Length                       Task
      10/4 - 23/4   2 weeks    Implementing The GAC algorithm and
                                           the Stay policy
       24/4 - 7/5   2 weeks       Implementing the BestManager,
                                     rearranging the server GUI
       8/5 - 21/5   2 weeks       Finishing up the UI for prototype
                                    presentation, integrating the
                              BestManager with the three algorithms
       22/5 - 4/6   2 weeks    Writing a User manual, expanding the
                                documentADD test part to a testing
       5/6 - 17/6   3 weeks    Setting up a large scale emulator test,
                                 Starting a field test (Beta release).

				
DOCUMENT INFO
Shared By:
Categories:
Tags:
Stats:
views:19
posted:12/11/2011
language:
pages:63