aboutsummaryrefslogtreecommitdiffstats
path: root/lib/orber/doc/src/interceptors.xml
diff options
context:
space:
mode:
authorErlang/OTP <[email protected]>2009-11-20 14:54:40 +0000
committerErlang/OTP <[email protected]>2009-11-20 14:54:40 +0000
commit84adefa331c4159d432d22840663c38f155cd4c1 (patch)
treebff9a9c66adda4df2106dfd0e5c053ab182a12bd /lib/orber/doc/src/interceptors.xml
downloadotp-84adefa331c4159d432d22840663c38f155cd4c1.tar.gz
otp-84adefa331c4159d432d22840663c38f155cd4c1.tar.bz2
otp-84adefa331c4159d432d22840663c38f155cd4c1.zip
The R13B03 release.OTP_R13B03
Diffstat (limited to 'lib/orber/doc/src/interceptors.xml')
-rw-r--r--lib/orber/doc/src/interceptors.xml283
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>
+