This class implements components for a dynamic-view server (see the class IlsMvServer). More...

#include <ilserver/mvcomp.h>

Inheritance diagram for IlsMvComponent:

Classes
class	RepresentationListener
	This nested class is the interface of a representation listener that can be registered to the component. More...

Public Member Functions
	IlsMvComponent ()
	Constructor. More...

Transaction Control
All interactions between an object server and a component are based on a two-tier transaction system that operates both on the server side and on the component side. On the component side, there are two kinds of transactions: those used to handle requests sent to the server (component-to-server transactions – also called `C2S` transactions), and those used to handle requests received from the server (server-to-component transactions – or `S2C` transactions). A send transaction can be created explicitly by calling the `beginC2STransaction()` function. This function buffers all the requests that must be sent to the server until the transaction is either committed by the `commitC2STransaction()` function or rolled back by the `rollbackC2STransaction()` function. Bufferization supports a three-tier control: At component level: This level of control supports multithreaded transactions. See the function `setC2SMT()`. At representation level: Refer to the member functions `IlsRepresentation::beginC2STransaction()`, `IlsRepresentation::commitC2STransaction()`, and `IlsRepresentation::rollbackC2STransaction()` for more information. At representation object level: Refer to the member functions `IlsRpObject::beginC2SUpdate()`, `IlsRpObject::endC2SUpdate()`, and `IlsRpObject::discardC2SUpdate()` for more information. You can control the way a component-to-server transaction executed on the server side will feed back on the component side. More precisely, you can decide whether: The transaction can be rolled back by the server if an update fails; The execution of the transaction must be followed by a notification cycle; The transaction must be acknowledged to the component. To carry out such controls, you must set: either a default status for component-to-server transactions through the member function `setDefaultC2STransStatus()`, or a specific status when committing the component-to-server transaction using the member function `commitC2STransaction()`. When a transaction is acknowledged by the server, an acknowledgement transaction is sent to the component. Acknowledgement is then propagated to all the representations and representation objects that have been updated by the component. In addition, the server initiates a notification transaction to all components whose representations need to be updated. If a transaction committed by a component fails on the server side, that failure triggers in return a server-to-component transaction, called rollback transaction, on the component side. As a result, the rollback transaction triggers the appropriate requests for the representation objects to be kept consistent with the server. Note No transaction can be rolled back if rollback mode has been disabled by the component. A component-to-server transaction can be locally aborted by the component (see the member function `rollbackC2STransaction()`). In that case, the transaction is rolled back either locally to the component in synchronous mode or by the server in asynchronous mode. In the latter case, the server is requested to update the component, as if the transaction had been actually committed by the component and rejected by the server. See the `setDefaultC2STransStatus()`. The type of a server-to-component transaction is defined by the `IlsS2CTransStatus` enumerated type, whether it originates from the server or from a local component rollback. This type can take the following values: `ILS_S2C_NOTIFY` for a notification transaction. `ILS_S2C_ACKNOWLEDGE` to acknowledge a transaction committed first by the component, then by the server. `ILS_S2C_SV_ROLLBACK` to roll back a transaction committed by the component but rejected by the server, or aborted by the component and rolled back by the server. `ILS_S2C_CP_ROLLBACK` for a local rollback of a transaction that was aborted by the component. When a component-to-server transaction succeeds, a notification transaction is issued for each representation that needs to be updated. The acknowledgment transaction is sent by the server only after these notification transactions are over. It is possible to suspend the execution of server transactions in the component by calling the member functions `suspendS2CTrans()` and `restartS2CTrans()`. Thus, after calling the function `suspendS2CTransaction()`, a component can update its representations without being temporarily disturbed by new updates coming from the server. Transaction Control from Component to Server
IlsBoolean	setC2SMT ()
	Selects the multithread mode for component-to-server transactions. More...

IlsBoolean	isC2SMT ()
	Returns `IlsTrue` if multithread mode has been enabled for component-to-server transactions.

virtual IlsTransactionId	beginC2STransaction ()
	Initializes a component-to-server transaction. More...

virtual IlsTransactionId	commitC2STransaction (IlsC2STransStatus tStat=ILS_C2S_DEFAULT)
	Sends the current component-to-server transaction that was previously initialized by the `beginC2STransaction()` function to the server. More...

virtual IlsTransactionId	rollbackC2STransaction ()
	Rolls back the current component-to-server transaction previously initialized by the `beginC2STransaction()` function. More...

IlsBoolean	isInC2STransaction ()
	Returns `IlsTrue` if a component-to-server transaction is already initialized in the component. Otherwise, it returns `IlsFalse`.

unsigned	getC2SPendingTransCount ()
	Returns the number of component-to-server transactions that have not been acknowledged (or rolled back) by the server yet.

IlsTransactionId	getTransactionId ()
	Returns the identifier of the current component-to-server transaction or `0` if no transaction has been initialized.

IlsTransactionId	getAckTransactionId ()
	Returns the identifier of the latest component-to-server transaction that has been acknowledged by the server.

