IlsMvComponent
Category
Dynamic view-related class (component side)
Inheritance Path
Description
The class
IlsMvComponent implements components for a dynamic-view server (see the class
IlsMvServer).
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 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.
Libraries
Synopsis
class IlsMvComponent {
public:
protected:
IlsMvComponent*
Narrow(IlsMvEndPoint& ep);
IlsMvComponentId
getId();
const IlsString& formalType);
const IlsRpObjModel*
getObjModel(IlsRpObject& collectorOwner,
IlsRpAttributeId collectorId);
IlsRpAttributeId collectorId,
IlsBoolean endUpdate=IlsTrue);
IlsRpObject*
newMapping(IlsRepresentation& repres,
const IlsRpObjModel& model,
IlsRpObject& cousin,
IlsBoolean endUpdate);
const IlsString& viewPattern,
const IlsString& viewTypePattern,
IlsBoolean caseSensitive,
IlsBoolean isSync=IlsFalse);
(RepresentationListener*);
(RepresentationListener*);
virtual void
openView(const IlsString& objLabel,
const IlsString& viewType,
IlsMvValue* params=0,
IlsCbArgNb paramsNb=0,
IlsBoolean force=IlsFalse);
virtual void
openView(const IlsString& objId,
const IlsString& viewName,
IlsMvValue* argv,
int argc,
IlsMvValue* ackArgv,
IlsCbArgNb resultIndex,
IlsBoolean force=IlsFalse);
IlsCbArgNb ackArgc);
IlsBoolean caseSensitive=IlsFalse);
const IlsString& viewPattern,
const IlsString& represPattern,
IlsBoolean caseSensitive=IlsFalse);
IlsMvValue* values,
int dim);
IlsBoolean isSync=IlsFalse);
(const IlsString& serverName,
const IlsString& hostName=IlsString::Null);
From Component to Server
(IlsC2STransStatus=ILS_C2S_DEFAULT);
From Server to Component
(IlsS2CTransStatus status,
IlsTransactionId id);
IlsTransactionId id);
(IlsS2CTransStatus,IlsTransactionId);
int nb);
IlsString const* viewIds,
int nb);
};
Constructor
IlsMvComponent();
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.
Destructor
virtual ~IlsMvComponent();
This destructor is protected. You should never called it explicitly. Instead, you should call the function
IlsMvEndPoint::suppress.
Member Functions
Narrowing
[static] IlsMvComponent* Narrow(IlsMvEndPoint& ep);
This static member function 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.
Accessors
IlsRepresentation* getRepresentation(IlsRepresentationId id);
This member function returns a pointer to the representation identified by id.
It returns 0 if this representation does not exist in the component.
IlsMvComponentId getId();
This member function returns the component identifier. This identifier is used internally by the protocol between the component and the object server.
Model Management
[virtual] void onNewRpModel(IlsRpModel&);
Before creating a representation for a given dynamic representation model, the object server sends a copy of this model to the component. The virtual member function onNewRpModel is called each time the component receives a new or an updated dynamic representation model. This function is empty and can be overridden.
IlsRpModel* getRpModel(IlsRpModelId id);
This member function returns a pointer to the dynamic representation model identified by id. It returns 0 if this model does not exist in the component.
IlsBoolean isMatchingSvType(const IlsString& actualType,
const IlsString& formalType);
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.
const IlsRpObjModel* getObjModel(IlsRpObject& collectorOwner,
IlsRpAttributeId collectorId);
This member function returns a pointer to the representation object model associated with the collector attribute collectorId of the collectorOwner object.
IlsBoolean getServerModel(IlsSvModelObserver&,
IlsBoolean isSync=IlsFalse);
This member function 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. This observer is a one-shot observer which Rogue Wave Server deletes as soon as the server model has been completely received and the API of that observer has been called.
Creating Objects
IlsRpObject* newInCollector(IlsRpObject& collectorOwner,
IlsRpAttributeId collectorId,
IlsBoolean endUpdate=IlsTrue);
This member function lets you create 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 takes the following parameters:
collectorOwner is the representation object that owns the collector.
collectorId is the identifier of the collector attribute.
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.
The newInCollector function returns a pointer to the new representation object or the null pointer if the function onAddToCollection fails.
IlsRpObject* newMapping(IlsRepresentation& repres,
const IlsRpObjModel& model,
IlsRpObject& cousin,
IlsBoolean endUpdate);
This member function 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. This function takes the following parameters:
repres is the representation in which the new object is created.
model is 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 is 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.
The
newMapping function returns a pointer to the new representation object or the null pointer if the function
IlsRpObject::setMapping fails.
View Types
IlsBoolean getViewTypes(const IlsString& objId,
const IlsString& viewPattern,
const IlsString& viewTypePattern,
IlsBoolean caseSensitive,
IlsBoolean isSync=IlsFalse);
IlsBoolean getViewTypes(IlsBoolean isSync=IlsFalse);
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.
Representation Management
[virtual] IlsRepresentation* newRepresentation(IlsRpModel&);
This virtual member function is 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.
[virtual] void delRepresentation(IlsRepresentation* rp);
This virtual member function is called by Rogue Wave Server to delete the rp representation.
It destroys rp. It can be overridden.
[virtual] void addRepresentationListener(RepresentationListener*);
This virtual member function adds a representation listener. Listeners are owned by the component which is responsible of their deletion.
[virtual] void removeRepresentationListener(RepresentationListener*);
This virtual member function removes a representation listener. Listeners are owned by the component which is responsible of their deletion.
Component Actions on the Server
[virtual] void openView(const IlsString& objLabel,
const IlsString& viewType,
IlsMvValue* params=0,
int paramsNb=0,
IlsBoolean force=IlsFalse);
This virtual member function requires 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.)
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.
The
paramsNb argument gives the number of values passed.
The
force argument 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.
In distributed environments, this member function operates in asynchronous mode. It always returns IlsTrue, unless the server is disconnected.
[virtual] void openView(const IlsString& objLabel,
const IlsString& viewName,
IlsMvValue* argv,
int argc,
IlsMvValue* ackArgv,
IlsCbArgNb ackArgc,
IlsCbArgNb resultIndex,
IlsBoolean force=IlsFalse);
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).
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.
[virtual] void ackOpenView(const IlsMvValue* ackArgv,
IlsCbArgNb ackArgc);
This virtual member function is 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.
IlsBoolean getObjectIds(const IlsString& objPattern,
IlsBoolean caseSensitive);
This member function takes the following parameters:
The first argument requests the list of the objects that are registered with the server and whose names match the character string
objPattern. See the function
IlsMvServer::DeclObjectLabel to learn how to associate a Server object with a label.
The second argument specifies whether the search should be case-sensitive.
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. This function always returns
IlsTrue, unless the server is disconnected.
IlsBoolean getViewIds(const IlsString& objName,
const IlsString& viewPattern,
const IlsString& represPattern,
IlsBoolean caseSensitive=IlsFalse);
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.
void execUserAsyncCallback(const IlsString& callbackName,
IlsMvValue* values,
int dim);
This member function 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
dim.
IlsBoolean getServerModel(IlsSvModelObserver&,
IlsBoolean isSync=IlsFalse);
This member function retrieves theserver 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.
Server Connection
[virtual] void disconnect();
This virtual member function disconnects the component from the server.
[virtual] void onDisconnect();
This virtual member function calls the function
IlsMvEndPoint::suppress. It can be overridden.
[static] IlsMvComponent* Connect(const IlsString& serverName,
const IlsString& hostName=IlsString::Null);
This static member function 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.
[virtual] void onConnect();
This virtual member function is called after the server has been successfully connected. It has an empty implementation and can be overridden.
[virtual] void connectionDenied(const IlsString& cause);
This virtual member function is 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.
void traceConnectionDenied(IlsBoolean b);
This member function allows you to control whether an error message should be displayed when a connection is refused.
[virtual] void connectionAllowed(IlsString msg);
This virtual member function is called if the request for connection has been accepted on the server side. See also the function
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.
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.
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:
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
[virtual] IlsTransactionId beginC2STransaction();
This virtual member function 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.
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.
[virtual] IlsTransactionId commitC2STransaction
(IlsC2STransStatus tStat=ILS_C2S_DEFAULT);
This virtual member function sends the current component-to-server transaction that was previously initialized by the beginC2STransaction function to the server.
The argument
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.
The commitC2STransaction function 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.
[virtual] IlsTransactionId rollbackC2STransaction();
This virtual member function 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. The
rollbackC2STransaction member function returns the identifier of the currently initialized transaction or defaults to
0.
IlsTransactionId getTransactionId();
This member function returns the identifier of the current component-to-server transaction or 0 if no transaction has been initialized.
IlsTransactionId getAckTransactionId();
This member function returns the identifier of the latest component-to-server transaction that has been acknowledged by the server.
IlsBoolean isInC2STransaction();
This member function returns IlsTrue if a component-to-server transaction is already initialized in the component. Otherwise, it returns IlsFalse.
void setDefaultC2STransStatus(IlsC2STransStatus tStat);
This member function 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
IlsMvComponent::rollbackC2STransaction described earlier). When creating the component, Rogue Wave Server implicitly assigns the default value
ILS_C2S_SV_ROLLBACK to the transaction status.
IlsC2STransStatus getDefaultC2STransStatus();
This member function 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.
unsigned getC2SPendingTransCount();
This member function returns the number of component-to-server transactions that have not been acknowledged (or rolled back) by the server yet.
IlsBoolean setC2SMT();
This member function 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. |
IlsBoolean isC2SMT();
This member function returns IlsTrue if multithread mode has been enabled for component-to-server transactions.
Transaction Control from Server to Component
[virtual] IlsBoolean beginS2CTransaction(IlsS2CTransStatus status,
IlsTransactionId id);
This virtual member function is called whenever a server-to-component transaction is opened.
The
id argument 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.
This function 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.
[virtual] void endS2CTransaction(IlsS2CTransStatus status,
IlsTransactionId id);
This virtual member function is called whenever a server-to-component transaction is over.
The
id argument 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.
unsigned suspendS2CTrans();
This member function 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 described below.
This function returns the value of the counter.
unsigned restartS2CTrans(IlsBoolean force=IlsFalse);
This member function decrements the counter incremented by the function suspendS2CUpdates documented above. If the counter is null, it allows the component to restart the processing of server-to-component transactions.
unsigned isSuspendedS2CTrans();
This member function 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.
unsigned getS2CPendingTransCount();
This member function returns the number of pending server-to-component transactions.
[virtual] void onNewS2CPendingTrans(IlsS2CTransStatus,IlsTransactionId);
This virtual function is 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. |
Server Actions on the Component
[virtual] void recvMessage(const IlsMvMessage::SvMsg&);
This virtual member function is 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.
[virtual] void recvObjectIds(const IlsString& const* objIds,int nb);
When called, this virtual member function sends the result of the member function
IlsMvComponent::getObjectIds.
This function takes the following parameters:
objIds represents an array of object identifiers.
nb is the size of the array.
This member function is empty. It is usually redefined in derived classes as, for instance, in
IlsSwComponent.
[virtual] void recvViewIds(const IlsString& objId,
const IlsString& const* viewIds,
int nb);
When called, this virtual member function transmits the result of the member function
IlsMvComponent::getViewIds.
objId represents the object identifier.
viewIds represents an array of views of
objId.
nb is the size of the array.
This function is empty. It is usually redefined in derived classes as, for instance, in
IlsSwComponent.
Exiting
void exitOnDeletion(IlsBoolean status);
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.
See Also
Version 5.8
Copyright © 2014, Rogue Wave Software, Inc. All Rights Reserved.