com.smartgwt.client.util

## Class Offline

- java.lang.Object
- - com.smartgwt.client.util.Offline

-     public class Offline
      extends java.lang.Object

  The Offline class provides features for storing and retrieving values in persistent browser storage. Because this storage is both persistent (ie, it remains available after the browser is closed and re-opened) and local to the browser, it allows applications to operate when the client is not connected to a network, albeit with some obvious limitations.

  As well as providing straightforward APIs for storing, retrieving and removing values, Offline support is integrated into the normal request/response cycle. You can configure the framework so that server responses are automatically cached in Offline storage. Then, at some future point when the client is offline, responses for known requests are returned from the Offline cache.

  Smart GWT makes use of various underlying storage techniques, depending on what the browser supports, but the API to a Smart GWT program is the same regardless of the underlying storage - simple key/value pairs. Currently, we provide Offline support for all HTML5-compliant browsers, plus earlier versions of Internet Explorer (6 and 7). The amount of storage available is dictated by the browser, and varies from approximately 500KB to approximately 5MB.

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `Offline()`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `static java.lang.Object` | `get(java.lang.String key)` Returns the value mapped to the passed-in key from browser-local storage, or null if no such key exists.
    `static void` | `goOffline()` Explicitly sets this session into offline mode.
    `static void` | `goOnline()` Explicitly sets this session into online mode.
    `static java.lang.Boolean` | `isOffline()` Returns true if the current browser session is offline (ie, not connected to a network).
    `static void` | `put(java.lang.String key, java.lang.Object value)` Stores the passed-in value in browser-local storage, mapped to the passed-in key.
    `static void` | `put(java.lang.String key, java.lang.Object value, boolean recycleEntries)` Stores the passed-in value in browser-local storage, mapped to the passed-in key.
    `static void` | `remove(java.lang.String key)` Removes the key/value pair mapped by the passed-in key from browser-local storage
    `static void` | `useNativeOfflineDetection()` Tells the Offline system to query the browser for the current online/offline state.

    - ### Methods inherited from class java.lang.Object

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

- - ### Constructor Detail

    - #### Offline

          public Offline()

  - ### Method Detail

    - #### goOffline

          public static void goOffline()

      Explicitly sets this session into offline mode. This setting will override whatever state the browser reports. This allows users to manually set an application into offline or online state.
      See Also:
        `goOnline()`, `useNativeOfflineDetection()`

    - #### goOnline

          public static void goOnline()

      Explicitly sets this session into online mode. This setting will override whatever state the browser reports. This allows users to manually set an application into offline or online state.
      See Also:
        `goOffline()`, `useNativeOfflineDetection()`

    - #### isOffline

          public static java.lang.Boolean isOffline()

      Returns true if the current browser session is offline (ie, not connected to a network). If an online/offline state has been set explicitly (see `Offline.goOffline` and `Offline.goOnline`), the explicitly-set state will be returned. Otherwise, the offline state as reported by the browser will be returned. See `useNativeOfflineDetection` for important notes on browser detection of offline state.
      Returns:
        true if the current browser session is offline
      See Also:
        `goOffline()`, `goOnline()`, `useNativeOfflineDetection()`

    - #### remove

          public static void remove(java.lang.String key)

      Removes the key/value pair mapped by the passed-in key from browser-local storage
      Parameters:
        `key` - The key to remove
      See Also:
        `put(java.lang.String, java.lang.Object)`, `get(java.lang.String)`

    - #### useNativeOfflineDetection

          public static void useNativeOfflineDetection()

      Tells the Offline system to query the browser for the current online/offline state. Calling this method switches off the explicit offline mode setting switched on by calling `Offline.goOnline` or `Offline.goOffline`.

      It is important to note that browsers vary quite considerably in their ability to detect that they are offline. Many older browsers simply can't do it; HTML5 browsers expose the `navigator.onLine` property, but each browser's implementation is different. Some browsers have a manual "Work Offline" mode which allows the user to make the decision, and Smart GWT provides an equivalent mechanism with the `goOffline` and `goOnline` methods. Generally speaking, these methods are more reliable than allowing the browser to decide whether your application is offline.

      See Also:
        `goOnline()`, `goOffline()`

    - #### get

          public static java.lang.Object get(java.lang.String key)

      Returns the value mapped to the passed-in key from browser-local storage, or null if no such key exists.
      Parameters:
        `key` - The key to retrieve a value for
      Returns:
        The value mapped to the passed in key, or null if no such key exists
      See Also:
        `put(java.lang.String, java.lang.Object)`

    - #### put

          public static void put(java.lang.String key,
                 java.lang.Object value)

      Stores the passed-in value in browser-local storage, mapped to the passed-in key. If there is no room left to store the value, we discard values from the offline store, oldest first, until there is room to store the value. If you don't want this behavior, explicitly pass false in the `recycleEntries` parameter.

      Note that limitations in the underlying storage engines mean that only primitive values - Strings, numbers and booleans - can be stored. If you wish to store an Array or Object, you will have to serialize it to JSON first, and then `eval` it after retrieval to turn it back into an object.

      Note: This method throws an exception if it could not store the value (either because storage is full and recycleEntries was false, or because the value to store is simply too large)

      Parameters:
        `key` - The key to use when storing the value
        `value` - The value to store

    - #### put

          public static void put(java.lang.String key,
                 java.lang.Object value,
                 boolean recycleEntries)

      Stores the passed-in value in browser-local storage, mapped to the passed-in key. If there is no room left to store the value, we discard values from the offline store, oldest first, until there is room to store the value. If you don't want this behavior, explicitly pass false in the `recycleEntries` parameter.

      Note that limitations in the underlying storage engines mean that only primitive values - Strings, numbers and booleans - can be stored. If you wish to store an Array or Object, you will have to serialize it to JSON first, and then `eval` it after retrieval to turn it back into an object.

      Note: This method throws an exception if it could not store the value (either because storage is full and recycleEntries was false, or because the value to store is simply too large)

      Parameters:
        `key` - The key to use when storing the value
        `value` - The value to store
        `recycleEntries` - If false, suppresses the default behavior of repeatedly discarding the oldest entry if there is insufficient space to store the value
      See Also:
        `get(java.lang.String)`