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.
4.4.2.
4.4.3.
4.4.4.
4.4.5.
4.5
4.5.1
4.5.2
4.5.3
4.5.4
5.
6.
7.
7.1
8.
Android Client……………………………………………………………………………………………..45
Server – General………………………………………………………………………………………….45
Storage Server…………………………………………………………………………………………….45
Prediction Server………………………………………………………………………………………...46
Other…………………………………………………………………………………………………………..46
Unit Testing…………………………………………………………………………………………………47
Basic Operations Testing……………………………………………………………………………..47
Framework Extensions Testing…………………………………………………………………….49
Framework Monitoring and Learning Testing……………………………………………...50
Server Requirements Testing………………………………………………………………………51
System Architecture…………………………………………………………………………………...53
User Interface Draft…………………………………………………………………………………….56
Testing………………………………………………………………………………………………………..57
Performance Constraints…………………………………………………………………………….57
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:
Primary actors:
Description:
Trigger:
Pre-conditions:
Post-conditions:
Flow of events:
Alternative flows:
ID:
Primary actors:
Description:
Trigger:
Pre-conditions:
Post-conditions:
Flow of events:
Alternative flows:
ID:
Primary actors:
Description:
Trigger:
Pre-conditions:
Post-conditions:
Flow of events:
Alternative flows:
1. Register user
Location-based application, user
The user adds himself to the system.
 In the mock application, the user clicks on the "Register" button.
 Location-based application calls the "register user" function.
Storage server is up
The location-based application knows the path to the storage server.
The location-based application is running.
The identifier of the user is saved in the DB.
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.
Case: the user already exists in the DB
Action: the system returns the system ID that was already allocated to
that user
2. Unregister user
User, Location-based application
The user removes himself from the system.
 In the mock application, the user clicks on the "Unregister" button.
 Location-based application calls the "unregister user" function.
Storage server is up
The location-based application knows the path to the storage server.
The location-based application is running.
The storage server sets the user's unregistration date.
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.
Case: user does not exist in the system
Action: the system returns a success message anyway
3. Add user location
User, Location-based application
The user informs the system about his current location.
 In the mock application, the user clicks on the "Add new location"
button.
 Location-based application calls the "add new location" function.
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.
The new location coordinates had been saved in the DB.
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
none
ID:
Primary actors:
Description:
Trigger:
Pre-conditions:
Post-conditions:
Flow of events:
Alternative flows:
ID:
Primary actors:
Description:
Trigger:
Pre-conditions:
Post-conditions:
Flow of events:
Alternative flows:
ID:
Primary actors:
Description:
Trigger:
Pre-conditions:
Post-conditions:
Flow of events:
Alternative flows:
4. Get last user locations
User, Location-based application
An application needs the last user locations
 In the mock application, the user clicks on the "get last user
locations" button.
 Location-based application calls the "get last user locations"
function.
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.
The function returns all the past locations of a specific user
1. The getLastUserLocations methods has been called
2. The function returns a list of all the past locations of a specific user
None.
5. Register service
Registered service
A service adds itself to the storage server, to be notified on events
The service calls the "register service" method
Storage server is up
The service knows the path to the storage server
The service is saved in the storage server's DB
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
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.
6. Unregister service
Registered service
A service disconnects itself from the storage server.
The service calls the "unregister service" method
Storage server is up
The service knows the path to the storage server
The storage server updates the service's "unregistration date" field.
The service sends its system ID to the storage server.
The storage server updates the service's "unregistration date" field in
the DB.
None.
ID:
Primary actors:
Description:
Trigger:
Pre-conditions:
Post-conditions:
Flow of events:
Alternative flows:
ID:
Main actors:
Short description;
Trigger:
Pre-conditions:
Post-conditions:
Flow of events:
ID:
Main actors:
Short
description:
Trigger:
Pre-conditions:
Post-conditions:
Flow of events:
7. Predict location
User, Location-based application
The client asks for its most predicted location.
 In the mock application, the user clicks on the "predict location"
