Skip to content

Commit

Permalink
Browse files Browse the repository at this point in the history
Added Teleport library
  • Loading branch information
josejuansanchez committed Mar 21, 2015
1 parent 24fc395 commit b121725
Show file tree
Hide file tree
Showing 61 changed files with 2,669 additions and 0 deletions.
33 changes: 33 additions & 0 deletions Teleport/.gitignore
@@ -0,0 +1,33 @@
# built application files
#*.apk
*.ap_

# files for the dex VM
*.dex

# Java class files
*.class

# generated files
bin/
gen/
out/


# Ignored by AndroidStudio
*.iws
*.iml

# Folders related to builds and Gradle
.gradle/
*/build/
build/

# Local settings (regenerated by Android Studio)
.idea/
local.properties
demo/apk/

#Personal Files
signing.properties
lic.properties
170 changes: 170 additions & 0 deletions Teleport/README.md
@@ -0,0 +1,170 @@
# Teleport - Data Sync & Messaging Library for Android Wear

![Screen](/doc/images/teleport_256.png)

Teleport is a library to easily setup and manage Data Syncronization and Messaging on Android Wearables.

*The library is thought for Android Studio.*



##Quick Overview

You can see Teleport as an Android Wear "plugin" you can add to your Activities and Services.

Teleport provides you **commodity classes** to easily establish a communication between a mobile handheld device and an Android Wear device.

* `TeleportClient` provides you "endpoints" you can put inside your Activities, both in Mobile and Wear.
* `TeleportService` is a full-fledged, already set-up 'WearableListenerService'.

Both these classes incapsulates all the `GoogleApiClient` setup required to establish a connection between Mobile and Wear.

`TeleportClient` and `TeleportService` also provide you two `AsyncTask` you can extend to easily perform operations with the synced DataItems and received Messages:

* `OnSyncDataItemTask` provides you a complete `DataMap` of synced data
* `OnGetMessageTask` provides you access to a received Message `path` in form of `String`.

You just need to *extend* these tasks inside your Activity/Service and you're good to go!

To Sync Data and send Messages, you can use commodity methods like

* `sync<ItemType>(String key, <ItemType> item)` to Sync Data across devices
* `sendMessage(String path, byte[] payload)` to send a Message to another device.

##Summary

* [Library Set Up:](/doc/SETUP.md) How to import Teleport library in your project.
* [TeleportClient in Activity:](/doc/TELEPORTCLIENT.md) How to setup a TeleportClient.
* [TeleportService:](/doc/TELEPORTSERVICE.md) How to setup a TeleportService.
* [Sync Data:](/doc/SYNCDATA.md) How to Sync Data
* [Send and Receive Messages:](/doc/MESSAGE.md) How to Send and Receive Messages
* [Advanced Usage:](/doc/ADVANCEDUSAGE.md) AsyncTask Factory and Callbacks

##Can I have an example of how easy is Teleport to use?

There you go :-)

Here's a *Mobile and a Wear Activity* already configured to Sync Data.

* The MobileActivity synchronizes a string "Hello, World!".
* The WearActivity shows a Toast with the synchronized string.

###MobileActivity.java
```java

public class MobileActivity extends Activity {

TeleportClient mTeleportClient;

@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_mobile);

mTeleportClient = new TeleportClient(this);
}

@Override
protected void onStart() {
super.onStart();
mTeleportClient.connect();
}

@Override
protected void onStop() {
super.onStop();
mTeleportClient.disconnect();
}


public void syncDataItem(View v) {
//Let's sync a String!
mTeleportClient.syncString("hello", "Hello, World!");
}

}
```

###WearActivity.java

```java

public class WearActivity extends Activity {

TeleportClient mTeleportClient;

@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_wear);

mTeleportClient = new TeleportClient(this);

mTeleportClient.setOnSyncDataItemTask(new ShowToastHelloWorldTask());

}

@Override
protected void onStart() {
super.onStart();
mTeleportClient.connect();
}

@Override
protected void onStop() {
super.onStop();
mTeleportClient.disconnect();

}

public class ShowToastHelloWorldTask extends TeleportClient.OnSyncDataItemTask {

@Override
protected void onPostExecute(DataMap dataMap) {

String hello = dataMap.getString("hello");

Toast.makeText(getApplicationContext(),hello,Toast.LENGTH_SHORT).show();
}
}

}
```

Jump to [Library Set Up](/doc/SETUP.md) !!!

##Follow me on
Author: Mario Viviani
<a href="https://plus.google.com/+MarioViviani/posts">
<img alt="Follow me on Google+"
src="https://github.com/Mariuxtheone/Teleport/raw/master/doc/images/googleplus64.png" />
</a>
<a href="https://it.linkedin.com/pub/mario-viviani/45/b96/a59/">
<img alt="Follow me on LinkedIn"
src="https://github.com/Mariuxtheone/Teleport/raw/master/doc/images/linkedin64.png" />
</a>

