-
Notifications
You must be signed in to change notification settings - Fork 1
Working with the source code
The source code of ChBoSync up to and including version 1.4 is provided as Eclipse project (after the release of version 1.4 the source code was migrated to a project for Android Studio, which in the meanwhile became the official IDE for Android development).
For the following description it is assumed that you have an installation of Eclipse with the "Android Developer Tools (ADT)", which can be obtained at the following URL: http://developer.android.com/sdk/index.html
-
Clone the Git repository with the following URL (for this you can use : https://github.com/mide42/chbosync4android.git
-
For cloning the Git repository you can use the eGit plugin for Eclipse) or a command line client for Git. For the latter one the command is:
git clone https://github.com/mide42/chbosync4android.git(the local clone of the repository will be in the current directory of the command line). -
In Eclipse/ADT choose "Import ..." in menu "File".
-
Selection of import source: "Existing Android Code Into Workspace" under node "Android".
-
Folder to select as "Root Directory": "ChBoSync_EclipseProject"
-
One project should appear in the table unter the "Root Directory"; ensure that in column "Project to Import" this project is selected and click on button "Finish".
-
The project contains all libraries needed for compiling in the folder "external-libs" (several Funambol libraries and "Joda Time".
-
Start the app in the emulator or a device connected via the "Android Debug Bridge (ADB)" to your PC by opening the context menu (right button of mouse) of the node labled "ChBoSync" in the "Package Explorer" and choose "Run As | Android Application".
A good starting point for exploring the source code are the screen classes in package de.chbosync.android.syncmlclient.activities, e.g. AndroidHomeScreen or AndroidLoginScreen. These classes are subclasses of class android.app.Activity.
The different types of data that can be synced (e.g., contacts, calendar or notes) are called "Sync Sources". For the setup of each of these Sync Sources there is a method in class AndroidAppSyncSourceManager, e.g. method setupContactsSource(). Each Sync Source is an instance of class AndroidAppSyncSource, whereas this class inherits from class AppSyncSource. For some data types there are special sub classes of AndroidAppSyncSource, e.g. CalendarAppSyncSource and ContactAppSyncSource.
If for the activation of a particular Sync Source it has to be checked if a particular 3rd party app is installed on the Android device, then the presence of this app is also checked in the setupXXXSource() method. For example, in method setupNotesSource() it is checked if "OI Notepad" is installed.
The big buttons on the app's main screen used for triggering the syncing of a particular syncing action (e.g. syncing of contacts or notes) are instances of class AndroidButtonUISyncSource.
Class AndroidHomeScreen represents the main screen of the app, i.e. the screen with the big buttons for the individual Sync Sources. The creation of these button is done in class UpdateAvailableSourcesUIThread, which is an inner class of AndroidHomeScreen .
When the button for a particular Sync Source is pressed (e.g., for syncing notes), then the following happens:
-
For each Sync Source's button an instance of class ButtonListener (inner class of class AndroidHomeScreen) is created.
-
The corresponding ButtonListener's method onClick() calls the method buttonPressed() of the HomeScreenController object referenced by the AndroidHomeScreen object (actually an object of class AndroidHomeScreenController, which is a sub class of HomeScreenController).
-
The method buttonPressed() of class HomeScreenController receives the index of the Sync Source as parameter. It fetches the corresponding object of class AppSyncSource and calls method HomeScreenController::syncSource().
-
Method syncSource() calls method synchronize() (still in class HomeScreenController). After several overloaded variants of this method have passed method SynchronizationController::forceSynchronization() is invoked.
-
After some checks by forceSynchronization() method continueSynchronizationAfterBandwithSaverDialog() is invoked, which again invokes another method named continueSynchronizationAfterFirstSyncDialog().
-
In this method an instance of class AppSyncRequest is created. An object of class AppSyncSource is added to this AppSyncRequest. The AppSyncRequest again is added to an object of class SyncScheduler.
-
For adding the AppSyncRequest the SyncScheduler's method addRequest() is called, which again calls method doSync().
-
Add the end of method SyncSchedule::doSync() method callListener() is invoked. At the end of this method the sync request's content is passed as argument to method sync() of an SyncSchedulerListener object.
-
Since SyncSchedulerListener is just an interface an object of class SyncEngine is used. Method sync() of SyncEngine is called, which calls method synchronize().
-
In method SyncEngine::synchronize() some checks are performed (e.g., if the device has connectivity). If all these checks are passed, then an object of class SyncThread is created and started. SyncThread is an inner class of class SyncEngine.
-
The work that is done in a background thread (rather than blocking the UI/main thread) is done in method SyncEngine::run(). This method just calls method sync() in the same class.
-
Method sync() calls method synchronize() (still in class SyncEngine). Within this method another method of SyncEngine is called, namely fireSync(). However, before this is done an instance of class SyncManager is returned, which is also one of fireSync()'s parameters. (There are two implementations of interface SyncManagerI, namely the already mentioned class SyncManager and class SapiSyncManager; however, for the Sync Sources supported by ChBoSync so far always class SyncManager is chosen. SapiSyncManager seems to be for media content like images.)
-
In method SyncEngine::fireSync() just method sync() of the SyncManager object is invoked.
-
Method SyncManager:sync() is rather long. Somewhere in this method the method postRequest() of the same class in invoked.
Hint: To navigate to the source code of any of these classes mentioned without knowing the package you can press STRG+SHIFT+T for dialog "Open Type" in Eclipse. In this dialog you can search for classes just by their name.
The app has its own logger class, namely com.funambol.util.Log, which has only static methods. This logger is initialized by the code in method initLog() of class AppInitializer. Here an appender object is created that is passed to method Log.initLog(). Currently only an instance of class AndroidLogAppender will be used as appender, because method AppInitializer::isFileTracingAllowed() returns a hard-coded false.
The AndroidLogAppender writes the log messages to the corresponding methods of Android's standard logger (class android.util.Log). The tag for all these log messages is "ChBoSync".
There are other classes implementing the interface Appender, namely FileAppender or ConsoleAppender. There is also class MultipleAppender for using more than just one appender at the same time.
All the classes for logging mentioned so far can be found in package com.funambol.util.
Management of app's setting/preferences (e.g. show button to install "OI Notepad" on main screen instead of sync button when this app is not found on the current device) is handled by class AndroidConfiguration in package de.chbosync.android.syncmlclient. This class implements the singleton pattern and stored the settings as shared preferences file named "fnblPref.xml" (full path on emulator's filesystem: /data/data/de.chbosync.android.syncmlclient/shared_prefs/fnblPref.xml) . The saving and loading of the settings used by the original Funambol client are handled in a superclass of this class, namely class Configuration in package com.funambol.client.configuration.
Some important methods in class AndroidAdvancedSettingsTab (on which the settings introduced by ChBoSync were added):
- initScreenElements(): Setup of UI element, e.g. instances of class TwoLinesCheckBox for settings concerning "OI Notepad".
- hasChanges(): Determines if at least one setting was changed, so that saving is necessary.
The default values for settings are defined in method load() either in class Configuration or in the subclass AndroidConfiguration.