main.tex

\documentclass[a4paper]{scrreprt}

%% Language and font encodings
\usepackage[english]{babel}
\usepackage[utf8x]{inputenc}
\usepackage[T1]{fontenc}

%% Sets page size and margins
\usepackage[a4paper,top=3cm,bottom=2cm,left=3cm,right=3cm,marginparwidth=1.75cm]{geometry}

%% Useful packages
\usepackage{amsmath}
\usepackage{graphicx}
\usepackage{wrapfig}
\usepackage[colorinlistoftodos]{todonotes}
\usepackage[colorlinks=true, allcolors=blue]{hyperref}

\usepackage{tabularx}

\usepackage{float}

\usepackage{fancyhdr}
\pagestyle{fancy}
\renewcommand{\chaptermark}[1]{%
	\markboth{\thechapter.\ #1}{}}
\fancyhf{}
\fancyhead[L]{\leftmark}


\title{ Neighborhood Security}
\subtitle{Software Design Document}
\author{Simone Ripamonti, Luca Stornaiuolo}
\titlehead{\centering\includegraphics[width=6cm]{imgs/polimi-logo}}


\begin{document}
\maketitle

\null\vfill
\noindent
Neighborhood Security Design Document \\
Version v1.0, July 2017\\
Copyright 2017 - Simone Ripamonti, Luca Stornaiuolo\\
\newpage

%\begin{abstract}
%Short abstract of the app (max 150 words)
%\end{abstract}

\tableofcontents


% ______________________
% chapter Introduction
% ______________________
\chapter{Introduction}

\section{About the Design Document}
In this section we want to introduce briefly our application.

\bigskip The application is developed for the course of "Design and Implementation of Mobile Applications" at Politecnico di Milano. The goal of the course is to efficiently design and implement a mobile application on a platform of our choice. This documents illustrates the decisions we made in order to accomplish this goal.

This Software Design Document is a document that provides documentation that will be used as a overall guidance to the architecture of the software project. In this document we provide a documentation of the software design of the project, including use case models, class and sequence diagrams.

The purpose of this document is to provide a full description of the design of \emph{Neighborhood Security}, a native Android application, providing insights into the structure and design of each component.

\section{Platform}
The choice of the platform was left to us. We decided to develop for Android.

\bigskip \noindent Main reasons:
\begin{itemize}
\item Android native applications are written in Java, which is a language that is familiar to us
\item We both use Android devices everyday, so we are familiar with the environment and we have the possibility to test the application on our physical devices
\end{itemize}

\section{Choice of the application}
We had full choice on the purpose of the application.

\bigskip The choice fall on an application that could support neighborhood watch associations, that are group of civilians devoted to crime and vandalism prevention within a neighborhood. The application gives the possibility to alert other user about criminal events that have just happened.

The particularity that characterizes this application is the possibility to receive notification about events in the user's favorite locations in real time and to brows a map of all the signaled events.

\bigskip The idea for the application came from personal experience. In our towns, groups of people are currently reporting criminal events using WhatsApp group chat, but this is not user friendly:
\begin{itemize}
\item You need to know and contact one of the administrators of the group
\item You need to share your personal phone number and information
\item You cannot have an ensemble view of all the reported events
\end{itemize}

\section{Risk analysis}
During the problem analysis, we identified some risks that can compromise the correct development of the project.

\bigskip We had to be very careful during the requirements collection phase, because the requirements must be clear so to avoid delays due to misunderstandings. Formal modeling of the application allows the reader not to be confused by it and to learn requirements in a clear way.

Another possible delay was learning Android concepts or techniques in advanced stages of the project, leading to possible code rewriting and inevitable loss of time.

\section{Time constraints}
Our time constraints were not as strict as they would have been in a project developed for real stakeholders. We had no precise and punctuated deadlines, but to deliver the project among the different call dates for the course.

\bigskip We begin to develop our application at the beginning of the second semester. Developing, testing and creating documentation took less than 6 months. Even the server side part was built and maintained during the same time span. We started development at February 2017 and complete it in July 2017.

\bigskip The team is composed by two people with both solid Java knowledge but little experience in Android, thus we had to dedicate some time to learn the environment.

\section{Stakeholders}
The main stakeholders of our project is the professor and the other students that might be attending the presentation. The audience wants to have a clear idea about the project idea and realization. Professor's main goal instead is to check if the concepts taught during the course are clear to us and if we succeeded in implementing them inside our project.

\bigskip Even though we had not currently planned to release our application in the Google Play Store, we designed it keeping simple and intuitive, suitable for every kind of users.

We used English as main language for our project, due to its diffusion in the world, and we currently provide an Italian translation. If we ever decide to officially release \emph{Neighborhood Security}, we will introduce other major languages to make it more usable. This can be easily done using localized string resource feature of Android.

% ______________________
% chapter General Overview
% ______________________
\chapter{General overview}

\section{Idea}
\emph{Neighborhood Security} is a native Android application that provides  users the possibility to report criminal events and receive notification about favorite areas.

\bigskip The application does not require users to be authenticated in order to browse the reported events, indeed everyone can easily  browse the reported events over a map and understand the safety of a certain location by simply checking how many reports have been done and of which kind.

Users can register an account, using a combination of email and password or using their Facebook or Google account. Registered users have access to a new set of functionalities, such as  subscribing to notification about a certain location, reporting events and voting already submitted events. Once subscribed to a location, users can now receive real time notifications as soon as another user report a criminal event.

\bigskip The main components of the project are:
\begin{itemize}
\item A server side part, composed by a relational database that contains events and subscriptions and the application logic that is in charge of notifying interested users about events;
\item A client side part, the Android application,  which tasks are to query the relational database, show the gathered informations and provide users a point of interaction with the service.
\end{itemize}

\section{Core features}
Here we list the core functionalities that can be found in our application. We decided to divide them considering the fragment in which is organized, allowing the reader to easily understand them and where they could be found in the application.
\begin{itemize}
\item Home
\begin{itemize}
\item First point of interaction with the user. A simple showcase presents to the user the main features of the application, such as seeing reported events and subscribe to notifications.
\item A lateral menu is provided to allow the user to access other features, such as the creation of an account that gives access to the interesting features of the application.
\item A set of icons provides the user with insights about his usage of the application.
\end{itemize}

\item Authentication
\begin{itemize}
\item Allows the user to authenticate using three different ways: a combination of email and password, a Google or Facebook account.
\item If they choose email and password authentication, users also have the capability to reset the chosen password in case they have forgotten it.
\item Choosing the other methods, users are required to allow the application to access their personal information such as profile data and email address.
\end{itemize}

\item Event map
\begin{itemize}
\item Provides users the possibility to see reported events placed on a map. Different kind of events are represented by means of different marker icons.
\item Last week tweets with the hashtag \#NeighborhoodSecurity are displayed in the map.
\item If the user gave permission to access location informations, the map is centered in the current position.
\item By clicking on an event marker, user can see more detailed information about the reported event.
\item By clicking on a tweet marker, the content of the Tweet is displayed.
\item In order to decrease the number of markers placed in the map, events are clustered according to their position. By clicking on a cluster, users can see the list of events that are contained in that cluster.
\item A search bar is provided in order to easily find and move to a particular location, with an auto-complete feature provided by Google.
\end{itemize}

\item Event list
\begin{itemize}
\item Shows a list of events that can be refreshed if the list is related to a specific location, subscription or submitting user. 
\item Users can easily understand the kind, by looking at characteristic icon, the location and date of the event.
\item By clicking on the event, a new view containing its details is shown.
\item If the user is the creator of a particular event, he can delete it by simply long clicking on the event.
\end{itemize}

\item Event creation
\begin{itemize}
\item Only authenticated users have access to this feature.
\item Events are categorized according to the kind of event: carjacking, burglary, robbery, theft, shady people and scammers.
\item Users must insert a brief description of the event.
\item Position of the event can be chosen by inserting the place name (using Google Places auto-complete service) or by inserting pure coordinates, that can be obtained by using the location service if authorized.
\end{itemize}

\item Event detail
\begin{itemize}
\item Shows all the informations available about the selected event. Reporter name is never shown to other users by design.
\item A small map allows users to understand more precisely where the event happened.
\item Authenticated users can vote the event. The more an event has been voted, the more we consider reliable the reported event.
\end{itemize}

\pagebreak
\item Subscription list
\begin{itemize}
\item Shows a list of subscriptions, if any, of the currently logged in user. The user can enable or disable notifications about a particular subscription and delete them if he is no longer interested in.
\item By clicking on a subscription, a new view containing the list of events that match the subscription is shown
\end{itemize}

\item Subscription creation
\begin{itemize}
\item Only authenticated users have access to this feature
\item Subscription are characterized by two components: a position, that can be a place or GPS coordinates, and a radius, up to 2000 metres.
\end{itemize}

\end{itemize}

\section{General qualities}
Our application has several characteristics of accessibility and usability. The user interface is easy to use and intuitive, so that the user quickly learns what to do. The design is enthralling and captivating to guarantee the best experience possible.
\begin{itemize}
\item Usability: the main actor of the system is the end user. For this reason we decided to make the user interface as easy as possible, but still keeping all the functionalities needed to provide the best user experience.
\item Nice User Interface: we tried to make our application as nice as possible, following Google's Material Design guidelines to have a clean and simple design.
\item No Account Required: we tried to provide the greatest number of features without needing users to register for an account.
\item Offline Mode: even when the user is not connected to a network, he can continue to use the application thanks to our caching system.
\end{itemize}

\section{Functional requirements}
In this section we present the requirements necessary to the correct behavior of the system:

\bigskip\underline{General requirements:}
\begin{itemize}
\item The application has to be comprehensible by as many people as possible, so we decided to use English language and provide an Italian translation.
\item The application has to start with a splash activity, meanwhile the initial settings are done.
\item The application has to provide a home activity that gives the user access to all the application functionalities.
\item The application needs to allow user to create an account but still partially work if the user doesn't want to.
\item The application has to provide users the possibility to report new events and create subscriptions.
\item The application has to provide a way to browse events and to manage active subscriptions.
\end{itemize}

\pagebreak
\underline{Home requirements}
\begin{itemize}
\item On first run, Home activity should introduce the application features to the user.
\item Home activity should provide immediate access to Subscription List functionality and Event Map functionality.
\item Home activity should have a left drawer to give user access to Authentication and additional features, such as Event and Subscription creation and user's Event list which are available only to authenticated users. The drawer should also display the current logged in user, if any.
\end{itemize}

\underline{Event map requirements}
\begin{itemize}
\item Event map activity should display events in the map in a clear and distinguishable way, clustering events by positions and using different icons according to the event type.
\item Event map activity should display the most recent Tweets containing the hashtag \#NeighborhoodSecurity, placing them on the map according to their position.
\item Event map activity should provide a search bar in which it is possible to search for a location and then update map position to the request location.
\item Event map activity should provide the possibility to create an event or subscription at a particular map position.
\end{itemize}

\underline{Event create requirements}
\begin{itemize}
\item Event create activity should be accessible only to registered users.
\item Event create activity should display an event type list where to select: carjacking, burglary, robbery, theft, shady people and scammers.
\item Event create activity should allow users to enter a brief description of the event.
\item Event create activity should allow user to select a location based on its address or GPS coordinate.
\item Event create activity should inform the user about the success or failure of the request.
\end{itemize}

\underline{Event list requirements}
\begin{itemize}
\item Event list activity should display all the events matching one criteria (id of the creating user, area of the event, subscription id) or provided in a list.
\item Event list activity should provide a way to refresh the list of events if they do not belong to a provided list.
\item Event list activity should provide a button to move to Event create activity.
\item Event list activity should provide a search bar to select a new location to search for new events to be displayed.
\item Event list activity should allow event's creator to delete the events by using a contextual menu.
\item Event list activity should sort events by creation date.
\end{itemize}

\underline{Event detail requirements}
\begin{itemize}
\item Event detail activity should display all the informations belonging to a single event: event type, description, location, creation date, number of votes.
\item Event detail activity should provide a map to easily understand where the event took place.
\item Event detail activity should provide a button to vote the currently displayed event, and a way to un-vote it.
\end{itemize}

\underline{Subscription create requirements}
\begin{itemize}
\item Subscription create activity should allow the choice of the location based on address or GPS coordinates.
\item Subscription create activity should allow the choice of the radius of interest up to 2000m.
\item Subscription create activity should inform the user about the success or failure of the request.
\end{itemize}

\underline{Subscription list requirements}
\begin{itemize}
\item Subscription list activity should be accessible only by registered users.
\item Subscription list activity should only display the subscriptions of the currently logged in user.
\item Subscription list activity should provide a way to refresh the list of subscription.
\item Subscription list activity should provide a button to move to Subscription create activity.
\item Subscription list activity should provide a way to enable or disable notification about a given subscription.
\end{itemize}

\underline{Authentication requirements}
\begin{itemize}
\item Authentication activity should be accessible only to users not currently logged in.
\item Authentication activity should allow users to register or login using email or to use their Facebook and Google accounts.
\item Authentication activity should delegate registration/access using Facebook or Google to the respective libraries.
\item Authentication activity should delegate registration/access using email to Email Authentication activity.
\item Authentication activity should return the user back to Home activity if the authentication is successful.
\end{itemize}

\underline{Email Authentication requirements}
\begin{itemize}
\item Email Authentication activity should allow user to register, login or reset the password.
\item Email Authentication should display fields for username, password and email, which might be hidden according to the operation the user is going to perform.
\end{itemize}

\section{Non-functional requirements}
These are the non-functional requirements that are necessary to guarantee a functional application.
\bigskip\begin{itemize}
\item \textbf{Portability}: in order to be used by the largest number of user possible, the application should also be extended to iOS platform and desktop users. This are modifications that will be further introduced by us in the future. 
\item \textbf{Stability}: the system should always be available to be used at any time it is needed. System failures and server side crashes must be avoided in order to guarantee this requirement.
\item \textbf{Availability}: the services must always be up and running even during a failure period. An administrator must restore the service as soon as possible. A backup facility must be present in order to do so.
\item \textbf{Reliability}: the data must be reliable, meaning that they are trustworthy and not corrupted by any other. So the remote database must be protected and secure for this purpose.
\item\textbf{Efficiency}: the application needs to use as less resource as possible. Algorithms and data structures have been developed to optimize the consumption of resources in the best way possible. 
\item \textbf{Extensibility}: the application was programmed with the idea that further extensions could be added in a simple way without deeply modifying the core of the application.
\item \textbf{Maintainability}: code is easily readable and commented, in this way it is maintainable by future programmers.

\end{itemize}

% ______________________
% chapter Data Design
% ______________________
\chapter{Data design}

\section{Internal software data structure}
The structure of our application is divided in two main parts: client-side and server-side.

\bigskip All the event, subscription and user data reside on a external database. These data are cached on the local database to allow the application to work also if Internet access is currently unavailable. Neighborhood Security is based on data displaying and data creation, so the data is isolated and accessed only with a Model-View-Controller system. The user by navigating in the different sections of the application will trigger data request from the database. Locally available data is shown immediately, meanwhile new fresh data is downloaded in an asynchronous way and the views are update as soon as possible. The communication between the server and the database is handled by a Retrofit client that communicates to our Rest web service and performs CRUD operations. The web service is hosted on Heroku\footnote{Heroku, \url{https://www.heroku.com/}} and has been developed using Java 8 and Jersey\footnote{Jersey, \url{https://jersey.github.io/}}. The permanent database storage is a MySQL database, called JawsDB\footnote{JawsDB, \url{https://www.jawsdb.com/}}, also hosted by Heroku.

On the client side there is a mirrored data structure of the data base, that is represented by model classes for Event, Subscription and User that will be filled after a specific request to the web server and stored in these objects. Locally stored data is timestamped, in this way we can remove old data in an automatized way. All the data obtained as the result of a request is stored in the local SQLite database. We also use shared preferences system of Android to locally store other information such as the list of already voted events and the list of active subscription notifications. In this way, Internet connection is not needed to show already cached events and subscriptions

\section{Database design \& implementation}
This kind of design has the aim to provide an abstract description of the data used by the application, independently from the database model. In our case only two simple classes represent the entire data structure needed on the client side and are Event and Subscription. On the server side, we need also to know information about registered users, in order to handle create or delete operations and to allow sending notifications.

\bigskip Below we put the attribute of each table object, their meaning, and their eventual relationship with other elements:
\begin{itemize}
\item \underline{\textbf{Event}}: This class represents the event object
\begin{enumerate}
\item \textbf{ID}: primary key, is a positive integer
\item \textbf{Date}: is the timestamp of creation
\item \textbf{Event Type}: is a value from an enumeration that categorizes the events: carjacking, burglary, robbery, theft, shady people and scammers
\item \textbf{Description}: is a string describing the event
\item \textbf{Country}: is a string representing the country where the event took place
\item \textbf{City}: is a string representing the city where the event took place
\item \textbf{Street}: is a string representing the street where the event took place
\item \textbf{Latitude}: is a double representing the latitude where the event took place
\item \textbf{Longitude}:  is a double representing the latitude where the event took place
\item \textbf{Votes}: is an integer representing the number of votes received by the event
\item \textbf{Submitter ID}: is a string representing the creator user, foreign key to User ID
\end{enumerate}

\item \underline{\textbf{Subscription}}:
\begin{enumerate}
\item \textbf{ID}: primary key, is a positive integer
\item \textbf{User ID}:  is a string representing the creator user, foreign key to User ID
\item \textbf{Minimum Latitude}: is a double representing the bottom bound of the area of interest
\item \textbf{Maximum Latitude}: is a double representing the top bound of the area of interest
\item \textbf{Minimum Longitude}: is a double representing the left bound of the area of interest
\item \textbf{Maximum Longitude}: is a double representing the right bound of the area of interest
\item \textbf{Radius}: is an integer approximating the radius of the area
\item \textbf{Country}: is a string representing the country in the center of the area
\item \textbf{City}:  is a string representing the city in the center of the area
\item \textbf{Street}:  is a string representing the street in the center of the area
\end{enumerate}

\item \underline{\textbf{User}}:
\begin{enumerate}
\item \textbf{ID}: primary key, is a string provided by Firebase and guaranteed to be unique across all the users registered to the application
\item \textbf{Name}:  is a string representing the name of the user
\item \textbf{Email}: is a string representing the email of the user
\item \textbf{FCM}: is a string representing a Firebase Cloud Messaging token of the user's last used device
\item \textbf{Superuser}: is a boolean that identifies if the user is a superuser or not, superusers bypass ownership check when deleting events or subscriptions
\end{enumerate}
\end{itemize}

\bigskip At the end the choice falls on a SQL database for these reasons:
\begin{itemize}
\item All the operations we are interested in are easily performed by writing simple SQL statements
\item Both of us are self-confident in using SQL databases
\end{itemize}

\bigskip Our \underline{remote database} is simply organized in five tables:
\begin{enumerate}
\item Event table: contains all the events
\item Votes table: contains all the votes registered as a pair event id and user id
\item Subscription table: contains all the subscriptions
\item User table: contains all the users
\item Authorization table: contains all particular authorizations as a pair user id and user level, where 1 is super user
\end{enumerate}

\par Our \underline{local cache database} is simpler since all the data is contained in two tables:
\begin {enumerate}
\item Event table: contains all the cached events, also with votes and timestamps
\item Subscription table: contains all the cached subscriptions, also with timestamps
\end{enumerate}
% ______________________
% chapter Architectures and Component Level Design
% ______________________
\chapter{Architectures and component level design}

\section{System architecture}
Neighborhood Security is divided in two main components: one is the Android client-side application and the other one is a server-side Java application. Now we will see them in detail.

\subsection{Client-side application}
This part of the application is divided in two different parts: the functional components represented by Java code and the graphical ones written in XML. The \textbf{Java code} provides all the functionality and methods to handle the graphics and user's interactions with the application. Some of the tasks it completes are for example: retrieve and store data, visualize data, display notifications, trigger events when the user interacts with the UI, etc.

The graphical component, all the \textbf{XML layout files}, are simply the interface that is visualized to the users. It is composed by various elements such as the navigation drawer, button, text boxes, images and other views of any kind, that are used to display all the informations and allow the user to interact easily with the application.

\subsection{Server-side application}
The server component of \emph{Neighborhood Security} is represented by a Java EE (Enterprise Edition) application, that provides a REST web service built using Jersey. The application is hosted by Heroku, which also hosts our SQL database based on JawsDB. The application interacts with the database using a JDBC (Java DataBase Connectivity) driver. The server application has two main objectives: a) expose the data on the database to the clients; b) send notifications to interested users, using Firebase Cloud Messaging. Because of this, the communication can be considered bidirectional.

\bigskip The architectural style is the usual of the enterprise application, based on different layers, distributed in different physical devices.

\subsection{Client-server interaction}
Now we will focus on the details regarding the internal structure of the mobile application, in order to better understand the interaction between the client device and the server.

\bigskip The paradigm we chose is the Model-View-Controller pattern for the entire system, because is the most suited for Android development and works well with the functionalities that we implemented in our application. In the Android client, the interfaces displayed to the user are the views. The controller logic is the part of application that allows interaction with the data, that is both stored locally and remotely, which represents our model. The server-side application has an important part of controller logic, in particular regarding the storage of new data and the delivery of notifications, but also the entire model of our data.

\bigskip Below we can see a visualization of the paradigm:
\begin{figure}[H]
	\centering
	\includegraphics[width=0.5\textwidth]{imgs/mvc}
	\caption{The MVC paradigm}
\end{figure}

As we said before the controller is split between client and server. For example the logic to display events is only present on the client side part as well as other classes that have the task to retrieve the data requested by the user. On the other hand, in the server part we provide the entire logic that handles the sending of notifications to the interested users based on their subscriptions and the created events

\bigskip After these considerations, we can assume that our client is a not a fat nor a thin one, because both the server-side and the client-side of the application have a considerable amount of logic inside.

Finally, as said before, the model is initially present in the server-side part, because the database stores the entire data about events, subscriptions and users; however it is partially replicated in the client-side part, since we need to cache data in order to allow the application to work even if no Internet connection is available.

\section{Architectural design}
In this section we will focus on briefly describe how the two part, the server-side and the client-side, are composed.

\bigskip The server side is composed by two main layers:
\begin{itemize}
\item \textbf{Data Layer}: contains the DBMS module and allow the data to be stored and be persistent
\item \textbf{Business Layer}: encapsulates the business logic and manages the communication with the stable memory of the database, retrieving the correct informations when needed
\end{itemize}

On the client side part, we have three divisions:
\begin{itemize}
\item \textbf{Data Layer}: includes those classes that are used to support the caching of the data on the local storage, it interacts with the business layer
\item \textbf{Business Layer}: contains different kind of classes, from the ones needed to query local database and the remote web services, to the ones that manage the application logic and support the view 
\item \textbf{View Layer}: provides interaction with the user. Since our is a mobile application, this layer is represented as the touch screen of the device used to visualize the application. This layer communicates with the logic level underneath that are used to communicate between the user interface and the application logic.
\end{itemize}

\begin{figure}[H]
	\centering
	\includegraphics[width=0.9\textwidth]{imgs/structure}
	\caption{Application architecture}
\end{figure}

\section{Java package organization}
\subsection{Application organization}
\begin{figure}[H]
	\centering
	\includegraphics{imgs/packages}
	\caption{Application packages}
\end{figure}

In this picture it is possible to see the overall organization of the application packages. The division was chosen in order to separate the application components. Now we will explain what each package contains.

\subsection{Model}
\begin{figure}[H]
	\centering
	\includegraphics{imgs/pack_model}
	\caption{The \emph{model} package}
\end{figure}
In this package we grouped the classes that represent the information that can be obtained from the web service and stored in the local database.

\subsection{Activity}
\begin{figure}[H]
	\centering
	\includegraphics{imgs/pack_activity}
	\caption{The \emph{activity} package}
\end{figure}
This package contains all the Android \emph{Activity} that have been implemented in the application, in most of the cases our activities are in charge of displaying the corresponding fragment and provide additional interactions to the user, such as floating buttons or action bars.

\subsection{Fragment}
\begin{figure}[H]
	\centering
	\includegraphics{imgs/pack_fragment}
	\caption{The \emph{fragment} package}
\end{figure}
This package contains all the Android \emph{Fragment} that have been implemented in the application. We decided to use fragments in order to be ready to reuse them when we will develop ad hoc interfaces for tablets or other devices.

\subsection{Adapter}
\begin{figure}[H]
	\centering
	\includegraphics{imgs/pack_adapter}
	\caption{The \emph{adapter} package}
\end{figure}
This package contains the required implementations of the \emph{Recycler View Adapter} that is needed to display custom objects in a Recycler View. We decided to extend the default behavior of Android's Recycler View by using \emph{RecyclerViewWithEmptyView} in order to show a default view when there are no items (events or subscriptions) in the adapter.

\subsection{Controller}
\begin{figure}[H]
	\centering
	\includegraphics{imgs/pack_controller}
	\caption{The \emph{controller} package}
\end{figure}
This package contains all the classes that are needed to interact with the local storage, in the \emph{db} sub-package, and with the REST web service, in the \emph{rest} sub-package. Fragments and activities should not interact directly with those packages, but only with \emph{NSService} that contains a set of auxiliary methods to perform specific operations that concern data or authentication. \emph{Constants} contains a set of useful predefined values that are used across the application.

\subsection{Services}
\begin{figure}[H]
	\centering
	\includegraphics{imgs/pack_services}
	\caption{The \emph{services} package}
\end{figure}
This package contains all the useful Android \emph{Service} that will run in the background even when the application is not open. In order for our application to work, we needed:
\begin{itemize}
	\item \emph{DatabaseCleanService} to perform database clean
	\item \emph{FCMReceiverService} to display notifications
	\item \emph{FCMTokenRefreshService} to update the device token in the web service
\end{itemize}


\section{Security}
Very little security countermeasure must be taken in consideration in our application.

\bigskip The unique way in which the DB could be compromised could be only a direct attack to our provider Heroku, but we assume that strict protection policies are taken against these type of attacks.

User authentication is handled by Google's Firebase platform, which we assume to be trustworthy and employing policies to protect their user data.

Moreover, our application does not contain sensible user data, so even if a potential attacker succeed in breaking the system, the damage will be minimum. SQL injections, that could be possible by exploiting query fields, are prevented by using prepared statements.



% ______________________
% chapter User Interfaces
% ______________________
\chapter{User interfaces}
In this section we will provide a certain number of screenshots of the application. We focused our attention in designing the application for mobile phones, even if some portions of code are already prepared to be displayed in larger screens. Layouts, dimensions and colors were chosen following the Android Material Design guidelines.\footnote{Material Design Guidelines, \url{https://material.io/guidelines/}}

\section{Splash screen}

\begin{minipage}{0.5\textwidth}
	\centering
	\includegraphics[width=0.7\textwidth]{imgs/splash}
	\captionof{figure}{The splash screen}
\end{minipage}
\begin{minipage}{0.5\textwidth}
	The splash screen welcomes the user when the application is starting, meanwhile it checks if a valid version of Google Play Services is installed on the device. If it is necessary, user is prompted to install a newer version of Google Play Services.
\end{minipage}

\section{Home}
\begin{minipage}{0.5\textwidth}
	\centering
	\includegraphics[width=0.7\textwidth]{imgs/home}
	\captionof{figure}{The home screen}
\end{minipage}
\begin{minipage}{0.5\textwidth}
	This screen is the first the user sees as soon as the splash activity is ended. If this is the first time the user launches the application, he will see a brief showcase that introduces the main functionalities of the application. It is mainly composed by two buttons: map and subscription list. These are the two main features of the application, so they are easily accessible. The icons in the top of the screen display auxiliary informations about the applications: statistics about events and subscriptions, general and Twitter help.
\end{minipage}
\begin{minipage}{0.5\textwidth}
	\centering
	\includegraphics[width=0.7\textwidth]{imgs/home_drawer}
	\captionof{figure}{The opened drawer}
\end{minipage}
\begin{minipage}{0.5\textwidth}
	Through a swipe from left to right, or by pressing the hamburger button, the user can access a lateral menu. In the menu the user gets access to other functions that are available in the applications, such as authentication and others that concern event and subscription creation or listing. This interface is really effective, since it keeps all the functionalities at a tap of distance, so the users will not lose time in searching how to reach functionalities.
\end{minipage}

\section{Authentication}
\begin{minipage}{0.5\textwidth}
	\centering
	\includegraphics[width=0.7\textwidth]{imgs/authentication}
	\captionof{figure}{The authentication screen}
\end{minipage}
\begin{minipage}{0.5\textwidth}
	The interface is simple and it just shows the three authentication methods, that are Email, Google and Facebook.
	By clicking on Google or Facebook buttons, the user will be prompted to choose which of his accounts he would like to use inside the application. This is the fastest way to create an account in \emph{Neighborhood Security}, since no other fields are required to be filled.
\end{minipage}
\begin{minipage}{0.5\textwidth}
	\centering
	\includegraphics[width=0.7\textwidth]{imgs/authentication_email}
	\captionof{figure}{The email authentication screen}
\end{minipage}
\begin{minipage}{0.5\textwidth}
	By clicking on "Login with email", a new page will open that and will let the user perform operations like registering a new account, signing in and resetting the password. 
\end{minipage}

\section{Map}
\begin{minipage}{0.5\textwidth}
	\centering
	\includegraphics[width=0.7\textwidth]{imgs/event_map}
		\captionof{figure}{The event map screen}
\end{minipage}
\begin{minipage}{0.5\textwidth}
	 The user can move and zoom in or out with the gesture he is used to (scroll and pinch-in / pinch-out). Users can also search for a  location by using the search form provided by Google Place Autocomplete, that also suggests places meanwhile the user is writing. 
	 By long clicking on a point of the map, a dialog is displayed showing additional functions to the user, allowing him to create an event or subscription at that specified point or to obtain th list of events that happened near there. Also, a floating action button is displayed, it is a simple shortcut to the event create page.
	 There are three class of markers that are displayed on the map: event, Twitter and cluster marker.
	 An event marker is characterized by an icon that suggests the kind of event that took place in the given position. By clicking on the event, the user will move to the event's detail page. 
	 The cluster marker instead, is characterized by the number of event that have been reported in that location. By clicking on the cluster, the user will see the list of events that happened in that location. 
\end{minipage}
\begin{minipage}{0.5\textwidth}
	\centering
	\includegraphics[width=0.7\textwidth]{imgs/twitter}
	\captionof{figure}{The twitter dialog fragment}
\end{minipage}
\begin{minipage}{0.5\textwidth}
	The Twitter marker is characterized by the social network logo. When the user clicks on a Twitter marker, a \textit{DialogFragment} is shown in order to display the Tweet content. In order to appear on the map, Tweets should use the hashtag \textbf{\#NeighborhoodSecurity} and provide fine or coarse location. Fine location is pure GPS coordinates, instead coarse location is based on points of interest, such as cities or neighborhoods. By clicking on the Tweet, Twitter application, if available, or website will open in order to allow further interaction with the user.
\end{minipage}

\section{Subscription list}
\begin{minipage}{0.5\textwidth}
	\centering
	\includegraphics[width=0.7\textwidth]{imgs/subscription_list}
	\captionof{figure}{The subscription list screen}
\end{minipage}
\begin{minipage}{0.5\textwidth}
	This page displays the list of active subscriptions, if any, otherwise a courtesy image is displayed, inviting the user to create new subscriptions. Each subscription displayed is characterized by it's notification status, which can be selected using the toggle on the right, and is easily understandable by the icon on the left. The main informations about the subscriptions are the location and its radius, both of them are easily readable on the screen. By clicking on a subscription, the user obtains the list of events that match that subscription. By long clicking on it, instead, the user will be asked if he wants to remove the subscription. The user can force a refresh of his subscriptions by simply doing a swipe top to bottom.
\end{minipage}

\section{Subscription creation}
\begin{minipage}{0.5\textwidth}
	\centering
	\includegraphics[width=0.7\textwidth]{imgs/subscription_create}
		\captionof{figure}{The subscription creation screen}
\end{minipage}
\begin{minipage}{0.5\textwidth}
	Its simple allows the user to create a subscription in few taps. A \emph{SeekBar} is provided in order to decide the radius of the subscription, from a minimum of 0 meters to a maximum of 2000. The user can decide the main location of the subscription in two ways, by searching for its name, for example by inserting the city and street name, or by using absolute coordinates. A button is provided to easily get the user current position, once he gave the application the permission to use location sensors. Creation is actually performed when the user clicks on the button in the top action bar.
\end{minipage}

\section{Event list}
\begin{minipage}{0.5\textwidth}
	\centering
	\includegraphics[width=0.7\textwidth]{imgs/event_list}
		\captionof{figure}{The event list screen}
\end{minipage}
\begin{minipage}{0.5\textwidth}
	This page shows the list of events that can match different criteria (submitted by a user, are matching a given subscription or belong to a particular area) or are provided in a list. Each displayed event is characterized by the kind of event, both using an icon and by text, the date it took place, the location and the number of votes it has received. All these information are easily understandable at a first glance. By clicking on a event, the user will see the full details of the event. By long clicking on a event instead, the user is asked if he wants to delete the even, this is only available if the event has been created by the current logged in user. The user can force a refresh of the events by simply performing a swipe from top to bottom. 
\end{minipage}

\section{Event creation}
\begin{minipage}{0.5\textwidth}
	\centering
	\includegraphics[width=0.7\textwidth]{imgs/event_create_2}
		\captionof{figure}{The event creation screen}
\end{minipage}
\begin{minipage}{0.5\textwidth}
	This interface is very similar to the subscription create one. Both share the fact that the location can be select both by address and by coordinates. The main difference is the presence of a text field, used to add a brief description of the event, and a spinner, that allows the user to select the kind of event. Creation is actually performed when the user clicks the menu button in the action bar.
\end{minipage}

\section{Event detail}
\begin{minipage}{0.5\textwidth}
	\centering
	\includegraphics[width=0.7\textwidth]{imgs/event_detail}
		\captionof{figure}{The event detail screen}
\end{minipage}
\begin{minipage}{0.5\textwidth}
	In this page the user obtains the full details of an event, that are displayed on a list. These details include date, type of event, description, location and number of events. The position of the event is also displayed in the map in the top portion of the screen, this is useful to easily localize the location where it took place. The button with a star is the way the user can vote an event. By clicking on it, the vote will be added and a snack bar is displayed to undo the operation, in case the user misclicks. The star will become full once the event has been voted.
\end{minipage}

\section{Notifications}
\begin{minipage}{0.33\textwidth}
	\centering
	\includegraphics[width=0.7\textwidth]{imgs/notification_android.png}
	\captionof{figure}{Notification on Android phone}
\end{minipage}
\begin{minipage}{0.33\textwidth}
	\centering
	\includegraphics[width=0.7\textwidth]{imgs/notification_wear_text.png}
	\captionof{figure}{Notification text on Android Wear}
\end{minipage}
\begin{minipage}{0.33\textwidth}
	\centering
	\includegraphics[width=0.7\textwidth]{imgs/notification_wear_map.png}
	\captionof{figure}{Notification map on Android Wear}
\end{minipage}
\par\bigskip
Notifications are used to show the user informations about the events that he is interested in, since they belong to one of his active subscription. By clicking on phone notification, the application will open and display the event details. On the wearable device instead, the notification is composed by two pages: on the first one, the user can see the location and description of the event, on the second one, a map showing the location of the event.

% ______________________
% chapter External Services
% ______________________
\chapter{External services and Libraries}
We have used several external services for our application, some of them are necessary for the proper behavior of the system, such as Retrofit to communicate with the server-side part of the application, and other only to enrich the overall experience of the user. They are completely transparent to the user and fully integrated within the application.

The main advantage in using these kind of services is first of all the ease to not to have to implement specific portion of code in order to achieve the same result that these external services already provide.

\bigskip Now we present the main external services that we have used and integrated in our application.

\section[Retrofit]{Retrofit\footnote{Retrofit, \url{http://square.github.io/retrofit/}}}
Is the fundamental service that allows our application to communicate with the REST interface of our server application, and thus with the remote database. The service provides an easy way to translate a simple Java method call into a request to the web service, handling all the marshalling/unmarshalling and serialization job. The services uses annotated Java classes to transform JSON objects into Java objects.

\section[Google Firebase]{Google Firebase\footnote{Google Firebase, \url{https://firebase.google.com/}}}

\subsection{Authentication}
This service is of foundamental importance since it handles all the authentication procedures for the users. In the client-side part of the application, it is used to allow user to register or login using their preferred method among Google, Facebook or classic email and password. In the server-side of the application, it is used to verify that the user token received in the header of a request are of a valid user. It has been easily integrated in both part of the application.

\subsection{Cloud Messaging}
This service handles the sending of messages from the server to the client. These messages are triggered by the creation or deletion of events on the server-side. The messages are of two different types: event creation and event deletion, that are sent to users that have an active subscription that matches the location of the events. In this way we can optimize the bandwidth consumption of our client-side application, indeed it is not required that it periodically checks if new events are available on the DB but it is informed by the server itself, result in a huge saving of bandwidth but also of workload on the server, since we reduce the number of requests. Although an official library exists for Android, the same is not true for Java, so we needed to use a third-party open source library to allow communication between our Java EE application and FCM Api.

\subsection{Job Dispatcher}
This secondary service is used in order to keep data stored in the local database consistent with the data available remotely, in particular we are interested in removing old events/subscriptions from the caching database. A simple way is to run a scheduled job every midnight in order to remove events and subscriptions that have not been refreshed since 7 days- In this way we prevent the user from seeing events available locally that have been deleted remotely

\section[Google Play Services]{Google Play Services\footnote{Google Play Services, \url{https://developers.google.com/android/}}}
\subsection{Authentication}
The service is used to obtain the Google user profile and email, that is then used by Firebase Authentication to handle new user creation or authentication.

\subsection{Location Places}
The service is used to allow user to search for locations in an easy way, since they can exploit an autocomplete feature for easier and faster location search.

\subsection{Maps}
It is a really important service, since in this way we can present the user the various event placed on a interactive map. Being able to see events placed in the map it's a really important feature of the application, since it is a quick way for the users to understand if a particular area is having particular intense criminal activity or if other users are active in the zone. A map is also displayed in the view that shows the detail of an event and also in the extended notification for Android Wear devices.

\subsection{Fused Location Provider}
This secondary service is used to obtain the device's last known position, it is useful to provide a fast way to let the user localize himself in the map, but also when creating an event or subscription at the user's position. This service requires the user to allow the application to have access to coarse or fine position. The application can continue to work even thought the user doesn't give these permissions.

\section[Facebook]{Facebook\footnote{Facebook, \url{https://developers.facebook.com/}}}
The service is used to obtain the Facebook user profile and email, that is then used by Firebase Authentication to handle new user creation or authentication.

\section[Twitter]{Twitter\footnote{Twitter, \url{https://dev.twitter.com/}}}
\subsection{Core}
This is the core of the Twitter service, it provides a way to interact with the REST Api of Twitter and perform searches across tweets. We used this service in order to be able to display Tweets on our Event Map. The library easily allowed us to search for Tweets matching our hashtag \#NeighborhoodSecurity and near a particular location.
\subsection{TweetUi}
We used this library to easily display Tweets in a fancy way, indeed it fully matches Twitter style guidelines when displaying the given Tweet.
\section{Other minor libraries}
\par Other libraries and services of secondary importance have been used in the application, mostly to make the development easy and quick, without the need to reimplement some basic functions.
\begin{itemize}
\item Glide\footnote{Glide, \url{https://github.com/bumptech/glide}}: an image loading and caching library, used to download the user profile picture and the static Google Map that is displayed on wearable devices during the notification of an event.
\item Xdroid Enum Format\footnote{Xdroid, \url{https://github.com/shamanland/xdroid}}: a library that allows to easily localize enumerations by means of annotations and XML files
\item UsefulViews\footnote{UsefulViews,\url{ https://github.com/FarbodSalamat-Zadeh/UsefulViews}}: a collection of views that follow current Google design guidelines for material design
\item Floating Action Button\footnote{Floating Action Button,\url{ https://github.com/Scalified/fab}}: a reimplementation of Google's floating action button that is enhanced with easier and richer customizations
\item Material Drawer\footnote{Material Drawer, \url{https://github.com/mikepenz/MaterialDrawer}}: it's a flexible, easy to use and all in one drawer implementation that provides the easiest possible implementation of a navigation drawer
\item Arc Layout\footnote{Arc Layout, \url{https://github.com/ogaclejapan/ArcLayout}}: a simple and customizable arc layout, we used id to display icons in the home page in a fancy way, without the need to use absolute positions
\item Fancy ShowCase View\footnote{Fancy ShowCase View, \url{https://github.com/faruktoptas/FancyShowCaseView}}: a library that easily allowed us to build a welcome and introduction screen for the new users
\end{itemize}

% ______________________
% chapter UML diagrams
% ______________________

\chapter{UML diagrams}
In this section we present some useful diagrams that helps the reader to better understand the interaction between the user and the application. Here we present some of them.
\section{Use Case diagrams}
These diagrams show the flow of operation triggered by a specific actor when it tries to perform some task. The actor can be the user (a human actor) or a system.
\par The use cases we propose show the main operations that are possible to perform in the system.
\subsection{Unlogged user interaction}
\begin{figure}[H]
	\centering
	\includegraphics[width=0.95\textwidth]{diagrams/use_case/unlogged_user.png}
	\caption{Use case: Unlogged user}
\end{figure}

\subsection{Logged user interaction}
\begin{figure}[H]
	\centering
	\includegraphics[width=0.95\textwidth]{diagrams/use_case/authenticated_user.png}
	\caption{Use case: Logged user}
\end{figure}
\pagebreak

\section{Class diagrams}
We decided to include a cumulative class diagram for our application. The structure is simple: almost all activity classes interact with their respective fragments, which may interact with the controller in order to show information to the user. The controller can interact with both the rest service and the local database. 
\begin{figure}[H]
 \centering
 \includegraphics[width=0.95\textwidth]{diagrams/class/class_diagram.png}
 \caption{Class diagram}
\end{figure}
\section{Sequence diagrams}
In this section we provide few sequence diagrams concerning the flow of the logical operations performed by our application once a certain operation is executed. These diagrams will show the interaction between methods and activities, rather than user and application.

\bigskip We decided to include only two examples of Sequence diagrams, in order to make the document not too complex and less readable.

\bigskip The two operation chosen are:
\begin{itemize}
	\item Displaying events given an area. This diagram shows how an activity can obtain a list of events, for example with the objective of displying them on a map or on a list. The activity asks NSService to retrieve the requested data, this class acts as a controller and interacts with both the Rest service and the local storage.
	\bigskip\begin{figure}[H]
		\centering
		\includegraphics[width=\textwidth]{diagrams/sequence/sequence_diag_eventbyarea.png}
		\caption{Displaying events by area sequence diagram}
	\end{figure}

	\pagebreak
	\item Reaching Event Detail activity. This diagram shows all the possible way to reach the Event Detail activity throughout all the possible user interactions, notice that some of the ways require particular conditions, such as the user to be logged in or to have received a notification	
	\bigskip\begin{figure}[H]
		\centering
		\includegraphics[width=\textwidth]{diagrams/sequence/sequence_diag_eventdetail.png}
		\caption{Reaching Event Detail activity sequence diagram}
	\end{figure}

\end{itemize}
% ______________________
% chapter Test cases
% ______________________

\chapter{Test cases}
This section describes the results of the main tests done on Neighborhood Security application.\\\\
\bigskip
\noindent
\begin{tabularx}{\linewidth}{|l|X|}
	\hline
	\textbf{Test Case} 	& \textbf{Display event list} \\ \hline
	Goal 				& Display event list \\ \hline
	Input 				& Select a cluster marker in  "Event map" activity or select "What's here" in  "Event map" activity or select "My Events" in "Home" activity drawer or select a subscription in "Subscription list" activity \\ \hline
	Expected outcome 	& The corresponding list of event is displayed \\ \hline
	Actual outcome 		& CORRECT: after loading events from the local storage and downloading new ones from the remote service, events are displayed in a list meanwhile the new ones are stored in local storage \\ \hline
\end{tabularx}
\bigskip
\noindent
\begin{tabularx}{\linewidth}{|l|X|}
	\hline
	\textbf{Test Case} 	& \textbf{Display subscription list} \\ \hline
	Goal 				& Display subscription list \\ \hline
	Input 				& Select "Subscription" button in "Home" activity \\ \hline
	Expected outcome 	& The list of subscription of the active user is displayed \\ \hline
	Actual outcome 		& CORRECT: if the user is authneticated, after loading subscription from the local storage and downloading new ones from the remote service, subscriptions are displayed in a list meanwhile the new ones stored in local storage \\ \hline
\end{tabularx}
\bigskip
\noindent
\begin{tabularx}{\linewidth}{|l|X|}
	\hline
	\textbf{Test Case} 	& \textbf{Display event map} \\ \hline
	Goal 				& Display event map \\ \hline
	Input 				& Select "Map" button in "Home" activity \\ \hline
	Expected outcome 	& The event map should load and display events near the user position \\ \hline
	Actual outcome 		& CORRECT: if the application was granted permission to access current location, the map will load centered in the user position meanwhile events are loaded from disk, refreshed from the remote service and stored on the device. \\ \hline
\end{tabularx}
\bigskip
\noindent
\begin{tabularx}{\linewidth}{|l|X|}
	\hline
	\textbf{Test Case} 	& \textbf{Create subscription (1)} \\ \hline
	Goal 				& Create subscription using Address\\ \hline
	Input 				& After selecting a radius in the range 0-2000 and a location obtained using Google Place Autcomplete, press the "Submit" button in the Action Bar \\ \hline
	Expected outcome 	& The subscription is created \\ \hline
	Actual outcome 		& CORRECT: the parameters are valid, so if network is available and a user logged in, the subscription is created and becomes active \\ \hline
\end{tabularx}
\bigskip
\noindent
\begin{tabularx}{\linewidth}{|l|X|}
	\hline
	\textbf{Test Case} 	& \textbf{Create subscription (2)} \\ \hline
	Goal 				& Create subscription using Coordinates\\ \hline
	Input 				& After selecting a radius in the range 0-2000 and a pair of legal coordinates, press the "Submit" button in the Action Bar \\ \hline
	Expected outcome 	& The subscription is created \\ \hline
	Actual outcome 		& CORRECT: the parameters are valid, so if network is available and a user logged in, the subscription is created and becomes active \\ \hline
\end{tabularx}
\bigskip
\noindent
\begin{tabularx}{\linewidth}{|l|X|}
	\hline
	\textbf{Test Case} 	& \textbf{Create event (1)} \\ \hline
	Goal 				& Create event using Address \\ \hline
	Input 				& After inserting a description, an event type and a location obtained using Google Place Autcomplete, press the "Submit" button in the Action Bar \\ \hline
	Expected outcome 	& The event is created \\ \hline
	Actual outcome 		& CORRECT: the parameters are valid, so if network is available and a user logged in, the event is created and interested users are notified \\ \hline
\end{tabularx}
\bigskip
\noindent
\begin{tabularx}{\linewidth}{|l|X|}
	\hline
	\textbf{Test Case} 	& \textbf{Create event (2)} \\ \hline
	Goal 				& Create event using Coordinates \\ \hline
	Input 				& After inserting a description, an event type and a pair of legal coordinates, press the "Submit" button in the Action Bar \\ \hline
	Expected outcome 	& The event is created \\ \hline
	Actual outcome 		& CORRECT: the parameters are valid, so if network is available and a user logged in, the event is created and interested users are notified \\ \hline
\end{tabularx}
\bigskip
\noindent
\begin{tabularx}{\linewidth}{|l|X|}
	\hline
	\textbf{Test Case} 	& \textbf{Disable notification for a subscription} \\ \hline
	Goal 				& Disable notification for a subscription \\ \hline
	Input 				& Toggle the switch for the desired subscription in the user's Subscription List \\ \hline
	Expected outcome 	& The switch is set on "off" and the bell icon changes  \\ \hline
	Actual outcome 		& CORRECT: if the subscription was previously enabled, as soon as the user moves the switch, the notification is disabled. If an event is received for that subscription, it will not be notified. \\ \hline
\end{tabularx}
\bigskip
\noindent
\begin{tabularx}{\linewidth}{|l|X|}
	\hline
	\textbf{Test Case} 	& \textbf{Enable notification for a subscription} \\ \hline
	Goal 				& Enable notification for a subscription \\ \hline
	Input 				& Toggle the switch for the desired subscription in the user's Subscription List \\ \hline
	Expected outcome 	& The switch is set on "on" and the bell icon changes \\ \hline
	Actual outcome 		& CORRECT: if the subscription was previously disabled, as soon as the user moves the switch, the notification is enabled. If an event is received for that subscription, it will be notified. \\ \hline
\end{tabularx}
\bigskip
\noindent
\begin{tabularx}{\linewidth}{|l|X|}
	\hline
	\textbf{Test Case} 	& \textbf{Delete event} \\ \hline
	Goal 				& Delete event \\ \hline
	Input 				& Long click on a current user's event on Event List \\ \hline
	Expected outcome 	& The event is deleted and disappears from the list \\ \hline
	Actual outcome 		& CORRECT: if the user is the creator of the selected event, after long clicking on the event, a popup menu will appear in order to allow the user to delete the event. Network connection is required in order to perform the operation. \\ \hline
\end{tabularx}
\bigskip
\noindent
\begin{tabularx}{\linewidth}{|l|X|}
	\hline
	\textbf{Test Case} 	& \textbf{Delete subscription} \\ \hline
	Goal 				& Delete subscription \\ \hline
	Input 				& Long click on a current user's subscription on Subscription List \\ \hline
	Expected outcome 	& The subscription is deleted and disappears from the list \\ \hline
	Actual outcome 		& CORRECT: after long clicking on the subscription, a popup menu will appear in order to allow the user to delete the subscription. Network connection is required in order to perform the operation. \\ \hline
\end{tabularx}
\bigskip
\noindent
\begin{tabularx}{\linewidth}{|l|X|}
	\hline
	\textbf{Test Case} 	& \textbf{Vote event} \\ \hline
	Goal 				& Vote the event \\ \hline
	Input 				& Click the star button on Event Detail screen \\ \hline
	Expected outcome 	& The current user vote is added and he is notified of the operation \\ \hline
	Actual outcome 		& CORRECT: if the button is not disabled, which means that the user has already voted the event, as soon as he clicks, the vote is added to the event. A snackbar is shown in order to undo the operation and the button icon changes. \\ \hline
\end{tabularx}
\bigskip
\noindent
\begin{tabularx}{\linewidth}{|l|X|}
	\hline
	\textbf{Test Case} 	& \textbf{Undo Vote event} \\ \hline
	Goal 				& Undo Vote event \\ \hline
	Input 				& After having voted an event, click the Undo button on the bottom bar \\ \hline
	Expected outcome 	& The current user vote is removed and he is notified of the operation \\ \hline
	Actual outcome 		& CORRECT: as soon as the user clicks the button, the event vote is removed and the snackbar disappears. After that the user can redo the vote. \\ \hline
\end{tabularx}
\bigskip
\noindent
\begin{tabularx}{\linewidth}{|l|X|}
	\hline
	\textbf{Test Case} 	& \textbf{Login using Facebook} \\ \hline
	Goal 				& Login using Facebook \\ \hline
	Input 				& Click on Facebook button in Authentication Activity \\ \hline
	Expected outcome 	& The user is logged in \\ \hline
	Actual outcome 		& CORRECT: after clicking on the button, the user is asked to access using his Facebook account and to grant the application permission to read profile information. If the user accepts, he is successfully authenticated in Neighborhood Security. If this is the first user access, then his informations are stored on the remote database.  A network connection is required to perform the operation. \\ \hline
\end{tabularx}
\bigskip
\noindent
\begin{tabularx}{\linewidth}{|l|X|}
	\hline
	\textbf{Test Case} 	& \textbf{Login using Google} \\ \hline
	Goal 				& Login using Google \\ \hline
	Input 				& Click on Google button in Authentication Activity \\ \hline
	Expected outcome 	& The user is logged in \\ \hline
	Actual outcome 		& CORRECT: after clicking on the button, the user is asked to access using his Google account and to grant the application permission to read profile information. If the user accepts, he is successfully authenticated in Neighborhood Security. If this is the first user access, then his informations are stored on the remote database. A network connection is required to perform the operation. \\ \hline
\end{tabularx}
\bigskip
\noindent
\begin{tabularx}{\linewidth}{|l|X|}
	\hline
	\textbf{Test Case} 	& \textbf{Login using Email and Password} \\ \hline
	Goal 				& Login using Email and Password \\ \hline
	Input 				& Click on "Sign in" in Email Authentication activity \\ \hline
	Expected outcome 	& The user is logged in \\ \hline
	Actual outcome 		& CORRECT: if the user inserts a valid email and password pair, after clicking on the "Sign in" button he is authenticated. A network connection is required to perform the operation. \\ \hline
\end{tabularx}
\bigskip
\noindent
\begin{tabularx}{\linewidth}{|l|X|}
	\hline
	\textbf{Test Case} 	& \textbf{Register using Email and Password} \\ \hline
	Goal 				& Register using Email and Password\\ \hline
	Input 				& Click on "Register now" and then "Sign up" in Email Authentication activity \\ \hline
	Expected outcome 	& The user is registered \\ \hline
	Actual outcome 		& CORRECT: if the user inserts valid email, password and username, after clicking on the "Sign up" button a new account is registered. A network connection is required to perform the operation. \\ \hline
\end{tabularx}
\bigskip
\noindent
\begin{tabularx}{\linewidth}{|l|X|}
	\hline
	\textbf{Test Case} 	& \textbf{Send Reset Password email} \\ \hline
	Goal 				& Send Reset Password email \\ \hline
	Input 				& Click on "Forgot password" and then "Reset password" in Email Authentication activity \\ \hline
	Expected outcome 	& The user receives an email with the instructions to perform password reset \\ \hline
	Actual outcome 		& CORRECT: if the user inserts his email, after clicking "Reset password" button, an email will be sent to his address. A network connection is required to perform the operation. \\ \hline
\end{tabularx}
\bigskip
\noindent
\begin{tabularx}{\linewidth}{|l|X|}
	\hline
	\textbf{Test Case} 	& \textbf{Show event markers when moving map (1)} \\ \hline
	Goal 				& Show event markers when moving map \\ \hline
	Input 				& Move the map in Event Map activity using gestures\\ \hline
	Expected outcome 	& Events matching the displayed portion of map are shown \\ \hline
	Actual outcome 		& CORRECT: as soon as the user moves the map using his fingers, events available locally are shown meanwhile a search is performed on the web service, in order to search for new events to display. \\ \hline
\end{tabularx}
\bigskip
\noindent
\begin{tabularx}{\linewidth}{|l|X|}
	\hline
	\textbf{Test Case} 	& \textbf{Show event markers when moving map (2)} \\ \hline
	Goal 				& Show event markers when moving map \\ \hline
	Input 				& Move the map in Event Map activity using Address search\\ \hline
	Expected outcome 	& Events matching the displayed portion of map are shown \\ \hline
	Actual outcome 		& CORRECT: as soon as the user selects a place using Place Autocomplete search, the map is moved to center the desired location, events available locally are shown meanwhile a search is performed on the web service, in order to search for new events to display. \\ \hline
\end{tabularx}
\bigskip
\noindent
\begin{tabularx}{\linewidth}{|l|X|}
	\hline
	\textbf{Test Case} 	& \textbf{Show Tweet markers when moving map (1)} \\ \hline
	Goal 				& Show tweet markers when moving map \\ \hline
	Input 				& Move the map in Event Map activity using gestures\\ \hline
	Expected outcome 	& Tweets matching the displayed portion of map are shown \\ \hline
	Actual outcome 		& CORRECT: as soon as the user moves the map using his fingers, a search for Tweets matching the displayed location and the hashtag \#NeighborhoodSecurity is performed, the resulting Tweets are displayed. \\ \hline
\end{tabularx}
\bigskip
\noindent
\begin{tabularx}{\linewidth}{|l|X|}
	\hline
	\textbf{Test Case} 	& \textbf{Show Tweet markers when moving map (2)} \\ \hline
	Goal 				& Show tweet markers when moving map \\ \hline
	Input 				& Move the map in Event Map activity using Address search\\ \hline
	Expected outcome 	& Events matching the displayed portion of map are shown \\ \hline
	Actual outcome 		& CORRECT: as soon as the user selects a place using Place Autocomplete search, the map is moved to center the desired location, a search for Tweets matching the displayed location and the hashtag \#NeighborhoodSecurity is performed, the resulting Tweets are displayed. \\ \hline
\end{tabularx}
\bigskip
\noindent
\begin{tabularx}{\linewidth}{|l|X|}
	\hline
	\textbf{Test Case} 	& \textbf{Show Tweet content} \\ \hline
	Goal 				& Show Tweet content \\ \hline
	Input 				& Click on Tweet marker on Event Map activity\\ \hline
	Expected outcome 	& The Tweet content is displayed on a dialog \\ \hline
	Actual outcome 		& CORRECT: When the user clicks on the Tweet marker, a DialogFragment is shown in order to display the content of the selected Tweet. The user can further click on the dialog, in order to open the Tweet in the browser or Twitter application. \\ \hline
\end{tabularx}

% ______________________
% chapter Cost Estimation
% ______________________

\chapter{Cost estimation}
Here we include a cost estimation for our project using the intermediate CoCoMo (Constructive Cost Model) model. This analysis has the goal to determine the number of month needed for the develop of a project of this type.

\bigskip The first step of the CoCoMo approach is to choose which type of software is being produced. This will classify the model parameters \emph{"a"} and \emph{"b"}.

\bigskip\noindent CoCoMo applies to three classes of projects:
\begin{itemize}
	\item \textbf{ORGANIC} projects have "small" teams with "good" experience working with "less than rigid" requirements
	\item \textbf{SEMI-DETACHED} projects have "medium" teams with mixed experience working with a mix of rigid and less than rigid requirements
	\item \textbf{EMBEDDED} projects are developed within a set of "tight" constraints. It is also combination of organic and semi-detached projects
\end{itemize}

The basic equation for our model is:
\[ EFFORT = EAF * a * (KLOC)^b  \]
where
\begin{itemize}
	\item \emph{EFFORT} is in terms of man-months
	\item \emph{EAF} is the effort adjustment factor
	\item \emph{KLOC} is the estimated number of thousand lines of code for the project
\end{itemize}

\bigskip
\noindent
\begin{tabularx}{\linewidth}{|X|l|l|}
	\hline
	\textbf{Intermediate Cocomo}	&\textbf{a}	&\textbf{b} \\ \hline
	Organic & 3.2 & 1.05 \\ \hline
	Semi-detached & 3.0 & 1.12 \\ \hline
	Embedded & 2.8 & 1.20 \\ \hline
\end{tabularx}
\bigskip

We decided to consider our project an ORGANIC one. Our team is a small one, just two people, and although this is our first time developing an Android application, we have a solid experience with Java. For this reason our coefficients are $ a = 3.2 $ and $ b = 1.05 $.

\bigskip Now in order to estimate \emph{EAF} we will use the standard provided tables, giving it a reasonable value. The value is calculated considering a set of four cost drivers: product attributes, hardware attributes, personnel attributes and project attributes.

\bigskip
\noindent
\begin{tabularx}{\linewidth}{|X|l|l|}
	\hline
	\textbf{Attributes} & \textbf{Rating} & \textbf{Value} \\ \hline
	Size of application database & Low & 0.94 \\ \hline
	Complexity of the product & Low & 0.85 \\ \hline
	Volatility of the virtual machine environment & Low & 0.87 \\ \hline
	Applications experience & Nominal & 1.00 \\ \hline
	Software engineer capability & Nominal & 1.00 \\ \hline
	Programming language experience & High & 0.95 \\ \hline
	Application of software engineering methods & High & 0.91 \\ \hline
	Use of software tools & High & 0.91 \\ \hline
	All others & Nominal & 1.00 \\ \hline
\end{tabularx}

\bigskip\noindent For our project we can calculate the number of person/month required:
\[ EFFORT = (0.94*0.85*0.87*1.00*1.00*0.95*0.91*0.91*1.00)*3.2*(6)^{1.05} \approx 11.5 \]
The number obtained is the number of people necessary to make the project in a month. In our case, we need 11.5 person month estimated. A manager will then schedule the number of people and time required accordingly.

However, we are a team of two people developing the application, so we can do the inverse procedure and determine th estimated time span required for our team.

We consider this equation of people needed based on duration and effort:
\[PEOPLE = EFFORT / DURATION\]
So we can calculate the inverse and obtain:
\[DURATION = EFFORT / PEOPLE = \frac{11.5\ person\cdot month}{2\ person} = 5.75\ month\]

The time of development is estimated in more or less 6 months of development.

%\bibliographystyle{alpha}
%\bibliography{sample}

\end{document}