IlsRpObject
Dynamic view-related class
Inheritance Path
IlsRpObject
Description
IlsRpObject is the base class for representation objects. This class defines a generic representation object API, upon which the interaction protocol between a dynamic server and application components is based. Any representation object types that are referenced in a dynamic view type specification should be implemented by a subtype of
IlsRpObject. Any instance of
IlsRpObject is configured by a dynamic representation object model, an instance of
IlsRpObjModel that is unique to a given representation specification.
To create or update representation objects, you use virtual editing member functions.
To actually update representation objects, you must either redefine these virtual functions or attach specific editing member functions to the class (see the macros
ILS_RP_ATTR_XXX,ILS_RP_INDEXED_ATTR_XXX). Symmetrically,
IlsRpObject defines a set of callback functions that should be invoked whenever a representation object is directly modified by an application component. These functions are responsible for sending the modifications to the server.
Libraries
Synopsis
class IlsRpObject {
public
IlsRpObject(IlsRepresentation& rp,
const IlsRpObjModel& model);
protected:
IlsRpAttributeId collectorAttrId,
const IlsRpObjModel* model=0,
IlsBoolean endUpdate=IlsTrue);
public:
int index);
IlsEditRights::Value right=
IlsEditRights::DEFAULT_EDIT) const;
Transaction Control
From Server to Component
protected:
(IlsS2CTransStatus transStatus,
IlsTransactionId transId)
(IlsS2CTransStatus transStatus,
IlsTransactionId transId);
IlsS2CTransStatus transStatus,
IlsTransactionId transId);
From Component to Server
public:
Opening a View
virtual void
openView(const IlsString& viewName,
IlsMvValue* argv=0,
int argc=0,
IlsBoolean force=IlsFalse);
virtual void
openView(const IlsString& viewName,
IlsMvValue* argv,
int argc,
IlsMvValue* ackArgv,
IlsCbArgNb ackArgc,
IlsCbArgNb resultIndex,
IlsBoolean force=IlsFalse);
IlsCbArgNb ackArgc);
Attribute Editing Functions
Primitive Value
virtual void
setBoolean(IlsRpAttributeId id,IlsBoolean value);
virtual void
setChar(IlsRpAttributeId id,char value);
virtual void
setShort(IlsRpAttributeId id,short value);
virtual void
setLong(IlsRpAttributeId id,long value);
virtual void
setFloat(IlsRpAttributeId id,float value);
virtual void
setDouble(IlsRpAttributeId id,double value);
const IlsString& value);
virtual void
setAny(IlsRpAttributeId id,IlsAny value);
User-Type Value
IlsMvUserType& value);
Object References
const IlsRpObject* objectPtr);
virtual void
setHRef(IlsRpAttributeId id,
const IlsString& hrefLabel);
Update Callback Functions (from Component to Server)
Suppressing
Updating Primitive Value
virtual IlsBoolean
onUpdate(IlsRpAttributeId id,
IlsBoolean value);
virtual IlsBoolean onUpdate(IlsRpAttributeId id,char value);
virtual IlsBoolean onUpdate(IlsRpAttributeId id,short value);
virtual IlsBoolean onUpdate(IlsRpAttributeId id,long value);
virtual IlsBoolean onUpdate(IlsRpAttributeId id,float value);
virtual IlsBoolean onUpdate(IlsRpAttributeId id,double value);
virtual IlsBoolean onUpdate(IlsRpAttributeId id,
const IlsString& value);
virtual IlsBoolean onUpdate(IlsRpAttributeId id,IlsAny value);
Updating User-Type Value
virtual IlsBoolean onUpdate(IlsRpAttributeId id,
const IlsMvUserType& value);
Updating Reference or Hyper-Reference
virtual IlsBoolean onUpdate(IlsRpAttributeId id,
const IlsRpObject& objRef);
virtual IlsBoolean
onUpdate(IlsRpAttributeId id,
const IlsRpObject& newHRefOwner,
IlsRpAttributeId newHRef);
const IlsRpObject* newTarget);
(IlsRpAttributeId id,
const IlsRpObject* newHRefOwner,
IlsRpAttributeId NewHRef);
IlsMvValue* argv=0,
int argc=0,
IlsBoolean force=IlsFalse);
IlsMvValue* argv,
IlsCbArgNb argc,
IlsMvValue* ackArgv,
IlsCbArgNb ackArgc,
IlsCbArgNb resultIndex,
IlsBoolean force=IlsFalse);
Editing Collections
(const IlsRpObject& collectorOwner,
IlsRpAttributeId collectorId);
(const IlsRpObject& collectorOwner,
IlsRpAttributeId collectorId,
IlsBoolean isDestroyed=IlsFalse);
(const IlsRpObject& collectorOwner,
IlsRpAttributeId collectorId);
Callbacks to Member Functions
(const IlsString& funNm,
IlsMvValue* args=0,
IlsCbArgNb argsNb=0,
IlsBoolean inTrans=IlsTrue,
IlsBoolean freeArgs=IlsFalse);
(const IlsString& funNm,
IlsMvValue* args,
IlsCbArgNb argsNb,
IlsMvValue& result,
IlsBoolean freeArgs=IlsFalse);
(const IlsString& funNm,
IlsMvValue* args,
IlsCbArgNb argsNb,
const IlsString& duplexFunNm,
IlsMvValue* duplexArgs=0,
IlsCbArgNb duplexNbArgs=0,
IlsCbArgNb resultIndex=0,
IlsBoolean inTrans=IlsTrue,
IlsBoolean freeArgs=IlsFalse);
Updating the Representation Status
Other Functions
virtual IlsBoolean
setMapping(const IlsRpObject& cousin);
};
Constructors
IlsRpObject(IlsRepresentation& rp,const IlsRpObjModel& model);
This constructor takes the following parameters:
rp is a reference to the representation into which the representation object will be inserted.
model is a reference to the associated representation object model.
Each class that derives from
IlsRpObject and that is declared as a representation class must have a constructor that takes both these parameters as arguments and passes them to the base class when it is initialized. For details on how to declare a class as a representation class, see the macros
ILS_RP_OBJECT_DECL and
ILS_RP_OBJECT_BEGIN/ILS_RP_OBJECT_END.
In this constructor, the representation object has not yet been assigned an identifier. Therefore, it cannot be used to perform component-to-server transactions using callback member functions until the virtual member function
afterInit has been called.
1. Create the
IlsRpObject instance using this constructor, passing the representation and the object model as the parameters. You can retrieve the object model from the representation model associated with the representation by using the member functions
IlsRepresentation::getModel and
IlsRpModel::getObjModel.
2. Call the member function
beginC2SUpdate(ILS_RP_CREATION):
ILS_RP_CREATION is the update type to use wheh a representation object is created on the component side.
3. Call the member function
endC2SUpdate to commit the component-to-server transaction.
IlsRpObject(const IlsRpObject& collectorOwner,
IlsRpAttributeId collectorAttrId,
const IlsRpObjModel* model=0,
IlsBoolean endUpdate=IlsTrue);
This constructor must be used when an application component creates a representation object to be inserted into a set of representation objects—called a collection—and this collection is owned by another representation object. It takes the following parameters:
collectorOwner designates the owner of the collection.
collectorAttrId specifies the identifier of the attribute that defines the collection.
The third argument is a pointer to a representation object model.
By default, this pointer is null and the dynamic representation object model is assumed to be the one referenced by the collector within the dynamic view type specification.
When the pointer is not null, it must point to a representation object model whose associated Server-object type matches the type of the target for the relation associated with the collector. (See
IlsRpObjModel::getSvTypeName and
IlsMvComponent::isMatchingSvType.)
If the object model is not compatible with the collector, the exception
IlsInvalidCollector is thrown. Otherwise, this constructor calls the function
IlsRpObject::onAddToCollection, passing
collectorOwner and
collectorAttrId as parameters.
When the
endUpdate parameter is set to
IlsTrue, the function
endC2SUpdate is invoked on the object. Otherwise, it is up to the user to invoke it, typically after the object attributes have been set.
Destructor
virtual ~IlsRpObject();
The destructor of a representation object is protected. It is invoked by the server via a call to the virtual member function
IlsRepresentation::deleteRpObject.
A representation object is implicitly destroyed if the representation in which it is contained is itself destroyed, unless the virtual member function
IlsRpObject::onRmRepresentation has been redefined and returns
IlsFalse. When the object destruction is triggered by a component, this event must be first notified to the server through a call to the
IlsRpObject::onSuppress function.
Member Functions
Accessors
[virtual] IlsString getLabel();
This virtual member function is mainly used by trace mode. It returns the label of the representation object. This label is unique.
IlsRpObjectId getId();
This member function returns the identifier of the representation object. This identifier is used internally by the interaction protocol between the server and the application components. It returns 0 if the representation object has not been associated with a Server object yet.
IlsRpAttributeId getAttributeId(const IlsString& label);
This member function takes the label of an attribute attached to the representation object as its argument and returns its identifier.
An attribute identifier is a number that reflects the order in which the attribute appears in a view specification.
Let us consider the following view specification:
subscribe Domain:
represent TreeItem Item:
Ref<IlsTree> tree=...;
string itemName=...;
The member function returns three different values depending on the arguments you pass:
If you pass the label
tree, the return value will be 1.
If you pass the label
itemName, the return value will be 2.
This function returns -1 if
label is not a representation object attribute.
IlsRpAttributeId getAttributeId(const IlsString& attrId,int index);
This member function takes the following parameters:
attrId is the identifier of an attribute attached to a representation object.
index is the position of this attribute.
This function returns the identifier of the representation attribute.
Let us consider the following view specification:
subscribe Line:
represent IlsSwRow row:
Ref<IlsSwTable> table=...;
string column[1]=...;
HyperRef column[2]=...};
The member function returns two different values depending on the arguments you pass:
If you pass the label
column and the index
1, the return value will be
2.
If you pass the label
column and the index
2, the return value will be
3.
IlsMvDataType getAttributeType(IlsRpAttributeId id);
This member function takes as its argument the identifier of an attribute attached to the representation object and returns an enumerated value specifying the attribute type.
const IlsRpObjModel* getModel();
This member function returns a pointer to the runtime representation object model associated with the representation object. This pointer is never null, except when the process exits.
IlsRepresentation* getRepresentation();
This member function returns a pointer to the representation that owns the representation object. This pointer is never null, except when the process exits.
IlsBoolean isEditable (IlsRpAttributeId id,
IlsEditRights::Value right=
IlsEditRights::DEFAULT_EDIT) const;
This member function returns IlsTrue if the attribute id has the editing rights specified by the variable right.
IlsBoolean isLocalHRef(IlsRpAttributeId id);
This member function returns IlsTrue if the arribute id is a local hyper-reference —in other words, a hyper-reference that has no associated relation.
IlsMvRef getReference() const;
This member function returns a reference object that identifies a representation object in the server-to-component protocol. This reference object can be encapsulated in an instance of
IlsMvValue and sent to the server. At the server level, the member function
IlsMvComponentItf::getSvObject gets the server object associated with this reference.
Transaction Control
From Server to Component
[virtual] IlsBoolean beginS2CUpdate(IlsS2CTransStatus transStatus,
IlsTransactionId transId);
This virtual member function is called by the member function
IlsRepresentation::beginS2CTransaction on any representation object involved in the transaction. The transaction status
transStatus is the same as the one passed to the function
IlsRepresentation::beginS2CTransaction, except that the value of this parameter is set to
ILS_S2C_NOTIFY_CREATION when a representation object is created.
This function, which can be overridden, returns IlsTrue. Its return value, or that of the overriding function, is used to control the execution of the transaction.
If the return value is
IlsTrue, the notification, acknowledgement or rollback is propagated to each attribute of the representation object involved in the transaction.
If the return value is
IlsFalse, the propagation aborts for this representation object.
[virtual] void endS2CUpdate(IlsS2CTransStatus,IlsTransactionId);
This virtual member function is automatically called when the server has finished updating a representation object after a server-to-component transaction. The parameter values passed to this function are the same as those passed to the previous function
IlsRpObject::beginS2CUpdate. This member function is empty and can be overridden.
[virtual] IlsBoolean ackAttrUpdate(IlsRpAttributeId attrId,
IlsS2CTransStatus transStatus,
IlsTransactionId transId);
This virtual member function is called for each attribute involved in a server-to-component transaction, except if the propagation has been aborted (see beginS2CUpdate above). The attrId parameter identifies the attribute involved.
The transStatus transaction status and the transId transaction identifier are the same as those passed to the beginS2CUpdate function.
This function, which can be overridden, returns IlsTrue.
When a notification cycle (transStatus = ILS_S2C_NOTIFY) or an asynchronous rollback (transStatus = ILS_S2C_SV_ROLLBACK) is performed, the attribute value is actually modified if the result of this function or of the overriding function is IlsTrue. If it is IlsFalse, the attribute value is not modified.
From Component to Server
void beginC2SUpdate();
This member function initializes a buffer where the updates performed on the representation objects are stored until they are either committed by a call to the function
IlsRpObject::endC2SUpdate or discarded by a call to the function
IlsRpObject::discardC2SUpdate.
You must call this member function just before a batch of updates is carried out. If you do not invoke this function explicitly, it will be implicitly called whenever an object is modified. (See the member functions IlsRpObject::onUpdate described later on.)
[virtual] void beginC2SUpdate(IlsRpUpdateType updType);
This virtual member function initializes a buffer where the updates performed on the representation objects are stored until they are either committed by a call to the function endC2SUpdate or discarded by a call to the function discardC2SUpdate.
You should use this function when a representation object is created locally on a component without any collector, with the type ILS_RP_CREATION passed as the argument to notify the server that a new representation object has been created locally.
void endC2SUpdate();
This member function commits the updates performed on the representation object by flushing the buffer where they are currently stored to the representation object update buffer. For further details, see
“Transaction Control” in the
IlsRepresentation class description.
You must call this member function when a batch of updates has been carried out on the representation object and only if the function
IlsRpObject::beginC2SUpdate has been previously and explicitly called.
void discardC2SUpdate();
This member function lets you discard the modifications currently stored in the representation object update buffer.
IlsBoolean isInC2SUpdate();
This member function returns
IlsTrue between a call to
beginC2SUpdate and a call to either
endC2SUpdate or
discardC2SUpdate. Otherwise, it returns
IlsFalse.
Opening a View
[virtual] void openView(const IlsString& viewName,
IlsMvValue* argv=0,
int argc=0,
IlsBoolean force=IlsFalse);
This virtual member function requests the server to open the view viewName on the server object associated with its corresponding representation object.
It takes the following arguments:
argv is an array of values starting from index 0, which are passed to the constructor of the class
IlsMvView or of a derived class in order to initialize the view parameter values (see the
IlsMvView constructor).
argc gives the number of values set in the array.
When the Boolean argument
force is set to
IlsTrue, a new view is opened, even if the same view has already been opened by the component. If its value is set to
IlsFalse, no new view is created and only the member function
IlsRepresentation::setSelection function is called on the representation associated with the view opened.
[virtual] void openView(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 representation object function ackOpenView during the acknowledgment 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 the 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 representation object 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.
Attribute Editing Functions
[virtual] void setBoolean(IlsRpAttributeId id,IlsBoolean value);
This virtual member function is called by the server when the Boolean attribute
id has no associated modifier and must be set to
value. The body of this function is empty.
For details on representation attribute modifiers, see the macros
ILS_RP_ATTR_XXX,
ILS_RP_INDEXED_ATTR_XXX,
ILS_RP_DEFAULT_XXX,
ILS_RP_INDEXED_DEFAULT_XXX.
[virtual] void setChar(IlsRpAttributeId id,char value);
This virtual member function is called by the server when the attribute id of type char has no associated modifier and must be set to value. The body of this function is empty.
For details on representation attribute modifiers, see the macros ILS_RP_ATTR_CHAR, ILS_RP_INDEXED_ATTR_CHAR, ILS_RP_DEFAULT_CHAR, ILS_RP_INDEXED_DEFAULT_CHAR.
[virtual] void setShort(IlsRpAttributeId id,short value);
This virtual member function is called by the server when the
id attribute of type
short has no associated modifier and must be set to
value. The body of this function is empty. For details on representation attribute modifiers, see the macros
ILS_RP_ATTR_XXX,
ILS_RP_INDEXED_ATTR_XXX,
ILS_RP_DEFAULT_XXX,
ILS_RP_INDEXED_DEFAULT_XXX.
[virtual] void setLong(IlsRpAttributeId id,long value);
This virtual member function is called by the server when the
id attribute of type
long has no associated modifier and must be set to
value. The body of this function is empty. For details on representation attribute modifiers, see the macros
ILS_RP_ATTR_XXX,
ILS_RP_INDEXED_ATTR_XXX,
ILS_RP_DEFAULT_XXX,
ILS_RP_INDEXED_DEFAULT_XXX.
[virtual] void setFloat(IlsRpAttributeId id,float value);
This virtual member function is called by the server when the
id attribute of type
float has no associated modifier and must be set to
value. The body of this function is empty. For details on representation attribute modifiers, see the macros
ILS_RP_ATTR_XXX,
ILS_RP_INDEXED_ATTR_XXX,
ILS_RP_DEFAULT_XXX,
ILS_RP_INDEXED_DEFAULT_XXX.
[virtual] void setDouble(IlsRpAttributeId id,double value);
This virtual member function is called by the server when the
id attribute of type
double has no associated modifier and must be set to
value. The body of this function is empty. For details on representation attribute modifiers, see the macros
ILS_RP_ATTR_XXX,
ILS_RP_INDEXED_ATTR_XXX,
ILS_RP_DEFAULT_XXX,
ILS_RP_INDEXED_DEFAULT_XXX.
[virtual] void setString(IlsRpAttributeId id,const IlsString& value);
This virtual member function is called by the server when the
id attribute of type
IlsString has no associated modifier and must be set to
value. The body of this function is empty. For details on representation attribute modifiers, see the macros
ILS_RP_ATTR_XXX,
ILS_RP_INDEXED_ATTR_XXX,
ILS_RP_DEFAULT_XXX,
ILS_RP_INDEXED_DEFAULT_XXX.
[virtual] void setAny(IlsRpAttributeId id,IlsAny value);
This virtual function is called by the server when the
IlsAny attribute identified by
id must be set to
value and this attribute has no attached modifier (see the macros
ILS_RP_ATTR_XXX,
ILS_RP_INDEXED_ATTR_XXX,
ILS_RP_DEFAULT_XXX,
ILS_RP_INDEXED_DEFAULT_XXX.). The body of this function is empty.
[virtual] void setUserTypeValue(IlsRpAttributeId id,IlsMvUserType& value);
This virtual member function is called by the server when the id attribute of type IlsMvUserType has no associated modifier and must be set to value. The body of this function is empty.
[virtual] void setReference(IlsRpAttributeId id,const IlsRpObject* objectPtr);
This virtual member function is called by the server when the
id attribute has no associated modifier and must reference the object pointed to by
objectPtr. The body of this function is empty. For details on representation attribute modifiers, see the macros
ILS_RP_ATTR_XXX,
ILS_RP_INDEXED_ATTR_XXX,
ILS_RP_DEFAULT_XXX,
ILS_RP_INDEXED_DEFAULT_XXX.
[virtual] void setHRef(IlsRpAttributeId id,const IlsString& hrefLabel);
This virtual member function is called by the server when the label of the hyper-reference
id has no associated modifier and must be set to
hrefLabel. The body of this function is empty. For details on representation attribute modifiers, see the macros
ILS_RP_ATTR_XXX,
ILS_RP_INDEXED_ATTR_XXX,
ILS_RP_DEFAULT_XXX,
ILS_RP_INDEXED_DEFAULT_XXX.
Update Callback Functions (from Component to Server)
The following callback functions are used to notify modifications on representation objects to the server. They must not be called if the modifications are requested by the server (see
“Transaction Control from Component to Server” in the
IlsMvComponent class description).
[virtual] void onSuppress(IlsBoolean isDestroyed);
This virtual member function should be called before the representation object is destroyed when the object destruction is triggered locally by the application component. This member function notifies the object destruction to the server. The Boolean parameter isDestroyed is set to IlsTrue if the representation object is destroyed locally by the component or to IlsFalse if not.
[virtual] IlsBoolean onUpdate(IlsRpAttributeId id,IlsBoolean value);
This virtual member function should be called when the component sets or needs to set the Boolean attribute
id to
value. It enables the server to be notified about this modification. This member function returns
IlsFalse if the modification is not allowed. See
IlsRpObject::isEditable for details.
[virtual] IlsBoolean onUpdate(IlsRpAttributeId id,char value);
This virtual member function should be called when the component sets or needs to set the attribute id of type char to value. It enables the server to be notified about this modification. This member function returns IlsFalse if the modification is not allowed. See IlsRpObject::isEditable for details.
[virtual] IlsBoolean onUpdate(IlsRpAttributeId id,short value);
This virtual member function should be called when the component sets or needs to set the attribute id of type short to value. It enables the server to be notified about this modification. This member function returns IlsFalse if the modification is not allowed. See IlsRpObject::isEditable for details.
[virtual] IlsBoolean onUpdate(IlsRpAttributeId id,const IlsMvUserType& value);
This virtual member function should be called when the component sets or needs to set the attribute id of type IlsMvUserType to value. It enables the server to be notified about this modification. This member function returns IlsFalse if the modification is not allowed. See IlsRpObject::isEditable for details.
[virtual] IlsBoolean onUpdate(IlsRpAttributeId id,long value);
This virtual member function should be called when the component sets or needs to set the attribute id of type long to value. It enables the server to be notified about this modification. This member function returns IlsFalse if the modification is not allowed. See IlsRpObject::isEditable for details.
[virtual] IlsBoolean onUpdate(IlsRpAttributeId id,float value);
This virtual member function should be called when the component sets or needs to set the attribute id of type float to value. It enables the server to be notified about this modification. This member function returns IlsFalse if the modification is not allowed. See IlsRpObject::isEditable for details.
[virtual] IlsBoolean onUpdate(IlsRpAttributeId id,double value);
This virtual member function should be called when the component sets or needs to set the attribute id of type double to value. It enables the server to be notified about this modification. This member function returns IlsFalse if the modification is not allowed. See IlsRpObject::isEditable for details.
[virtual] IlsBoolean onUpdate(IlsRpAttributeId id,const IlsString& value);
This virtual member function should be called when the component sets or needs to set the attribute id of type IlsString to value. It enables the server to be notified about this modification. This member function returns IlsFalse if the modification is not allowed. See IlsRpObject::isEditable for details.
[virtual] IlsBoolean onUpdate(IlsRpAttributeId id,IlsAny value);
This virtual member function should be called when the component sets or needs to set the attribute id of type IlsAny to value. It enables the server to be notified of this modification. The functions returns IlsFalse if the modification is not allowed.
See IlsRpObject::isEditable for details.
[virtual] IlsBoolean onUpdate(IlsRpAttributeId id,const IlsRpObject& objRef);
This virtual member function should be called when the application component sets or needs to set the attribute id of a reference to another representation object. It enables the server to be notified about this modification.
The attribute can be a reference (see
IlsMvDataType::MV_REF) or a hyper-reference (see
IlsMvDataType::MV_HREF).
This member function returns
IlsFalse if the modification is not allowed. Before using this function, make certain the resulting changes on the server side are valid. For details, see the member functions
IlsRpObject::isMatchingRef.
[virtual] IlsBoolean onUpdate(IlsRpAttributeId id,
const IlsRpObject& newHRefOwner,
IlsRpAttributeId newHRef);
This virtual member function is called when the application component needs to replace the target object of a Server relation with another object. The new target object is identified by a hyper-reference. It takes the following parameters:
On the server side, the path associated with the reference or the hyper-reference indicates the relation whose target must be modified.
newHRefOwner is a reference to a representation object.
newHRef is the identifier of an attribute of this object.
On the server side, the second and third parameters specify the object that is the new target of the relation.
This member function returns IlsFalse if the modification is not allowed. Before using it, make certain that the resulting changes on the server side are valid. For further details, see the member functions IlsRpObject::isMatchingHRef.
[virtual] IlsBoolean onNullifyRef(IlsRpAttributeId id);
This virtual member function should be called when the application component needs to reset the reference attribute id to null, so as to notify the server about this modification. This member function returns IlsFalse if the modification is not allowed.
[virtual] IlsBoolean isMatchingRef(IlsRpAttributeId id,
const IlsRpObject* newTarget);
This virtual member function tests whether the id attribute can be assigned the value of the object pointed to by newTarget. More specifically, it checks that the resulting updates of the relations on the server side will not impair the type integrity of the Server object model.
[virtual] IlsBoolean isMatchingHRef(IlsRpAttributeId id,
const IlsRpObject* newHRefOwner,
IlsRpAttributeId newHRef);
This virtual member function tests whether the id attribute can be assigned the hyper-reference identified by newHRef and belonging to newHRefOwner. More specifically, it checks that the resulting updates of the relations on the server side will not impair the type integrity of the Server object model.
[virtual] IlsBoolean onDereference(IlsRpAttributeId attrId,
IlsMvValue* argv=0,
int argc=0,
IlsBoolean force=IlsFalse);
This virtual member function lets you open a view by dereferencing a hyper-reference (see
“Hyper-References”). It takes the following arguments:
attrId is the attribute identifier, which must be a hyper-reference.
argv is an array of values starting from index 0, which will be passed to the constructor of
IlsMvView or of a derived class in order to initialize the view parameter values (see the
IlsMvView constructor).
argc provides the number of values set in the array.
The fourth argument is the Boolean
force.
When this argument is set to
IlsTrue, a new view is opened even if the same view has already been opened by the component.
If it is set to
IlsFalse, no new view is created and only the member function
IlsRepresentation::setSelection is called on the representation associated with the view opened.
This function returns IlsFalse if the attrId attribute is not a hyper reference or if the hyper-reference is not associated with any view. Otherwise, it returns IlsTrue.
[virtual] IlsBoolean onDereference(IlsRpAttributeId,
IlsMvValue* argv,
IlsCbArgNb argc,
IlsMvValue* ackArgv,
IlsCbArgNb ackArgc,
IlsCbArgNb resultIndex,
IlsBoolean force=IlsFalse);
This virtual member function is identical to the previous one except that Server calls the representation object function
ackOpenView during the acknowledgement or rollback of the transaction that includes the call to the member function
openView. If the transaction is successful, Server also calls the notification function
IlsRepresentation::onCreation on the new representation. See the second function
openView (documented above) for more information about the role of the additional arguments
ackArgv,
ackArgc and
resultIndex.
Editing Collections
[virtual] IlsBoolean onAddToCollection(const IlsRpObject& collectorOwner,
IlsRpAttributeId collectorId);
This virtual member function enables the component to request the server to set or add a target to a relation (usually a n-ary relation).
The relation is designated by the collector attribute identifier
collectorId.
Its owner is referenced through its associated representation object
collectorOwner.
The new target is referenced by the representation object to which the function applies. If this representation object is not associated with a Server object yet, the Server object is created on the Server side, and then is assigned as the target of the relation.
This member function returns
IlsFalse if the update is not allowed (see the member function
IlsRpObject::isEditable) or if the resulting updates on the server side might impair the Server object model type integrity. See the member function
IlsRpObject::testCollection.
If a new representation object is inserted into a collector using the appropriate IlsRpObject constructor, this function must not be called.
[virtual] IlsBoolean onRmFromCollection(const IlsRpObject& collectorOwner,
IlsRpAttributeId collectorId,
IlsBoolean isDestroyed=IlsFalse);
This virtual member function enables the component to request the server to remove a target in a relation (usually a n-ary relation).
The relation is designated by the collector attribute identifier
collectorId.
Its owner is referenced through its associated representation object
collectorOwner. The target to be removed is referenced by the representation object to which the function applies.
The third argument is the parameter
isDestroyed.
If it is set to
IlsTrue, the representation object is destroyed locally by the component.
If it is set to
IlsFalse, the destruction must be notified by the server.
The function returns IlsFalse if the attribute is not a collector or is not editable.
See the member function IlsRpObject::isEditable.
[virtual] IlsBoolean testCollection(IlsRpObject& collectorOwner,
IlsRpAttributeId collector);
This virtual member function tests whether the representation object can be added to the collection of objects designated by the attribute collector and owned by the representation object collectorOwner. More specifically, it checks that the resulting relation updates on the server side will not impair the type integrity of the Server object model.
Callbacks to Member Functions
These callbacks are used to execute functions on the Server object to which a representation object is bound.
Synchronous/Asynchronous Callbacks
A callback can be asynchronous, synchronous or duplex. A duplex callback is a pair of symmetric asynchronous calls. The result of the original callback performed on the Server object is sent back as an argument to a duplex callback executed on the representation object. To avoid deadlock problems related to synchronous calls, it is strongly recommended to keep a full asynchronous interaction protocol between components and servers. This enables you to choose duplex callbacks whenever possible instead of synchronous callbacks. This mechanism is subject to the following declarations:
The member function executed on the Server object must have been previously declared to the Server model interpreter by means of the macros
ILS_MEMBER_FUNCTION.
The duplex member function executed on the representation object must have been previously declared to the representation model interpreter by means of the macros
ILS_RP_MEMBER_FUNCTION.
[virtual] IlsBoolean execAsyncCallback(const IlsString& funNm,
IlsMvValue* args=0,
IlsCbArgNb argsNb=0,
IlsBoolean inTrans=IlsTrue,
IlsBoolean freeArgs=IlsFalse);
This virtual member function executes an asynchronous call to the function
funNm on the Server object that matches the current representation object. The arguments to be passed to the function are stored in the parameter
args, which is an array of
IlsMvValue objects. This callback also takes the following parameters:
nbArgs is the dimension of this array.
inTrans is a Boolean argument, which specifies whether the callback must be executed using the transaction mechanism or not (see
“Transaction Control” in the
IlsMvComponent class description). If so, and if no current transaction has been initialized, a new one is implicitly created and committed. By default, the parameter
inTrans is set to
IlsTrue.
The last argument
freeArgs indicates whether the argument
args must be freed by Rogue Wave Server or not.
If its value is
IlsFalse, the array is copied by Rogue Wave Server to build the request.
If it is
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 this callback is asynchronous, the IlsTrue return value does not mean that the function funNm has been successfully executed. |
[virtual] IlsBoolean execSyncCallback(const IlsString& funNm,
IlsMvValue* args,
IlsCbArgNb argsNb,
IlsMvValue& result,
IlsBoolean freeArgs=IlsFalse);
This virtual member function executes a synchronous call to the callback function
funNm on the server object that matches the current representation object. The arguments to be passed to the function are stored in the parameter
args, which is an array of
IlsMvValue objects.
This callback also takes the following parameters:
argsNb is the dimension of this array.
The parameter
result is a reference assigned by Server to the result of the member function.
The last argument
freeArgs specifies whether the argument
args must be freed by Rogue Wave Server or not.
If its value is
IlsFalse, the array is copied by Rogue Wave Server to build the request.
If it is
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.
[virtual] IlsBoolean execDuplexCallback(const IlsString& funNm,
IlsMvValue* args,
IlsCbArgNb argsNb,
const IlsString& duplexFunNm,
IlsMvValue* duplexArgs=0,
IlsCbArgNb duplexNbArgs=0,
IlsCbArgNb resultIndex=0,
IlsBoolean inTrans=IlsTrue,
IlsBoolean freeArgs=IlsFalse);
This virtual member function executes an asynchronous call to the function
funNm on the server object, the representation object is bound to. As explained in
Synchronous/Asynchronous Callbacks, the result the function is sent back through a call to the duplex function
duplexFunNm on the representation object.
Note: The duplex callback must have at least one parameter that stores the result of the callback. |
The arguments to be passed to the function
funNm are stored in the in the parameter
args, which is an array of
IlsMvValue objects.
This callback also takes the following arguments:
argsNb is the dimension of this array.
resultIndex is the index of the arguments of the function
duplexFunNm,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 (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. |
Updating the Representation Status
[virtual] void setRpStatus(IlsRpStatus);
This virtual member function requests modification of the representation status of the server object associated with the representation object in the view to which the representation is attached.
Other Functions
[virtual] void onRmRepresentation();
This virtual member function is called when the representation that owns the representation object is destroyed and invokes in turn the representation object destructor. This function can be overridden.
IlsBoolean setConstAttribute(IlsRpAttributeId);
This member function sets the value of a constant attribute for a representation object. The constant attribute is identified by the attribute identifier passed as the parameter. It must have been specified with a literal value in the dynamic-view type specification.
This function can be called on each constant attribute instead of the function setConstAttributes documented below whenever you need fine control on the order in which such constant attributes are assigned.
This function returns IlsFalse if the argument does not identify a constant attribute.
void setConstAttributes();
This member function sets the value of the constant attributes of a representation object. The constant attributes are those specified with a literal value in the dynamic view type specification. This function is particularly useful when a representation object is created directly on the component side, because in that case, the value of constant attributes is not notified by the server.
[virtual] IlsBoolean setMapping(const IlsRpObject& cousin);
This virtual member function lets you associate a new representation object with an existing Server object. This Server object is identified by a “cousin” object that acts as its representation.
This function should be only invoked on an object that was created locally by the component. Such object must not be already associated with a Server object and must not have been previously added to a collector (see the member functions
IlsRpObject::onAddToCollection and
IlsRpObject::getId documented earlier).
If those conditions are not met, the mapping is not performed and the function returns IlsFalse.
Note: The new representation object can be inserted into a collector after the function setMapping has been called. |
[virtual] void afterInit();
This virtual member function is called immediately after an object has been created when a representation object is instantiated by the Server. When this method has been called, the representation object has been assigned an identifier and you can use it to perform component-to-server transactions via callback member functions.
[virtual] void beforeDeletion(IlsTransactionId);
This virtual member function is called between
beginS2CUpdate and
endS2CUpdate in the transaction that deletes the
RpObject instance. The
RpObject instance is effectively destroyed just after the call to
endS2CUpdate in the same transaction. The default implementation does nothing.
See Also
ILS_MEMBER_FUNCTION,
IlsMvComponent,
IlsMvDataType::Kind,
IlsMvView,
IlsRepresentation,
ILS_RP_ATTR_XXX,
ILS_RP_DEFAULT_XXX,
ILS_RP_INDEXED_ATTR_XXX,
ILS_RP_INDEXED_DEFAULT_XXX,
ILS_RP_MEMBER_FUNCTION,
ILS_RP_OBJECT_BEGIN/ILS_RP_OBJECT_END,
ILS_RP_OBJECT_DECL,
IlsRpObjModel
Version 5.8
Copyright © 2014, Rogue Wave Software, Inc. All Rights Reserved.