001 
002 /*
003  *  JScripter Standard 1.0 - To Script In Java
004  *  Copyright (C) 2008-2011  J.J.Liu<jianjunliu@126.com> <http://www.jscripter.org>
005  *  
006  *  This program is free software: you can redistribute it and/or modify
007  *  it under the terms of the GNU Affero General Public License as published by
008  *  the Free Software Foundation, either version 3 of the License, or
009  *  (at your option) any later version.
010  *  
011  *  This program is distributed in the hope that it will be useful,
012  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
013  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
014  *  GNU Affero General Public License for more details.
015  *  
016  *  You should have received a copy of the GNU Affero General Public License
017  *  along with this program.  If not, see <http://www.gnu.org/licenses/>.
018  */
019 
020 package js.user;
021 
022 import js.*;
023 import js.core.*;
024 
025 /**
026  * <p>An <b>opaque</b> class representing JavaScript client-side objects of the global 
027  * {@link JsClient#DOMException} class.</p>
028  * <p>An object of this class is thrown when a DOM method or property is used incorrectly 
029  * or in an inappropriate context. The value of the {@link JsDOMException#code} property 
030  * indicates the general type of exception that occurred. Note that an object of this 
031  * class may be thrown when reading or writing a property of an object as well as when 
032  * calling a method of an object.</p>
033  * <p>The descriptions of object properties and methods in this specification include a 
034  * list of exception types they may throw. Note, however, that certain commonly thrown 
035  * exceptions are omitted from these lists. An object of {@link JsDOMException} with the 
036  * {@link JsDOMException#code} value of {@link JsDOMException#NO_MODIFICATION_ALLOWED_ERR} 
037  * is thrown any time an attempt is made to modify a read-only node. Thus, most methods 
038  * and read/write properties of the {@link JsNode} and of its subclass may throw this 
039  * exception. Because read-only nodes appear only in XML documents and not in HTML 
040  * documents, and because it applies so universally to the methods and writable properties 
041  * of {@link JsNode} objects, the {@link JsDOMException#NO_MODIFICATION_ALLOWED_ERR} 
042  * exception is omitted from the descriptions of those methods and properties</p>
043  * <p>Similarly, many DOM methods and properties that return strings may throw a 
044  * {@link JsDOMException} with the value {@link JsDOMException#code} of {@link JsDOMException#DOMSTRING_SIZE_ERR}, 
045  * which indicates that the text to be returned is too long to be represented as a string 
046  * value in the underlying JavaScript implementation. Although this type of exception 
047  * may theoretically be thrown by many properties and methods, it is very rare in 
048  * practice and is omitted from the descriptions of those methods and properties</p>
049  * <p>Note that not all exceptions in the DOM are signaled with a {@link JsDOMException}. 
050  * Exceptions involving the DOM Range module cause a {@link JsRangeException} to be 
051  * thrown.</p>
052  *
053  * @author <a href="mailto:jianjunliu@126.com">J.J.Liu (Jianjun Liu)</a> at <a href="http://www.jscripter.org" target="_blank">http://www.jscripter.org</a>
054  *
055  * @javascript <b>Opaque</b> types can be resolved but no class objects for them can be
056  * generated into the target codes. Re-compilers must exit with error on the operations of
057  * accessing that kind of class objects.
058  * The <tt>checkcast</tt> operation to the class literal of this interface must be ignored
059  * and <tt>instanceof</tt> to it always <tt>true</tt>.
060  */
061 public class JsDOMException extends JsClient.DOMException.Prototype
062 {
063     /**
064      * A legal value for the {@link #code} property of a {@link JsDOMException} object 
065      * indicating an out-of-bounds error for an array or string index.
066      * @since 1.0
067      * @see js.dom.DOM2Core.DOMException#INDEX_SIZE_ERR
068      * @see js.dom.DOM2Core.DOMException.Member#INDEX_SIZE_ERR
069      */
070     public static final int INDEX_SIZE_ERR              = 1;
071     /**
072      * A legal value for the {@link #code} property of a {@link JsDOMException} object 
073      * indicating that a requested text is too big to fit into a string in the current 
074      * JavaScript implementation.
075      * @since 1.0
076      * @see js.dom.DOM2Core.DOMException#DOMSTRING_SIZE_ERR
077      * @see js.dom.DOM2Core.DOMException.Member#DOMSTRING_SIZE_ERR
078      */
079     public static final int DOMSTRING_SIZE_ERR          = 2;
080     /**
081      * A legal value for the {@link #code} property of a {@link JsDOMException} object 
082      * indicating that an attempt was made to place a node somewhere illegal in the 
083      * document-tree hierarchy.
084      * @since 1.0
085      * @see js.dom.DOM2Core.DOMException#HIERARCHY_REQUEST_ERR
086      * @see js.dom.DOM2Core.DOMException.Member#HIERARCHY_REQUEST_ERR
087      */
088     public static final int HIERARCHY_REQUEST_ERR       = 3;
089     /**
090      * A legal value for the {@link #code} property of a {@link JsDOMException} object 
091      * indicating an attempt to use a node with a document that is different from the 
092      * document that created the node.
093      * @since 1.0
094      * @see js.dom.DOM2Core.DOMException#WRONG_DOCUMENT_ERR
095      * @see js.dom.DOM2Core.DOMException.Member#WRONG_DOCUMENT_ERR
096      */
097     public static final int WRONG_DOCUMENT_ERR          = 4;
098     /**
099      * A legal value for the {@link #code} property of a {@link JsDOMException} object 
100      * indicating that an illegal character is used (in an element name, for example).
101      * @since 1.0
102      * @see js.dom.DOM2Core.DOMException#INVALID_CHARACTER_ERR
103      * @see js.dom.DOM2Core.DOMException.Member#INVALID_CHARACTER_ERR
104      */
105     public static final int INVALID_CHARACTER_ERR       = 5;
106     /**
107      * A legal value for the {@link #code} property of a {@link JsDOMException} object 
108      * not currently used.
109      * @since 1.0
110      * @see js.dom.DOM2Core.DOMException#NO_DATA_ALLOWED_ERR
111      * @see js.dom.DOM2Core.DOMException.Member#NO_DATA_ALLOWED_ERR
112      */
113     public static final int NO_DATA_ALLOWED_ERR         = 6;
114     /**
115      * A legal value for the {@link #code} property of a {@link JsDOMException} object 
116      * indicating that an attempt was made to modify a node that is read-only and does 
117      * not allow modifications.
118      * @since 1.0
119      * @see js.dom.DOM2Core.DOMException#NO_MODIFICATION_ALLOWED_ERR
120      * @see js.dom.DOM2Core.DOMException.Member#NO_MODIFICATION_ALLOWED_ERR
121      */
122     public static final int NO_MODIFICATION_ALLOWED_ERR = 7;
123     /**
124      * A legal value for the {@link #code} property of a {@link JsDOMException} object 
125      * indicating that a node was not found where it was expected.
126      * @since 1.0
127      * @see js.dom.DOM2Core.DOMException#NOT_FOUND_ERR
128      * @see js.dom.DOM2Core.DOMException.Member#NOT_FOUND_ERR
129      */
130     public static final int NOT_FOUND_ERR               = 8;
131     /**
132      * A legal value for the {@link #code} property of a {@link JsDOMException} object 
133      * indicating that a method or property is not supported in the current DOM 
134      * implementation.
135      * @since 1.0
136      * @see js.dom.DOM2Core.DOMException#NOT_SUPPORTED_ERR
137      * @see js.dom.DOM2Core.DOMException.Member#NOT_SUPPORTED_ERR
138      */
139     public static final int NOT_SUPPORTED_ERR           = 9;
140     /**
141      * A legal value for the {@link #code} property of a {@link JsDOMException} object 
142      * indicating that an attempt was made to associate an {@link JsAttr} node with a 
143      * {@link JsElement} node when that {@link JsAttr} node was already associated with 
144      * a different {@link JsElement} node.
145      * @since 1.0
146      * @see js.dom.DOM2Core.DOMException#INUSE_ATTRIBUTE_ERR
147      * @see js.dom.DOM2Core.DOMException.Member#INUSE_ATTRIBUTE_ERR
148      */
149     public static final int INUSE_ATTRIBUTE_ERR         = 10;
150     /**
151      * A legal value for the {@link #code} property of a {@link JsDOMException} object 
152      * indicating an attempt to use an object that is not yet, or is no longer, in a 
153      * state that allows such use.
154      * @since 1.0
155      * @see js.dom.DOM2Core.DOMException#INVALID_STATE_ERR
156      * @see js.dom.DOM2Core.DOMException.Member#INVALID_STATE_ERR
157      */
158     public static final int INVALID_STATE_ERR           = 11;
159     /**
160      * A legal value for the {@link #code} property of a {@link JsDOMException} object 
161      * indicating that a specified string contains a syntax error. Commonly used with 
162      * CSS property specifications.
163      * @since 1.0
164      * @see js.dom.DOM2Core.DOMException#SYNTAX_ERR
165      * @see js.dom.DOM2Core.DOMException.Member#SYNTAX_ERR
166      */
167     public static final int SYNTAX_ERR                  = 12;
168     /**
169      * A legal value for the {@link #code} property of a {@link JsDOMException} object 
170      * indicating an attempt to modify the type of a {@link JsCSSRule} or 
171      * {@link JsCSSStyleSheet} object.
172      * @since 1.0
173      * @see js.dom.DOM2Core.DOMException#INVALID_MODIFICATION_ERR
174      * @see js.dom.DOM2Core.DOMException.Member#INVALID_MODIFICATION_ERR
175      */
176     public static final int INVALID_MODIFICATION_ERR    = 13;
177     /**
178      * A legal value for the {@link #code} property of a {@link JsDOMException} object 
179      * indicating an error involving element or attribute namespaces.
180      * @since 1.0
181      * @see js.dom.DOM2Core.DOMException#NAMESPACE_ERR
182      * @see js.dom.DOM2Core.DOMException.Member#NAMESPACE_ERR
183      */
184     public static final int NAMESPACE_ERR               = 14;
185     /**
186      * A legal value for the {@link #code} property of a {@link JsDOMException} object 
187      * indicating an attempt to access an object in a way that is not supported by the 
188      * implementation.
189      * @since 1.0
190      * @see js.dom.DOM2Core.DOMException#INVALID_ACCESS_ERR
191      * @see js.dom.DOM2Core.DOMException.Member#INVALID_ACCESS_ERR
192      */
193     public static final int INVALID_ACCESS_ERR          = 15;
194 
195     /**
196      * <p>An <b>internal</b> class containing membership data for its enclosing
197      * opaque class.</p>
198      * <p>This class is only used inside of <b>opaque</b> or <b>internal</b> classes or
199      * class members.</p>
200      *
201      * @author <a href="mailto:jianjunliu@126.com">J.J.Liu (Jianjun Liu)</a> at <a href="http://www.jscripter.org" target="_blank">http://www.jscripter.org</a>
202      * 
203      * @javascript Re-compilers must report error on resolving an <b>internal</b> class.
204      */
205     protected static abstract class Members extends JsClient.DOMException.Prototype.Members
206     {
207         /**
208          * <p>An <b>internal</b> static field defining a member ID of the field name and
209          * used internally to define a member of the same name.</p>
210          * @since 1.0
211          * @see JsDOMException#code
212          * @see JsDOMException.Member#code
213          * @javascript Re-compilers must report error on accessing an <b>internal</b> field.
214          */
215         public final static Mid code = id("code");
216     }
217     /**
218      * <p>An <b>opaque</b> class representing members of its enclosing <b>opaque</b> type.</p>
219      * <p>Note that, this class is <b>opaque</b> but its constructors are all <b>internal</b>. 
220      * This class and the subclasses of this class are used to declare either <b>opaque</b> 
221      * <tt>public</tt> instance fields of the opaque type {@link js.Var.Member} or the 
222      * <b>opaque</b> <tt>public</tt> static fields of other <b>opaque</b> types while their 
223      * constructors are used to define the fields inside <b>opaque</b> classes. Under 
224      * either circumstance, the field names must be exactly same as the member names, as 
225      * the <b>opaque</b> fields of <b>opaque</b> types are resolved by re-compilers directly 
226      * based on the field names.</p>
227      *
228      * @author <a href="mailto:jianjunliu@126.com">J.J.Liu (Jianjun Liu)</a> at <a href="http://www.jscripter.org" target="_blank">http://www.jscripter.org</a>
229      * 
230      * @javascript <b>Opaque</b> types can be resolved but no class objects for them can be created
231      * in the target codes. Re-compilers must exit with error on operations accessing that kind 
232      * of class objects.
233      * Re-compilers must resolve an <b>opaque</b> instance field declared by this class in
234      * {@link js.Var.Member} or its subclasses to the JavaScript identifier: 
235      * <pre>q.m</pre>
236      * where <tt>m</tt> is the identifier of the field name and <tt>q</tt> is the identifier
237      * resolved from the instance of the enclosing member. Re-compilers must resolve an 
238      * <b>opaque</b> static field declared by this class in <b>opaque</b> types other than 
239      * {@link js.Var.Member} and its subclasses to the JavaScript identifier: 
240      * <pre>m</pre>
241      * where <tt>m</tt> is the identifier of the field name. And re-compilers must report
242      * error on the access to <b>opaque</b> fields declared by this class under any other 
243      * circumstances.
244      */
245     public static class Member extends JsClient.DOMException.Prototype.Member
246     {
247         /**
248          * <p>Internally constructs a member based on a qualifying member.</p>
249          * <p>This constructor is <b>internal</b> and only called inside of <b>opaque</b>
250          * or <b>internal</b> classes or class members.</p>
251          * <p>Note that, this constructor is <b>internal</b> but its declaring class is
252          * <b>opaque</b>. This constructor is used to define <b>opaque</b> instance fields 
253          * declared in the declaring class of this constructor itself or its subclasses. 
254          * Under this circumstance, the field names must be exactly same as the member 
255          * names, as the <b>opaque</b> instance fields of the <b>opaque</b> type 
256          * {@link js.Var.Member} or its subclasses are resolved by re-compilers directly
257          * to their names appending to the name resolved from the specified qualifying 
258          * member with a dot in between.</p>
259          * @param q A qualifying member
260          * @param mid The ID of the member to construct
261          * @since 1.0
262          * @javascript Re-compilers must report error on the invocation to an <b>internal</b> constructor.
263          */
264         public Member(JsObject.Member q, Mid mid) {
265             super(q, mid);
266         }
267         /**
268          * <p>Internally constructs a member without a qualifying member.</p>
269          * <p>This constructor is <b>internal</b> and only called inside of <b>opaque</b>
270          * or <b>internal</b> classes or class members.</p>
271          * <p>Note that, this constructor is <b>internal</b> but its declaring class is
272          * <b>opaque</b>. This constructor is used to define <b>opaque</b> static fields, 
273          * declared in <b>opaque</b> types other than the declaring class of this constructor 
274          * itself and its subclasses. Under this circumstance, the field names must be
275          * exactly same as the member names, as the <b>opaque</b> static fields of <b>opaque</b>
276          * types are generally resolved by re-compilers directly to identifiers of their names.</p>
277          * @param mid The ID of the member to construct
278          * @since 1.0
279          * @javascript Re-compilers must report error on the invocation to an <b>internal</b> constructor.
280          */
281         public Member(Mid mid) {
282             super(mid);
283         }
284         @Override
285         /**
286          * <p>Evaluates the property, represented by the current member instance, of the
287          * argument object.</p>
288          * @param o The argument object
289          * @return The value of the current member based on the object argument.
290          * @since 1.0
291          * @javascript Re-compilers must convert the instance invocation of this method into
292          * the JavaScript expression: 
293          * <pre>o.m</pre>
294          * where <tt>m</tt> is the identifier name resolved from the current member
295          * instance of the invocation.
296          */
297         public JsDOMException with(ObjectLike o) {
298             return new JsDOMException(super.with(o));
299         }
300 
301         /**
302          * <p>An <b>opaque</b> instance field defining a sub-member that is named by the
303          * name of this field, qualified by the current member instance of the field, and 
304          * to access the property of the name on an object.</p>
305          * <p>The property, identified by this member, of a {@link JsDOMException} 
306          * object refers to an error code that provides some detail about what caused 
307          * the exception. The legal values and their meanings for the property are 
308          * defined by the static constants of {@link JsDOMException} class.</p>
309          * @since 1.0
310          * @javascript Re-compilers must resolve the member of this instance field to the
311          * identifier of the field name appending to the identifier resolved from its 
312          * qualifying member with a dot in between.
313          */
314         public final Value.Number.Member code = new Value.Number.Member(this, Members.code);
315     }
316 
317     /**
318      * <p>Casts an <b>opaque</b> object to the current <b>opaque</b> type by wrapping it
319      * with the wrapping constructor.</p>
320      * @param var The argument of an <b>opaque</b> object.
321      * @since 1.0
322      * @javascript Re-compilers must ignore the construction operation of this constructor,
323      * that is, replacing it with its only argument.
324      */
325     public JsDOMException(JsObject var) {
326         super(var);
327     }
328 
329     /**
330      * <p>An <b>opaque</b> static field defining a member that is named by the field name
331      * without a qualifying member and to access the property of the name on an object.</p>
332      * <p>The property, identified by this member, of a {@link JsDOMException} 
333      * object refers to an error code that provides some detail about what caused 
334      * the exception. The legal values and their meanings for the property are 
335      * defined by the static constants of {@link JsDOMException} class.</p>
336      * @since 1.0
337      * @javascript Re-compilers must resolve the member of this static field to the
338      * identifier of the field name.
339      */
340     public static final Value.Number.Member code = new Value.Number.Member(Members.code);
341 
342     @Override
343     /**
344      * <p>Returns the primitive value associated with the current instance, if there is one.
345      * This invocation simply returns the instance itself for the current instance is an 
346      * object and there is no primitive value for it.</p>
347      * @return The current object itself.
348      * @since 1.0
349      * @javascript Re-compilers must convert the instance invocation of this method directly
350      * into a JavaScript invocation on its current object instance without changing the 
351      * method name, but expanding variable arguments, if any, into comma-separated values. 
352      */
353     public JsDOMException valueOf() {
354         return new JsDOMException((JsObject)var().valueOf());
355     }
356 }