public final class GeofenceManager

Object
GeofenceManager

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.

Nested types

class GeofenceManager.Listener The Listener class that is registered to receive Geofence events.

Methods

`public static` `GeofenceManager getInstance()`	Obtains reference to the singleton GeofenceManager
`public int getBubbleRadius()`	Gets the radius of the “bubble” region, in metres.
`public void setBubbleRadius(int bubbleRadius)`	Sets the radius of the “bubble” regin, in metres.
`public long getBubbleExpiration()`	Gets the expiration duration (in milliseconds) of the bubble region.
`public void setBubbleExpiration(long bubbleExpiration)`	Sets the expiration duration (in milliseconds) of the bubble region.
`public boolean isBubble(String id)`	Checks if the given ID is for the “bubble” region.
`public synchronized` `Class<? extends GeofenceListener> getListenerClass()`	Gets the currently registered Listener class.
`public synchronized void setListenerClass(Class<? extends GeofenceListener> c)`	Sets the GeofenceListener class that should receive Geofence events.
`public synchronized void add(Geofence... geofence)`	Adds a set of regions to be monitored by GeofenceManager.
`public synchronized void add(Collection<Geofence> geofences)`	Adds a set of regions to be monitored by GeofenceManager.
`public synchronized boolean isCurrentlyActive(String id)`
`public synchronized void remove(String... ids)`	Removes a set of regions (by ID) so that they will no longer be monitored.
`public synchronized void remove(Collection<String> ids)`
`public synchronized void clear()`	Removes all current regions.
`public synchronized int size()`	Checks the number of regions that are currently being monitored.
`public synchronized` `Map<String, Geofence> asMap()`	Returns the Geofences as a Map.
`public synchronized` `List<Geofence> asList()`	Returns the Geofences as a list.
`public synchronized` `List<Geofence> asSortedList()`	Returns all Geofences sorted by distance from the current location.
`public synchronized void refresh()`	Reloads geofences from storage.
`public synchronized void update(int timeout)`	Updates the active Geofences that are being monitored on the OS.
`public synchronized void update(int timeout, boolean forceRefresh)`	Updates the active Geofences that are being monitored on the OS.
`public` `Iterator<Geofence> iterator()`	Iterates over all geofences that are being monitored.

Inherited methods

From Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait, clone

From Iterable

forEach

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 int: 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 long: the bubbleExpiration to set

isBubble

public boolean isBubble(String id)

Checks if the given ID is for the “bubble” region.

Parameters

id String: An ID to check.

Returns

True if id is for the “bubble” region.

getListenerClass

public synchronized Class<? extends GeofenceListener> getListenerClass()

Gets the currently registered Listener class.

setListenerClass

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

Sets the GeofenceListener class that should receive Geofence events.

add

public synchronized void add(Geofence... geofence)

Adds a set of regions to be monitored by GeofenceManager.

add

public synchronized void add(Collection<Geofence> geofences)

Adds a set of regions to be monitored by GeofenceManager.

isCurrentlyActive

public synchronized boolean isCurrentlyActive(String id)

remove

public synchronized void remove(String... ids)

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

remove

public synchronized void remove(Collection<String> ids)

clear

public synchronized void clear()

Removes all current regions.

size

public synchronized int size()

Checks the number of regions that are currently being monitored.

asMap

public synchronized Map<String, Geofence> asMap()

Returns the Geofences as a Map.

asList

public synchronized List<Geofence> asList()

Returns the Geofences as a list.

asSortedList

public synchronized List<Geofence> asSortedList()

Returns all Geofences sorted by distance from the current location.

refresh

public synchronized void refresh()

Reloads geofences from storage.

update

public synchronized 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 int: Timeout (in milliseconds)

update

public synchronized 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 int: Timeout (in milliseconds)
forceRefresh boolean: 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.

Returns

An Iterator instance.