IlsMvEndPoint

Category

Dynamic view-related class (server side and component side)

Inheritance Path

IlsMvEndPoint

Description

This class is the base class for any component connected to a dynamic view server and for the interface of these components as handled by the server.

Each time a connection is established between a component and a view server, an instance of IlsMvComponent or of a derived class is built on the component side and an instance of IlsMvComponentItf or of a derived class is built on the server side. This means that any connection is handled at both end points by an object derived from the class IlsMvEndPoint.

See the functions IlsMvComponent::Narrow and IlsMvComponentItf::Narrow to learn how to downcast an IlsMvEndPoint object safely.

The class IlsMvEndPoint defines the basic API that enables interaction between a server and a component. Most of this API is used internally by the component or by the server. However, the API for callback functions can be accessed directly by the user on this class.

IlsMvEndPoint controls how incoming and outgoing requests are executed both on the component side and on the server side. This class ensures a consistent behavior, whether the component and the server are distributed or linked in the same process.

IlsMvEndPoint also implements the trace mode for each server/component connection.

Libraries

Header File

#include <ilserver/mvendpt.h>

Synopsis

class IlsMvEndPoint

{

public:

Suppression

virtual void suppress();

Accessors

const IlsString& getPeerHost() const;

const IlsString& getPeerName() const;

IlsBoolean isComponent()const;

IlsBoolean isLinked()const;

Connection Control

IlsBoolean disconnect();

virtual void onConnect();

virtual void onDisconnect();

static IlsMvEndPoint* GetInteractor();

virtual void addConnectionListener(ConnectionListener*);

virtual void removeConnectionListener(ConnectionListener*);

virtual IlsConnectionStatus testConnection

(IlsTime* timeout = 0);

Callbacks to Member Functions

IlsBoolean execAsyncObjectCallback

(const IlsMvRef& ref,

const IlsString& funNm,

IlsMvValue* args,

IlsCbArgNb nbArgs,

IlsBoolean inTrans=IlsTrue,

IlsBoolean freeArgs=IlsFalse);

IlsBoolean execSyncObjectCallback

(const IlsMvRef& ref,

const IlsString& funNm,

IlsMvValue* args,

IlsCbArgNb nbArgs,

IlsMvValue& result,

IlsBoolean freeArgs=IlsFalse);

IlsBoolean execDuplexObjectCallback

(const IlsMvRef& ref,

const IlsString& funNm,

IlsMvValue* args,

IlsCbArgNb nbArgs,

const IlsString& duplexFunNm,

IlsMvValue* duplexArgs=0,

IlsCbArgNb duplexNbArgs=0,

IlsCbArgNb resultIndex=0,

IlsBoolean inTrans=IlsTrue,

IlsBoolean freeArgs = IlsFalse);

Callbacks to Global Functions

IlsBoolean execAsyncGlobalCallback

(const IlsString& funNm,

IlsMvValue* args,

IlsCbArgNb nbArgs,

IlsBoolean inTrans=IlsTrue,

IlsBoolean freeArgs=IlsFalse);

IlsBoolean execSyncGlobalCallback

(const IlsString& funNm,

IlsMvValue* args,

IlsCbArgNb nbArgs,

IlsMvValue& result,

IlsBoolean freeArgs=IlsFalse);

IlsBoolean execDuplexGlobalCallback

(const IlsString& funNm,

IlsMvValue* args,

IlsCbArgNb nbArgs,

const IlsString& duplexFunNm,

IlsMvValue* duplexArgs=0,

IlsCbArgNb duplexNbArgs=0,

IlsCbArgNb resultIndex=0,

IlsBoolean inTrans=IlsTrue,

IlsBoolean freeArgs = IlsFalse);

Loading View Specification

void loadViewSpec(const IlsString& fileOrString,

IlsBoolean isString,

IlsBoolean useXmlParser,

IlsBoolean isSync = IlsFalse);

Request Input/Output Control

IlsBoolean setEncoder(IlsMsgEncoder encoding);

IlsBoolean setDecoder(IlsMsgDecoder decoding);

IlsMsgEncoder getEncoder() const;

IlsMsgDecoder getDecoder() const;

Thread Control

static void SetMT();

IlsThread* startSendThread();

IlsBoolean stopSendThread(IlsBoolean flush=IlsFalse);

IlsBoolean isSendingThread();

Trace

void trace(int=TRACE_TRANS);

IlsBoolean isTraced(int=TRACE_TRANS);

int getTraceType()const;

static void Trace(int=TRACE_TRANS);

static IlsBoolean IsTraced(int=TRACE_TRANS);

static int GetTraceType();

};

