Class GeofenceManager

java.lang.Object
com.codename1.location.GeofenceManager
All Implemented Interfaces:
Iterable<Geofence>
public final class GeofenceManager extends Object implements Iterable<Geofence>

A utility class to simplify Geofencing in Codename One. Using this class to manage an app's Geofences works around the 20-region limit on iOS and 100-region limit on Android, so that your app can monitor an unlimited number of Geofences simulataneously.

How it Works

GeofenceManager maintains a "bubble" region around the current device location. You may register as many regions as you like to be monitored with GeofenceManager, but it will only register the regions that intersect the current "bubble" region. When you exit the bubble region, the GeofenceManager will clear all of the previously registered regions, create a new bubble, and then register only those regions that intersect this new bubble.

GeofenceManager uses Storage to maintain its own active list of regions.

Limitations

GeofenceManager will only register 19 regions at a time, so if more than 19 regions intersect the current "bubble" region, some of them won't make the cut. You can set the radius of the "bubble" region using #setBubbleRadius(int) to increase or decrease the "bubble" region area, so that no regions are left behind.

Although you can set any positive radius value you like, a typical Android or iOS device has a minimum effective radius of about 100m.

Note: If your app uses GeofenceManager, you shouldn't also add your own Geofences manually using com.codename1.location.Geofence) as your manual regions may conflict.

Usage

GeofenceManager mgr = GeofenceManager.getInstance(); mgr.setListenerClass(MyGeofenceListener.class); mgr.add(geofence1, geofence2, geofence3); mgr.update(10000);

And the MyGeofenceListener class should be an instance of Geofence.

Reloading Geofences Upon Exiting Bubble

While there is no absolute limit on the number of regions that you can register in GeofenceManager simulataneously, since it is actually storing the list of Geofences in Storage, there is a practical limit. E.g. It probably wouldn't perform well if you stored several thousand at a time. If you want to monitor large quantifies of regions (thousands, or millions), you can simply respond to the GeofenceListener#onExit(java.lang.String) event for the "bubble" region, and "reload" the GeofenceManager with new regions related to the device's current location. You might load the new locations from a web-service, for example. Use the #isBubble(java.lang.String) method to check if the id parameter is for the bubble region, and act accordintly.

  • Method Details

    • getInstance

      public static GeofenceManager getInstance()
      Obtains reference to the singleton GeofenceManager

    • getBubbleRadius

      public int getBubbleRadius()

      Gets the radius of the "bubble" region, in metres.

      Returns

      the bubbleRadius

    • setBubbleRadius

      public void setBubbleRadius(int bubbleRadius)

      Sets the radius of the "bubble" regin, in metres. Default value is 1000.

      Parameters
      • bubbleRadius: the bubbleRadius to set

    • getBubbleExpiration

      public long getBubbleExpiration()

      Gets the expiration duration (in milliseconds) of the bubble region.

      Returns

      the bubbleExpiration

    • setBubbleExpiration

      public void setBubbleExpiration(long bubbleExpiration)

      Sets the expiration duration (in milliseconds) of the bubble region. Default is -1 meaning "No expiration".

      Parameters
      • bubbleExpiration: the bubbleExpiration to set

    • isBubble

      public boolean isBubble(String id)

      Checks if the given ID is for the "bubble" region.

      Parameters
      • id: An ID to check.
      Returns

      True if id is for the "bubble" region.

    • getListenerClass

      public Class<? extends GeofenceListener> getListenerClass()
      Gets the currently registered Listener class.

    • setListenerClass

      public void setListenerClass(Class<? extends GeofenceListener> c)

      Sets the GeofenceListener class that should receive Geofence events.

      Parameters
      • c

    • add

      public void add(Geofence... geofence)

      Adds a set of regions to be monitored by GeofenceManager.

      Parameters
      • geofence

    • add

      public void add(Collection<Geofence> geofences)

      Adds a set of regions to be monitored by GeofenceManager.

      Parameters
      • geofences

    • isCurrentlyActive

      public boolean isCurrentlyActive(String id)

    • remove

      public void remove(String... ids)

      Removes a set of regions (by ID) so that they will no longer be monitored.

      Parameters
      • ids

    • remove

      public void remove(Collection<String> ids)

    • clear

      public void clear()
      Removes all current regions.

    • size

      public int size()
      Checks the number of regions that are currently being monitored.

    • asMap

      public Map<String,Geofence> asMap()
      Returns the Geofences as a Map.

    • asList

      public List<Geofence> asList()
      Returns the Geofences as a list.

    • asSortedList

      public List<Geofence> asSortedList()
      Returns all Geofences sorted by distance from the current location.

    • refresh

      public void refresh()
      Reloads geofences from storage.

    • update

      public void update(int timeout)

      Updates the active Geofences that are being monitored on the OS. This should be called after making changes to the set of Geofences you wish to monitor.

      Parameters
      • timeout: Timeout (in milliseconds)

    • update

      public void update(int timeout, boolean forceRefresh)

      Updates the active Geofences that are being monitored on the OS. This should be called after making changes to the set of Geofences you wish to monitor.

      Parameters

      • timeout: Timeout (in milliseconds)

      • forceRefresh: If true, then this will force removal and re-addition of all geofences.

    • iterator

      public Iterator<Geofence> iterator()
      Iterates over all geofences that are being monitored.
      Specified by:
      iterator in interface Iterable<Geofence>