# 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.

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `static class`
  `GeofenceManager.Listener`
  The Listener class that is registered to receive Geofence events.

- ## Method Summary

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

  ### Methods inherited from class Object

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

- ## 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>`