Member Functions

Suppression

[virtual] void suppress();

Call this virtual member function instead of the destructor if you want to delete an instance of IlsMvEndPoint. This function:

Closes the connection between the server and the component cleanly.

Marks the object as to be deleted. The object will be actually destroyed when no more incoming or outgoing requests are being processed by this object.

Accessors

const IlsString& getPeerHost()const;

In case of a distributed component-to-server connection, this member function returns the host name of the connected process. Otherwise, it returns the null constant IlsString::Null.

const IlsString& getPeerName() const;

This member function returns the name assigned to the process at the peer end point of the connection (by a call to the static member function IlsMvProcess::SetName). By default, or if the connection is closed, the function returns the null string.

.IlsBoolean isComponent()const;

This member function returns IlsTrue when the object is an instance of IlsMvComponent or of a derived class. Otherwise, it returns IlsFalse.

IlsBoolean isLinked()const;

This member function returns IlsTrue when the component and the server are implemented in the same process. Otherwise, it returns IlsFalse.

Connection Control

IlsBoolean disconnect();

This member function closes the connection between the local end point and its peer end point, and then calls the function onDisconnect. If no connection is established, the function does nothing and returns IlsFalse. Otherwise, it returns IlsTrue.

[virtual] void onConnect();

This virtual member function is called when the connection between the component and the server is established. It has an empty implementation. It can be overridden.

[virtual] void onDisconnect();

This virtual member function is called when the connection between the component and the server is destroyed. This function has an empty implementation. It is overridden in the subclasses IlsMvComponent and IlsMvComponentItf.

[static] IlsMvEndPoint* GetInteractor();

This static member function returns the current interacting component. A current interactor is set when an incoming message is being processed, that is when a callback is executed, or when an notification is processed, or when a component-to-server request is processed. The interactor is:

either an instance of IlsMvComponent (or of a subclass) if the method is called while a message is processed on the component side, or

an instance of IlsMvComponentItf if the method is called dwhile a message is processed on the server side.

If the method is called without any message processing, it returns 0;.

[virtual] void addConnectionListener(ConnectionListener*);

[virtual] void removeConnectionListener(ConnectionListener*);

These virtual member functions respectively add or remove a connection listener.

[virtual] IlsConnectionStatus testConnection(IlsTime* timeout = 0);

This virtual member function can be used from server to component or from component to server to test the underlying connection between two processes. This call performs a synchronous ping to the peer process and waits for an acknowledgement. The timeout parameter controls how long the acknowledgement is expected. The default value is 0 which correspond to an infinite timeout.

This function returns the connection status as a value of the enumerated type IlsConnectionStatus:

CONN_OK if the test has been performed correctly;

CONN_TIMEOUT if the test timed out;

CONN_ERROR if an exception was raised during the test, indicating that the connection is no longer available;

CONN_CLOSED if the connection has already been closed.


Note: This function is implemented only on the MvTCP communication layer and that it may block the invoking process for the duration of the timeout at most if the peer process is not responsive.

If you want to use this function from a separate thread, call the SetMT function to set up the multithread safety of the function.

Callbacks to Member Functions

These callbacks are used to execute functions on objects that are implemented at the end point of the connection.

Synchronous/Asynchronous Callbacks

Callbacks can be asynchronous, synchronous or duplex. A duplex callback is a pair of symmetric asynchronous calls. The result of the original callback is sent back to the caller as an argument to a second callback.

To avoid deadlock problems related to synchronous calls, it is strongly recommended to keep a fully asynchronous interaction protocol between components and servers. This enables you to choose duplex callbacks whenever possible instead of synchronous callbacks. The relevant member functions must have been previously declared to the server model interpreter or to the representation model interpreter by using the macros ILS_MEMBER_FUNCTION for Server-object member functions or ILS_RP_MEMBER_FUNCTION (for representation-object member functions).
See the class IlsModelInterpreter for details.

Callbacks for member functions take a reference to the object that must execute the function as their first parameter.

On the server side, you can obtain such a reference by using the member functions IlsMvView::getCurrentRef or IlsMvView::getReference.

