aboutsummaryrefslogtreecommitdiffstats
path: root/lib/orber/doc/src/ch_exceptions.xml
diff options
context:
space:
mode:
Diffstat (limited to 'lib/orber/doc/src/ch_exceptions.xml')
-rw-r--r--lib/orber/doc/src/ch_exceptions.xml237
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>
+