IlsC2STransStatus	getDefaultC2STransStatus ()
	Returns the default transaction status for the transaction sent to the server by the component. More...

void	setDefaultC2STransStatus (IlsC2STransStatus s)
	Sets the default transaction status for the transaction sent to the server by the component. More...

Exiting
void	exitOnDeletion (IlsBoolean status)
	Chooses the behavior on deletion. More...

Accessors
IlsMvComponentId	getId () const
	Returns the component identifier. More...

IlsRepresentation *	getRepresentation (IlsRepresentationId id)
	Returns a pointer to the representation identified by id. More...

Model Management
virtual void	onNewRpModel (IlsRpModel &)
	Called each time the component receives a new or an updated dynamic representation model. More...

IlsRpModel *	getRpModel (IlsRpModelId) const
	Returns a pointer to the dynamic representation model identified by `id`. More...

const IlsRpObjModel *	getObjModel (IlsRpObject &collectorOwner, IlsRpAttributeId collectorId)
	Returns a pointer to the representation object model associated with the collector attribute collectorId of the collectorOwner object.

IlsBoolean	isMatchingSvType (const IlsString &actualType, const IlsString &formalType)
	Checks matching with server type. More...

Component Actions on the Server
virtual void	openView (const IlsString &objId, const IlsString &viewId, IlsMvValue *argv=0, IlsCbArgNb argc=0, IlsBoolean force=IlsFalse)
	Requests the server to open an instance of the dynamic view type viewType on the Server object previously registered with the label objLabel. More...

virtual void	openView (const IlsString &objId, const IlsString &viewName, IlsMvValue argv, IlsCbArgNb argc, IlsMvValue ackArgv, IlsCbArgNb ackArgc, IlsCbArgNb resultIndex, IlsBoolean force=IlsFalse)
	Like `openView(const IlsString&,const IlsString&,IlsMvValue*,IlsCbArgNb)` but requests aknowledge call. More...

virtual void	ackOpenView (const IlsMvValue *ackArgv, IlsCbArgNb ackArgc)
	Called by Server to acknowledge or to roll back a call to the second virtual member function `openView()` (documented above). More...

void	execUserAsyncCallback (const IlsString &fun, IlsMvValue *args, IlsCbArgNb argsNb, IlsBoolean freeArgs=IlsFalse)
	Executes the callback function callbackName for the user object that is associated with the component on the server side. More...

IlsBoolean	getObjectIds (const IlsString &objPattern, IlsBoolean caseSensitive)
	Requests objects list according to a pattern. More...

IlsBoolean	getViewIds (const IlsString &objId, const IlsString &viewPattern, const IlsString &viewTypePattern, IlsBoolean caseSensitive)
	requests from the server a list of views. More...

IlsBoolean	getServerModel (IlsSvModelObserver &, IlsBoolean isSync=IlsFalse)
	Retrieves the server model declared to the runtime model interpreter on the server side and invokes the API of the observer passed to this method. More...

View Types
Call one of these member functions to retrieve either all the view types or a set of the view types that were declared on an identified object, from the server. The call can be synchronous or asynchronous. You must derive the class `IlsMvComponent` and override the function `IlsRtModelParser::declViewType()` in your subclass. You must also override the API declared on the `IlsRtModelParser` to receive the result.
IlsBoolean	getViewTypes (const IlsString &objId, const IlsString &viewPattern, const IlsString &viewTypePattern, IlsBoolean caseSensitive, IlsBoolean isSync=IlsFalse)

IlsBoolean	getViewTypes (IlsBoolean isSync=IlsFalse)

Transaction Control from Server to Component
unsigned	suspendS2CTrans ()
	Suspends the processing of any new transaction issued by the server. More...

unsigned	restartS2CTrans (IlsBoolean force=IlsFalse)
	Decrements the counter incremented by the function `suspendS2CUpdates()`. More...

unsigned	isSuspendedS2CTrans ()
	Returns the value of the counter maintained by the functions `suspendS2CUpdates()` and `restartS2CUpdates()` above. More...

unsigned	getS2CPendingTransCount ()
	Returns the number of pending server-to-component transactions.

virtual void	onNewS2CPendingTrans (IlsS2CTransStatus, IlsTransactionId)
	Called each time the processing of a server-to-component transaction is postponed. More...

virtual IlsBoolean	beginS2CTransaction (IlsS2CTransStatus status, IlsTransactionId id)
	Called whenever a server-to-component transaction is opened. More...

virtual void	endS2CTransaction (IlsS2CTransStatus status, IlsTransactionId id)
	Called whenever a server-to-component transaction is over. More...

Creating Objects
IlsRpObject *	newInCollector (IlsRpObject &collectorOwner, IlsRpAttributeId collectorId, IlsBoolean endUpdate=IlsTrue)
	Creates a new representation object associated with a collector attribute. More...

IlsRpObject *	newMapping (IlsRepresentation &r, const IlsRpObjModel &model, IlsRpObject &cousin, IlsBoolean endUpdate)
	Enables the component to create a new representation object associated with a collector attribute. More...