On the component side, each representation object is associated with a reference (see the member function IlsRpObject::getReference). In fact, the present callbacks are wrapped in corresponding callbacks documented with the API of the class IlsRpObject. For example:

IlsRpObject::execAsyncCallback

is a wrapper for

IlsMvEndPoint::execAsyncObjectCallback.

IlsBoolean execAsyncObjectCallback(const IlsMvRef& ref,

const IlsString& funNm,

IlsMvValue* args,

IlsCbArgNb nbArgs,

IlsBoolean inTrans=IlsTrue,

IlsBoolean freeArgs=IlsFalse);

This callback executes an asynchronous call to the function funNm on the object identified by the reference ref. It also takes the following parameters:

The arguments to be passed to the function are stored in the parameter args, which is an array of IlsMvValue objects.

The parameter nbArgs is the size of this array.

The Boolean parameter inTrans indicates whether the callback must be executed using the transaction mechanism or not (see Transaction Control in the IlsMvComponent class description). If this parameter is set to IlsTrue (default value) and no current transaction has been initialized, a new transaction is implicitly created and committed.

The last argument freeArgs indicates whether the argument array must be freed by Rogue Wave Server or not.

If it is set to IlsFalse (default value), the array is copied by Rogue Wave Server to build the request.

If it is set to IlsTrue, the array is directly used in the request and freed by Rogue Wave Server when the request is completed.

If the inTrans parameter is false, the call is performed immediately and the method returns IlsFalse when the callback request cannot be sent, which means that the connection has been closed; otherwise it returns IlsTrue.

If the inTrans parameter is true, the call is batched in the current update transaction and the method returns true.


Note: Because this callback is asynchronous, the IlsTrue return value does not mean that the function funNm has been successfully executed.

IlsBoolean execSyncObjectCallback(const IlsMvRef& ref,

const IlsString& funNm,

IlsMvValue* args,

IlsCbArgNb nbArgs,

IlsMvValue& result,

IlsBoolean freeArgs=IlsFalse);

This callback executes a synchronous call to the callback function funNm on the object identified by the reference ref. It takes the following additional parameters:

The arguments to be passed to the function are stored in the parameter args, an array of IlsMvValue objects.

nbArgs is the size of this array.

The parameter result is a reference assigned by Rogue Wave Server to the result of the member function.

The last argument freeArgs indicates whether the argument array must be freed by Rogue Wave Server or not.

If it is set to IlsFalse (default value), the array is copied by Rogue Wave Server to build the request.

If it is set to IlsTrue, the array is directly used in the request and freed by Rogue Wave Server when the request is completed.

This function returns IlsFalse when the callback request cannot be sent, which means that the connection has been closed. Otherwise, it returns IlsTrue.

IlsBoolean execDuplexObjectCallback(const IlsMvRef& ref,

const IlsString& funNm,

IlsMvValue* args,

IlsCbArgNb nbArgs,

const IlsString& duplexFunNm,

IlsMvValue* duplexArgs=0,

IlsCbArgNb duplexNbArgs=0,

IlsCbArgNb resultIndex=0,

IlsBoolean inTrans=IlsTrue,

IlsBoolean freeArgs=IlsFalse);

This callback executes an asynchronous call to the function funNm on the “remote” object identified by the reference ref. As explained in Synchronous/Asynchronous Callbacks, the result of the function is sent back to the caller through a call to the duplex function duplexFunNm on the “local” object associated with the reference ref.

This function takes the following additional parameters:

The arguments to be passed to the function funNm are stored in the array of IlsMvValue objects args.

nbArgs is the size of this array.

The arguments to be passed to the duplex function duplexFunNm are stored in the parameter duplexArgs, an array of IlsMvValue objects.

duplexNbArgs is the size of this array.

resultIndex is the index of the arguments passed to the duplexFunNm function, which will contain the result of the function funNm.

The Boolean parameter inTrans indicates whether the callback must be executed using the transaction mechanism or not (see Transaction Control in the IlsMvComponent class description). If this parameter is set to IlsTrue (its default value) and no current transaction has been initialized, a new transaction is implicitly created and committed.

The last argument freeArgs indicates whether the argument array must be freed by Rogue Wave Server or not.

If it is set to IlsFalse (default value), the array is copied by Rogue Wave Server to build the request.

If it is set to IlsTrue, the array is directly used in the request and freed by Rogue Wave Server when the request is completed.

