[API Review] RT-29584 Implement window.localStorage

[Vasiliy Baranov]

Hi,

In the context of adding support for persistent 'window.localStorage' to 
WebView/WebEgnine as requested by 
https://javafx-jira.kenai.com/browse/RT-29584, I propose a few additions 
to javafx.scene.web APIs as speced in the attached diff.

Note that the property being added to WebEngine is read-only but has a 
separately documented setter method.

Also note the addition of a new exception class representing a somewhat 
unusual error condition.

Thoughts, opinions?

Thanks,
-- Vasiliy
-------------- next part --------------
diff -r 4702e476a15e javafx-ui-webnode/src/javafx/scene/web/WebEngine.java
--- a/javafx-ui-webnode/src/javafx/scene/web/WebEngine.java	Tue Apr 02 13:56:51 2013 +0400
+++ b/javafx-ui-webnode/src/javafx/scene/web/WebEngine.java	Tue Apr 09 18:48:27 2013 +0400
@@ -496,6 +496,65 @@
     }
     
+    /**
+     * Specifies the directory used by this {@code WebEngine} to store
+     * local user data.
+     *
+     * <p>Currently, local user data consists solely of
+     * {@code window.localStorage} data associated with visited origins.
+     * In the future, local user data may also include cookies,
+     * application caches, IndexedDB data, etc.
+     *
+     * <p>The value of this property may be either an absolute pathname
+     * or {@code null}. A non-{@code null} value turns on all
+     * {@code WebEngine} features requiring local user data;
+     * the value of {@code null} turns all such features off.
+     *
+     * <p>This property may only be modified before any content is loaded
+     * into the {@code WebEngine}.
+     * 
+     * <p>Multiple {@code WebEngine} instances may share a single user
+     * data directory as long as they run in the same VM.
+     * {@code WebEngine} instances running in different VMs are not
+     * allowed to share the same user data directory.
+     *
+     * @defaultValue null
+     * @since 8.0
+     */
+    private ReadOnlyObjectWrapper<File> userDataDirectory;
+
+    public final File getUserDataDirectory() {
+        ...
+    }
+
+    /**
+     * Sets the value of the {@code userDataDirectory} property.
+     * 
+     * <p>This method creates the specified directory if it does not
+     * exist yet.
+     * 
+     * @param value The new value of the {@code userDataDirectory} property
+     * @throws IllegalArgumentException If {@code value} is a non-absolute
+     *         pathname
+     * @throws IllegalStateException If this {@code WebEngine} has already
+     *         been loaded with some content
+     * @throws IOException If an I/O error occurs while creating
+     *         or accessing the specified directory
+     * @throws DirectoryAlreadyInUseException If the specified directory
+     *         is already in use by a {@code WebEngnine} running in
+     *         a different VM
+     * @throws SecurityException If a security error occurs while creating
+     *         or accessing the specified directory
+     * @since 8.0
+     */
+    public final void setUserDataDirectory(File value) throws IOException {
+        ...
+    }
+
+    public final ReadOnlyObjectProperty<File> userDataDirectoryProperty() {
+        ...
+    }
+
     /**
      * Specifies user agent ID string. This string is the value of the
      * {@code User-Agent} HTTP header.
      * 
diff -r 4702e476a15e javafx-ui-webnode/src/javafx/scene/web/DirectoryAlreadyInUseException.java
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/javafx-ui-webnode/src/javafx/scene/web/DirectoryAlreadyInUseException.java	Tue Apr 09 18:48:54 2013 +0400
@@ -0,0 +1,15 @@
+package javafx.scene.web;
+
+/**
+ * Thrown to indicate that a directory is already in use by another entity.
+ * 
+ * @see WebEngine#setUserDataDirectory
+ * @since 8.0
+ */
+ at NoBuilder
+public final class DirectoryAlreadyInUseException extends RuntimeException {
+    
+    DirectoryAlreadyInUseException(String message) {
+        super(message);
+    }
+}