Server Actions on the Component
virtual void	recvMessage (const IlsMvMessage::SvMsg &msg)
	Called when a message issued by the server is received (see `IlsMvServer::ReplyMessage()`). More...

virtual void	recvObjectIds (IlsString const *objIds, int nb)
	Invoked asynchronoulsy after a `getObjectIds()` request was sent to the server. It receives the requested result. More...

virtual void	recvViewIds (const IlsString &objId, IlsString const *viewIds, int nb)
	Invoked asynchronoulsy after a `getViewIds()` request was sent to the server. It receives the requested result. More...

Public Member Functions inherited from IlsMvEndPoint
void	traceConnectionDenied (IlsBoolean b)
	Allows you to control whether an error message should be displayed when a connection is refused.

const IlsString &	getPeerName () const
	Returns remote process name. More...

const IlsString &	getPeerHost () const
	Returns host if remote connection. More...

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.

virtual void	suppress ()
	Call this virtual member function instead of the destructor if you want to delete an instance of `IlsMvEndPoint`. More...

IlsBoolean	setEncoder (IlsMsgEncoder)
	Declares the function encoding to be applied on any message before it is sent through the connnection. More...

IlsBoolean	setDecoder (IlsMsgDecoder)
	Declares the function encoding to be applied on any message received through the connnection. More...

IlsMsgEncoder	getEncoder () const
	Returns the encoding function set through a call to the function `setEncoder()` or 0 by default.

IlsMsgDecoder	getDecoder () const
	Returns the decoding function set through a call to the function `setDecoder()` or 0 by default.

void	loadViewSpec (const IlsString &fileOrString, IlsBoolean isString, IlsBoolean useXmlParser, IlsBoolean isSync)
	Loads a dynamic view-type specification to the server. More...

