diff options
Diffstat (limited to 'lib/orber/doc/src/ch_exceptions.xml')
| -rw-r--r-- | lib/orber/doc/src/ch_exceptions.xml | 237 |
1 files changed, 237 insertions, 0 deletions
diff --git a/lib/orber/doc/src/ch_exceptions.xml b/lib/orber/doc/src/ch_exceptions.xml new file mode 100644 index 0000000000..a8fb98fe1e --- /dev/null +++ b/lib/orber/doc/src/ch_exceptions.xml @@ -0,0 +1,237 @@ +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE chapter SYSTEM "chapter.dtd"> + +<chapter> + <header> + <copyright> + <year>2001</year><year>2009</year> + <holder>Ericsson AB. All Rights Reserved.</holder> + </copyright> + <legalnotice> + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + </legalnotice> + + <title>CORBA System and User Defined Exceptions</title> + <prepared></prepared> + <docno></docno> + <date>2000-12-19</date> + <rev></rev> + <file>ch_exceptions.xml</file> + </header> + + <section> + <title>System Exceptions</title> + <p><c>Orber</c>, or any other <c>ORB</c>, may raise a <c>System Exceptions</c>. + These exceptions contain status- and minor-fields and may not appear in the + operations raises exception IDL-definition.</p> + + <section> + <title>Status Field</title> + <p>The status field indicates if the request was completed or not and will be + assigned one of the following Erlang atoms:</p> + <table> + <row> + <cell align="center" valign="middle"><em>Status</em></cell> + <cell align="center" valign="middle"><em>Description</em></cell> + </row> + <row> + <cell align="left" valign="middle">'COMPLETED_YES'</cell> + <cell align="left" valign="middle">The operation was invoked on the target object but an error occurred after the object replied. This occur, for example, if a server replies but Orber is not able to marshal and send the reply to the client ORB.</cell> + </row> + <row> + <cell align="left" valign="middle">'COMPLETED_NO'</cell> + <cell align="left" valign="middle">Orber failed to invoke the operation on the target object. This occur, for example, if the object no longer exists.</cell> + </row> + <row> + <cell align="left" valign="middle">'COMPLETED_MAYBE'</cell> + <cell align="left" valign="middle">Orber invoked the operation on the target object but an error occurred and it is impossible to decide if the request really reached the object or not.</cell> + </row> + <tcaption>System Exceptions Status</tcaption> + </table> + </section> + + <section> + <title>Minor Field</title> + <p>The minor field contains an integer (VMCID), which is related to a more + specific reason why an invocation failed. The function + <c>orber:exception_info/1</c> can be used to map the minor code to a string. + Note, for VMCID:s not assigned by the OMG or Orber, the documentation + for that particular ORB must be consulted.</p> + </section> + + <section> + <title>Supported System Exceptions</title> + <p>The OMG CORBA specification defines the following exceptions:</p> + <list type="bulleted"> + <item><em>'BAD_CONTEXT'</em> - if a request does not contain a correct + context this exception is raised.</item> + <item><em>'BAD_INV_ORDER'</em> - this exception indicates that operations + has been invoked operations in the wrong order, which would cause, + for example, a dead-lock.</item> + <item><em>'BAD_OPERATION'</em> - raised if the target object exists, but + that the invoked operation is not supported.</item> + <item><em>'BAD_PARAM'</em> - is thrown if, for example, a parameter is out + of range or otherwise considered illegal.</item> + <item><em>'BAD_TYPECODE'</em> - if illegal type code is passed, for example, + encapsulated in an any data type the <c>'BAD_TYPECODE'</c> exception + will be raised.</item> + <item><em>'BAD_QOS'</em> - raised whenever an object cannot support the + required quality of service.</item> + <item><em>'CODESET_INCOMPATIBLE'</em> - raised if two ORB's cannot + communicate due to different representation of, for example, + <c>char</c> and/or <c>wchar</c>.</item> + <item><em>'COMM_FAILURE'</em> - raised if an ORB is unable to setup + communication or it is lost while an operation is in progress.</item> + <item><em>'DATA_CONVERSION'</em> - raised if an ORB cannot convert data + received to the native representation. See also the + <c>'CODESET_INCOMPATIBLE'</c> exception.</item> + <item><em>'FREE_MEM'</em> - the ORB failed to free dynamic memory and + failed.</item> + <item><em>'IMP_LIMIT'</em> - an implementation limit was exceeded in the + ORB at run time. A object factory may, for example, limit the + number of object clients are allowed to create.</item> + <item><em>'INTERNAL'</em> - an internal failure occurred in an ORB, which + is unrecognized. You may consider contacting the ORB providers + support.</item> + <item><em>'INTF_REPOS'</em> - the ORB was not able to reach the interface + repository, or some other failure relating to the interface + repository is detected.</item> + <item><em>'INITIALIZE'</em> - the ORB initialization failed due to, for + example, network or configuration error.</item> + <item><em>'INVALID_TRANSACTION'</em> - is raised if the request carried an + invalid transaction context.</item> + <item><em>'INV_FLAG'</em> - an invalid flag was passed to an operation, + which caused, for example, a connection to be closed.</item> + <item><em>'INV_IDENT'</em> - this exception indicates that an IDL + identifier is incorrect.</item> + <item><em>'INV_OBJREF'</em> - this exception is raised if an object + reference is malformed or a nil reference (see + also corba:create_nil_objref/0).</item> + <item><em>'INV_POLICY'</em> - the invocation cannot be made due to an + incompatibility between policy overrides that apply to the + particular invocation.</item> + <item><em>'MARSHAL'</em> - this exception may be raised by the client- or + server-side when either ORB is unable to marshal/unmarshal requests or + replies.</item> + <item><em>'NO_IMPLEMENT'</em> - if the operation exists but no implementation + exists, this exception is raised.</item> + <item><em>'NO_MEMORY'</em> - the ORB has run out of memory.</item> + <item><em>'NO_PERMISSION'</em> - the caller has insufficient privileges, + such as, for example, bad <c>SSL</c> certificate.</item> + <item><em>'NO_RESOURCES'</em> - a general platform resource limit + exceeded.</item> + <item><em>'NO_RESPONSE'</em> - no response available of a deferred + synchronous request.</item> + <item><em>'OBJ_ADAPTER'</em> - indicates administrative mismatch; the object + adapter is not able to associate an object with the implementation + repository.</item> + <item><em>'OBJECT_NOT_EXIST'</em> - the object have been disposed or + terminated; clients should remove all copies of the object reference + and initiate desired recovery process.</item> + <item><em>'PERSIST_STORE'</em> - the ORB was not able to establish a + connection to its persistent storage or data contained in the + the storage is corrupted.</item> + <item><em>'REBIND'</em> - a request resulted in, for example, a + <c>'LOCATION_FORWARD'</c> message; if the policies are incompatible + this exception is raised.</item> + <item><em>'TIMEOUT'</em> - raised if a request fail to complete within the + given time-limit.</item> + <item><em>'TRANSACTION_MODE'</em> - a transaction policy mismatch detected.</item> + <item><em>'TRANSACTION_REQUIRED'</em> - a transaction is required for the + invoked operation but the request contained no transaction context.</item> + <item><em>'TRANSACTION_ROLLEDBACK'</em> - the transaction associated with + the request has already been rolled back or will be.</item> + <item><em>'TRANSACTION_UNAVAILABLE'</em> - no transaction context can be + supplied since the ORB is unable to contact the Transaction + Service.</item> + <item><em>'TRANSIENT'</em> - the ORB could not determine the current status + of an object since it could not be reached. The error may be + temporary.</item> + <item><em>'UNKNOWN'</em> - is thrown if an implementation throws a + non-CORBA, or unrecognized, exception.</item> + </list> + </section> + </section> + + <section> + <title>User Defined Exceptions</title> + <p>User exceptions is defined in IDL-files and is listed in operations raises + exception listing. For example, if we have the following IDL code:</p> + <code type="none"> +module MyModule { + + exception MyException {}; + exception MyExceptionMsg { string ExtraInfo; }; + + interface MyInterface { + + void foo() + raises(MyException); + + void bar() + raises(MyException, MyExceptionMsg); + + void baz(); + }; +}; + </code> + </section> + + <section> + <title>Throwing Exceptions</title> + <p>To be able to raise <c>MyException</c> or <c>MyExceptionMsg</c> exceptions, + the generated <c>MyModule.hrl</c> must be included, and typical usage is:</p> + <code type="none"> +-module('MyModule_MyInterface_impl'). +-include("MyModule.hrl"). + +bar(State) -> + case TestingSomething of + ok -> + {reply, ok, State}; + {error, Reason} when list(Reason) -> + corba:raise(#'MyModule_MyExceptionMsg'{'ExtraInfo' = Reason}); + error -> + corba:raise(#'MyModule_MyException'{}) + end. + </code> + </section> + + <section> + <title>Catching Exceptions</title> + <p>Depending on which operation we invoke we must be able to handle:</p> + <list type="bulleted"> + <item>foo - <c>MyException</c> or a system exception.</item> + <item>bar - <c>MyException</c>, <c>MyExceptionMsg</c> or a system + exception.</item> + <item>baz - a system exception.</item> + </list> + <p>Catching and matching exceptions can bee done in different ways:</p> + <code type="none"> + case catch 'MyModule_MyInterface':bar(MIReference) of + ok -> + %% The operation raised no exception. + ok; + {'EXCEPTION', #'MyModule_MyExceptionMsg'{'ExtraInfo' = Reason}} -> + %% If we want to log the Reason we must extract 'ExtraInfo'. + error_logger:error_msg("Operation 'bar' raised: ~p~n", [Reason]), + ... do something ...; + {'EXCEPTION', E} when record(E, 'OBJECT_NOT_EXIST') -> + ... do something ...; + {'EXCEPTION', E} -> + ... do something ... + end. + </code> + </section> +</chapter> + |