TOI3 Exceptions

Error handling in TOI is done exclusively using exceptions. There are multiple types of exceptions, each signalling a type of error condition. For each method available in TOI, the possible exceptions, if any, are enumerated in the API reference. It is highly advisable to handle these exceptions to avoid erratic application behavior.

Exception types

TOI3/JS exceptions are compatible with the built-in ECMAScript Error type and relate to each other in the following way:

┌──────────────────────────────────┐
│ Error (ECMAScript built-in type) │
└────┬─────────────────────────────┘
┌────┴─────────┐
│ ToiException │
└────┬─────────┘
     ├──────────────────────────────┬───────────────────────────────┬──┄┄┄
┌────┴────────────────────────┐ ┌───┴──────────────────────────┐ ┌──┴──┄┄┄
│ ToiInvalidArgumentException │ │ ToiPermissionDeniedException │ │ ...
└─────────────────────────────┘ └──────────────────────────────┘ └─────┄┄┄

Handling exceptions

Like standard exceptions, all TOI exceptions have name and message properties, as well as the usual toString() implementation:

try {
  toi.informationService.getObject("nonExistingObject");
} catch (exception) {
  alert(exception.name);    // gives "ToiInvalidArgumentException"
  alert(exception.message); // gives "Unknown object nonExistingObject"
  alert(exception);         // gives "ToiInvalidArgumentException: Unknown object nonExistingObject"
}

The type of exception caught can be determined using the instanceof operator, like so:

try {
  // TOI call
} catch (exception) {
  if (exception instanceof toi.ToiInvalidArgumentException) {
    ...
  } else if (exception instanceof toi.ToiOperationNotSupportedException) {
    ...
  }
  ...
}

It's possible to tell TOI exceptions apart from non-TOI exceptions by checking if the exception is an instanceof the base type toi.ToiException

try {
  // TOI call
} catch (exception) {
  if (exception instanceof toi.ToiException) {
    ...
  } else {
    throw exception;
  }
}

A comparison between TOI2/JS and TOI3/JS exceptions

Exceptions in TOI3/JS work slightly different from how they worked in TOI2/JS. They are somewhat easier to use now and work more like how JavaScript programmers expect them to.

try {
  // TOI call
} catch (rawException) {
  var exception = toi.utils.convertToiException(rawException);
  ...
}

try {
  // TOI call
} catch (exception) {
  ...
}

if (exception instanceof TToiInvalidArgumentException) {

if (exception instanceof toi.ToiInvalidArgumentException) {

if (e.code == 603) {

if (e instanceof toi.ToiInvalidArgumentException) {

if (e.name == "ToiInvalidArgumentException") {