IlsBoolean	execAsyncObjectCallback (const IlsMvRef &ref, const IlsString &funNm, IlsMvValue *args, IlsCbArgNb nbArgs, IlsBoolean inTrans=IlsTrue, IlsBoolean freeArgs=IlsFalse)
	Executes an asynchronous call to the function funNm on the object identified by the reference ref. More...

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. More...

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)
	Executes an asynchronous call to the function funNm on the "remote" object identified by the reference ref. More...

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. More...

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. More...

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`. More...

IlsBoolean	disconnect ()
	Closes the connection between the local end point and its peer end point, and then calls the function onDisconnect. More...

virtual IlsConnectionStatus	testConnection (IlsTime *timeout=0)
	Can be used from server to component or from component to server to test the underlying connection between two processes. More...

virtual void	addConnectionListener (ConnectionListener *)
	Add a connection listener.

virtual void	removeConnectionListener (ConnectionListener *)
	Remove a connection listener.

IlsThread *	startSendThread ()
	Starts a thread in charge of sending the message to the peer end point. More...

IlsThread *	threadSending ()
	Starts a thread that sends all notification updates and other messages generated by the server to the component. More...

IlsBoolean	stopSendThread (IlsBoolean flush)
	Stops the thread used to send messages. More...

IlsBoolean	isSendingThread ()
	Returns `IlsTrue` if a special thread is started to send notification updates and other messages generated by the server to the component. More...

void	monitorSendingQueue (IlsBoolean b)
	Allows you to monitor the sending queue. More...

unsigned int	getPendingOutput ()
	Returns the number of output messages stored in the sending queue associated with this component, if any. More...

void	trace (int=TRACE_TRANS)
	Selects the type of traces at one of the end points of a view server-to-component connection. More...

IlsBoolean	isTraced (int=TRACE_TRANS)
	Tests the type of traces at one of the end points of a view server-to-component connection. More...

int	getTraceType () const
	Returns the type of traces currently selected.

Public Member Functions inherited from IlsRtModelParser
virtual void	declAttribute (const IlsString &name, IlsMvDataType type, IlsRTTypes::AttributeKind kind, const IlsMvValue &defaultValue, IlsBoolean isIndexed, IlsBoolean canEdit, IlsBoolean isImplicit, IlsBoolean isExported, IlsBoolean isDynamic)
	Called by Rogue Wave Server to declare the Server attribute name. More...

virtual void	declClass (const IlsString &name, IlsBoolean isExported, IlsBoolean isDynamic)
	Called by Rogue Wave Server to declare a Server object type. More...

virtual void	declFunction (const IlsString &signature, IlsBoolean isImplicit, IlsBoolean isExported, IlsBoolean isDynamic, IlsBoolean global)
	Called by Rogue Wave Server to declare a Server member function. More...

virtual void	declRelation (const IlsString &name, const IlsString &target, IlsRTTypes::RelationKind kind, const IlsString &reverseRelName, IlsBoolean canEdit, IlsBoolean isImplicit, IlsBoolean isMandatory, IlsBoolean isExported, IlsBoolean isDynamic)
	Called by Rogue Wave Server to declare the Server relation name. More...

virtual void	declViewType (const IlsString &viewTypeName, const IlsString &viewInfo, const IlsString &filename, IlsMvViewParamInfo **params, int nbParams)
	Called for each view types received that matches the request (see the member function `IlsMvComponent::getViewTypes()`). More...

Static Public Member Functions
static IlsMvComponent *	Narrow (IlsMvEndPoint &ep)
	Operates a safe downcast of the reference `ep` into a pointer to a component. More...

Static Public Member Functions inherited from IlsMvEndPoint
static IlsMvEndPoint *	GetInteractor ()
	Returns the current interacting component. More...

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.

static void	Trace (int=TRACE_TRANS)
	Selects the default type of traces selected. More...

static IlsBoolean	IsTraced (int=TRACE_TRANS)
	Tests the default type of traces selected. More...

static int	GetTraceType ()
	Returns the default type of traces.

Protected Member Functions
virtual	~IlsMvComponent ()
	Destructor. More...

void	declParentClass (IlsString derived, IlsString parent)
	Called by Rogue Wave Server to declare that the Server type derived derives directly from the Server type parent. More...

Friends
class	IlsRepresentation

class	IlsRpObject

Server Connection
virtual void	disconnect ()
	Disconnects the component from the server.

virtual void	onConnect ()
	Called after the server has been successfully connected. More...

virtual void	onDisconnect ()
	Calls the function `IlsMvEndPoint::suppress()`. More...

virtual void	connectionDenied (const IlsString &cause)
	Called when the server has refused the connection. More...

virtual void	connectionAllowed (const IlsString &cause)
	Called if the request for connection has been accepted on the server side. More...

virtual void	onRmIOMS ()
	Disconnects the component from the server.

static IlsMvComponent *	Connect (const IlsString &serverName=IlsString::Null, const IlsString &hostName=IlsString::Null)
	Establishes a connection with the server serverName on the machine hostName. More...

Representation Management
virtual void	addRepresentationListener (RepresentationListener *)
	Adds a representation listener. More...

virtual void	removeRepresentationListener (RepresentationListener *)
	Removes a representation listener. More...

virtual IlsRepresentation *	newRepresentation (IlsRpModel &)
	Called to create a new representation if no subtype of the class `IlsRepresentation` is specified in the associated dynamic view type. More...

Additional Inherited Members
Public Types inherited from IlsMvEndPoint
enum	TraceType { NO_TRACE, TRACE_TRANS, TRACE_MSG , TRACE_TAG_ERR, TRACE_TAG_PRINT }
	Specifies the type of trace attached to interactions between an object server and its components. See the trace functions of the class `IlsMvEndPoint` for more information. More...

Detailed Description

This class implements components for a dynamic-view server (see the class IlsMvServer).

Library: mvserver
and mvcomp

A component of type IlsMvComponent lets you open dynamic views (see IlsMvView). Opening a view causes a representation to be created in the component. A component features a transaction mechanism that controls how representation updates are notified to the server and how server feedbacks are performed on the representations.

Warning: The class IlsMvEndPoint, which is the base class of IlsMvComponent, holds a reference counter that is incremented or decremented internally by ILOG Server. Therefore, you must never call the destructor of a component explicitly.

Moreover, you must manipulate instances of this class only through reference or pointers. Server is in charge of the destruction of an IlsMvComponent. To tell Server that you want a component to be deleted, you must use the function IlsMvEndPoint::suppress(). When the view server disconnects from the component, the virtual function onDisconnect() is executed by Server. When this function is not overridden, it calls IlsMvEndPoint::suppress().

See also: IlsMvComponentFactory, IlsMvServer, IlsMvView, IlsRepresentation, IlsRpModel, IlsRpObject, IlsRtModelParser, IlsString, IlsSwComponent.

Constructor & Destructor Documentation

◆ IlsMvComponent()

IlsMvComponent::IlsMvComponent ( )

Constructor.

A new instance of IlsMvComponent is created each time a connection is established with an object server at runtime. If you want to subclass IlsMvComponent, you must override the member function IlsMvComponentFactory::newInstance(), which is used by Rogue Wave Server to build a new component.

◆ ~IlsMvComponent()

virtual IlsMvComponent::~IlsMvComponent ( )

protectedvirtual

Destructor.

This destructor is protected. You should never called it explicitly. Instead, you should call the function IlsMvEndPoint::suppress().

Member Function Documentation

◆ ackOpenView()

virtual void IlsMvComponent::ackOpenView	(	const IlsMvValue *	ackArgv,
		IlsCbArgNb	ackArgc
	)

virtual

Called by Server to acknowledge or to roll back a call to the second virtual member function openView() (documented above).

This function as an empty implementation. It can be overridden.

Reimplemented in IlsSwComponent.

◆ addRepresentationListener()

virtual void IlsMvComponent::addRepresentationListener ( RepresentationListener * )

virtual

Adds a representation listener.

Listeners are owned by the component which is responsible of their deletion.

◆ beginC2STransaction()

virtual IlsTransactionId IlsMvComponent::beginC2STransaction ( )

virtual

Initializes a component-to-server transaction.

A local buffer is created to store the requests emitted by the component, the representations or the representation objects until they are sent to the server. Actually, these requests are not sent until the commitC2STransaction() function is called.

If a component-to-server transaction has already been initialized, the function does not create a new transaction. However, when the multithreaded transaction mode has been selected using the member function setC2SMT(), each thread can concurrently initialize its own component-to-server transaction.

When no transaction has been previously initialized, the functions beginC2STransaction() and commitC2STransaction() are implicitly called each time a transaction on a representation is committed or the opening of a dynamic view is requested by the component. See the function IlsRepresentation::commitC2STransaction() for details.

Returns: This function returns either the new transaction identifier, or 0 when a component-to-server transaction has already be initialized. In this case, it only increments an internal transaction depth counter which will be used to balance the calls to commitC2STransaction().

Reimplemented in IlsSwComponent.

◆ beginS2CTransaction()

virtual IlsBoolean IlsMvComponent::beginS2CTransaction	(	IlsS2CTransStatus	status,
		IlsTransactionId	id
	)

virtual

Called whenever a server-to-component transaction is opened.

Parameters

status	shows the transaction type (see Transaction Control).
id	provides the identifier of the component-to-server transaction that triggered the current server-to-component transaction. The value of this argument is `0` for a notification transaction.

Returns: always returns IlsTrue. When it is overridden and returns IlsFalse, the transaction is aborted. Otherwise, modification, acknowledgement, or rollback events are propagated to the representations. See also the IlsRepresentation::beginC2STransaction() member function.

Reimplemented in IlsSwComponent.

◆ commitC2STransaction()

virtual IlsTransactionId IlsMvComponent::commitC2STransaction ( IlsC2STransStatus tStat = ILS_C2S_DEFAULT )

virtual

Sends the current component-to-server transaction that was previously initialized by the beginC2STransaction() function to the server.

Parameters

tStat associates a status with that transaction. This status specifies how the transaction must be executed in the server. See the type definition IlsC2STransStatus for more information on the possible values of the tStat parameter.
When the value of tStat is set to ILS_C2S_DEFAULT, the actual status is assigned a value depending on the default transaction status associated with the component (see the member function setDefaultC2STransStatus()). If this default transaction status has not been redefined, the tStat parameter is set to ILS_C2S_ALL, thus requiring notification and acknowledgement and allowing transaction rollback.

Returns: the transaction identifier, except when the internal transaction depth counter is greater than one, which means that the function has been called several times. In this case, the function does nothing but decrements the counter and returns 0.

Reimplemented in IlsSwComponent.

◆ Connect()

static IlsMvComponent* IlsMvComponent::Connect	(	const IlsString &	serverName = `IlsString::Null`,
		const IlsString &	hostName = `IlsString::Null`
	)

static

Establishes a connection with the server serverName on the machine hostName.

If the connection succeeds, it returns a pointer to the created component. If it fails, it returns a null pointer.

◆ connectionAllowed()

virtual void IlsMvComponent::connectionAllowed ( const IlsString & cause )

virtual

Called if the request for connection has been accepted on the server side.

See also: IlsMvServer::acceptConnection().

The msg parameter is the explanation that may have been set in the call to the function IlsMvServer::acceptConnection() on the server side.

Reimplemented from IlsMvEndPoint.

◆ connectionDenied()

virtual void IlsMvComponent::connectionDenied ( const IlsString & cause )

virtual

Called when the server has refused the connection.

By default, an error message is issued. You can override this behavior by calling the function traceConnectionDenied().

Reimplemented from IlsMvEndPoint.

◆ declParentClass()

void IlsMvComponent::declParentClass	(	IlsString	derived,
		IlsString	parent
	)

protectedvirtual

Called by Rogue Wave Server to declare that the Server type derived derives directly from the Server type parent.

Warning: This member function is private.

Reimplemented from IlsRtModelParser.

◆ endS2CTransaction()

virtual void IlsMvComponent::endS2CTransaction	(	IlsS2CTransStatus	status,
		IlsTransactionId	id
	)

virtual

Called whenever a server-to-component transaction is over.

Parameters

status	shows the transaction type (see Transaction Control).
id	provides the identifier of the component-to-server transaction that triggered the current server-to-component transaction. The value of this argument is `0` for a notification transaction.

Reimplemented in IlsSwComponent.

◆ execUserAsyncCallback()

void IlsMvComponent::execUserAsyncCallback	(	const IlsString &	fun,
		IlsMvValue *	args,
		IlsCbArgNb	argsNb,
		IlsBoolean	freeArgs = `IlsFalse`
	)

Executes the callback function callbackName for the user object that is associated with the component on the server side.

The user object type should be a subtype of IlsMvUser. The parameters of this function are passed to an array of values of size argsNb.

◆ exitOnDeletion()

void IlsMvComponent::exitOnDeletion ( IlsBoolean status )

Chooses the behavior on deletion.

If this member function is invoked with the status argument set to IlsTrue, the component exits the application when the component is destroyed.

If invoked with the status argument set to IlsFalse, this member function prevents the function IlsMvComponent::exit(), described hereafter, from being called when the component is destroyed. By default, this property is set to IlsFalse.

◆ getDefaultC2STransStatus()

IlsC2STransStatus IlsMvComponent::getDefaultC2STransStatus ( )

Returns the default transaction status for the transaction sent to the server by the component.

See the type definition IlsC2STransStatus, as well as the member function setDefaultC2STransStatus() described above, for information about the semantics of this status.

◆ getId()

IlsMvComponentId IlsMvComponent::getId ( ) const

Returns the component identifier.

This identifier is used internally by the protocol between the component and the object server.

◆ getObjectIds()

IlsBoolean IlsMvComponent::getObjectIds	(	const IlsString &	objPattern,
		IlsBoolean	caseSensitive
	)

Requests objects list according to a pattern.

When the server has selected the list of matching objects, this list is filtered by a call to the function IlsViewed::acceptView() on each object of the list with a view-type name argument set to null. As a response, the resulting list is sent to the component through a call to the function IlsMvComponent::recvObjectIds(), which operates in asynchronous mode in distributed environments.

Parameters

objPattern	pattern of the names of the objects as declared on Server with `IlsMvServer::DeclObjectLabel()`.
caseSensitive	specifies whether the search should be case-sensitive

Returns: This function always returns IlsTrue, unless the server is disconnected.

◆ getRepresentation()

IlsRepresentation* IlsMvComponent::getRepresentation ( IlsRepresentationId id )

Returns a pointer to the representation identified by id.

It returns 0 if this representation does not exist in the component.

◆ getRpModel()

IlsRpModel* IlsMvComponent::getRpModel ( IlsRpModelId ) const

virtual

Returns a pointer to the dynamic representation model identified by id.

It returns 0 if this model does not exist in the component.

Implements IlsMvEndPoint.

◆ getServerModel()

IlsBoolean IlsMvComponent::getServerModel	(	IlsSvModelObserver &	,
		IlsBoolean	isSync = `IlsFalse`
	)

Retrieves the server model declared to the runtime model interpreter on the server side and invokes the API of the observer passed to this method.

Note that this observer is a one-shot observer; Rogue Wave Server deletes it as soon as the server model has been completely received and its API has been called.

◆ getViewIds()

IlsBoolean IlsMvComponent::getViewIds	(	const IlsString &	objId,
		const IlsString &	viewPattern,
		const IlsString &	viewTypePattern,
		IlsBoolean	caseSensitive
	)

requests from the server a list of views.

This member function requests from the server a list of the views that meet the following criteria:

The main origin type of the dynamic view type must be that of a Server object associated with the label objName or a parent type.
The name of the view must match the character string viewPattern.
The representation type in the view must match represPattern.
The last argument specifies whether the search should be case-sensitive. By default, this argument is set to IlsFalse.

When the server has determined the list of matching dynamic view types, this list is filtered by a call to the function IlsViewed::acceptView() on each view type name.

In response, the resulting list is sent to the component through a call to the function IlsMvComponent::recvViewIds(), which operates in asynchronous mode in distributed environments.

This function always returns IlsTrue, unless the server is disconnected.

◆ isMatchingSvType()

IlsBoolean IlsMvComponent::isMatchingSvType	(	const IlsString &	actualType,
		const IlsString &	formalType
	)

Checks matching with server type.

This member function returns IlsTrue if the actualType argument on the server side is the name of a subtype derived from the type named formalType. Otherwise, the function returns IlsFalse. It also returns IlsFalse if the component is not connected to any server.

◆ isSuspendedS2CTrans()

unsigned IlsMvComponent::isSuspendedS2CTrans ( )

Returns the value of the counter maintained by the functions suspendS2CUpdates() and restartS2CUpdates() above.

Because the value of the counter is 0 when transaction processing is not suspended, this function can be used as returning a Boolean type.

◆ Narrow()

static IlsMvComponent* IlsMvComponent::Narrow ( IlsMvEndPoint & ep )

static

Operates a safe downcast of the reference ep into a pointer to a component.

If that downcast is successful, the function returns the address of this component. Otherwise, it returns the null pointer.

◆ newInCollector()

IlsRpObject* IlsMvComponent::newInCollector	(	IlsRpObject &	collectorOwner,
		IlsRpAttributeId	collectorId,
		IlsBoolean	endUpdate = `IlsTrue`
	)

Creates a new representation object associated with a collector attribute.

On the server side, this new representation object will be associated with a new Server object, which itself will be included in the relation specified by the collector.

This function determines the representation object type associated with the collector in the view specification. It calls the constructor of this object type and calls the function IlsRpObject::onAddToCollection() with collectorOwner and collectorId as parameters on the new object.

Then, if the parameter endUpdate is true, the function IlsRpObject::endC2SUpdate() is invoked.

Parameters

collectorOwner	the representation object that owns the collector
collectorId	the identifier of the collector attribute
endUpdate	controls the calls to the function `IlsRpObject::endC2SUpdate()`

Returns: a pointer to the new representation object or the null pointer if the function onAddToCollection() fails

◆ newMapping()

IlsRpObject* IlsMvComponent::newMapping	(	IlsRepresentation &	r,
		const IlsRpObjModel &	model,
		IlsRpObject &	cousin,
		IlsBoolean	endUpdate
	)

Enables the component to create a new representation object associated with a collector attribute.

On the server side, this representation object will be associated with an existing server object.

Parameters

r	the representation in which the new object is created.
model	the object model from which the object is created. See the member function `IlsMvComponent::getObjModel()` to know how to find the representation object model associated with a collector.
cousin	a reference to a representation object. Rogue Wave Server uses this reference to determine with which server object the new representation object should be associated.
endUpdate	controls the calls to the function `IlsRpObject::endC2SUpdate()`. This function is invoked on the new representation object only if the endUpdate parameter is true.

Returns: a pointer to the new representation object or the null pointer if the function IlsRpObject::setMapping fails.

◆ newRepresentation()

virtual IlsRepresentation* IlsMvComponent::newRepresentation ( IlsRpModel & )

protectedvirtual

Called to create a new representation if no subtype of the class IlsRepresentation is specified in the associated dynamic view type.

This function calls the IlsRepresentation constructor and returns the instance created. It can be overridden.

◆ onConnect()

virtual void IlsMvComponent::onConnect ( )

virtual

Called after the server has been successfully connected.

It has an empty implementation and can be overridden.

Reimplemented from IlsMvEndPoint.

◆ onDisconnect()

virtual void IlsMvComponent::onDisconnect ( )

virtual

Calls the function IlsMvEndPoint::suppress().

It can be overridden.

Reimplemented from IlsMvEndPoint.

◆ onNewRpModel()

virtual void IlsMvComponent::onNewRpModel ( IlsRpModel & )

virtual

Called each time the component receives a new or an updated dynamic representation model.

Before creating a representation for a given dynamic representation model, the object server sends a copy of this model to the component.

This function is empty and can be overridden.

Reimplemented in IlsSwComponent.

◆ onNewS2CPendingTrans()

virtual void IlsMvComponent::onNewS2CPendingTrans	(	IlsS2CTransStatus	,
		IlsTransactionId
	)

virtual

Called each time the processing of a server-to-component transaction is postponed.

Note: The processing of a pending transaction is automatically delayed if another server-to-component transaction is in progress.

◆ openView() [1/2]

virtual void IlsMvComponent::openView	(	const IlsString &	objId,
		const IlsString &	viewId,
		IlsMvValue *	argv = `0`,
		IlsCbArgNb	argc = `0`,
		IlsBoolean	force = `IlsFalse`
	)

virtual

Requests the server to open an instance of the dynamic view type viewType on the Server object previously registered with the label objLabel.

See IlsMvServer::DeclObjectLabel() to know how to associate a Server object with a label.

In distributed environments, this member function operates in asynchronous mode.

Parameters

objId	object label
viewId	view name
argv	An array of `IlsMvValue` values can be supplied as the third argument. If the view opens successfully, these values are used to initialize the dynamic view parameters as they are declared in the dynamic view type specification file. The first value in the array (i.e. `params=0`) is assigned to the first view parameter, the second value to the second view parameter, and so on in sequential order. Since view parameters all have a default value, it is not mandatory to pass a value for each parameter.
argc	the number of values passed
force	forces the opening of a view previously opened by the component. Its default value is `IlsFalse`. If the view has already been opened by the component, it is not duplicated, but the `IlsRepresentation::setSelection()` function is called on the representation associated with this view.

◆ openView() [2/2]

virtual void IlsMvComponent::openView	(	const IlsString &	objId,
		const IlsString &	viewName,
		IlsMvValue *	argv,
		IlsCbArgNb	argc,
		IlsMvValue *	ackArgv,
		IlsCbArgNb	ackArgc,
		IlsCbArgNb	resultIndex,
		IlsBoolean	force = `IlsFalse`
	)

virtual

Like openView(const IlsString&,const IlsString&,IlsMvValue*,IlsCbArgNb) but requests aknowledge call.

This virtual member function is identical to the previous one except that Server executes a call to the component function ackOpenView during the acknowledgment or rollback of the transaction that includes the call to openView().

The three additional arguments ackArgv, ackArgc and resultIndex are used to specify the parameters that will be passed to the function ackOpenView:

ackArgv is an array of IlsMvValue objects that can be null.
ackArgc is the number of arguments in this array.
resultIndex is the index of the argument in this array that will contain the result of the view opening. This argument is not modified if the including transaction is rolled back. This argument is automatically assigned the value IlsFalse if the including transaction fails or is rolled back. A successful transaction has two effects:
- The argument is automatically assigned the view opening status (see type definition IlsOpenViewStatus for more information on the possible values).
- ILOG Server calls the virtual function IlsRepresentation::onCreation() on the new representation just after it has been created. The function IlsRepresentation::onCreation() is called with the same argument values as those of the member function ackOpenView. But while the latter is called on the component during the acknowledgement or rollback of the transaction, `onCreation()~ is called on the representation itself during the notification phase.