This function returns IlsFalse when the callback request cannot be sent, which means that the connection has been closed. Otherwise, it returns IlsTrue.


Note: As with a “single” asynchronous callback, the IlsTrue return value does not mean that the function funNm has been successfully executed.

Callbacks to Global Functions

These callbacks are used to execute global functions at the end point of the connection. As callbacks to member functions, global callbacks can be asynchronous, synchronous or duplex. A duplex callback is a pair of symmetric asynchronous calls. See Synchronous/Asynchronous Callbacks for more comments on these modes.

The relevant global functions must have been previously declared to the server model interpreter of the server or to the representation model interpreter by using the macros ILS_GLOBAL_FUNCTION (for Server-object member functions) or ILS_RP_GLOBAL_FUNCTION (for representation-object member functions).
See the classes IlsModelInterpreter and IlsRpModelInterpreter, respectively, for details.

IlsBoolean execAsyncGlobalCallback(const IlsString& funNm,

IlsMvValue* args,

IlsCbArgNb nbArgs,

IlsBoolean inTrans=IlsTrue,

IlsBoolean freeArgs=IlsFalse);

This callback executes an asynchronous call to the global function funNm. It also takes the following parameters:

The arguments to be passed to the function are stored in the array of IlsMvValue objects args.

The parameter nbArgs is the size of this array.

The last argument freeArgs indicates whether the argument array must be freed by Rogue Wave Server or not.

If it is set to IlsFalse (default value), the array is copied by Rogue Wave Server to build the request.

If it is set to IlsTrue, the array is directly used in the request and freed by Rogue Wave Server when the request is completed.

This function returns IlsFalse when the callback request cannot be sent, which means that the connection has been closed. Otherwise, it returns IlsTrue.


Note: Because the callback is aynchronous, the IlsTrue return value does not mean that the function funNm has been successfully executed.

IlsBoolean execSyncGlobalCallback(const IlsString& funNm,

IlsMvValue* args,

IlsCbArgNb nbArgs,

IlsMvValue& result,

IlsBoolean freeArgs=IlsFalse);

This callback executes a synchronous call to the global function funNm. It takes the following additional parameters:

The arguments to be passed to the function are stored in the parameter args, an array of IlsMvValue objects.

nbArgs is the size of this array.

The parameter result is a reference assigned by Rogue Wave Server to the result of the global function.

The last argument freeArgs indicates whether the argument array must be freed by Rogue Wave Server or not.

If it is set to IlsFalse (default value), the array is copied by Rogue Wave Server to build the request.

If it is set to IlsTrue, the array is directly used in the request and freed by Rogue Wave Server when the request is completed.

This function returns IlsFalse when the callback request cannot be sent, which means that the connection has been closed. Otherwise, it returns IlsTrue.

When the callback fails, the value of the result parameter remains unchanged.

IlsBoolean execDuplexGlobalCallback(const IlsString& funNm,

IlsMvValue* args,

IlsCbArgNb nbArgs,

const IlsString& duplexFunNm,

IlsMvValue* duplexArgs=0,

IlsCbArgNb duplexNbArgs=0,

IlsCbArgNb resultIndex=0,

IlsBoolean inTrans=IlsTrue,

IlsBoolean freeArgs=IlsFalse);

This callback executes an asynchronous call to the global function funNm. As explained in Synchronous/Asynchronous Callbacks, the result of the function is sent back to the caller through a call to the duplex function duplexFunNm.

This function takes the following additional parameters:

The arguments to be passed to the function funNm are stored in the array of IlsMvValue objects args.

nbArgs is the size of this array.

The arguments to be passed to the duplex function duplexFunNm are stored in the parameter duplexArgs, an array of IlsMvValue objects.

duplexNbArgs is the size of this array.

resultIndex is the index of the arguments passed to the duplexFunNm function, which will contain the result of the function funNm.

The last argument freeArgs indicates whether the argument array must be freed by Rogue Wave Server or not.

If it is set to IlsFalse (default value), the array is copied by Rogue Wave Server to build the request.

If it is set to IlsTrue, the array is directly used in the request and freed by Rogue Wave Server when the request is completed.

This function returns IlsFalse when the callback request cannot be sent, which means that the connection has been closed. Otherwise, it returns IlsTrue.


Note: As with a “single” asynchronous callback, the IlsTrue return value does not mean that the function funNm has been successfully executed. Note: The function referred to by the duplexFunNm parameter must have been declared locally as a global function.

