diff --git a/README.md b/README.md index e1662d3..5bf60f2 100644 --- a/README.md +++ b/README.md @@ -1,67 +1,132 @@ # Getting started with the project migrate SDK: -You can obtain the Migrate binary SDK on the migrate github wiki page: +You can download the Project Migrate binary SDK on the migrate github wiki page: +``` https://github.com/wileyenterpriseandroid/migrate/wiki +``` Specifically on the migrate releases page: +``` https://github.com/wileyenterpriseandroid/migrate-sdk/releases/ +``` -The best way to get started working with the SDK is to explore the MigrateContacts -example from the book samples repository: +If you have not already downloaded and unpacked the latest SDK, please do so now. -git clone https://github.com/wileyenterpriseandroid/Examples.git +Installation: +---------- -Follow the instructions for using the example contained in MigrateContacts/README, which -contains detailed information about configuring the SDK and importing the MigrateContacts -example into Eclipse. +The projectmigrate SDK has two major pieces: -For comprehensive background and explanation, we recommend that you buy a copy of -Enterprise Android (@Amazon.com: search for "Enterprise Android"): +- Client: -http://www.amazon.com/Enterprise-Android-Programming-Database-Applications-ebook/dp/B00FX89KXM/ref=sr_1_1?ie=UTF8&qid=1403662172&sr=8-1&keywords=enterprise+android +A client in the form of an apk that contains the migrate content provider and +sync adapter. Install the client using the included install script: ----------- +``` +$SDK_DIR/install_client.sh +``` -If you have any questions about the migrate SDK or the Enterprise Android Examples, -please post them here: +Or execute the following command lines: -http://p2p.wrox.com/book-enterprise-android-programming-android-database-applications-enterprise-751/ +``` +adb install -r ./migrate-browser.apk +adb install -r ./migrate-client.apk +``` + + +- Service: + +The migrate backend service supports generic migrate synchronization persistence. +Its recommended to simply use the projectmigrate beta service at the following URL: + +``` +http://project-migrate-beta.appspot.com/ +``` + +This url is the default when configuring a migrate client account in Android. You +dont need to do anything other than install the migrate-client.apk to use this +instance of the migrate backend. + +Alternatively, you can also install the migrate server locally using the install script: + +``` +$SDK_DIR/install_server.sh +``` + +Or by copying installing apache tomcat and then copying migrate.war to: + +``` +$CATALINA_HOME/webapps +``` + +and the then restarting tomcat. -## Getting the code -If you, OPTIONALLY, choose to work with the migrate sdk and service code checkout the repos: +Configuration: +---------- -migrate-sdk -migrate -migrate-client -EnterpriseAndroidExamples +After you have installed the SDK, configure a client account one on your device +or emulator using: -Note: We dont recommend that you try to work with the code until you -have had some success working with the binary version of the SDK. +``` +Settings -> Accounts/Add Account(+) -> ProjectMigrate SyncAdapter +``` -As listed on the following page: -https://github.com/wileyenterpriseandroid +Fill out the sign-in screen using the appropriate migrate url, as following: -The best way to download this code, along with the examples that support it, -is by using the Repo tool. Get it like this: ``` -curl https://dl-ssl.google.com/dl/googlesource/git-repo/repo > ~/bin/repo +http://project-migrate-beta.appspot.com/ ``` -Once repo is installed, download this source with the following commands: +For a local tomcat installation use: ``` -repo init -u https://github.com/wileyenterpriseandroid/manifests.git -repo sync +http://10.0.2.2:8080/migrate/ ``` -You can download the source without using repo, with the following two commands: +Schema configuration: +---------- + +Any migrate based applications that you write will need to make use of a schema. +You can either create the schema using the web front end of the migrate service, +or you can generate it from a class. Please see, samples, MigrateContacts/README +for instructions on generating a migrate schema and making it available for sync +with the migrate backend service. +Samples: +---------- + +After you have installed and configured the projectmigrate components, the easiest +way to get started working with the SDK is to explore the SDK samples listed below: + +samples/MigrateContacts + +---------- + +Enterprise Android + +For comprehensive background and explanation of projectmigrate, we recommend that you buy a copy of +Enterprise Android (@Amazon.com: search for "Enterprise Android"): + +``` +http://www.amazon.com/Enterprise-Android-Programming-Database-Applications-ebook/dp/B00FX89KXM/ref=sr_1_1?ie=UTF8&qid=1403662172&sr=8-1&keywords=enterprise+android ``` -git clone https://github.com/wileyenterpriseandroid/migrate-sdk.git -git clone https://github.com/wileyenterpriseandroid/Examples.git ea-examples + +The book Enterprise Android also has examples that explore projectmigrate, you can download +these examples from the following location: + +``` +git clone https://github.com/wileyenterpriseandroid/Examples.git ``` +---------- + +If you have any questions about the Migrate SDK or the Enterprise Android Examples, +please post them here: + +``` +http://p2p.wrox.com/book-enterprise-android-programming-android-database-applications-enterprise-751/ +``` diff --git a/README_MIGRATE_LOCAL.txt b/README_MIGRATE_LOCAL.txt new file mode 100644 index 0000000..9c9b91d --- /dev/null +++ b/README_MIGRATE_LOCAL.txt @@ -0,0 +1,42 @@ +Optionally run the migrate service using Tomcat: +----- + +This file explains how to run and configure an instance of migrate on +your local machine, if you dont want to use the migrate instance at: + +http://project-migrate-beta.appspot.com/ + +----- + +Follow the instructions below only if you want to setup your own +local migrate instance (advanced and optional): + +Make sure that you have a mysql instance running with root +credentials as: + +User: root +Pass: mysql + +Copy the migrate.war binary to the Tomcat webapps directory: + +cp $MIGRATE_SDK/migrate.war $CATALINA_HOME/webapps +$CATALINA_HOME/bin/shutdown.sh +$CATALINA_HOME/bin/startup.sh + +Verify that the service is running by loading the following URL in a browser: +http://localhost:8080/ + +This location should display information about Migrate. + +Debugging Tomcat +------ + +To debug problems with Tomcat, view the contents of the file: + +$CATALINA_HOME/logs/catalina.out + +or the log file named with the current date. Aside from simply running the +'cat' command in a shell, you can also have the contents printed live to a +console in a shell using the tail command as follows: + +tail $CATALINA_HOME/logs/catalina.out diff --git a/build.xml b/build.xml index a3ec243..2deb543 100644 --- a/build.xml +++ b/build.xml @@ -135,8 +135,10 @@ - - + + + + @@ -166,7 +168,8 @@ - + + diff --git a/samples/MigrateContacts/README b/samples/MigrateContacts/README index 9229258..a4392ab 100644 --- a/samples/MigrateContacts/README +++ b/samples/MigrateContacts/README @@ -1,122 +1,91 @@ -This repository contains the code for the Example in chapter 10 of -"Enterprise Android" from Wrox Press. +MigrateContacts +-------------------------------------------------- + +This migrate sample application provides a simple contacts application that +tracks information about people you know. + +Requirements +-------------------------------------------------- This project was tested on an ARM emulator for a Galaxy Nexus device, running Android API Level 15, Ice Cream Sandwich, with a gig of memory. It should run, -as well, on most any device, API Level 14 or greater.This MigrateContacts +as well, on most any device, API Level 11 or greater. This MigrateContacts application depends on the Migrate project SDK and will work only on a device that has an installed Migrate client (migrate-client.apk). You must configure the Migrate client to communicate with a valid Migrate backend service instance that implements the WebData API - the binary apk in the sdk, connects to a local migrate instance and assumes that it runs in the Android emulator. -This README describes the following tasks: - -- Running the Migrate Proxy (migrate-client.apk). -- Configuring the MigrateContacts project. -- Creating and posting contact schema. -- Compiling and running the Migrate contacts APK. - -- Setting up an OPTIONAL local Migrate service instance. - -Get started: - +Getting started: -------------------------------------------------- -1. Download the Migrate SDK from the following location: - -https://github.com/wileyenterpriseandroid/migrate/wiki - -Click the link that says, "Download the Migrate SDK" Instructions refer to the unpacked archive directory as $MIGRATE_SDK. -The SDK contains the following items: - -- migrate-beta.war -- migrate-client-beta.apk -- SDK build files (contract generation and POST) +This README describes the following tasks you'll need to complete to get the +migrate contacts example working. they're pretty straight forward - and can +be summarized as follows: +Unpack the SDK, install the apks, create a migrate account, setup the schema, +turn on sync, run the MigrateContacts client. The project is designed to be +simple to install, yet powerful enough to address all of your application's +networking and persistence needs. --------------------------------------------------- -2. Optionally run the migrate service using Tomcat: +Make sure you have completed all the steps from the main SDK readme. +This file describes the following tasks: -NOTE: If you dont plan to use the default migrate backend instance -located at http://project-migrate-beta.appspot.com/, then you -will need to run your own migrate instance as listed below. - -The binary SDK is configured to use this endpoint by default. -If you want to use your own endpoint, you will need to configure -if when you add the migrate sync adapter in Android settings. - -NOTE: You can create an account when you configure the migrate -sync adapter, or you can create one by registering at: -http://project-migrate-beta.appspot.com/ - -If you do not plan to use the default instance, then you can -skip the rest of step 2. - ------ - -Follow the instructions below only if you want to setup your own -local migrate instance (advanced and optional): - -Make sure that you have a mysql instance running with root -credentials as: - -User: root -Pass: mysql - -Copy the migrate.war binary to the Tomcat webapps directory: - -cp $MIGRATE_SDK/migrate.war $CATALINA_HOME/webapps -$CATALINA_HOME/bin/shutdown.sh -$CATALINA_HOME/bin/startup.sh - -Note: Use .bat on windows. - -Verify that the service is running by loading the following URL in a browser: -http://localhost:8080/ - -This location should display information about Migrate. +- You need to have installed the migrate-client.apk, explained in the overall + $MIGRATE_SDK/README.md +- Configuring the MigrateContacts project. +- Creating a contract and posting schema. +- Compiling and running the Migrate contacts APK. -------------------------------------------------- -3. Configure MigrateContacts +Configure MigrateContacts -Follow the instructions in migrate.xml. -There is a copy of a typical migrate.properties file in the tools -directory (./tools) +Follow the instructions in migrate.xml. Note that for the MigrateContacts +SDK sample, you likely wont need to edit migrate.properties, its already +been copied to the MigrateContacts directory and edited so that it will work +"out of the box" with Android studio. However, the instructions below +are written so that you will know what the relevant files to copy and +edit when you create your own migrate application. -cd $CODE/MigrateContacts +cd $MIGRATE_SDK/samples/MigrateContacts - Drag and drop or copy migrate.xml into place: cd $CODE/MigrateContacts cp $MIGRATE_SDK/migrate.xml . +In fact for the SDK sample, the file is already in place. + - Drag and drop or copy migrate.properties into place and edit it for your project. -cp tools/migrate.properties . +cp $MIGRATE_SDK/tools/migrate.properties . + +For MigrateContacts, the file is already edited. Set the location the migrate sdk in this file as follows: migrate.sdk.root=$MIGRATE_SDK - The actual line might look like the following: migrate.sdk.root=../../migrate-sdk-beta +For MigrateContacts, leave it as ../.. - Copy the migrate-api.jar into place: mkdir -p libs cp $MIGRATE_SDK/lib/api/migrate-api.jar ./libs +Omit for MigrateContacts + -------------------------------------------------- -4. Compile your schema contract class: +Compile your schema contract class: -cd $CODE/MigrateContacts +cd $MIGRATE_SDK/samples/MigrateContacts ant -f build-schema.xml This ant task outputs the following class that directs the generation @@ -125,12 +94,11 @@ of the Migrate contacts API: build/classes-schema/com/enterpriseandroid/migratecontacts/Contact.class -------------------------------------------------- -5. Generate the schema contract: +Generate the schema contract: -First, make sure the Android generated source directory exists. You -might need to: - -mkdir gen +First, make sure the Android generated source directory exists. For MigrateContacts +it already does, just use, $MIGRATE_SDK/samples/app/src (its already configured as +app/src/main/java). - The following command creates a data API for your Android application using the class from the previous step: @@ -139,14 +107,12 @@ ant -f migrate.xml On success, the code will create the following source file: -$CODE/MigrateContacts/gen/com/enterpriseandroid/migratecontacts/ContactContract.java +$MIGRATE_SDK/samples/MigrateContacts/app/src/main/java/com/enterpriseandroid/migratecontacts/ContactContract.java -Warning: If you do a clean build in Eclipse, it will wipe the files -in the gen directory, which will mean you will have to manually -re-run the generate command above. +The file ContactContract.java ships with the migrate sdk. -------------------------------------------------- -6. Post the schema to the migrate service: +Post the schema to the migrate service using: ant -f migrate.xml postSchema @@ -156,23 +122,22 @@ in step 4. - Test your posted schema, by using curl to retrieve it: -curl -X GET http://localhost:8080/migrate/schema/com.enterpriseandroid.migratecontacts.Contact +curl -X GET http://project-migrate-beta.appspot.com/schema/com.enterpriseandroid.migratecontacts.Contact Should return: -{"wd_id":"com.enterpriseandroid.migratecontacts.Contact","wd_version":1,"wd_classname":"com.migrate.webdata.model.PersistentSchema","wd_updateTime":1375631349189,"wd_namespace":"__schema","wd_deleted":false,"jsonSchema":{"properties":{"wd_version":{"required":true,"type":"integer"},"wd_deleted":{"required":true,"type":"integer"},"phoneNumber":{"type":"string"},"email":{"type":"string"},"lastname":{"type":"string"},"wd_id":{"required":true,"type":"string"},"wd_namespace":{"type":"string"},"firstname":{"type":"string"},"wd_classname":{"type":"string"},"wd_updateTime":{"required":true,"type":"long"}},"type":"object"},"indexList":null,"status":0} +{"wd_id":"com.enterpriseandroid.migratecontacts.Contact","wd_version":1,"wd_classname":"com.migrate.webdata.model.PersistentSchema","wd_updateTime":1420414340970,"wd_namespace":"__schema","wd_deleted":false,"jsonSchema":{"properties":{"wd_version":{"required":true,"type":"integer"},"wd_deleted":{"required":true,"type":"integer"},"phoneNumber":{"type":"string"},"email":{"type":"string"},"lastname":{"type":"string"},"wd_id":{"required":true,"type":"string"},"wd_namespace":{"type":"string"},"firstname":{"type":"string"},"wd_classname":{"type":"string"},"wd_updateTime":{"required":true,"type":"long"}},"type":"object"},"indexList":null,"status":0} -------------------------------------------------- -7. Install and run the migrate-client.apk from the SDK: +Install and run the migrate-client.apk from the SDK: - Run the android emulator, as you've seen in earlier chapters, you can run -the emulator using the command line with the AVD manager, or using Eclipse. -Once its running, install the Migrate client APK: +the emulator from Android studio. Once its running, install the Migrate client APK: -adb install $MIGRATE_SDK/migrate-client.apk +$MIGRATE_SDK/install_client.sh The binary client in the SDK assumes that the service uses the beta instance, -http://beta.wroxenterpriseandroid.net/ . If you run your own instance, you +http://project-migrate-beta.appspot.com/ . If you run your own instance, you will need to use the android Emulator host (10.0.2.2), or localhost. On success, you will see a Toast that says, "Migrate is up!" Next you @@ -180,85 +145,25 @@ will turn on sync, and then run the MigrateContacts client application itself. -------------------------------------------------- -8. Activate Migrate sync using: - -Settings -> Accounts (webdata SyncAdapter) -> Check the sync checkbox. - --------------------------------------------------- -9. Configure MigrateContacts for use with Eclipse, there are a few ways to do -this: - -== Building with Eclipse -In order to build this project, using Eclipse, you will, first, have to -copy the necessary project files into the project root directory -The needed file are: - -tools/ide/eclipse/project => .project -tools/ide/eclipse/classpath => .classpath -tools/project.properties => project.properties - -=== From Windows Explorer: -Navigate to this directory (e.g., C:\Users\[user-name]\ea-examples\MigrateContacts\tools) - and double click the file "setup.bat" +Activate Migrate sync using: -It seems that Explorer will not change the name of a file so that -it begins with a period (.), so dragging and renaming may not work. +Settings -> Accounts (Projectmigrate SyncAdapter) -> Check the sync checkbox. -=== From a Windows CMD prompt: -Navigate to the project tools directory and use the setup.bat file -The user "blake" might, for instance, do this: -C:\Users\blake\ea-examples\MigrateContacts>cd tools -C:\Users\blake\ea-examples\MigrateContacts\tools>setup.bat - -=== From a *NIX shell prompt like Cygwin -$ cd tools -$ . setup.sh - -=== Using ant -$ ant -f tools/eclipse.xml - -Once the project has been set up, from eclipse: - -Import... >> General >> Existing Projects into Workspace - -Note that "Import >> Android >> Existing Android Code into Workspace" is -something else entirely. It may work, but if you use it you are on your -own. - -Occasionally, eclipse gets confused about the version of the Java compiler -to use on a newly imported project. If you see messages about the compiler -compliance level, try using Properties >> Java Compiler to change the -"Compiler compliance level" to anything other than its current value. -"Apply" the change, and then change it again, to 1.6 +Note that the contacts application will not save data until you complete this +step. ---------- -10. Run the MigrateContacts client: - -Select Run As Android application in Eclipse to start the Migrate Contacts project. +Run the migrate samples project. ---- +Open $MIGRATE_SDK/samples/MigrateContacts in Android Studio. -Congratulations, you have successfully installed a Migrate service -and the Migrate Contacts demonstration client. You can now sync like you -did in the other examples. +Edit a run configuration and choose and avd. If you have setup the server properly +and +---------- +Optionally, run the migrate browser. -== Building Migrate Contacts with Ant - -These instructions assume a *NIX shell prompt. If you are using - Windows CMD you will have to adapt them appropriately. - -To build this project with ant, you need two files; - -local.properties -build.xml - -Both of these files can be generated using the "android" tool -(assuming you have put the directory $ANDROID_HOME/sdk/tools onto your $PATH) - -$ android update project --path . +The Migrate SDK also comes with a generic "browser" application that allows developers +to view migrate sync'ed data from all active schema. Simple select the migrate browser -There is also a build.xml file in ./tools which should be identical -to the one produced by the command above, except that it contains -the "eclipse" target, which sets this project up for eclipse. diff --git a/tools/install.sh b/tools/install_client.sh similarity index 66% rename from tools/install.sh rename to tools/install_client.sh index 0ea0424..208b105 100755 --- a/tools/install.sh +++ b/tools/install_client.sh @@ -8,25 +8,10 @@ function scriptDir() { scriptDir=`scriptDir` -if [ -z "$CATALINA_HOME" ] ; then -echo Please set CATALINA_HOME -exit 0 -fi - -cd $CATALINA_HOME -./bin/shutdown.sh - -rm -rf ./webapps/migrate/ -rm ./webapps/migrate.war - -cp $scriptDir/migrate.war ./webapps - -./bin/startup.sh - echo Uninstalling, then installing migate client apk, please make sure that the android emulator is running... -#adb uninstall com.migrate > /dev/null 2>&1 -adb install -r ${scriptDir}/migrate-client.apk - #adb uninstall com.migrate.browser > /dev/null 2>&1 adb install -r ${scriptDir}/migrate-browser.apk + +#adb uninstall com.migrate > /dev/null 2>&1 +adb install -r ${scriptDir}/migrate-client.apk diff --git a/tools/install_service.sh b/tools/install_service.sh new file mode 100755 index 0000000..97eeeac --- /dev/null +++ b/tools/install_service.sh @@ -0,0 +1,24 @@ +#!/bin/bash + +function scriptDir() { + local dn=`dirname $0` + local abs=`cd $dn; pwd` + echo $abs +} + +scriptDir=`scriptDir` + +if [ -z "$CATALINA_HOME" ] ; then +echo Please set CATALINA_HOME +exit 0 +fi + +cd $CATALINA_HOME +./bin/shutdown.sh + +rm -rf ./webapps/migrate/ +rm ./webapps/migrate.war + +cp $scriptDir/migrate.war ./webapps + +./bin/startup.sh