##Thanks to:
Damien Cavaillès - https://github.com/thedamfr


##License

Teleport is released under the **Apache License 2.0**

Copyright 2014-2015 Mario Viviani

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

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.



20 changes: 20 additions & 0 deletions Teleport/build.gradle
@@ -0,0 +1,20 @@
// Top-level build file where you can add configuration options common to all sub-projects/modules.

buildscript {
repositories {
jcenter()
}
dependencies {
classpath 'com.android.tools.build:gradle:1.0.0-rc4'


// NOTE: Do not place your application dependencies here; they belong
// in the individual module build.gradle files
}
}

allprojects {
repositories {
jcenter()
}
}
58 changes: 58 additions & 0 deletions Teleport/doc/ADVANCEDUSAGE.md
@@ -0,0 +1,58 @@
#ADVANCED USAGE

## Using AsyncTask Factory

AsyncTask are single shot.

Most of the time it will be okay with the basic use. But if you are using Message or DataSyncing with at a **certain rate or running on a low end phone**, you might be running into a corner case.

Sometime, the event come and the AsyncTask is still currently running and it ends in a Exception.

There you should not use classical setters but use the `Builder` setter.

Each AsyncTask is provided with an appropriate builder. The main purpose is that every time a new event is triggered, a new AsyncTask will be instantiated automatically.

```java
mTeleportClient.setOnGetMessageTaskBuilder (
new OnGetMessageTask.Builder () {
@Override
public void build() {
return new ShowToastAsyncTask();
}
}
);


mTeleportClient.setOnSyncDataItemTaskBuilder (
new OnSyncDataItemTask.Builder () {
@Override
public void build() {
return new ShowToastAsyncTask();
}
}
);
```

##Using Callbacks

If you want to manage yourself the response of Data sync or Message received, you can use Callbacks. There are `OnGetMessageCallback` and `OnSyncDataItemCallback` you can set in your `TeleportClient` and `TeleportService`.

Remember: in this case you need to **manage the threading yourself!**. Callbacks are not asynchronous like AsyncTask and AsyncTask Factory.

``` java
//OnGetMessageCallback
mTeleportClient.setOnGetMessageCallback(new TeleportClient.OnGetMessageCallback() {
@Override
public void onCallback(String dataMap) {
//your callback here...
}
});

//OnGetMessageCallback
mTeleportClient.setOnSyncDataItemCallback(new TeleportClient.OnSyncDataItemCallback() {
@Override
public void onDataSync(DataMap dataMap) {
//your callback here...
}
});
```
70 changes: 70 additions & 0 deletions Teleport/doc/MESSAGE.md
@@ -0,0 +1,70 @@
#Send and Receive Messages

##Send Messages

To send a Message to another device, you can use the method `sendMessage(String path, byte[] payload)`

provided by `TeleportClient` and `TeleportService`.


*Example:* if you want to send a "startActivity" message, you can do it this way

``` java

mTeleportClient.sendMessage("startActivity", null);
```

You can use the `payload` argument to attach a payload (100KB max) to your message (at the moment the Payload is not used by Teleport)

##Listen and react to Messages

`TeleportClient` and `TeleportService` provide you a custom async tasks `OnGetMessageTask` that react to received Messages

**You need to *extend* these abstract Task inside your Activity, implementing the `OnPostExecute()` method.**


###OnSyncDataItemTask

`OnGetMessageTask` allows you to easily get the path of a received Message.

**Example:**, let's say we want to start an Activity when the String with the `path` "startActivity" is synced:

We just need to extend `OnSyncDataItemTask` like this:

``` java

private static final String STARTACTIVITY = "startActivity";

public class StartActivityTask extends TeleportClient.OnGetMessageTask {

@Override
protected void onPostExecute(String path) {

if (path.equals(STARTACTIVITY)){
Intent startIntent = new Intent(getBaseContext(), WearActivity.class);
startIntent.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK);
startActivity(startIntent);
}

}
}
```

Easy, right? ;-)

*NOTE: Remember that a AsyncTask will be executed only once, so you might need to **reset the task** if you want to perform it again.*

###Set the OnGetMessageTask

After we`ve implemented our Task, we need to **set it in our TeleportClient/Service**.

`TeleportClient/Service` provide you with a method `setOnGetMessageTask(OnGetMessageTask onGetMessageTask)` to set up the task.

You can add it where you want, for example to your Activity `onCreate()` like this (following the above example):

``` java

mTeleportClient.setOnGetMessageTask(new StartActivityTask());
```

If you need more advanced usage, you can use AsyncTask Factory or Callbacks. Learn more here: [Advanced Usage](/doc/ADVANCEDUSAGE.md)

0 comments on commit b121725

Please sign in to comment.