Loading View Specification

void loadViewSpec(const IlsString& fileOrString,

IlsBoolean isString,

IlsBoolean useXmlParser,

IlsBoolean isSync = IlsFalse);

This member function loads a dynamic view-type specification to the server, either as an instance of IlsString (if the isString parameter is set to IlsTrue) or from the name of the view specification file (if isString is set to IlsFalse). The isString parameter must be specified because it has no default value. The useXmlParameter must be specified in order to use (or not) the XML Parser to load the view. The function call is synchronous if the isSync parameter is set to IlsTrue, or asynchronous otherwise.

This member function returns IlsTrue if the file is found and the syntax of the dynamic-view type specification is valid. Otherwise, it returns IlsFalse.

Request Input/Output Control

IlsBoolean setEncoder(IlsMsgEncoder encoding);

This member function declares the function encoding to be applied on any message before it is sent through the connnection. It returns IlsFalse if no connection is associated with the end point (server and component being linked within the same process). Else it returns IlsTrue.


Note: It is your responsibility to install the relevant decoder at the peer end point of the connection.

This function must be called from the function IlsMvServer::acceptConnection on the server side and IlsMvComponent::onConnect on the component side.

IlsBoolean setDecoder(IlsMsgDecoder decoding);

This member function declares the function encoding to be applied on any message received through the connnection. It returns IlsFalse if no connection is associated with the end point (server and component being linked within the same process). Else it returns IlsTrue.


Note: It is your responsibility to install the relevant encoder at the peer end point of the connection.

This function must be called from the function IlsMvServer::acceptConnection on the server side and IlsMvComponent::onConnect on the component side.

IlsMsgEncoder getEncoder() const;

This member function returns the encoding function set through a call to the function setEncoder (documented above) or 0 by default.

IlsMsgDecoder getDecoder() const;

This member function returns the decoding function set through a call to the function setDecoder (documented above) or 0 by default.

Thread Control

[static] void SetMT(IlsBoolean isMT);

Call this static member function with the isMT parameter set to IlsTrue if you want to use the component API or the component interface API in a multithread context.

IlsThread* startSendThread();

This static member function starts a thread in charge of sending the message to the peer end point. The multithread mode must have been previously selected. See also the static member function SetMT documented above.

This member function returns a pointer to the created thread or 0 if the thread execution failed.

IlsBoolean stopSendThread(IlsBoolean flush=IlsFalse);

This member function stops the thread used to send messages. When the argument flush is set to IlsTrue, the pending output messages are sent before the thread is stopped.

This function returns:

IlsTrue when the thread is actually stopped.

IlsFalse if no “sending thread” has been previously started.

IlsBoolean isSendingThread();

This member function returns IlsTrue if a sending thread has been started. Otherwise, it returns IlsFalse.

Trace

void trace(int=TRACE_TRANS);

This member function selects the type of traces at one of the end points of a view server-to-component connection. The parameter should be assigned a value of type IlsMvEndPoint::TraceType or an ORing expression of values of this enumerated type. By default, this parameter is assigned the value TRACE_TRANS. Notice that the type TRACE_TAG_ERR cannot be selected after a transaction message has been exchanged through the connection.

IlsBoolean isTraced(int=TRACE_TRANS);

This member function tests the type of traces at one of the end points of a view server-to-component connection. The parameter should be assigned a value of type IlsMvEndPoint::TraceType value or an ORing expression of values of this enumerated type. By default, this parameter is assigned the value TRACE_TRANS.

This function returns IlsTrue if all the trace type values making of the parameter value match the currently selected value.

int getTraceType() const;

This member function returns the type of traces currently selected.

[static] void Trace(int=TRACE_TRANS);

This static member function selects the default type of traces selected. The parameter should be assigned a value of type IlsMvEndPoint::TraceType or an ORing expression of values of this enumerated type. By default, this parameter is assigned the value TRACE_TRANS.

[static] IlsBoolean IsTraced(int=TRACE_TRANS);

This static member function tests the default type of traces selected. The parameter should be assigned a value of type IlsMvEndPoint::TraceType or an ORing expression of values of this enumerated type. By default, this parameter is assigned the value TRACE_TRANS.

This function returns IlsTrue if all the trace type values making up the parameter value correspond to the selected default value.

[static] int GetTraceType();

This static member function returns the default type of traces.