Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Documentation changes for Android and bulk loaders.
- Loading branch information
Showing
8 changed files
with
338 additions
and
4 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,314 @@ | ||
| <?xml version="1.0" encoding="UTF-8"?> | ||
| <!-- Licensed to JumpMind Inc under one or more contributor license agreements. | ||
| See the NOTICE file distributed with this work for additional information | ||
| regarding copyright ownership. JumpMind Inc licenses this file to you under | ||
| the GNU General Public License, version 3.0 (GPLv3) (the "License"); you | ||
| may not use this file except in compliance with the License. You should have | ||
| received a copy of the GNU General Public License, version 3.0 (GPLv3) along | ||
| with this library; if not, see <http://www.gnu.org/licenses/>. Unless required | ||
| by applicable law or agreed to in writing, software distributed under the | ||
| License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS | ||
| OF ANY KIND, either express or implied. See the License for the specific | ||
| language governing permissions and limitations under the License. --> | ||
| <section version="5.0" xml:id="android" xmlns="http://docbook.org/ns/docbook" | ||
| xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude" | ||
| xmlns:svg="http://www.w3.org/2000/svg" xmlns:ns="http://docbook.org/ns/docbook" | ||
| xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:html="http://www.w3.org/1999/xhtml"> | ||
| <title>Synchronization to and from Android Devices </title> | ||
|
|
||
| <para> | ||
| SymmetricDS now has its web-enabled, fault-tolerant, database | ||
| synchronization | ||
| software available on the Android mobile computing | ||
| platform. The Android client follows all of the same concepts and | ||
| brings to Android | ||
| all of the same core SymmetricDS features as the | ||
| full-featured, | ||
| Java-based SymmetricDS client. The Android client is a | ||
| little bit different | ||
| in that it is not a stand-alone application, but | ||
| is designed to | ||
| be referenced | ||
| as a library to run in-process with an | ||
| Android | ||
| application | ||
| requiring | ||
| synchronization for its SQLite database. | ||
| </para> | ||
| <para> | ||
| By using SymmetricDS, mobile application development is | ||
| simplified, in that the mobile application developer can now focus | ||
| solely on interacting with their local SQLite database. SymmetricDS | ||
| takes care of capturing and moving data changes to and from a | ||
| centralized database when the network is available | ||
| </para> | ||
| <para> | ||
| One of the main goals of the SymmetricDS 3 release was to support | ||
| deployment to Android devices. SymmetricDS's overall footprint was | ||
| reduced by eliminating a number of external dependencies in order to | ||
| better deploy to Android. Also, the database access layer was | ||
| abstracted so that the Android specific database access layer could be | ||
| used. This allows SymmetricDS to be efficient in accessing the SQLite | ||
| database on the Android device. | ||
| </para> | ||
| <para> | ||
| In order to convey how to use the SymmetricDS Android libraries, | ||
| the example below will show how to integrate SymmetricDS into the NotePad | ||
| sample application that comes with the Android ADK. | ||
| </para> | ||
| <para> | ||
| The NotePad sample application is a very simple task list | ||
| application | ||
| that persists “notes” to a SQLite database table called | ||
| Notes. The | ||
| Notes table will be configured to synchronize to a | ||
| centralized version | ||
| of the table. The Notes table looks as follows: | ||
| </para> | ||
| <para> | ||
| <table> | ||
| <title>Notes Table</title> | ||
| <tgroup cols="2"> | ||
| <thead> | ||
| <row> | ||
| <entry>Column Name</entry> | ||
| <entry>Column Type</entry> | ||
| </row> | ||
| </thead> | ||
| <tbody> | ||
| <row> | ||
| <entry>_ID(PK)</entry> | ||
| <entry>INTEGER</entry> | ||
| </row> | ||
| <row> | ||
| <entry>TITLE</entry> | ||
| <entry>TEXT</entry> | ||
| </row> | ||
| <row> | ||
| <entry>NOTES</entry> | ||
| <entry>TEXT</entry> | ||
| </row> | ||
| <row> | ||
| <entry>CREATED</entry> | ||
| <entry>INTEGER</entry> | ||
| </row> | ||
| <row> | ||
| <entry>MODIFIED</entry> | ||
| <entry>INTEGER</entry> | ||
| </row> | ||
| </tbody> | ||
| </tgroup> | ||
| </table> | ||
| </para> | ||
| <para> | ||
| Next, we will describe how to embed SymmetricDS in the NotePad | ||
| application. Eclipse 3.7.2 and Android ADK 20.0.3 were used for this | ||
| example. | ||
| </para> | ||
| <para> | ||
| To start,create the NotePad project. You do | ||
| this by adding a new Android Sample Project. Select the NotePad | ||
| project. | ||
| </para> | ||
| <para> | ||
| <figure id="New Sample NotePad Project"> | ||
| <title>New Sample NotePad Project</title> | ||
| <mediaobject> | ||
| <imageobject> | ||
| <imagedata fileref="images/sync-android-1.png" | ||
| format="PNG" /> | ||
| </imageobject> | ||
| </mediaobject> | ||
| </figure> | ||
| </para> | ||
| <para> | ||
| SymmetricDS for Android comes as a zip file of Java archives (jar | ||
| files) that are required by the SymmetricDS client at runtime. This | ||
| zip file ()symmetric-ds-3.4.7-android.zip) can be downloaded from | ||
| the SymmetricDS.org website. The first step to using SymmetricDS in an Android | ||
| application is to unzip the jar files into a location where the | ||
| project will recognize them. The latest Android SDK and the Eclipse | ||
| ADK requires that these jar files be put into a libs directory under | ||
| the Android application project. | ||
| </para> | ||
| <para> | ||
| <figure id="Sample NotePad Project"> | ||
| <title>New Sample NotePad Project</title> | ||
| <mediaobject> | ||
| <imageobject> | ||
| <imagedata fileref="images/sync-android-2.png" width="9.5in" scalefit="1" align="center" | ||
| format="PNG" /> | ||
| </imageobject> | ||
| </mediaobject> | ||
| </figure> | ||
| </para> | ||
| <para> | ||
| Unzip the symmetric-ds-x.x.x-android.zip file to the NotePad | ||
| project directory. Refresh the NotePad project in Eclipse. You should | ||
| end up with a libs directory that is automatically added to the Android | ||
| Dependencies. | ||
| </para> | ||
| <para> | ||
| <figure id="Jar Files Added to Libs"> | ||
| <title>Jar Files Added to Libs</title> | ||
| <mediaobject> | ||
| <imageobject> | ||
| <imagedata fileref="images/sync-android-3.png" width="9.5in" scalefit="1" align="center" | ||
| format="PNG" /> | ||
| </imageobject> | ||
| </mediaobject> | ||
| </figure> | ||
| </para> | ||
| <para> | ||
| The Android version of the SymmetricDS engine is a Java class that can | ||
| be | ||
| instantiated directly or wired into an application via a provided | ||
| Android service. Whether you are using the service or the engine | ||
| directly you need to provide a few required startup parameters to the | ||
| engine: | ||
| <itemizedlist> | ||
| <listitem><command>SQLiteOpenHelper</command> – It is best (but not required) if the | ||
| SQLiteOpenHelper is shared with the application that will be sharing | ||
| the SQLite database. This core Android Java class provides software | ||
| synchronization around the access to the database and minimizes | ||
| locking errors. | ||
| </listitem> | ||
| <listitem><command>registrationUrl</command> – This is the URL of where the centralized | ||
| SymmetricDS instance is hosted. | ||
| </listitem> | ||
| <listitem><command>externalId</command> – This is the identifier that can be used by the | ||
| centralized SymmetricDS server to identify whether this instance | ||
| should get data changes that happen on the server. It could be the | ||
| serial number of the device, an account username, or some other | ||
| business concept like store number. | ||
| </listitem> | ||
| <listitem><command>nodeGroupId</command> – This is the group id for the mobile device in | ||
| the synchronization configuration. For example, if the nodeGroupId | ||
| is 'handheld', then the SymmetricDS configuration might have a group | ||
| called 'handheld' and a group called 'corp' where 'handheld' is | ||
| configured to push and pull data from 'corp.' | ||
| </listitem> | ||
| <listitem><command>properties</command> – Optionally tweak the settings for SymmetricDS. | ||
| </listitem> | ||
| </itemizedlist> | ||
| </para> | ||
| <para> | ||
| In order to integrate SymmetricDS into the NotePad application, | ||
| the | ||
| Android-specific SymmetricService will be used, and we need to tell | ||
| the Android application this by adding the service to the | ||
| AndroidManifest.xml file. Add the following snipped to the Manifest as | ||
| the last entry under the <![CDATA[<application>]]> | ||
| tag. | ||
| </para> | ||
| <para> | ||
| <programlisting> | ||
| <![CDATA[<service android:name="org.jumpmind.symmetric.android.SymmetricService" android:enabled="true" > | ||
| <intent-filter> | ||
| <action android:name="org.jumpmind.symmetric.android.SymmetricService" /> | ||
| </intent-filter> | ||
| </service>]]> | ||
| </programlisting> | ||
| </para> | ||
|
|
||
| <para> | ||
| The other change required in the Manifest is to give the application | ||
| permission to use the Internet. Add this as the first entry in the | ||
| AndroidManifest.xml right before the | ||
| <![CDATA[<application> tag]]>. | ||
| </para> | ||
|
|
||
| <para> | ||
| <programlisting> | ||
| <![CDATA[<uses-permission android:name="android.permission.INTERNET"></uses-permission> ]]> | ||
| </programlisting> | ||
| </para> | ||
|
|
||
| <para> | ||
| The only additional change needed is the call to start the service in the | ||
| application. The service needs to be started manually because we need | ||
| to give the application a chance to provide configuration information | ||
| to the service. | ||
| </para> | ||
|
|
||
| <para> | ||
| In NotePadProvider.java add the following code snippet in the onCreate | ||
| method. | ||
| </para> | ||
|
|
||
| <para> | ||
| <figure id="NotePadProvider.java"> | ||
| <title>NotePadProvider.java</title> | ||
| <mediaobject> | ||
| <imageobject> | ||
| <imagedata fileref="images/sync-android-4.png" width="9.5in" scalefit="1" align="center" | ||
| format="PNG" /> | ||
| </imageobject> | ||
| </mediaobject> | ||
| </figure> | ||
| </para> | ||
|
|
||
| <para> | ||
| <programlisting> | ||
| <![CDATA[ | ||
| final String HELPER_KEY = "NotePadHelperKey"; | ||
| // Register the database helper, so it can be shared with the | ||
| SymmetricService | ||
| SQLiteOpenHelperRegistry.register(HELPER_KEY, mOpenHelper); | ||
| Intent intent = new Intent(getContext(), SymmetricService.class); | ||
| // Notify the service of the database helper key | ||
| intent.putExtra(SymmetricService.INTENTKEY_SQLITEOPENHELPER_REGISTRY_KEY, | ||
| HELPER_KEY); | ||
| intent.putExtra(SymmetricService.INTENTKEY_REGISTRATION_URL, | ||
| "http://10.0.2.2:31415/sync/server"); | ||
| intent.putExtra(SymmetricService.INTENTKEY_EXTERNAL_ID, | ||
| "android-simulator"); | ||
| intent.putExtra(SymmetricService.INTENTKEY_NODE_GROUP_ID, "client"); | ||
| intent.putExtra(SymmetricService.INTENTKEY_START_IN_BACKGROUND, | ||
| true); | ||
| Properties properties = new Properties(); | ||
| // initial load existing notes from the Client to the Server | ||
| properties.setProperty(ParameterConstants.AUTO_RELOAD_REVERSE_ENABLED, | ||
| "true"); | ||
| intent.putExtra(SymmetricService.INTENTKEY_PROPERTIES, properties); | ||
| getContext().startService(intent); | ||
| ]]> | ||
| </programlisting> | ||
| </para> | ||
|
|
||
| <para> | ||
| This code snippet shows how the SQLiteOpenHelper is shared. The | ||
| application's SQLiteOpenHelper is registered in a static registry | ||
| provided by the SymmetricDS Android library. When the service is | ||
| started, the key used to store the helper is passed to the service so | ||
| that the service may pull the helper back out of the registry. | ||
| </para> | ||
|
|
||
| <para> | ||
| The various parameters needed by SymmetricDS are being set in the Intent | ||
| which will be used by the SymmetricService to start the engine. | ||
| </para> | ||
|
|
||
| <para> | ||
| Most of the parameters will be familiar to SymmetricDS users. In this case | ||
| a property is being set which will force an initial load of the | ||
| existing Notes from the client to the server. This allows the user of | ||
| the application to enter Notes for the first time offline or while the | ||
| SymmetricDS engine is unregistered and still have them arrive at the | ||
| centralized server once the SymmetricDS engine does get registered. | ||
| </para> | ||
|
|
||
| <para> | ||
| That's all you have to do to integrate SymmetricDS with your Android | ||
| application. Users who are adventurous or are already familiar with | ||
| SymmetricDS can probably figure out how to setup the central | ||
| SymmetricDS server and configuration synchronization for the Notes | ||
| table. The second part of this article will describe exactly that. A | ||
| few transformation goodies will be thrown in as well. | ||
| </para> | ||
| </section> |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.