DOMException#
Wstęp#
Wyjątek DOMException stanowi definicję Web IDL dla obiektów reprezentujących błędy, które powstały w wyniku niewłaściwego zastosowania poleceń DOM w programie. Są one potocznie nazywane wyjątkami DOM # i wykorzystywane w ogólnym mechanizmie obsługi wyjątków JavaScriptu.
Z teoretycznego punktu widzenia wyjątki Web IDL różnią się od interfejsów Web IDL tym, że wyjątki mogą posiadać jedynie stałe oraz pola wyjątków (łącznie zwanych członkami wyjątku), w przeciwieństwie do trzech typów członków interfejsu (stałe, atrybuty i operacje).
Wyjątki DOM są ściśle określone przez specyfikację DOM. Mają konkretne nazwy oraz odpowiadające im stałe i wartości. Każda implementacja DOM powinna wspierać ten rodzaj błędów w taki sposób, jaki opisuje to specyfikacja.
Algorytm zrzucania # (throw) wyjątku o nazwie name jest następujący:
- Niech code ma wartość zero.
- Jeśli name znajduje się w pierwszej kolumnie tabeli nazwanych błędów oraz ma odpowiadającą wartość pola
codewyjątku w czwartej kolumnie, to ustaw code na tę wartość. - Zrzuć nowy wyjątek typu
DOMException, którego wiadomością jest wartość zdefiniowana przez aplikację kliencką, nazwą jest name, i którego polecodewyjątku to code.
Aby zrzucić wyjątek "TimeoutError" aplikacja kliencka powinna utworzyć wyjątek typu DOMException, którego nazwą jest "TimeoutError", wartością pola code wyjątku jest 23, i rzeczywiście zrzucić ten objekt jako wyjątek. W JavaScripcie wyjątek ten będzie miał właściwość name, której wartością będzie "TimeoutError".
Wyjątek DOMException nie dziedziczy z żadnego innego wyjątku w ogólnym ujęciu DOM, chociaż w środowisku JS obiekty implementujące ten wyjątek będą dziedziczyły z podstawowego błędu typu Error, dlatego mają dostęp do wszystkich poleceń z jego prototypu (oraz z kolejnych prototypów w łańcuchu dziedziczenia).
W poniższej tabeli zamieszczam wykaz nazwanych błędów # oraz ich specyficzne cechy.
| Nazwa | Opis (EN) | Odpowiadająca stała | Wartość stałej (pola code) |
|---|---|---|---|
"IndexSizeError" # | The index is not in the allowed range. | INDEX_SIZE_ERR | 1 |
"HierarchyRequestError" # | The operation would yield an incorrect node tree. | HIERARCHY_REQUEST_ERR | 3 |
"WrongDocumentError" # | The object is in the wrong document. | WRONG_DOCUMENT_ERR | 4 |
"InvalidCharacterError" # | The string contains invalid characters. | INVALID_CHARACTER_ERR | 5 |
"NoModificationAllowedError" # | The object can not be modified. | NO_MODIFICATION_ALLOWED_ERR | 7 |
"NotFoundError" # | The object can not be found here. | NOT_FOUND_ERR | 8 |
"NotSupportedError" # | The operation is not supported. | NOT_SUPPORTED_ERR | 9 |
"InUseAttributeError" # | The attribute is in use. | INUSE_ATTRIBUTE_ER | 10 |
"InvalidStateError" # | The object is in an invalid state. | INVALID_STATE_ERR | 11 |
"SyntaxError" # | The string did not match the expected pattern. | SYNTAX_ERR | 12 |
"InvalidModificationError" # | The object can not be modified in this way. | INVALID_MODIFICATION_ERR | 13 |
"NamespaceError" # | The operation is not allowed by Namespaces in XML. | NAMESPACE_ERR | 14 |
"InvalidAccessError" # | The object does not support the operation or argument. | INVALID_ACCESS_ERR | 15 |
"SecurityError" # | The operation is insecure. | SECURITY_ERR | 18 |
"NetworkError" # | A network error occurred. | NETWORK_ERR | 19 |
"AbortError" # | The operation was aborted. | ABORT_ERR | 20 |
"URLMismatchError" # | The given URL does not match another URL. | URL_MISMATCH_ERR | 21 |
"QuotaExceededError" # | The quota has been exceeded. | QUOTA_EXCEEDED_ERR | 22 |
"TimeoutError" # | The operation timed out. | TIMEOUT_ERR | 23 |
"InvalidNodeTypeError" # | The supplied node is incorrect or has an incorrect ancestor for this operation. | INVALID_NODE_TYPE_ERR | 24 |
"DataCloneError" # | The object can not be cloned. | DATA_CLONE_ERR | 25 |
"EncodingError" # | The encoding operation (either encoded or decoding) failed. | - | - |
"NotReadableError" # | The I/O read operation failed. | - | - |
"UnknownError" # | The operation failed for an unknown transient reason (e.g. out of memory). | - | - |
"ConstraintError" # | A mutation operation in a transaction failed because a constraint was not satisfied. | - | - |
"DataError" # | Provided data is inadequate. | - | - |
"TransactionInactiveError" # | A request was placed against a transaction which is currently not active, or which is finished. | - | - |
"ReadOnlyError" # | The mutating operation was attempted in a "readonly" transaction. | - | - |
"VersionError" # | An attempt was made to open a database using a lower version than the existing version. | - | - |
"OperationError" # | The operation failed for an operation-specific reason. | - | - |
Część nazwanych błędów z poprzednich specyfikacji DOM uznana została za przestarzałe i w nowym DOM4 nie jest już opisywana. Takie błędy celowo pominąłem w powyższej tabeli.
Przy opisach poszczególnych algorytmów w DOM4 jasno zdefiniowano, które wyjątki powinny zostać zrzucone w przypadku niewłaściwego działania poleceń DOM. Nowoczesne przeglądarki zachowują się w tym obszarze dosyć spójnie, ale udostępniają różne właściwości dla błędów. Największa różnica występuje w przypadku odczytywania właściwości name:
- Firefox - wszystko poprawnie, z zachowaniem wielkości znaków.
- Chrome - nazwa stałej, czyli wszystko zapisane wielkimi literami z podkreślnikami (błąd).
- Opera - ogólna nazwa wyjątku
"DOMException"(błąd). - IE9 - brak obsługi właściwości, wartość
undefined(błąd).
Opieranie obsługi błędów na podstawie domyślnych komunikatów zwracanych przez programy nie jest dobrym pomysłem, nigdy nie ma gwarancji zwrócenia tego samego wyjątku w każdej aplikacji.
Właściwości DOMException#
| Nazwa | Opis |
|---|---|
DOMException.code | Zwraca kod danego wyjątku reprezentowany przez stałą wartość liczbową. |
Stałe DOMException#
| Nazwa | Wartość |
|---|---|
INDEX_SIZE_ERR | 1 |
DOMSTRING_SIZE_ERR | 2 |
HIERARCHY_REQUEST_ERR | 3 |
WRONG_DOCUMENT_ERR | 4 |
INVALID_CHARACTER_ERR | 5 |
NO_DATA_ALLOWED_ERR | 6 |
NO_MODIFICATION_ALLOWED_ERR | 7 |
NOT_FOUND_ERR | 8 |
NOT_SUPPORTED_ERR | 9 |
INUSE_ATTRIBUTE_ERR | 10 |
INVALID_STATE_ERR | 11 |
SYNTAX_ERR | 12 |
INVALID_MODIFICATION_ERR | 13 |
NAMESPACE_ERR | 14 |
INVALID_ACCESS_ERR | 15 |
VALIDATION_ERR | 16 |
TYPE_MISMATCH_ERR | 17 |
SECURITY_ERR | 18 |
NETWORK_ERR | 19 |
ABORT_ERR | 20 |
URL_MISMATCH_ERR | 21 |
QUOTA_EXCEEDED_ERR | 22 |
TIMEOUT_ERR | 23 |
INVALID_NODE_TYPE_ERR | 24 |
DATA_CLONE_ERR | 25 |
Wyjątek Web IDL#
exception DOMException {
const unsigned short INDEX_SIZE_ERR = 1;
const unsigned short DOMSTRING_SIZE_ERR = 2; // historical
const unsigned short HIERARCHY_REQUEST_ERR = 3;
const unsigned short WRONG_DOCUMENT_ERR = 4;
const unsigned short INVALID_CHARACTER_ERR = 5;
const unsigned short NO_DATA_ALLOWED_ERR = 6; // historical
const unsigned short NO_MODIFICATION_ALLOWED_ERR = 7;
const unsigned short NOT_FOUND_ERR = 8;
const unsigned short NOT_SUPPORTED_ERR = 9;
const unsigned short INUSE_ATTRIBUTE_ERR = 10;
const unsigned short INVALID_STATE_ERR = 11;
const unsigned short SYNTAX_ERR = 12;
const unsigned short INVALID_MODIFICATION_ERR = 13;
const unsigned short NAMESPACE_ERR = 14;
const unsigned short INVALID_ACCESS_ERR = 15;
const unsigned short VALIDATION_ERR = 16; // historical
const unsigned short TYPE_MISMATCH_ERR = 17; // historical; use JavaScript's TypeError instead
const unsigned short SECURITY_ERR = 18;
const unsigned short NETWORK_ERR = 19;
const unsigned short ABORT_ERR = 20;
const unsigned short URL_MISMATCH_ERR = 21;
const unsigned short QUOTA_EXCEEDED_ERR = 22;
const unsigned short TIMEOUT_ERR = 23;
const unsigned short INVALID_NODE_TYPE_ERR = 24;
const unsigned short DATA_CLONE_ERR = 25;
unsigned short code;
};