◆ recvMessage()

virtual void IlsMvComponent::recvMessage ( const IlsMvMessage::SvMsg & msg )

virtual

Called when a message issued by the server is received (see IlsMvServer::ReplyMessage()).

It displays the text of the message. It is usually redefined in derived classes as, for instance, in IlsSwComponent.

Reimplemented in IlsSwComponent.

◆ recvObjectIds()

virtual void IlsMvComponent::recvObjectIds	(	IlsString const *	objIds,
		int	nb
	)

virtual

Invoked asynchronoulsy after a getObjectIds() request was sent to the server. It receives the requested result.

The default implementation does nothing.

Parameters

objIds	an array of object identifiers.
nb	the size of the array.

Warning: This function is private.

Reimplemented from IlsMvEndPoint.

◆ recvViewIds()

virtual void IlsMvComponent::recvViewIds	(	const IlsString &	objId,
		IlsString const *	viewIds,
		int	nb
	)

virtual

Invoked asynchronoulsy after a getViewIds() request was sent to the server. It receives the requested result.

The default implementation does nothing.

Parameters

objId	the object identifier.
viewIds	an array of views of objId.
nb	the size of the array.

Warning: This function is private.

Reimplemented from IlsMvEndPoint.

◆ removeRepresentationListener()

virtual void IlsMvComponent::removeRepresentationListener ( RepresentationListener * )