button.
 Location-based application calls the "predict location" function.
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.
The client application gets the coordinate of the most predicted
location.
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.
Case: not enough data / cannot predict a location for the user
Action: a constant result will be returned: the unexisting coordinate
[200,200].
8. Monitor server data
Administrator
View the storage server data via server GUI, exposed as web pages.
The admin browses the server web GUI.
 Storage server (and its database) is up
 Administrator has logged in successfully to the web system
 A web page with the desired data is displayed to the administrator.
1. Admin chooses a database table to view
2. The system displays the table elegantly.
9. Audit server data
Administrator
Edit the storage server data via server GUI, exposed as web pages.
The admin pressed the "edit" button when viewing the server web GUI.
 Administrator is viewing the server data that he wants to change
 Administrator is logged into the system
 Storage server is up
 The storage server has changed according to the administrator's
changes.
 A web page containing the changed data is displayed to the
administrator.
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
A server operation
was made
Initiated By
System, triggered by
the application
developer (or the
user in the mock
application)
Description
The server
communicates
through REST
protocol. The user
can either use Loca
API to call a client
operation which will
call the server via
REST, or call the
server himself by
entering the right
parameters in a REST
call, or press a
button in the mock
application.
Action
When the server is
triggered, depending
on the operation it
initiates a database
session, and uses the
database to
read/write relevant
data. If the caller was
a client application
and the function has
an output, it is
returned via REST
protocol.
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
User registers
Initiated By
Application
developer
Description
The user has to register
itself before starting to
track locations.
LocaManager has a function
for that.
User starts
tracking
location
Application
developer
The user initiates the
location collection process
Location
polling
interval
passed
System
GPS signal is
received
System
Sometimes, we wish to
query the location sources
every X seconds for the
current location, just to
ensure we're synced and a
little more accurate
The system asks GPS for the
current user location, or
receives an event from the
GPSSynchronizer
Accelerator /
Compass
System
The system asks an internal
sensor for some input, or
Action
After notifying Loca Server
with the user's phone
identifier (IMEI), a unique user
ID is returned and saved. From
now on, the system can start
tracking locations.
Concrete LocaManager starts
managing the user's locations.
In BestManager's case, it starts
listening to signals from each
of the LocationSource classes.
Concrete LocaManager asks
the specified LocationSource
for the current location, gets
it, and continues its
calculations.
If BestManager is selected to
manage locations, it sends the
new location with its accuracy
to all the other LocationSource
classes, and they synchronize
accordingly.
StayPolicy calculates whether
the user has moved
signal is
received
User stops
tracking
location
receives an event from it.
Application
developer
The user asks LocaManager
to stop the location
tracking.
significantly from the last
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.
If BestManager is selected to
manage locations, it turns off
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 autogenerated. 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
Add user
location
Description
Localization client / 
registered service send to
the storage server a location
update, about a user, a 
specific time, and location
coordinate.


Get last user
locations
Localization client / 
registered service query the
storage server about
locations of a group of
users. Optional filtering 
parameters: date range,
max results to return.



Start
localization
client
Localization client begins 
getting user's locations
every period of time, and
sending updates to the 
server.
Stop
localization
client
Localization client stops the 
process of requirement
Register
service
A service adds itself to 
receive event notifications
from the storage server
("push").
This also gives the service 
permission to ask the server
Tests
Test that Localization
client can add a valid
location.
Test that a client can’t
add a non existing
location.
Test that a nonregistered client can’t
add new location
Verify that added
locations are stored in
the DB
Comments
Test that the
Localization client can
query for single user
last location
Test that the
Localization client can
query for a group of
users last location
Test filtering by date
on a query
Test filtering by max
results query
Test that a nonregistered client can’t
get user locations
Test that starting the
client does add
location periodically
Test that the location
sent are saved in the
right order in the DB
Test that after
stopping, no new
locations are added
for the client
Test that a service can
register to receive
notifications from the
server.
Test that a service
can’t register itself
This is mainly a
timed call to
“add location”
and so its tests
are covered by
it
for past locations and add
new user locations. 
more than one time
Test that a registered
service does get
notifications when
relevant events
happen (relevant
locations are added)
Unregister
service
Removes a service from the 
list of known clients from
the storage server.

