The R13B03 release.OTP_R13B03

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>
+