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) {
  console.log(exception.name);    // gives "ToiInvalidArgumentException"
  console.log(exception.message); // gives "Unknown object nonExistingObject"
  console.log(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;
  }
}

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

if (exception instanceof toi.ToiInvalidArgumentException) {
  ...
}

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