63
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
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 description:
Edit the storage server data via server GUI, exposed as web pages.
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 was made
System, triggered by the application developer (or the user in the mock application)
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.
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 Initiated By Description Action
User registers Application developer
The user has to register itself before starting to track locations. LocaManager has a function for that.
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.
User starts tracking location
Application developer
The user initiates the location collection process
Concrete LocaManager starts managing the user's locations. In BestManager's case, it starts listening to signals from each of the LocationSource classes.
Location polling interval passed
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
Concrete LocaManager asks the specified LocationSource for the current location, gets it, and continues its calculations.
GPS signal is received
System The system asks GPS for the current user location, or receives an event from the GPSSynchronizer
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.
Accelerator / Compass
System The system asks an internal sensor for some input, or
StayPolicy calculates whether the user has moved
signal is received
receives an event from it. 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.
User stops tracking location
Application developer
The user asks LocaManager to stop the location tracking.
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 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 location
Localization client / registered service send to
the storage server a location update, about a user, a
specific time, and location coordinate.
Test that Localization client can add a valid location.
Test that a client can’t add a non existing location.
Test that a non-registered client can’t add new location
Verify that added locations are stored in the DB
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.
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 non-registered client can’t get user locations
Start localization
client
Localization client begins getting user's locations
every period of time, and sending updates to the
server.
Test that starting the client does add location periodically
Test that the location sent are saved in the right order in the DB
This is mainly a timed call to
“add location” and so its tests are covered by
it
Stop localization
client
Localization client stops the process of requirement
Test that after stopping, no new locations are added for the client
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
Test that a service can register to receive notifications from the server.
Test that a service can’t register itself
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.
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
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.
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
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 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 Description Tests Comments
Location prediction
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.
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.
Predict next location
A function of the recommendation service.
Returns the next recommended location of
the given user based on the algorithm inside it.
Test that Prediction for a registered return a location.
Test that the locations returned are valid coordinates
Test the a non-registered user trying to use prediction get an error message
Mock application
A demonstrator for the localization client and the registered service will be
Implemented.
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
4.5.3. Framework Monitoring and Learning Testing Functionality Description Tests Comments
Configuration management
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
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
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.
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
Logger The system shall have a logging mechanism, to
view all the user commands
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
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 Description Tests Comments
Server Database
The storage server shall hold a database with all the
users, the users' locations, registered services and the
events the services are registered to.
Server sessions
monitoring
The storage server shall manage a log file that will
indicate who contacted the server, when the
connection occurred and all the data transfer.
Test that all connections to the server are logged
Test that failed connections attempt are logged
Test that all location data transfers are logged
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.
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
possible to unregister and delete a user using the GUI
Test that it is possible
Server Deployment
An installation guide on how to set up a new
storage server will be provided
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
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:
Storage server Registered service
Location recommendation
Mock application
Localization client
Location-based application
Legend: Communication
Inheritance
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 storage server should take less than 5 seconds.
The location update from the client to the server should take less than 5 seconds.
The location prediction should take less than 10 seconds.
In order to test the speed constraint We will use
the emulator array to -
Connecting to the server
Adding a new location
Getting a prediction
Capacity The number of users that can access the storage server simultaneously will not exceed 999(TCP/IP capabilities).
The number of active users can the storage server can handle will not exceed 999
Test that it is possible to add 999 users to the system
We will use the emulator array to check that it is possible to connect with up to 80 client simultaneously
A higher capacity test will be performed at the beta testing stage
Throughput The storage server should handle as many as 150 requests simultaneously (The server is available to max. 999 users simultaneously, although some of them might wait until a thread becomes available).
The predication server should handle as many as 150 requests simultaneously
We will use the emulator array to send 150 prediction requests simultaneously.
We will verify that the 150 request got a location prediction as an answer
Reliability In 100% of the cases when an unregistered client makes a request, the operation fails.
Each registration that is supposed to succeed shall take place.
Each request of a register
Legal and illegal registration requests will be sent to test durability of the system. Simulation of a
Registered and unregistered users
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.
will send prediction request, all registered should get a prediction and all unregistered should get an error message
Safety & Security
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
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.
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 standards-compatible 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.
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 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
Test that the javadoc is accessible via the internet
Functional testing of the mock application will cover the usability test of the application
Availability 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.
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 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 ADD test part to a testing document
5/6 - 17/6
3 weeks Setting up a large scale emulator test, Starting a field test (Beta release).