Test that a service can
un-register itself from
the server.
Test that an
unregistered service
doesn’t get
notifications for any
event
Register user
Localization client sends a 
unique identifier of the user
("strong identity") to the
storage server. The storage
server returns an ID of the 
user, and that's how the
user is recognized from now
on. If the user already exists,
the server returns its
existing ID. 
Unregister
user
Localization client lets the 
server know that a user has
unregistered from the 
platform. The server simply
mentions the unregistration
date and time.

Events for the
registered
service
Previous Functional 
requirements can trigger
events for any registered
service that registered to
accept them. Whenever one
of those functions happens,
the storage server triggers
the following event in the
registered services that
requested to be notified on
that event.
Test that a user can
register from a client
and get an ID from the
server
Test that if an existing
user tries to register
again he will get his
stored ID (same one as
the first time)
Test the two different
registering users get
different IDs
Test that a user can
unregister.
Test that the server
reply an unregistering
user with the current
time
Test that the user is
removed from the DB
Test that a registered
service gets events for
every update – add
location, get last
location, register a
user and unregister a
user.
4.5.2. Framework Extensions Testing
Functionality
Location
prediction
Predict next
location
Description
Three algorithms for
recommending the next
movement of a user in the
system will be implemented
by a "registered service".
That service will register for
the event of "add user
location", so that every time
a new location is added, the
recommendation service is
notified.
A function of the 
recommendation service.
Returns the next
recommended location of 
the given user based on the
algorithm inside it.

Mock
application
A demonstrator for the 
localization client and the
registered service will be
Implemented.



Tests
Test that Prediction
for a registered
return a location.
Test that the
locations returned
are valid
coordinates
Test the a nonregistered user
trying to use
prediction get an
error message
Test that Users can
register and
unregister using the
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
Comments
Evaluating the
quality of the
prediction
algorithms is not a
functional
requirement
itself. Deciding the
quality of the
prediction will be
done later by beta
tester.
4.5.3. Framework Monitoring and Learning Testing
Functionality
Configuration
management
Description
The framework should
provide the user the ability
to control the
configuration of
the data usage frequency:
 Duration between the
location updates a
localization client
sends.
 If using the location
prediction service,
frequency of calling
that service.
And additional parameters,
such as:
 Address of the storage
server





Security
The framework should not 
expose the entire database
to one user, only the
information that relevant
for him. The localization 
client will get information
only relevant to the user it
represents.

Logger
The system shall have a 
logging mechanism, to
view all the user
commands


Tests
Test that the
default
configurations
work smoothly
Change the
frequency of
sending locations
using the demo
client UI
Change the
update
frequency using
the demo client
UI
Test the ability to
change the
location storage
server
Test that after
changing the
location server
location are still
saved
Test that the user
can’t get
prediction for
other users
Test that a user
can’t add
location for
another user
Test that a user
cant register
without its
unique ID
Test that it’s
possible to
change log level
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
Comments
the log.
Deployment
The localization client will 
be a code library, to be
used as reference inside
the location-based
application that will be
developed by the 
platform's user.
Test that the
localization client
can be imported
and added to a
new project
Test run the
client with the
imported project
4.5.4. Server Requirements Testing
Functionality
Server
Database
Server
sessions
monitoring
Description
The storage server shall
hold a database with all the
users, the users' locations,
registered services and the
events the services are
registered to.
The storage server shall 
manage a log file that will
indicate who contacted the
server, when the
connection occurred and all 
the data transfer.

