From 84adefa331c4159d432d22840663c38f155cd4c1 Mon Sep 17 00:00:00 2001 From: Erlang/OTP Date: Fri, 20 Nov 2009 14:54:40 +0000 Subject: The R13B03 release. --- lib/orber/doc/src/interceptors.xml | 283 +++++++++++++++++++++++++++++++++++++ 1 file changed, 283 insertions(+) create mode 100644 lib/orber/doc/src/interceptors.xml (limited to 'lib/orber/doc/src/interceptors.xml') 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 @@ + + + + +
+ + 20012009 + Ericsson AB. All Rights Reserved. + + + 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. + + + + interceptors + + + + + + 1999-09-03 + A +
+ interceptors + Describe the functions which must be exported by any supplied Orber native interceptor. + +

This module contains the mandatory functions for user supplied native + interceptors and their intended behavior. See also the User's Guide.

+ +

Using Interceptors 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.

+ + +

It is possible to alter the Data, Bin and Args + parameter for the in_reply and out_reply, + in_reply_encoded, in_request_encoded, + out_reply_encoded and out_request_encoded, + in_request and out_request respectively. But, + if it is done incorrectly, the consequences can be serious.

+ + +

The Extra 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.

+ + +

The Ref parameter is set to 'undefined' by Orber when calling + new_in_connection or new_out_connection using + the first interceptor. The user supplied interceptor may set NewRef + to any Erlang term. If an interceptor change this parameter it will be + passed on to the next interceptor in the list uninterpreted.

+ + + + + new_in_connection(Ref, PeerHost, PeerPort) -> NewRef + new_in_connection(Ref, PeerHost, PeerPort, SocketHost, SocketPort) -> NewRef + Invoke when a new client ORB wants to setup a connection + + Ref = term() | undefined + PeerHost = SocketHost = string(), e.g., "myHost@myServer" or "192.0.0.10" + PeerPort = SocketPort = integer() + NewRef = term() | {'EXIT', Reason} + + +

When a new connection is requested by a client side ORB this operation + is invoked. If more than one interceptor is supplied, e.g., + {native, ['myInterceptor1', 'myInterceptor2']}, the return value + from 'myInterceptor1' is passed to 'myInterceptor2' as Ref. + Initially, Orber uses the atom 'undefined' as Ref 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 Ref parameter can, for example, be used as a unique + identifier to mnesia or ets where information/restrictions for + this connection is stored.

+

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.

+

If, for some reason, we do not allow the client ORB to connect + simply invoke exit(Reason).

+ + + + new_out_connection(Ref, PeerHost, PeerPort) -> NewRef + new_out_connection(Ref, PeerHost, PeerPort, SocketHost, SocketPort) -> NewRef + Invoke when setting up a new connection to a server side ORB + + Ref = term() | undefined + PeerHost = SocketHost = string(), e.g., "myHost@myServer" or "192.0.0.10" + PeerPort = SocketPort = integer() + NewRef = term() | {'EXIT', Reason} + + +

When a new connection is set up this function is invoked. Behaves + just like new_in_connection; 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.

+ + + + closed_in_connection(Ref) -> NewRef + Invoke when an existing connection to a client side ORB have been terminated + + Ref = term() + NewRef = term() + + +

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.

+

The input parameter Ref is the return value from + new_in_connection/3.

+ + + + closed_out_connection(Ref) -> NewRef + Invoke when an existing connection to a server side ORB have been terminated + + Ref = term() + NewRef = term() + + +

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.

+

The input parameter Ref is the return value from + new_out_connection/3.

+ + + + in_reply(Ref, Obj, Ctx, Op, Data, Extra) -> Reply + Invoke when replies arrives at the client side ORB + + Ref = term() + Obj = #objref + Ctx = [#'IOP_ServiceContext'{}] + Op = atom() + Data = [Result, OutParameter1, ..., OutPramaterN] + Reply = {NewData, NewExtra} + + +

When replies are delivered from the server side ORB to the client side + ORB this operation is invoked. The Data 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 out or inout in + the IDL-specification.

+ + + + in_reply_encoded(Ref, Obj, Ctx, Op, Bin, Extra) -> Reply + Invoke when replies arrives at the client side ORB with undecoded reply body + + Ref = term() + Obj = #objref + Ctx = [#'IOP_ServiceContext'{}] + Op = atom() + Bin = #binary + Reply = {NewBin, NewExtra} + + +

When replies are delivered from the server side ORB to the client side + ORB this operation is invoked. The Bin parameter is the reply + body still uncoded.

+ + + + in_request(Ref, Obj, Ctx, Op, Args, Extra) -> Reply + Invoke when requests arrive at the server side ORB + + Ref = term() + Obj = #objref + Ctx = [#'IOP_ServiceContext'{}] + Op = atom() + Args = [Argument] - defined in the IDL-specification + Reply = {NewArgs, NewExtra} + + +

When a new request arrives at the server side ORB this operation is + invoked.

+ + + + in_request_encoded(Ref, Obj, Ctx, Op, Bin, Extra) -> Reply + Invoke when requests arrive at the server side ORB with undecoded request body + + Ref = term() + Obj = #objref + Ctx = [#'IOP_ServiceContext'{}] + Op = atom() + Bin = #binary + Reply = {NewBin, NewExtra} + + +

When a new request arrives at the server side ORB this operation is + invoked before decoding the request body.

+ + + + out_reply(Ref, Obj, Ctx, Op, Data, Extra) -> Reply + Invoke after the target object replied + + Ref = term() + Obj = #objref + Ctx = [#'IOP_ServiceContext'{}] + Op = atom() + Data = [Result, OutParameter1, ..., OutPramaterN] + Reply = {NewData, NewExtra} + + +

After the target object have been invoked this operation is invoked + with the result. The Data 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 out or inout in + the IDL-specification.

+ + + + out_reply_encoded(Ref, Obj, Ctx, Op, Bin, Extra) -> Reply + Invoke after the target object replied with the reply encoded + + Ref = term() + Obj = #objref + Ctx = [#'IOP_ServiceContext'{}] + Op = atom() + Bin = #binary + Reply = {NewBin, NewExtra} + + +

This operation is similar to out_reply; the only difference is + that the reply body have been encoded.

+ + + + out_request(Ref, Obj, Ctx, Op, Args, Extra) -> Reply + Invoke on the client side ORB before encoding and sending the request + + Ref = term() + Obj = #objref + Ctx = [#'IOP_ServiceContext'{}] + Op = atom() + Args = [Argument] - defined in the IDL-specification + Reply = {NewArgs, NewExtra} + + +

Before a request is sent to the server side ORB, out_request is + invoked.

+ + + + out_request_encoded(Ref, Obj, Ctx, Op, Bin, Extra) -> Reply + Invoke on the client side ORB before sending the request + + Ref = term() + Obj = #objref + Ctx = [#'IOP_ServiceContext'{}] + Op = atom() + Bin = #binary + Reply = {NewBin, NewExtra} + + +

This operation is similar to out_request; the only + difference is that the request body have been encoded.

+ + + + + + -- cgit v1.2.3