Welcome to Deacon!

Deacon is a push notifications library intended for use on Android devices, but which is also usable in pure-Java form. Deacon is free and open-source software, and is produced by the members of The Deacon Project.

Deacon can be used in two "modes", pure-Java and Android. Each is detailed below.

Using Deacon in Android Apps

You can integrate Deacon into your Android app or service by creating a new Deacon object, configuring it, then subscribing the object's context to receive callbacks when push notifications are received.

• The Activity or Service that receives callbacks from your Deacon object must implement the DeaconServiceObserver interface.
• Deacon's Android integration automatically takes care of caling Deacon.stop() and Deacon.start() on any changes in network connectivity.
• Deacon requires the following permissions be set in your AndroidManifest.xml file:
  • uses-permission android:name="android.permission.INTERNET"
  • uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"

1. Ensure the Deacon source or JAR file is on your project's build path.
2. Instantiate a Deacon object from within your Android Activity or Service:
   Deacon myDeacon = new Deacon("data.myserver.com", 4670, this);
3. Configure the Deacon object:
   myDeacon.joinChannel("channelname", 0);
4. Register your context with Deacon to receive callbacks:
   myDeacon.register(this);
5. Start the Deacon service:
   myDeacon.start();

Using Deacon in Java programs

Using Deacon in pure-Java is just like using it in Android, except that instead of instantiating Deacon, you instantiate its parent class, DeaconService. The configuration is the same, but the instantiating context is not required when you make a new DeaconService, and you must start and stop the service.

Other configuration and features...

• You can subscribe to multiple channels; the DeaconResponse objects you get back on incoming push notifications contain both channel and payload members. Thus, your onPush method will need to separate out the pushes based on channel the same way you might detect and separate button pushes in an onClick(View view) method in Android.
• You can specify a backtrack when you subscribe to a channel; this is a one-time retrieval of a set number of messages that were pushed prior to your subscription.
• You can specify a catchUpTimeOut for each Deacon or DeaconService object you instantiate. If Deacon is stopped while running (for example due to a momentary interruption in network connectivity on Android), it will automatically retrieve missed push notifications from the Meteor server, as long as the catchUpTimeOut has not expired. For example, setting a catchUpTimeOut interval of 60 will attempt to catch up all subscribed channels as long as the service is restarted within 60 seconds of stopping.