Server GUI
The storage server will have 
basic GUI, exposed via web
pages, with a pleasant view
of the database and past
operations. Access to the
pages will require the 
username & password of
the storage server
administrator.


Tests
Test that all
connections to
the server are
logged
Test that failed
connections
attempt are
logged
Test that all
location data
transfers are
logged
Test that the
server GUI can
be logged in with
valid admin
credentials
Test that the
server GUI can’t
be access
without logging
in
Test that it is
possible to get a
specific User
location via the
server GUI
Test that it is
Comments

Server
Deployment
An installation guide on 
how to set up a new
storage server will be
provided
possible to
unregister and
delete a user
using the GUI
Test that it is
possible
Verify that
Server is
installed and
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
Registered service
Storage server
Location recommendation
Localization client
Location-based
application
Mock application
Legend:
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 constraintrelated.
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.
2.
3.
4.
Compile the SQL schema into automatic classes (the commons.loca package).
Import external JARs and libraries to use by the server.
Copy all the JARs, libraries and projects, into the server "shared\lib" folder.
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
In order to test the speed
 The connection with the
constraint We will use
storage server should take
the emulator array to less than 5 seconds.
 Connecting to the
 The location update from
server
the client to the 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
system. Simulation of
 Each registration that is
a
supposed to succeed shall
take place.
 Registered and
unregistered users
 Each request of a register


Safety &
Security


client should be succeeded,
in case the server is online.
Each request for location
update should be
succeeded, in case the
server is online.
Each request for location
prediction should be
succeeded, in case the
server is online.
When a user sends a
location update the storage
server will update only this
specific user's data
When a user sends a
location prediction request,
he will get the correct
information only about him
will send prediction
request, all
registered should get
a prediction and all
unregistered should
get an error message


Portability &
Reliability





The system works on the
Android mobile operating
The server GUI web
interface will be 100%
compatible with HTML
standards and therefore be
available to every standardscompatible web browser.
The following web browsers
are expected to be fully
supported: Google Chrome,
and Firefox.
The system should support
only in an English text
In case of a network failure
any connection between
client and server will be
disconnected.
When the server crashes,
whether it is its software
crashing or its hardware
crashing, it is supposed to
go back up restoring above
90% of the data it previously
acquired.




We will use the
emulator array to
simulate a state
where many users
are adding different
locations, and check
that for each user it
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.
All of the client teat
will be performed on
Android OS.
(Emulators and real
phones)
Test that it is possible
to install the
application on the
last version of the
Android OS
We will perform the
server GUI functional
test on the three
web browsers
mentioned above to
make sure that the
application is not
failing on them.
Test that it is possible
to restore the system
from a daily backup
dump - To verify
support of restoring
in case of the server
crushing.
Usability



Availability


The API documentation will
be available as static stand
alone web pages
("Javadoc").
The mock application will
provide a way to check the
following functions:
o Registration.
o Send current
location.
o Predict next location
The client will be able to
configure the sending
current location frequency
and the prediction
frequency
The database server and
prediction server shall run at
least 95% of the time, and
listen to requests from
clients.
On the client side, the
application can be shut
down and the client decides
when to turn it on.





Test that the javadoc
is accessible via the
internet
Functional testing of
the mock application
will cover the
usability test of the
application
This will have to
tested over a long
period of running
time. Mainly in the
beta testing stage.
Test that the android
application is starting
smoothly
Test that the android
application shutting
down gracefully on
the users command
8. Task List
Period
10/4 - 23/4
Length
2 weeks
24/4 - 7/5
2 weeks
8/5 - 21/5
2 weeks
22/5 - 4/6
2 weeks
5/6 - 17/6
3 weeks
Task
Implementing The GAC algorithm and
the Stay policy
Implementing the BestManager,
rearranging the server GUI
Finishing up the UI for prototype
presentation, integrating the
BestManager with the three algorithms
Writing a User manual, expanding the
documentADD test part to a testing
Setting up a large scale emulator test,
Starting a field test (Beta release).