ContainerOpener

public class ContainerOpener

Helper class for opening containers.

This is a wrapper around openContainer(String, Container.Callback) method for users who don't need the fine level of control that it provides.

There are three states a container can be in:

  • Default: this is the container that ships with the app (either a binary container or a json file that's converted to a container).
  • Stale: a container that's been downloaded from the server, but not recently.
  • Fresh: a container that's been downloaded from the server recently.

Here's an example where the caller wants to wait up to 100 milliseconds to get the non-default container (retrieving the default container if it times out). 

   ContainerFuture future =
       ContainerOpener.openContainer(tagManager, containerId, OpenType.PREFER_NON_DEFAULT, 100);
   Container container = future.get();

If the caller wants to be asynchronously notified when the container is available but wants to manually specify the timeout to 0.5 seconds, then the caller should subclass ContainerOpener.Notifier. Sample usage: 

   ContainerOpener.openContainer(tagManager, containerId, OpenType.PREFER_NON_DEFAULT,
       500, new ContainerOpener.Notifier() {
         @Override
         void containerAvailable(Container container) {
           // Code to handle the container available notification and save the container.
         }
       });

Nested Class Summary

interface ContainerOpener.ContainerFuture An object that will return a Container. 
interface ContainerOpener.Notifier Object that will receive a notification when a container is available for use. 
enum ContainerOpener.OpenType Preferences for opening a container. 

Constant Summary

long DEFAULT_TIMEOUT_IN_MILLIS The default timeout in milliseconds for requesting the container.

Public Method Summary

static ContainerOpener.ContainerFuture
openContainer(TagManager tagManager, String containerId, ContainerOpener.OpenType openType, Long timeoutInMillis)
static void
openContainer(TagManager tagManager, String containerId, ContainerOpener.OpenType openType, Long timeoutInMillis, ContainerOpener.Notifier notifier)

Constants

public static final long DEFAULT_TIMEOUT_IN_MILLIS

The default timeout in milliseconds for requesting the container.

Constant Value: 2000

Public Methods

public static ContainerOpener.ContainerFuture openContainer (TagManager tagManager, String containerId, ContainerOpener.OpenType openType, Long timeoutInMillis)

Waits up to timeoutInMillis time for a container to be loaded (non default or fresh depending on the specified openType).

If the open type is PREFER_NON_DEFAULT, a non-default (saved or retrieved from network) container is loaded and the ContainerFuture is unblocked as soon as one of the following happens:

  • a saved container is loaded.
  • if there is no saved container, a network container is loaded or a network error occurs.
  • the timer expires.

If a network error occurs or the timer expires, get() may return a default container.

If the open type is PREFER_FRESH, a fresh (saved or retrieved from network) container is loaded and the ContainerFuture is unblocked as soon as one of the following happens:

  • a saved fresh container is loaded.
  • if there is no saved container or saved container is stale, a network container is loaded or a network error occurs.
  • the timer expires.

If a network error occurs or the timer expires, get() may return a default container or a saved stale container.

If you call openContainer a second time with a given containerId, a ContainerFuture will be returned whose get() will return the same container as the first call did.

Parameters
tagManager the TagManager on which to call openContainer
containerId the ID of the container to load
openType the choice of how to open the container
timeoutInMillis the maximum number of milliseconds to wait to load the container (from saved store). If null, DEFAULT_TIMEOUT_IN_MILLIS will be used.
Returns
  • an object whose get method will return the container, but can block up to timeoutInMillis until the container is available.

public static void openContainer (TagManager tagManager, String containerId, ContainerOpener.OpenType openType, Long timeoutInMillis, ContainerOpener.Notifier notifier)

Waits up to timeoutInMillis time for a container to be loaded (non default or fresh depending on the specified openType).

If the open type is PREFER_NON_DEFAULT, a non-default (saved or retrieved from network) container is loaded and passed into the notifier. The notifier is called as soon as one of the following happens:

  • a saved container is loaded.
  • if there is no saved container, a network container is loaded or a network error occurs.
  • the timer expires.

If a network error occurs or the timer expires, the container passed into containerAvailable(Container) is a default container.

If the open type is PREFER_FRESH, a fresh (saved or retrieved from network) container is loaded and passed into the notifier. The notifier is called as soon as one of the following happens:

  • a saved fresh container is loaded.
  • if there is no saved container or saved container is stale, a network container is loaded or a network error occurs.
  • the timer expires.

If a network error occurs or the timer expires, the container passed into containerAvailable(Container) may be a default or a stale saved container.

If you call openContainer(TagManager, String, ContainerOpener.OpenType, Long) a second time with a given containerId, the same container returned from the previous call will be passed into the notifier as soon as it's available.

Parameters
tagManager the TagManager on which to call openContainer
containerId the ID of the container to load
openType the choice of how to open the container
timeoutInMillis the maximum number of milliseconds to wait to load the container (from saved store and/or network). If null, DEFAULT_TIMEOUT_IN_MILLIS will be used.
notifier a notifier which will be called when the container is available. It will be called with the saved or network container, if available and loaded before the timeout. Otherwise, it will be called with the default container. The notifier may be called from a different thread.