Survey
* Your assessment is very important for improving the workof artificial intelligence, which forms the content of this project
* Your assessment is very important for improving the workof artificial intelligence, which forms the content of this project
Mass Observation Technical documentation Version 1.0 Mass Observation Technical documentation Version: 1.0 Date: 2011-01-14 Revision History Date Version Description Author 2011-01-14 1.0 First version Josip Petrić Doc. No.: Page 3 Mass Observation Technical documentation Version: 1.0 Date: 2011-01-14 1. Introduction 1.1 Purpose of this document The purpose of this document is to give insight to architecture and implementation of Mass Observation project. 1.2 Document organization The document is organized as follows: Section 1, Introduction, describes contents of this guide, used documentation during developing process etc. Section 2, Web application, gives insight to web application architecture and implementation details. Section 3, Web application detailed software design, describes software design of web application. Section 4, Mobile application, gives insight in mobile application implementation. 1.3 Intended Audience The intended audience is: Future developers of MOb 1.4 Scope The scope of this document is to give a detailed technical description of MOb and all its components. 1.5 References 1. Generated javadoc for mobile application - http://www.fer.hr/rasip/dsd/projects/btw/documents Page 4 Mass Observation Technical documentation Version: 1.0 Date: 2011-01-14 Table of content Mass Observation 2 Technical documentation 2 Version 1.0 2 1. Introduction 4 1.1 1.2 1.3 1.4 1.5 4 4 4 4 4 Purpose of this document Document organization Intended Audience Scope References Table of content 5 2. Web application 6 2.1 2.2 Web application user interface Web application menu generation 2.2.1 Web application architecture 2.2.2 The MVC architecture 2.3 System specification 6 6 6 8 8 Web application 8 2.4 9 1. 3. 4. Error handling Web application detailed software design 10 3.1 Directory structure 3.1.1 Web application directory structure 3.1.2 Web application Class diagram 3.2 Database model 3.2.1 Admin module 3.2.2 Initiator module 3.2.3 Observer module 3.2.4 Customer module 10 10 12 13 13 13 14 14 Mobile application 15 4.1 15 15 16 17 18 19 20 21 Mobile application classes 4.1.1 dsd.mob.communication 4.1.2 dsd.mob.interfaces 4.1.3 dsd.mob.main 4.1.4 dsd.mob.model 4.1.5 dsd.mob.parsers 4.1.6 dsd.mob.security 4.1.7 dsd.mob.utility Page 5 Mass Observation Technical documentation Version: 1.0 Date: 2011-01-14 2. Web application 2.1 Web application user interface The user interface of the Mass Observation system is a standards-compliant and user-friendly web application user interface. It is based on HTML, CSS and JavaScript (with the jQuery framework). This conforms to the best practices that the W3C recommends. Figure 2.1: Web application user interface sketch The sketch of the web application user interface shows regions of the site the user is going to interact with. The navigation is based on two menus. We have a main menu that is generated depending on the permissions that a user has. Side menu displays the options that are available depending on the module that was selected in main menu. All users can see the user bar for logout, change profile preferences and additional functions if necessary. Forms, lists, status messages and other main content will appear within a Main content region. Copyrights, site info and a link list are displayed in the footer part. 2.2 Web application menu generation Each user have permissions/roles to specific modules (Initiator, Observer, Consumer and Admin). Main menu is generated by special library (MainMenu) depending on the permissions that a user has. Each of the modules will be implemented within its controller. The controller will load the view with main content and side menu. 2.2.1 Web application architecture Page 6 Mass Observation Technical documentation Version: 1.0 Date: 2011-01-14 Figure 2.2: Web application model MySQL Database is used for data persistation, Apache server with PHP module for web application and standard web browser on user side. Page 7 Mass Observation Technical documentation Version: 1.0 Date: 2011-01-14 2.2.2 The MVC architecture Figure 2.3 MVC Architecture The aim of using MVC architecture is to devide application logic from the presentation and busniess logic. The anvantage of using MVC: Easier maintenance, testing, update the application Flexibility in planning and implementing object Model. Reuseability and morularoity Parallel developmnet of objects The application is extensible and scalable Model – Business logic. It represents data structures. Provide functions for retrieve, insert and update information in our database. View – Presentation logic. It is the information that is being presented to a user. Normally, this is the web page, but in Codeigniter a view can also be a page fragment (header or footer). Also it can be RSS page, or any other type of “page”. Controller – Application logic – contains logic of the page. It joins everything together and generates the page for the user 2.3 System specification Web application is powered by: Virtual machine: Linux OS Server: Apache 2.2 Database: MySQL 5.x Languages: PHP, Javascript Frameworks: Codeigniter (the PHP framework), JQuery (Javascript framework) Styles: HTML, CSS 1. Web application Page 8 Mass Observation Technical documentation Version: 1.0 Date: 2011-01-14 Mobile application is Android based application and because of that is will be written using Java programming language. Mobile application will be developed using Eclipse development tool and will be written for Android 1.5 operating system. It won’t have problems running on mobile phones with higher operating system. 2.4 Error handling We will use several methods to capture errors: show_error('message') This function will display the error message supplied to it using the following error template: “application/errors/error_general.php” show_404('page') This function will display the 404 error message supplied to it using the following error template: “application/errors/error_404.php” log_message('level', 'message') There are three message types (error, debug, info): 1. Error Messages. These are actual errors, such as PHP errors or user errors. 2. Debug Messages. These are messages that assist in debugging. For example, if a class has been initialized, you could log this as debugging info. 3. Informational Messages. These are the lowest priority messages, simply giving information regarding some process. Error occurred while processing the form will be caught by Form Validation Library Error page doesn’t exist username or password is incorrect the user name already exists in the database, when adding the user forbidden characters appear in URL Failed connection to database PHP scripting error Field not filled Invalid email address Invalid url in form If alphabetical character is inserted, but not allowed Action Show 404 error page Message incorrect username or password Message: user already exists Alert URL is incorrect Alert user and administrator Alert user and administrator Message: Field is required. Message: Field must contain a valid email address Message: Field must contain a valid URL Message: Field may only contain alpha-numeric characters Page 9 Mass Observation Technical documentation Version: 1.0 Date: 2011-01-14 3. Web application detailed software design 3.1 Directory structure 3.1.1 Web application directory structure systems application mass_observation cache config config codeigniter controllers controllers database errors fonts errors helpers helpers helpers language language language libraries libraries logs models logs models views views views Figure 3.1: Web application directory structure Using the CodeIgniter framework we have the ability to make few applications with the same framework core. For example, if we want to make a new application, only what we have to do is create a new folder with the application name inside the application folder (in our case we have created a new folder with name “mass_observation”). Additional we have to copy all of folders from the application to our new application folder (config, controllers, errors…). Same steps are for second application. If we have only one application, it is not needed to make previous actions, simple we can use application folder as the main folder of our application. Directories description: system – the main folder. It separates Web application from the other files and folders on the server. This folder contains an application folder for our application(s) and other folders and files which describe application core. Commonly we will not use any other folder than application folder because it can be “dangerous” change file from the application core. application – as said before, this is the folder of our application. Application folder consists of: config – the configuration folder consist all files necessary for configure our application (e.g., base url, index page, default language, database connectivity settings, routing, …) controllers – in the controllers folder we make our controllers as requires MVC (model – view – controller) architecture. Controller is the hart of our application, as they determine how HTTP request should be handled. Page 10 Mass Observation Technical documentation Version: 1.0 Date: 2011-01-14 errors – folder for specifying errors for application. We can separate errors from the our controller what is very important for maintenance. helpers – consists files (classes) which help us with tasks. Each helper file is simply a collection of functions in a particular category. For example we have “URL Helpers” that assist in creating links, “Form Helpers” that help us create form elements… language – as the name of folder says this folder help us to create multi language application. libraries – libraries folder consists modules for our application. CodeIgniter have much default libraries (e.g. Calendar, Database, Email, File uploading…). The one library is described as class which has configurations and methods for module. models – models folder consist PHP classes that are designed to work with information in our database. For example, model class contains functions to insert, update and retrieve our page. Models are required by the MVC architecture. views – views folder consist view files. View files are simply a web page, or a page fragment, like a header, footer, sidebar, etc. Views are never called directly; they must be loaded by a controller as required by the MVC architecture. Page 11 Mass Observation Technical documentation Version: 1.0 Date: 2011-01-14 3.1.2 Web application Class diagram Web services modul Webservice «uses» CodeIgniter Framework +login() +get_interface() +make_ob() +list_ob() SecurityLibrary +encrypt() +decrypt() CodeIgniter Libraries Web services modul UserAuthLibrary Authentication «uses» Controller CI_Base -instance +CI_Base() +get_instance() -_ci_scaffolding -_ci_scaff_table +Controller() +_ci_initialize() +_ci_scaffolding() +index() +login() +logout() +registration() +set_table() +set_identity() +set_credential() +authenticate() +is_valid() +has_identity() Admin modul ACLLibrary «uses» MOB_Controller +init() +add_role() +add_resource() +allow() +is_allowed() Accounts_model Admin «uses» +index() +add_user() +edit_user() +delete_user() +list() Initiator modul Observation modul ObservationEvents_model «uses» Initiator Observations_model +create_ob() +ignore_ob() +read_ob() «uses» Observer +index() +make_ob() +list() +index() +create_oe() +edit_oe() +start_oe() +stop_oe() +list() +create_account() +get_accounts() +get_by_username() +get_type() +update_account() +update_password() +delete_account() «uses» +create_oe() +get_oe() +update_oe() +start_oe() +stop_oe() InterfaceComponents_model +add_checkbox() +add_image_capture() +add_voice_recording() +add_writen_node() +get_oe_components() +get_component_types() Figure 3.2: Web application initial class diagram Image shows class diagram which contains representative classes of the model and controller layers of the application, and shows how those classes are connected and dependant on each other. Each of the modules will be implemented within its controller. Each controller inherits the basic controller. MOB_Controller - Used to check access and initiate specific resources common to all controllers. Webservice controller – Needs to implement web service actions for login, get interface of observation event, make and list observations events available for specific user. Authentication controller - Needs to implement actions for login, logout and registration new users. Page 12 Mass Observation Technical documentation Version: 1.0 Date: 2011-01-14 Admin controller - Needs to implement actions for add user, edit user, delete user and list available users. Initiator controller – Needs to implement actions for create, edit, start, stop and list observation events. Observer controller - Needs to implement actions for make and list available observations. Accounts_model - Needs to implement methods for manipulating accounts data in the database. ObservationEvents_model - Needs to implement methods for manipulating observations events data in the database. InterfaceComponents_model - Needs to implement methods for manipulating interface of observation event. Observations_model - Needs to implement methods for save and read observations data in the database. SecurityLibrary - There is to maintain the security of data transfer which is non-functional requirement UserAuthLibrary - Needs to implement authentication functionality and maintaining the session. ACLLibrary - Needs to implement Access control list functionality. You can add role and application resources (Controller, method and parameters) and allow user access to certain resources. After that is used to check if the user has access to certain resources. 3.2 Database model Figure 3.3: Database model Figure 11 shows ER model. We have four modules: the admin, the initiator, the observer and the customer module. 3.2.1 Admin module Administration module consists of the authentication and the administrator module – user control, group control, observation event control, observations control. Account describes a user who has an account. Every account (user) has role (admin, initiator, customer or observer). Every user can have more than one role. Also every user can belong to any group. Group has one or more users. It can be group of observers, or group of customers. 3.2.2 Initiator module Initiator module consists of the observation event. Every initiator can develop observation event. Every observation event has one or more interface component. The interface component describes component which initiator want to use for observation event. Every interface component has type of component. Type of component determines which table to use for form generation. As required we have four elementary tables: checkbox, image capture, voice recording and written notes (more types may be added later). Every table is Page 13 Mass Observation Technical documentation Version: 1.0 Date: 2011-01-14 specific in relation to type. So, every interface component can have one type or more types. 3.2.3 Observer module Observation module consists of the observation. Every observation has one observation event, one group of observers, time and location stamp. Location can have exactly name of location and x, y coordinate. One location has one observation. 3.2.4 Customer module Customer model will contain all the tables necessary to represent observations data in more details and suitable for further analysis. Page 14 Mass Observation Technical documentation Version: 1.0 Date: 2011-01-14 4. Mobile application 4.1 Mobile application architecture 4.1 Mobile application classes 4.1.1 dsd.mob.communication 4.1.1.1 Communication public class Communication extends java.lang.Object implements iCommunication This class handles all the communication with web-server. It implements iCommunicaton interface. This class implements Singleton pattern. Unique class object is accessible through method call Communication.getCommunicationInstance() Author: Josip Petric Method Summary DefaultHttpClient createClient(java.lang.String username, java.lang.String password) Method creates default http client with user credentials static iCommunication getCommunicationInstance() Method returns unique Communication object. RecievedData getMethod(java.lang.String uri, DefaultHttpClient client) Implementation of getMethod Page 15 Mass Observation Technical documentation RecievedData Version: 1.0 Date: 2011-01-14 postFile(java.lang.String uri, DefaultHttpClient client, java.io.File fileToSend, java.lang.String dataToSend, java.lang.String type) This method is used for uploading files to the web server. RecievedData postMethod(java.lang.String uri, DefaultHttpClient client, java.lang.String dataToSend) Implementation of POST method. void uploadFile(Context context, java.io.File file, java.lang.String interfaceWebId, int oeId, java.lang.String uploadUri, java.lang.String fileType, double latitude, double longitude, java.lang.String time) Method for uploading files to the web-server. 4.1.2 dsd.mob.interfaces 4.1.2.1 iCommunication public interface iCommunication Interface which every class for communication with web-server must implement. Author: Josip Petric Method Summary DefaultHttpClient createClient(java.lang.String username, java.lang.String password) Method creates default http client with user credentials RecievedData getMethod(java.lang.String uri, DefaultHttpClient client) Implementation of getMethod RecievedData postFile(java.lang.String uri, DefaultHttpClient client, java.io.File fileToSend, java.lang.String dataToSend, java.lang.String type) This method is used for uploading files to the web server. RecievedData postMethod(java.lang.String uri, DefaultHttpClient client, java.lang.String dataToSend) Implementation of POST method. void uploadFile(Context context, java.io.File file, java.lang.String interfaceWebId, int oeId, java.lang.String uploadUri, java.lang.String fileType, double latitude, double longitude, java.lang.String time) Method for uploading files to the web-server. 4.1.2.2 iParser public interface iParser Interface for classes that parse data sent from web-server. Author: Josip Petric Method Summary java.lang.String makeJsonForEventStatus(int eventId, int status) This method creates json object. java.lang.String makeJsonForNotes(NotesComponent notes) Page 16 Mass Observation Technical documentation Version: 1.0 Date: 2011-01-14 This method creates json String for user notes interface. java.lang.String makeJsonForObserverGroups(java.util.List<GroupsData> groups) Method to create JSON object containing selected groups for an observer java.lang.String makeJsonForQuiz(QuizComponent quiz) This method creates json String for user quiz interface. java.lang.String makeJsonForSendingFilesToWeb(java.lang.String interfaceid, int parentEventId, java.lang.String fileName, double latitude, double longitude, java.lang.String time) Method that creates Json object with informations about files that are being sent to the web server. java.lang.String makeJsonForUploadingQuizes(QuizComponent quiz) Method that creates JSON for quiz uploading. java.lang.String makeJsonStringFromOeList(java.util.LinkedList<ObservationEvent> oeList) This method creates json string from list of Observation Events NotesComponent makeNotesFromJson(java.lang.String jsonObject) This method converts json object to the Notes class. QuizComponent makeQuizFromJson(java.lang.String jsonObject) This method converts json object to the Quiz class. java.util.List<GroupsData> parseGroupData(java.lang.String recievedData) Method that parses the group names received from web server for a logged user java.util.LinkedList<ObservationEvent> parseOeData(java.lang.String data) Method gets Observation Event data and returns list of Observation Events UserData parseUserData(java.lang.String data) Method parse received data. 4.1.3 dsd.mob.main Package dsd.mob.main holds all the classes that forms View of MVC pattern. Classes will just be listed without many details about them. Details can be seen in generated javadoc. Class Summary AudioScreen Audio Interface Activity class. CameraScreen This is Activity class for Image interface screen CheckboxPollScreen GroupSettingsScreen Implementation of Settings screen Activity. LoginScreen Login Screen Activity class. MainScreen Main application's screen Activity. NewEventScreen Activity that shows new Observation Event to user. NotesScreen ObservationEventScreen This class represents Observation Event activity. R R.attr R.drawable R.id Page 17 Mass Observation Technical documentation Version: 1.0 Date: 2011-01-14 R.layout R.string R.styleable RadioPollScreen SettingsScreen Implementation of Settings screen Activity. VideoPlayer This class implements Video Player for previewing recorded video files. VideoRecorder Class that implements Video Recorder. VideoScreen This class is Video interface Activity implementation 4.1.4 dsd.mob.model This package is model of MVC pattern. Class Summary AbstractComponent Abstract class for Observation Event interface components Every component must inherit this class. AudioComponent This class represents Audio component, a type of Observation Event interface GroupsData NotesComponent This class represents Written notes, type of Observation Event interface. ObservationEvent Class represents Observation Event ObservationEventsList This class holds List of Observation Events OeArray This class represents array of Observation Events. PicturesComponent This class represents Pictures component, a type of Observation Event interface QuizComponent This class represents Quiz component, a type of Observation Event interface. RecievedData This class holds all user data recovered from web-server database UserData This class represents the application user. VideoComponent This class represents Video component, a type of Observation Event interface 4.1.4.1 Abstract component public abstract class AbstractComponent extends java.lang.Object Abstract class for Observation Event interface components Every component must inherit this class. Author: Josip Petric Method Summary int getComponentId() java.lang.String getComponentTitle() AbstractComponent.Type getComponentType() Page 18 Mass Observation Technical documentation Version: 1.0 Date: 2011-01-14 java.lang.String getInterfaceIdOnWeb() double getLatitude() double getLongitude() int getParentEventId() int getStatus() java.lang.String getTimeOfObservation() void setComponentId(int componentId) void setComponentTitle(java.lang.String componentTitle) void setComponentType(AbstractComponent.Type componentType) void setInterfaceIdOnWeb(java.lang.String interfaceIdOnWeb) void setLatitude(double latitude) void setLongitude(double longitude) void setParentEventId(int parentEventId) void setStatus(int status) void setTimeOfObservation(java.lang.String timeOfObservation) Other classes can be seen in generated javadoc. 4.1.5 dsd.mob.parsers 4.1.5.1 JsonParser public class JsonParser extends java.lang.Object implements iParser This class is used to parse all the data (JSON) received from web-server so that the rest of application can use that data. This class implements iParser interface. This class implements Singleton design pattern. Unique class object is accessible through method call JsonParser.getJsonParserInstance(); Author: Josip Petric Method Summary static iParser getJsonParserInstance() Page 19 Mass Observation Technical documentation Version: 1.0 Date: 2011-01-14 java.lang.String makeJsonForEventStatus(int eventId, int status) This method creates json object. java.lang.String makeJsonForNotes(NotesComponent notes) This method creates json String for user notes interface. java.lang.String makeJsonForObserverGroups(java.util.List<GroupsData> groups) Method to create JSON object containing selected groups for an observer java.lang.String makeJsonForQuiz(QuizComponent quiz) This method creates json String for user quiz interface. java.lang.String makeJsonForSendingFilesToWeb(java.lang.String interfaceid, int parentEventId, java.lang.String fileName, double latitude, double longitude, java.lang.String time) Method that creates Json object with informations about files that are being sent to the web server. java.lang.String makeJsonForUploadingQuizes(QuizComponent quiz) Method that creates JSON for quiz uploading. java.lang.String makeJsonStringFromOeList(java.util.LinkedList<ObservationEvent> oeList) This method creates json string from list of Observation Events NotesComponent makeNotesFromJson(java.lang.String jsonObject) This method converts json object to the Notes class. QuizComponent makeQuizFromJson(java.lang.String jsonObject) This method converts json object to the Quiz class. java.util.List<GroupsData> parseGroupData(java.lang.String receivedData) Method that parses the group names received from web server for a logged user java.util.LinkedList<Observat parseOeData(java.lang.String data) ionEvent> Method gets Observation Event data and returns list of Observation Events UserData parseUserData(java.lang.String data) Method parse received data. 4.1.6 dsd.mob.security More security features will be added. public class AuthDataManager extends java.lang.Object Class holds methods for managing authentication data Author: Josip Petric Method Summary static boolean isAuthenticationValidated(RecievedData data) Method checks if authentication is valid. static java.lang.String[] readAuthenticationData(Context context) Method returns authentication data for the user. static void saveAuthenticationData(java.lang.String username, java.lang.String password, Context context) This method writes username and password to private file. Page 20 Mass Observation Technical documentation Version: 1.0 Date: 2011-01-14 4.1.7 dsd.mob.utility 4.1.7.1 ImageAdapter public class ImageAdapter extends BaseAdapter This is a class for Image adapter. It is used to make a image gallery for each image interface for every Observation Event. Author: Josip Petric Constructor Summary ImageAdapter(Context context, java.io.File[] filesOfImages) Constructor class for Image Adapter. Method Summary int getCount() java.lang.Object getItem(int arg0) long getItemId(int arg0) View getView(int position, View view, ViewGroup arg2) 4.1.7.2 RecorderPreview public class RecorderPreview extends SurfaceView This class implements Surface View that is necessary for previewing what we can with the camera while recording. Author: Josip Petric Constructor Summary RecorderPreview(Context context, MediaRecorder recorder) Constructor of Preview Class. Method Summary Surface getSurface() void surfaceChanged(SurfaceHolder holder, int format, int w, int h) void surfaceCreated(SurfaceHolder holder) void surfaceDestroyed(SurfaceHolder holder) Page 21 Mass Observation Technical documentation Version: 1.0 Date: 2011-01-14 4.1.7.3 Utility public class Utility extends java.lang.Object Class is containing all necessary utility methods. Mostly for storing and reading data from memory. Author: Josip Petric Method Summary static java.lang.String componentTypeToString(AbstractComponent.Type type) This method returns String representation of interface component type. static java.lang.String convertStreamToString(java.io.InputStream is) This method converts input stream to its string representation static boolean deleteDirectory(java.io.File path) Method for deleting directories. static AbstractComponent getComponentById(int oeId, int componentId, Context context, java.lang.String username) Returns component by it's parent and it's own id static java.lang.String getCurrentTime() This method return current time static java.lang.String getDataFromFile(Context context, java.lang.String fileName) Method that returns data written in memory. static double[] getLocationForFile(java.lang.String filePath, Context context) This method returns location data for selected file. static java.lang.String getTimeForFile(java.lang.String fileName, Context context) This method returns the time for selected observation. static void markComponentAsUploaded(int oeId, int componentId, Context context, java.lang.String username) This method gets component from memory, marks it as uploaded and saves component back to memory. static java.lang.String readDataFromExternalMemory(java.lang.String fileName, java.lang.String extraPath) This method returns data from file in external memory. static void saveLocationOfObservation(java.lang.String filePath, Location location, Context context) This method creates file that contains location of observation. static void saveStringDataToExternalStorage(java.lang.String fileName, java.lang.String extraPath, java.lang.String data) This method writes given string data to external storage file. static void saveTimeOfObservation(java.lang.String fileName, Context context) This method writes the time of observation to the file. Page 22 Mass Observation Technical documentation static void Version: 1.0 Date: 2011-01-14 writeDataToFile(java.lang.String data, Context context, java.lang.String fileName) Method used to get initial data for application When user logs in for the first time initial data will be removed and real data will be written to file. Page 23