Difference between revisions of "Documentation/DevGuide/WritingUNO/Defining an Exception"

Revision as of 22:26, 20 March 2008

An exception type is a type that contains information about an error . If an operation detects an error that halts the normal process flow, it must raise an exception and send information about the error back to the caller through an exception object. This causes the caller to interrupt its normal program flow as well and react according to the information received in the exception object. For details about exceptions and their implementation, refer to the chapters UNO Language Bindings and Exception Handling.

There are a number of exceptions to use. The exceptions should be sufficient in many cases, because a message string can be sent back to the caller. When defining an exception, do it in such a way that other developers could reuse it in their contexts.

An exception declaration opens with the keyword exception, gives an identifier for the new exception type and has an exception body in braces. It is terminated by a semicolon. The exception body contains a list of exception member declarations that are defined by a known type and an identifier for the exception member. The member declarations must end with a semicolon, as well.

Exceptions must be based on com.sun.star.uno.Exception or com.sun.star.uno.RuntimeException, directly or indirectly through derived exceptions of these two exceptions. com.sun.star.uno.Exceptions can only be thrown in operations specified to raise them while com.sun.star.uno.RuntimeExceptions can always occur. Inheritance is expressed by a colon :, followed by the full name of the parent type.

  // com.sun.star.uno.Exception is the base exception for all exceptions
  exception Exception {
      string Message;
      XInterface Context;
  };
 
  // com.sun.star.lang.IllegalArgumentException tells the caller which 
  // argument caused trouble
  exception IllegalArgumentException: com::sun::star::uno::Exception
  { 
      /** identifies the position of the illegal argument. 
          <p>This field is -1 if the position is not known.</p>
       */
      short ArgumentPosition; 
 
  }; 
 
  // com.sun.star.uno.RuntimeException is the base exception for serious errors
  // usually caused by programming errors or problems with the runtime environment
  exception RuntimeException : com::sun::star::uno::Exception {
  };
 
  // com.sun.star.uno.SecurityException is a more specific RuntimeException 
 
  exception SecurityException : com::sun::star::uno::RuntimeException {
  };