View Javadoc
1   /*
2    * Copyright (c) 2002-2026 Gargoyle Software Inc.
3    *
4    * Licensed under the Apache License, Version 2.0 (the "License");
5    * you may not use this file except in compliance with the License.
6    * You may obtain a copy of the License at
7    * https://www.apache.org/licenses/LICENSE-2.0
8    *
9    * Unless required by applicable law or agreed to in writing, software
10   * distributed under the License is distributed on an "AS IS" BASIS,
11   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12   * See the License for the specific language governing permissions and
13   * limitations under the License.
14   */
15  package org.htmlunit.javascript.host.event;
16  
17  import org.htmlunit.corejs.javascript.Context;
18  import org.htmlunit.corejs.javascript.Function;
19  import org.htmlunit.corejs.javascript.Scriptable;
20  import org.htmlunit.corejs.javascript.ScriptableObject;
21  import org.htmlunit.corejs.javascript.VarScope;
22  import org.htmlunit.javascript.JavaScriptEngine;
23  import org.htmlunit.javascript.configuration.JsxClass;
24  import org.htmlunit.javascript.configuration.JsxConstructor;
25  import org.htmlunit.javascript.configuration.JsxFunction;
26  import org.htmlunit.javascript.configuration.JsxGetter;
27  import org.htmlunit.javascript.host.Storage;
28  
29  /**
30   * A JavaScript object for {@code StorageEvent}.
31   *
32   * @author Ahmed Ashour
33   * @author Ronald Brill
34   *
35   * @see <a href="https://html.spec.whatwg.org/multipage/webstorage.html#the-storageevent-interface">
36   *     HTML Living Standard - The StorageEvent interface</a>
37   */
38  @JsxClass
39  public class StorageEvent extends Event {
40  
41      private String key_;
42      private String oldValue_;
43      private String newValue_;
44      private String url_ = "";
45      private Storage storageArea_;
46  
47      /**
48       * JavaScript constructor.
49       *
50       * @param type the event type
51       * @param details the event details (optional)
52       */
53      @Override
54      @JsxConstructor
55      public void jsConstructor(final String type, final ScriptableObject details) {
56          super.jsConstructor(type, details);
57  
58          if (details != null && !JavaScriptEngine.isUndefined(details)) {
59              key_ = toNullableString(details.get("key"));
60              oldValue_ = toNullableString(details.get("oldValue"));
61              newValue_ = toNullableString(details.get("newValue"));
62  
63              final Object url = details.get("url");
64              if (url != NOT_FOUND && !JavaScriptEngine.isUndefined(url)) {
65                  url_ = JavaScriptEngine.toString(url);
66              }
67  
68              final Object storageArea = details.get("storageArea");
69              if (storageArea instanceof Storage storage) {
70                  storageArea_ = storage;
71              }
72              else if (storageArea != null && storageArea != NOT_FOUND
73                          && !JavaScriptEngine.isUndefined(storageArea)) {
74                  throw JavaScriptEngine.typeError(
75                          "Failed to construct 'StorageEvent': member storageArea is not of type Storage.");
76              }
77          }
78      }
79  
80      private static String toNullableString(final Object value) {
81          if (value == null || value == NOT_FOUND || JavaScriptEngine.isUndefined(value)) {
82              return null;
83          }
84          return JavaScriptEngine.toString(value);
85      }
86  
87      /**
88       * Initializes this storage event.
89       *
90       * @param type the event type
91       * @param bubbles whether the event bubbles
92       * @param cancelable whether the event is cancelable
93       * @param key the changed key or {@code null} if the storage was cleared
94       * @param oldValue the old value or {@code null}
95       * @param newValue the new value or {@code null}
96       * @param url the URL of the document whose storage was changed
97       * @param storageArea the affected storage
98       */
99      public void initStorageEvent(final String type, final boolean bubbles, final boolean cancelable,
100             final String key, final String oldValue, final String newValue,
101             final String url, final Storage storageArea) {
102         initEvent(type, bubbles, cancelable);
103         key_ = key;
104         oldValue_ = oldValue;
105         newValue_ = newValue;
106         url_ = url;
107         storageArea_ = storageArea;
108     }
109 
110     /**
111      * Implementation of the JavaScript function
112      * {@code initStorageEvent(type, bubbles, cancelable, key, oldValue, newValue, url, storageArea)}.
113      *
114      * @param context the context
115      * @param scope the scope
116      * @param thisObj this object
117      * @param args the arguments
118      * @param function the function
119      */
120     @JsxFunction(functionName = "initStorageEvent")
121     public static void jsInitStorageEvent(final Context context, final VarScope scope,
122             final Scriptable thisObj, final Object[] args, final Function function) {
123         if (!(thisObj instanceof StorageEvent event)) {
124             throw JavaScriptEngine.typeError("Illegal invocation");
125         }
126         if (args.length < 1) {
127             throw JavaScriptEngine.typeError("Failed to execute 'initStorageEvent' on 'StorageEvent': "
128                     + "1 argument required, but only 0 present.");
129         }
130 
131         final String type = JavaScriptEngine.toString(args[0]);
132         final boolean bubbles = args.length > 1 && JavaScriptEngine.toBoolean(args[1]);
133         final boolean cancelable = args.length > 2 && JavaScriptEngine.toBoolean(args[2]);
134         final String key = args.length > 3 ? toNullableString(args[3]) : null;
135         final String oldValue = args.length > 4 ? toNullableString(args[4]) : null;
136         final String newValue = args.length > 5 ? toNullableString(args[5]) : null;
137         String url = "";
138         if (args.length > 6 && !JavaScriptEngine.isUndefined(args[6])) {
139             url = JavaScriptEngine.toString(args[6]);
140         }
141         Storage storageArea = null;
142         if (args.length > 7) {
143             if (args[7] instanceof Storage storage) {
144                 storageArea = storage;
145             }
146             else if (args[7] != null && !JavaScriptEngine.isUndefined(args[7])) {
147                 throw JavaScriptEngine.typeError("Failed to execute 'initStorageEvent' on 'StorageEvent': "
148                         + "parameter 8 is not of type 'Storage'.");
149             }
150         }
151         event.initStorageEvent(type, bubbles, cancelable, key, oldValue, newValue, url, storageArea);
152     }
153 
154     /**
155      * Returns the key that was changed.
156      * @return the key or {@code null} if the storage was cleared
157      */
158     @JsxGetter
159     public String getKey() {
160         return key_;
161     }
162 
163     /**
164      * Returns the old value of the changed key.
165      * @return the old value or {@code null}
166      */
167     @JsxGetter
168     public String getOldValue() {
169         return oldValue_;
170     }
171 
172     /**
173      * Returns the new value of the changed key.
174      * @return the new value or {@code null}
175      */
176     @JsxGetter
177     public String getNewValue() {
178         return newValue_;
179     }
180 
181     /**
182      * Returns the URL of the document whose storage was changed.
183      * @return the URL
184      */
185     @JsxGetter
186     public String getUrl() {
187         return url_;
188     }
189 
190     /**
191      * Returns the storage that was affected.
192      * @return the storage or {@code null}
193      */
194     @JsxGetter
195     public Storage getStorageArea() {
196         return storageArea_;
197     }
198 }