The R13B03 release.OTP_R13B03

1 files changed, 283 insertions, 0 deletions

diff --git a/lib/orber/doc/src/interceptors.xml b/lib/orber/doc/src/interceptors.xml
new file mode 100644
index 0000000000..8d1f97d5a2
--- /dev/null
+++ b/lib/orber/doc/src/interceptors.xml
@@ -0,0 +1,283 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE erlref SYSTEM "erlref.dtd">
+
+<erlref>
+  <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>interceptors</title>
+    <prepared></prepared>
+    <responsible></responsible>
+    <docno></docno>
+    <approved></approved>
+    <checked></checked>
+    <date>1999-09-03</date>
+    <rev>A</rev>
+  </header>
+  <module>interceptors</module>
+  <modulesummary>Describe the functions which must be exported by any supplied Orber native interceptor.</modulesummary>
+  <description>
+    <p>This module contains the mandatory functions for user supplied native
+      interceptors and their intended behavior. See also the User's Guide.</p>
+    <warning>
+      <p>Using <c>Interceptors</c> may reduce the through-put significantly
+        if the supplied interceptors invoke expensive operations. Hence, 
+        one should always supply interceptors which cause as little overhead
+        as possible.</p>
+    </warning>
+    <warning>
+      <p>It is possible to alter the <c>Data</c>, <c>Bin</c> and <c>Args</c>
+        parameter for the <c>in_reply</c> and <c>out_reply</c>, 
+        <c>in_reply_encoded</c>, <c>in_request_encoded</c>, 
+        <c>out_reply_encoded</c> and <c>out_request_encoded</c>,
+        <c>in_request</c> and <c>out_request</c> respectively. But,
+        if it is done incorrectly, the consequences can be serious.</p>
+    </warning>
+    <note>
+      <p>The <c>Extra</c> parameter is set to 'undefined' by Orber when calling
+        the first interceptor and may be set to any Erlang term.  If an
+        interceptor change this parameter it will be passed on to the next
+        interceptor in the list uninterpreted.</p>
+    </note>
+    <note>
+      <p>The <c>Ref</c> parameter is set to 'undefined' by Orber when calling
+        <c>new_in_connection</c> or <c>new_out_connection</c> using
+        the first interceptor. The user supplied interceptor may set <c>NewRef</c>
+        to any Erlang term.  If an interceptor change this parameter it will be
+        passed on to the next interceptor in the list uninterpreted.</p>
+    </note>
+  </description>
+  <funcs>
+    <func>
+      <name>new_in_connection(Ref, PeerHost, PeerPort) -> NewRef</name>
+      <name>new_in_connection(Ref, PeerHost, PeerPort, SocketHost, SocketPort) -> NewRef</name>
+      <fsummary>Invoke when a new client ORB wants to setup a connection</fsummary>
+      <type>
+        <v>Ref    = term() | undefined</v>
+        <v>PeerHost = SocketHost = string(), e.g., "myHost@myServer" or "192.0.0.10"</v>
+        <v>PeerPort = SocketPort = integer()</v>
+        <v>NewRef = term() | {'EXIT', Reason}</v>
+      </type>
+      <desc>
+        <p>When a new connection is requested by a client side ORB this operation
+          is invoked. If more than one interceptor is supplied, e.g., 
+          <c>{native, ['myInterceptor1', 'myInterceptor2']}</c>, the return value
+          from 'myInterceptor1' is passed to 'myInterceptor2' as <c>Ref</c>.
+          Initially, Orber uses the atom 'undefined' as <c>Ref</c> parameter
+          when calling the first interceptor. The return value from the last
+          interceptor, in the example above 'myInterceptor2', is passed
+          to all other functions exported by the interceptors. Hence,
+          the <c>Ref</c> parameter can, for example, be used as a unique 
+          identifier to mnesia or ets where information/restrictions for
+          this connection is stored.</p>
+        <p>The PeerHost and PeerPort variables supplied data of
+          the client ORB which requested a new connection. SocketHost 
+          and SocketPort are the local interface and port the client
+          connected to.</p>
+        <p>If, for some reason, we do not allow the client ORB to connect
+          simply invoke <c>exit(Reason)</c>.</p>
+      </desc>
+    </func>
+    <func>
+      <name>new_out_connection(Ref, PeerHost, PeerPort) -> NewRef</name>
+      <name>new_out_connection(Ref, PeerHost, PeerPort, SocketHost, SocketPort) -> NewRef</name>
+      <fsummary>Invoke when setting up a new connection to a server side  ORB</fsummary>
+      <type>
+        <v>Ref    = term() | undefined</v>
+        <v>PeerHost = SocketHost = string(), e.g., "myHost@myServer" or "192.0.0.10"</v>
+        <v>PeerPort = SocketPort = integer()</v>
+        <v>NewRef = term() | {'EXIT', Reason}</v>
+      </type>
+      <desc>
+        <p>When a new connection is set up this function is invoked. Behaves
+          just like <c>new_in_connection</c>; the only difference is that
+          the PeerHost and PeerPort variables identifies the target ORB's bootstrap
+          data and SocketHost and SocketPort are the local interface and port
+          the client ORB connected via.</p>
+      </desc>
+    </func>
+    <func>
+      <name>closed_in_connection(Ref) -> NewRef</name>
+      <fsummary>Invoke when an existing connection to a client side ORB have been terminated</fsummary>
+      <type>
+        <v>Ref    = term()</v>
+        <v>NewRef = term()</v>
+      </type>
+      <desc>
+        <p>When an existing connection is terminated this operation is invoked.
+          The main purpose of this function is to make it possible for a user
+          to clean up all data associated with the associated connection.</p>
+        <p>The input parameter <c>Ref</c> is the return value from 
+          <c>new_in_connection/3</c>.</p>
+      </desc>
+    </func>
+    <func>
+      <name>closed_out_connection(Ref) -> NewRef</name>
+      <fsummary>Invoke when an existing connection to a server side ORB have been terminated</fsummary>
+      <type>
+        <v>Ref    = term()</v>
+        <v>NewRef = term()</v>
+      </type>
+      <desc>
+        <p>When an existing connection is terminated this operation is invoked.
+          The main purpose of this function is to make it possible for a user
+          to clean up all data associated with the associated connection.</p>
+        <p>The input parameter <c>Ref</c> is the return value from 
+          <c>new_out_connection/3</c>.</p>
+      </desc>
+    </func>
+    <func>
+      <name>in_reply(Ref, Obj, Ctx, Op, Data, Extra) -> Reply</name>
+      <fsummary>Invoke when replies arrives at the client side ORB</fsummary>
+      <type>
+        <v>Ref   = term()</v>
+        <v>Obj   = #objref</v>
+        <v>Ctx   = [#'IOP_ServiceContext'{}]</v>
+        <v>Op    = atom()</v>
+        <v>Data  = [Result, OutParameter1, ..., OutPramaterN]</v>
+        <v>Reply = {NewData, NewExtra}</v>
+      </type>
+      <desc>
+        <p>When replies are delivered from the server side ORB to the client side
+          ORB this operation is invoked. The <c>Data</c> parameter is a list in which
+          the first element is the return value value from the target object and
+          the rest is a all parameters defined as <c>out</c> or <c>inout</c> in
+          the IDL-specification.</p>
+      </desc>
+    </func>
+    <func>
+      <name>in_reply_encoded(Ref, Obj, Ctx, Op, Bin, Extra) -> Reply</name>
+      <fsummary>Invoke when replies arrives at the client side ORB with undecoded reply body</fsummary>
+      <type>
+        <v>Ref   = term()</v>
+        <v>Obj   = #objref</v>
+        <v>Ctx   = [#'IOP_ServiceContext'{}]</v>
+        <v>Op    = atom()</v>
+        <v>Bin   = #binary</v>
+        <v>Reply = {NewBin, NewExtra}</v>
+      </type>
+      <desc>
+        <p>When replies are delivered from the server side ORB to the client side
+          ORB this operation is invoked. The <c>Bin</c> parameter is the reply 
+          body still uncoded.</p>
+      </desc>
+    </func>
+    <func>
+      <name>in_request(Ref, Obj, Ctx, Op, Args, Extra) -> Reply</name>
+      <fsummary>Invoke when requests arrive at the server side ORB</fsummary>
+      <type>
+        <v>Ref   = term()</v>
+        <v>Obj   = #objref</v>
+        <v>Ctx   = [#'IOP_ServiceContext'{}]</v>
+        <v>Op    = atom()</v>
+        <v>Args  = [Argument] - defined in the IDL-specification</v>
+        <v>Reply = {NewArgs, NewExtra}</v>
+      </type>
+      <desc>
+        <p>When a new request arrives at the server side ORB this operation is 
+          invoked.</p>
+      </desc>
+    </func>
+    <func>
+      <name>in_request_encoded(Ref, Obj, Ctx, Op, Bin, Extra) -> Reply</name>
+      <fsummary>Invoke when requests arrive at the server side ORB with undecoded request body</fsummary>
+      <type>
+        <v>Ref   = term()</v>
+        <v>Obj   = #objref</v>
+        <v>Ctx   = [#'IOP_ServiceContext'{}]</v>
+        <v>Op    = atom()</v>
+        <v>Bin   = #binary</v>
+        <v>Reply = {NewBin, NewExtra}</v>
+      </type>
+      <desc>
+        <p>When a new request arrives at the server side ORB this operation is 
+          invoked before decoding the request body.</p>
+      </desc>
+    </func>
+    <func>
+      <name>out_reply(Ref, Obj, Ctx, Op, Data, Extra) -> Reply</name>
+      <fsummary>Invoke after the target object replied</fsummary>
+      <type>
+        <v>Ref   = term()</v>
+        <v>Obj   = #objref</v>
+        <v>Ctx   = [#'IOP_ServiceContext'{}]</v>
+        <v>Op    = atom()</v>
+        <v>Data  = [Result, OutParameter1, ..., OutPramaterN]</v>
+        <v>Reply = {NewData, NewExtra}</v>
+      </type>
+      <desc>
+        <p>After the target object have been invoked this operation is invoked
+          with the result. The <c>Data</c> parameter is a list in which
+          the first element is the return value value from the target object and
+          the rest is a all parameters defined as <c>out</c> or <c>inout</c> in
+          the IDL-specification.</p>
+      </desc>
+    </func>
+    <func>
+      <name>out_reply_encoded(Ref, Obj, Ctx, Op, Bin, Extra) -> Reply</name>
+      <fsummary>Invoke after the target object replied with the reply  encoded</fsummary>
+      <type>
+        <v>Ref   = term()</v>
+        <v>Obj   = #objref</v>
+        <v>Ctx   = [#'IOP_ServiceContext'{}]</v>
+        <v>Op    = atom()</v>
+        <v>Bin   = #binary</v>
+        <v>Reply = {NewBin, NewExtra}</v>
+      </type>
+      <desc>
+        <p>This operation is similar to <c>out_reply</c>; the only difference is
+          that the reply body have been encoded.</p>
+      </desc>
+    </func>
+    <func>
+      <name>out_request(Ref, Obj, Ctx, Op, Args, Extra) -> Reply</name>
+      <fsummary>Invoke on the client side ORB before encoding and sending the request</fsummary>
+      <type>
+        <v>Ref   = term()</v>
+        <v>Obj   = #objref</v>
+        <v>Ctx   = [#'IOP_ServiceContext'{}]</v>
+        <v>Op    = atom()</v>
+        <v>Args  = [Argument] - defined in the IDL-specification</v>
+        <v>Reply = {NewArgs, NewExtra}</v>
+      </type>
+      <desc>
+        <p>Before a request is sent to the server side ORB, <c>out_request</c> is
+          invoked.</p>
+      </desc>
+    </func>
+    <func>
+      <name>out_request_encoded(Ref, Obj, Ctx, Op, Bin, Extra) -> Reply</name>
+      <fsummary>Invoke on the client side ORB before sending the request</fsummary>
+      <type>
+        <v>Ref   = term()</v>
+        <v>Obj   = #objref</v>
+        <v>Ctx   = [#'IOP_ServiceContext'{}]</v>
+        <v>Op    = atom()</v>
+        <v>Bin   = #binary</v>
+        <v>Reply = {NewBin, NewExtra}</v>
+      </type>
+      <desc>
+        <p>This operation is similar to <c>out_request</c>; the only
+          difference is that the request body have been encoded.</p>
+      </desc>
+    </func>
+  </funcs>
+  
+</erlref>
+