virtual

Removes a representation listener.

Listeners are owned by the component which is responsible of their deletion.

◆ restartS2CTrans()

unsigned IlsMvComponent::restartS2CTrans ( IlsBoolean force = IlsFalse )

Decrements the counter incremented by the function suspendS2CUpdates().

If the counter is null, it allows the component to restart the processing of server-to-component transactions.

◆ rollbackC2STransaction()

virtual IlsTransactionId IlsMvComponent::rollbackC2STransaction ( )

virtual

Rolls back the current component-to-server transaction previously initialized by the beginC2STransaction() function.

If the asynchronous mode is enabled, a rollback request is sent to the server. The server then triggers within a server-to-component transaction all modifications needed to revert the representations in the component to a consistent state.
If the asynchronous rollback mode is disabled, a synchronous rollback transaction is performed by the component.

Returns: the identifier of the currently initialized transaction or defaults to 0.

Reimplemented in IlsSwComponent.

◆ setC2SMT()

IlsBoolean IlsMvComponent::setC2SMT ( )

Selects the multithread mode for component-to-server transactions.

In this mode, a thread can create and commit its own component transaction independently of those created and committed by other threads.

Note: The multithread mode acts only at component level, not at representation level. At a given time, therefore, only one transaction can be open on a representation.

◆ setDefaultC2STransStatus()

