com.google.gwt.storage.client.Storage Maven / Gradle / Ivy
/*
* Copyright 2011 Google Inc.
*
* Licensed under the Apache License, Version 2.0 (the "License"); you may not
* use this file except in compliance with the License. You may obtain a copy of
* the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
* WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
* License for the specific language governing permissions and limitations under
* the License.
*/
package com.google.gwt.storage.client;
import com.google.gwt.core.client.GWT;
import com.google.gwt.dom.client.PartialSupport;
import com.google.gwt.event.shared.HandlerRegistration;
/**
* Implements the HTML5 Storage interface.
*
*
* You can obtain a Storage by either invoking
* {@link #getLocalStorageIfSupported()} or
* {@link #getSessionStorageIfSupported()}.
*
*
*
* Experimental API: This API is still under development
* and is subject to change.
*
*
*
* If Web Storage is NOT supported in the browser, these methods return
* null.
*
*
*
* Note: Storage events into other windows are not supported.
*
*
*
*
* This may not be supported on all browsers.
*
*
* @see W3C Web Storage -
* Storage
* @see Safari
* Client-Side Storage and Offline Applications Programming Guide -
* Key-Value Storage
* @see Quirksmode.org -
* HTML5 Compatibility - Storage
* @see Wiki - Quickstart Guide
*/
// TODO(pdr): Add support for Object values, instead of just Strings. The
// Storage API spec specifies this, but browser support poor at the moment.
// TODO(pdr): Add support for native events once browsers correctly implement
// storage events.
@PartialSupport
public final class Storage {
// Still a separate class to prevent native calls on class load as it my break existing code.
private static class StorageSupportDetector {
static final boolean localStorageSupported = checkStorageSupport(StorageImpl.LOCAL_STORAGE);
static final boolean sessionStorageSupported = checkStorageSupport(StorageImpl.SESSION_STORAGE);
// Adapted from modernizr
private static native boolean checkStorageSupport(String storage) /*-{
var c = '_gwt_dummy_';
try {
$wnd[storage].setItem(c, c);
$wnd[storage].removeItem(c);
return true;
} catch (e) {
return false;
}
}-*/;
}
static final StorageImpl impl = GWT.create(StorageImpl.class);
private static Storage localStorage;
private static Storage sessionStorage;
/**
* Registers an event handler for StorageEvents.
*
* @see W3C Web
* Storage - the storage event
* @param handler
* @return {@link HandlerRegistration} used to remove this handler
*/
public static HandlerRegistration addStorageEventHandler(
StorageEvent.Handler handler) {
return impl.addStorageEventHandler(handler);
}
/**
* Returns a Local Storage.
*
*
* The returned storage is associated with the origin of the
* Document.
*
*
* @see W3C Web
* Storage - localStorage
* @return the localStorage instance, or null if Web Storage is
* NOT supported.
*/
public static Storage getLocalStorageIfSupported() {
if (localStorage == null && isLocalStorageSupported()) {
localStorage = new Storage(StorageImpl.LOCAL_STORAGE);
}
return localStorage;
}
/**
* Returns a Session Storage.
*
*
* The returned storage is associated with the current top-level browsing context.
*
*
* @see W3C Web
* Storage - sessionStorage
* @return the sessionStorage instance, or null if Web Storage is
* NOT supported.
*/
public static Storage getSessionStorageIfSupported() {
if (sessionStorage == null && isSessionStorageSupported()) {
sessionStorage = new Storage(StorageImpl.SESSION_STORAGE);
}
return sessionStorage;
}
/**
* Returns true if the localStorage part of the
* Storage API is supported on the running platform.
*/
public static boolean isLocalStorageSupported() {
return StorageSupportDetector.localStorageSupported;
}
/**
* Returns true if the sessionStorage part of the
* Storage API is supported on the running platform.
*/
public static boolean isSessionStorageSupported() {
return StorageSupportDetector.sessionStorageSupported;
}
/**
* Returns true if the Storage API (both localStorage and
* sessionStorage) is supported on the running platform.
*/
public static boolean isSupported() {
return isLocalStorageSupported() && isSessionStorageSupported();
}
/**
* De-registers an event handler for StorageEvents.
*
* @see W3C Web
* Storage - the storage event
* @param handler
*/
public static void removeStorageEventHandler(StorageEvent.Handler handler) {
impl.removeStorageEventHandler(handler);
}
// Contains either "localStorage" or "sessionStorage":
private final String storage;
/**
* This class can never be instantiated externally. Use
* {@link #getLocalStorageIfSupported()} or
* {@link #getSessionStorageIfSupported()} instead.
*/
private Storage(String storage) {
this.storage = storage;
}
/**
* Removes all items in the Storage.
*
* @see W3C Web
* Storage - Storage.clear()
*/
public void clear() {
impl.clear(storage);
}
/**
* Returns the item in the Storage associated with the specified key.
*
* @param key the key to a value in the Storage
* @return the value associated with the given key
* @see W3C Web
* Storage - Storage.getItem(k)
*/
public String getItem(String key) {
return impl.getItem(storage, key);
}
/**
* Returns the number of items in this Storage.
*
* @return number of items in this Storage
* @see W3C Web
* Storage - Storage.length()
*/
public int getLength() {
return impl.getLength(storage);
}
/**
* Returns the key at the specified index.
*
* @param index the index of the key
* @return the key at the specified index in this Storage
* @see W3C Web
* Storage - Storage.key(n)
*/
public String key(int index) {
return impl.key(storage, index);
}
/**
* Removes the item in the Storage associated with the specified key.
*
* @param key the key to a value in the Storage
* @see W3C
* Web Storage - Storage.removeItem(k)
*/
public void removeItem(String key) {
impl.removeItem(storage, key);
}
/**
* Sets the value in the Storage associated with the specified key to the
* specified data.
*
* Note: The empty string may not be used as a key.
*
* @param key the key to a value in the Storage
* @param data the value associated with the key
* @see W3C Web
* Storage - Storage.setItem(k,v)
*/
public void setItem(String key, String data) {
// prevent the empty string due to a Firefox bug:
// bugzilla.mozilla.org/show_bug.cgi?id=510849
assert key.length() > 0;
impl.setItem(storage, key, data);
}
}