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 {
/**
* Detector for browser support of Storage.
*/
private static class StorageSupportDetector {
private final boolean isLocalStorageSupported = detectLocalStorageSupport();
private final boolean isSessionStorageSupported =
detectSessionStorageSupport();
public boolean isLocalStorageSupported() {
return isLocalStorageSupported;
}
public boolean isSessionStorageSupported() {
return isSessionStorageSupported;
}
private native boolean detectLocalStorageSupport() /*-{
return typeof $wnd.localStorage != "undefined";
}-*/;
private native boolean detectSessionStorageSupport() /*-{
return typeof $wnd.sessionStorage != "undefined";
}-*/;
}
/**
* Detector for browsers that do not support Storage.
*/
@SuppressWarnings("unused")
private static class StorageSupportDetectorNo extends StorageSupportDetector {
@Override
public boolean isLocalStorageSupported() {
return false;
}
@Override
public boolean isSessionStorageSupported() {
return false;
}
}
static final StorageImpl impl = GWT.create(StorageImpl.class);
private static Storage localStorage;
private static Storage sessionStorage;
/**
* Singleton for Support detector.
*/
private static StorageSupportDetector supportDetectorImpl;
/**
* 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 (isLocalStorageSupported()) {
if (localStorage == null) {
localStorage = new Storage(StorageImpl.LOCAL_STORAGE);
}
return localStorage;
}
return null;
}
/**
* 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 (isSessionStorageSupported()) {
if (sessionStorage == null) {
sessionStorage = new Storage(StorageImpl.SESSION_STORAGE);
}
return sessionStorage;
}
return null;
}
/**
* Returns true if the localStorage part of the
* Storage API is supported on the running platform.
*/
public static boolean isLocalStorageSupported() {
return getStorageSupportDetector().isLocalStorageSupported();
}
/**
* Returns true if the sessionStorage part of the
* Storage API is supported on the running platform.
*/
public static boolean isSessionStorageSupported() {
return getStorageSupportDetector().isSessionStorageSupported();
}
/**
* 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);
}
private static StorageSupportDetector getStorageSupportDetector() {
if (supportDetectorImpl == null) {
supportDetectorImpl = GWT.create(StorageSupportDetector.class);
}
return supportDetectorImpl;
}
// 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);
}
}