|
1 | | -# pubsub-android |
2 | | - |
3 | | - |
4 | | -## Installing and consuming Pubsub.io in Android |
5 | | -**Android libraries are somewhat different from normal Java libraries in that you will often download the whole Eclipse project rather than a pre-compiled .jar file. That's why you need:** |
6 | | - |
7 | | -**Installing the library** |
8 | | - |
9 | | -1. Install a Git client for your computer |
10 | | -2. Clone this repository by writing the following in the terminal. **git clone https://github.com/pubsubio/pubsub-android** |
11 | | -3. Start Eclipse |
12 | | -4. **Right-click** the **Package Explorer** area (don't right-click a project!) and select **Import** |
13 | | -5. Select **General** and then **Existing projects into workspace** |
14 | | -6. Select the **Select root_directory** radio button and press **browse** |
15 | | -7. Navigate to, and select, the directory/folder where you cloned the pubsub-android library (*see: point 2 in this list*) |
16 | | -8. Press **Finish** |
17 | | - |
18 | | -**Consuming the library** |
19 | | - |
20 | | -1. Create your new Android project |
21 | | -2. **Right-click** your **project** in the **Package Explorer** and select **Properties** |
22 | | -3. Select **Android** and **scroll down** to the section called **Library** |
23 | | -4. Press **Add** and select the library called **pubsub_android** |
24 | | - |
25 | | -## Getting started with Pubsub.io for Android |
26 | | - |
27 | | -**First, create a ServiceConnection in your activity. This is required because pubsub-android is a Service, and also where we define what hub & sub to connect to.** |
28 | | - |
29 | | -``` java |
30 | | - private ServiceConnection serviceConnection = new ServiceConnection() { |
31 | | - @Override |
32 | | - public void onServiceConnected(ComponentName className, IBinder service) { |
33 | | - mPubsub = ((Pubsub.LocalBinder) service).getService(); |
34 | | - mPubsub.setHandler(mHandler); |
35 | | - mPubsub.connect(); |
36 | | - } |
37 | | - |
38 | | - @Override |
39 | | - public void onServiceDisconnected(ComponentName className) { |
40 | | - mPubsub = null; |
41 | | - mPubsub.setHandler(null); |
42 | | - } |
43 | | - }; |
44 | | -``` |
45 | | - |
46 | | -**Now we can register callbacks that our app will react to, these are just plain integers (They should be unique!).** |
47 | | - |
48 | | -``` java |
49 | | - // Create your own callback id, random number. Make sure they don't have the same values as any of the Pubsub constants. |
50 | | - private int MY_OWN_CALLBACK = 6322; |
51 | | - |
52 | | - // Use our new callback id to subscribe to specific events on the sub |
53 | | - JSONObject json_filter = new JSONObject(); |
54 | | - |
55 | | - // Our filter is currently looking for version numbers that are GREATER THAN 0.1! |
56 | | - try { |
57 | | - JSONObject version = new JSONObject(); |
58 | | - version.put("$gt", 0.1); |
59 | | - |
60 | | - json_filter.put("version", version); |
61 | | - } catch (JSONException e) { |
62 | | - e.printStackTrace(); |
63 | | - } |
64 | | - |
65 | | - mPubsub.subscribe(json_filter, MY_OWN_CALLBACK); |
66 | | -``` |
67 | | - |
68 | | -**Then, create the Handler. This will act as a message callback between the Service and your Activity.** |
69 | | - |
70 | | -``` java |
71 | | - private Handler mHandler = new Handler() { |
72 | | - @Override |
73 | | - public void handleMessage(Message msg) { |
74 | | - switch (msg.what) { |
75 | | - case Pubsub.RAW_TEXT: |
76 | | - byte[] readBuf = (byte[]) msg.obj; |
77 | | - String readMessage = new String(readBuf, 0, msg.arg1); |
78 | | - // TODO Do something with the message here... |
79 | | - break; |
80 | | - case Pubsub.TERMINATED: |
81 | | - // TODO React when the connection fails... |
82 | | - break; |
83 | | - case Pubsub.ERROR: |
84 | | - // TODO Read error messages here... |
85 | | - break; |
86 | | - case MY_OWN_CALLBACK: |
87 | | - try { |
88 | | - double version = doc.getDouble("version"); |
89 | | - Log.i(TAG, "Version message from Pubsub.io: " + version); |
90 | | - } catch (JSONException e) { |
91 | | - e.printStackTrace(); |
92 | | - } |
93 | | - break; |
94 | | - } |
95 | | - } |
96 | | - }; |
97 | | -``` |
98 | | - |
99 | | -**To start the service, you'll use an intent in the "onResume()" activity method.** |
100 | | - |
101 | | -``` java |
102 | | - @Override |
103 | | - protected void onResume() { |
104 | | - // Connect to the service |
105 | | - Intent intent = new Intent(this, Pubsub.class); |
106 | | - bindService(intent, serviceConnection, Context.BIND_AUTO_CREATE); |
107 | | - |
108 | | - super.onResume(); |
109 | | - } |
110 | | -``` |
111 | | - |
112 | | -**And make sure to disconnect from the service in "onPause()" too! Note, this will NOT shut down your connection.** |
113 | | - |
114 | | -``` java |
115 | | - @Override |
116 | | - protected void onPause() { |
117 | | - // Disconnect from the service |
118 | | - unbindService(serviceConnection); |
119 | | - |
120 | | - super.onPause(); |
121 | | - } |
122 | | -``` |
123 | | - |
124 | | -## Also, you must make sure NOT to forget your AndroidManifest, it's imperative that you make the following changes! |
125 | | - |
126 | | -* Add a <service> tag that points to the Pubsub service, otherwise you can't connect to it. |
127 | | -* Add a <uses-permission> tag with the INTERNET rule. |
128 | | -* Add a <user-permission> tag with the ACCESS_NETWORK_STATE rule. |
| 1 | +# pubsub-android |
| 2 | + |
| 3 | + |
| 4 | +## Installing and consuming Pubsub.io in Android |
| 5 | +**Android libraries are somewhat different from normal Java libraries in that you will often download the whole Eclipse project rather than a pre-compiled .jar file. That's why you need:** |
| 6 | + |
| 7 | +**Installing the library** |
| 8 | + |
| 9 | +1. Install a Git client for your computer |
| 10 | +2. Clone this repository by writing the following in the terminal. **git clone https://github.com/pubsubio/pubsub-android** |
| 11 | +3. Start Eclipse |
| 12 | +4. **Right-click** the **Package Explorer** area (don't right-click a project!) and select **Import** |
| 13 | +5. Select **General** and then **Existing projects into workspace** |
| 14 | +6. Select the **Select root_directory** radio button and press **browse** |
| 15 | +7. Navigate to, and select, the directory/folder where you cloned the pubsub-android library (*see: point 2 in this list*) |
| 16 | +8. Press **Finish** |
| 17 | + |
| 18 | +**Consuming the library** |
| 19 | + |
| 20 | +1. Create your new Android project |
| 21 | +2. **Right-click** your **project** in the **Package Explorer** and select **Properties** |
| 22 | +3. Select **Android** and **scroll down** to the section called **Library** |
| 23 | +4. Press **Add** and select the library called **pubsub_android** |
| 24 | + |
| 25 | +## Getting started with Pubsub.io for Android |
| 26 | + |
| 27 | +** Create the Pubsub object, this will be your main interaction channel with the Pubsub service.** |
| 28 | + |
| 29 | +``` java |
| 30 | + Pubsub mPubsub = new Pubsub( this, mHandler ); |
| 31 | +``` |
| 32 | + |
| 33 | +** All events in Pubsub.io are recievied through a Handler interface, register a new Handler and call it "mHandler". ** |
| 34 | + |
| 35 | +``` java |
| 36 | + private Handler mHandler = new Handler() { |
| 37 | + @Override |
| 38 | + public void handleMessage(Message msg) { |
| 39 | + switch (msg.what) { |
| 40 | + case Pubsub.CONNECTED_TO_HOST: |
| 41 | + // React when a connection attempt was successfull, for example: |
| 42 | + // Subscribing or publishing |
| 43 | + break; |
| 44 | + case Pubsub.CONNECTION_FAILED: |
| 45 | + // React when a connection attempt failed, for example: |
| 46 | + // Issue another connection attempt in a few seconds. |
| 47 | + break; |
| 48 | + case Pubsub.CONNECTION_LOST: |
| 49 | + // React when a connection was lost, for example: |
| 50 | + // Inform the user and abort any pubsub-dependant tasks. |
| 51 | + break; |
| 52 | + } |
| 53 | + } |
| 54 | + }; |
| 55 | +``` |
| 56 | + |
| 57 | +** Subscribing to a topic. ** |
| 58 | +``` java |
| 59 | + private static final int MY_FILTER = 1; |
| 60 | + |
| 61 | + JSONObject filter = new JSONObject(); |
| 62 | + try { |
| 63 | + filter.put("name", "value"); |
| 64 | + mPubsub.subscribe(filter, MY_FILTER); |
| 65 | + } catch (JSONException e) { |
| 66 | + e.printStackTrace(); |
| 67 | + } |
| 68 | +``` |
| 69 | + |
| 70 | +** Publishing to a topic. ** |
| 71 | +``` java |
| 72 | + JSONObject doc = new JSONObject(); |
| 73 | + try { |
| 74 | + filter.put("name", "value"); |
| 75 | + mPubsub.publish(doc); |
| 76 | + } catch (JSONException e) { |
| 77 | + e.printStackTrace(); |
| 78 | + } |
| 79 | +``` |
| 80 | + |
| 81 | +## Also, make sure to add the following <uses-permission> tags in your manifest file. |
| 82 | + |
| 83 | +* Add a <uses-permission> tag with the INTERNET rule. |
| 84 | +* Add a <user-permission> tag with the ACCESS_NETWORK_STATE rule. |
0 commit comments