void IlsMvComponent::setDefaultC2STransStatus ( IlsC2STransStatus s )

Sets the default transaction status for the transaction sent to the server by the component.

See the type definition IlsC2STransStatus for information on the possible values of the tStat parameter.

You should be aware that using the value ILS_C2S_SV_ROLLBACK means that the transaction is rolled back on the server side, not locally on the component side (see the member function rollbackC2STransaction()). When creating the component, Rogue Wave Server implicitly assigns the default value ILS_C2S_SV_ROLLBACK to the transaction status.

◆ suspendS2CTrans()

unsigned IlsMvComponent::suspendS2CTrans ( )

Suspends the processing of any new transaction issued by the server.

However, it does not interrupt the execution of the current server-to-component transaction, if any. Each call to this function increments a counter that is initialized at 0 and is decremented by the member function restartS2CUpdates().

Returns: the value of the counter.

Classes

Public Member Functions

Static Public Member Functions

Protected Member Functions

Friends

Server Connection

Representation Management

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ IlsMvComponent()

◆ ~IlsMvComponent()

Member Function Documentation

◆ ackOpenView()

◆ addRepresentationListener()

◆ beginC2STransaction()

◆ beginS2CTransaction()

◆ commitC2STransaction()

◆ Connect()

◆ connectionAllowed()

◆ connectionDenied()

◆ declParentClass()

◆ endS2CTransaction()

◆ execUserAsyncCallback()

◆ exitOnDeletion()

◆ getDefaultC2STransStatus()

◆ getId()

◆ getObjectIds()

◆ getRepresentation()

◆ getRpModel()

◆ getServerModel()

◆ getViewIds()

◆ isMatchingSvType()

◆ isSuspendedS2CTrans()

◆ Narrow()

◆ newInCollector()

◆ newMapping()

◆ newRepresentation()

◆ onConnect()

◆ onDisconnect()

◆ onNewRpModel()

◆ onNewS2CPendingTrans()

◆ openView() [1/2]

◆ openView() [2/2]

◆ recvMessage()

◆ recvObjectIds()

◆ recvViewIds()

◆ removeRepresentationListener()

◆ restartS2CTrans()

◆ rollbackC2STransaction()

◆ setC2SMT()

◆ setDefaultC2STransStatus()

◆ suspendS2CTrans()