Server
API Reference Guide
Product Documentation:

Visualization Server
Documentation Home
List of all members | Public Member Functions | Protected Member Functions | Friends
IlsRpObject Class Reference

Base class for component side representation objects. More...

#include <ilserver/rp.h>

Inheritance diagram for IlsRpObject:
IlsRepresentation IlsSwRow IlsSwTable IlsSwRepresentation

Public Member Functions

virtual void afterInit ()
 Called immediately after an object has been created when a representation object is instantiated by the Server. More...
 
virtual void onRmRepresentation ()
 Called when the representation that owns the representation object is destroyed and invokes in turn the representation object destructor. More...
 
IlsBoolean setConstAttribute (IlsRpAttributeId)
 Sets the value of a constant attribute for a representation object. More...
 
void setConstAttributes ()
 Sets the value of the constant attributes of a representation object. More...
 
virtual IlsBoolean setMapping (const IlsRpObject &cousin)
 Associates a new representation object with an existing Server object. More...
 
Accessors
virtual IlsString getLabel () const
 Returns the label of the representation object. More...
 
IlsRpObjectId getId () const
 Returns the identifier of the representation object. More...
 
IlsRpAttributeId getAttributeId (const IlsString &label) const
 Returns an attribute identifier from its name. More...
 
IlsRpAttributeId getAttributeId (const IlsString &label, int index) const
 Returns an indexed attribute identifier from its name and its index. More...
 
IlsMvDataType getAttributeType (IlsRpAttributeId) const
 Returns the attribute type of a given attribute. More...
 
const IlsRpObjModelgetModel () const
 Returns a pointer to the runtime representation object model associated with the representation object. More...
 
IlsRepresentationgetRepresentation () const
 Returns a pointer to the representation that owns the representation object. More...
 
IlsBoolean isEditable (IlsRpAttributeId id, IlsEditRights::Value right=IlsEditRights::DEFAULT_EDIT) const
 Returns IlsTrue if the attribute id has the editing rights specified by the variable right.
 
IlsBoolean isLocalHRef (IlsRpAttributeId id)
 Returns IlsTrue if the attribute id is a local hyper-reference – in other words, a hyper-reference that has no associated relation.
 
IlsMvRef getReference () const
 Returns a reference object that identifies a representation object in the server-to-component protocol. More...
 
Transaction Control from Component to Server
virtual void beginC2SUpdate (IlsRpUpdateType)
 Initializes a set of updates on the representation object. More...
 
void beginC2SUpdate ()
 Initializes a set of updates on the representation object. More...
 
IlsBoolean isInC2SUpdate ()
 Returns IlsTrue between a call to beginC2SUpdate() and a call to either endC2SUpdate() or discardC2SUpdate(). Otherwise, it returns IlsFalse.
 
virtual void endC2SUpdate ()
 Commits updates performed on the representation object. More...
 
virtual void discardC2SUpdate ()
 Discards the modifications currently stored in the representation object update buffer.
 
Opening a view
virtual void openView (const IlsString &viewName, IlsMvValue *argv=0, IlsCbArgNb argc=0, IlsBoolean force=IlsFalse)
 Requests the server to open the view viewName on the server object associated with its corresponding representation object. More...
 
virtual void openView (const IlsString &viewName, IlsMvValue *argv, IlsCbArgNb argc, IlsMvValue *ackArgv, IlsCbArgNb ackArgc, IlsCbArgNb resultIndex, IlsBoolean force=IlsFalse)
 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(). 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...
 
Attribute Editing Functions
virtual void setBoolean (IlsRpAttributeId id, IlsBoolean value)
 Called by the server when the Boolean attribute id has no associated modifier and must be set to value. More...
 
virtual void setChar (IlsRpAttributeId id, char value)
 Called by the server when the attribute id of type char has no associated modifier and must be set to value. More...
 
virtual void setShort (IlsRpAttributeId id, short value)
 Called by the server when the id attribute of type short has no associated modifier and must be set to value. More...
 
virtual void setLong (IlsRpAttributeId id, long value)
 Called by the server when the attribute id of type long has no associated modifier and must be set to value. More...
 
virtual void setFloat (IlsRpAttributeId id, float value)
 Called by the server when the attribute id of type float has no associated modifier and must be set to value. More...
 
virtual void setDouble (IlsRpAttributeId id, double value)
 Called by the server when the attribute id of type double has no associated modifier and must be set to value. More...
 
virtual void setString (IlsRpAttributeId id, const IlsString &value)
 Called by the server when the attribute id of type IlsString has no associated modifier and must be set to value. More...
 
virtual void setAny (IlsRpAttributeId id, IlsAny value)
 Called by the server when the attribute id of type IlsAny has no associated modifier and must be set to value. More...
 
virtual void setUserTypeValue (IlsRpAttributeId id, IlsMvUserType &value)
 Called by the server when the attribute id of type IlsMvUserType (or derived) has no associated modifier and must be set to value. More...
 
virtual void setReference (IlsRpAttributeId id, const IlsRpObject *objectPtr)
 Called by the server when the id attribute has no associated modifier and must reference the object pointed to by objectPtr. More...
 
virtual void setHRef (IlsRpAttributeId id, const IlsString &hrefLabel)
 called by the server when the label of the hyper-reference id has no associated modifier and must be set to hrefLabel. More...
 
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=IlsFalse)
 This member function notifies the object destruction to the server. More...
 
virtual void setRpStatus (IlsRpStatus)
 Requests modification of the representation status of the server object associated with the representation object in the view to which the representation is attached.
 
virtual IlsBoolean onUpdate (IlsRpAttributeId id, IlsBoolean value)
 Requests the server to set the IlsBoolean attribute id to value. More...
 
virtual IlsBoolean onUpdate (IlsRpAttributeId id, char value)
 Requests the server to set the char attribute id to value. More...
 
virtual IlsBoolean onUpdate (IlsRpAttributeId id, short value)
 Requests the server to set the short attribute id to value. More...
 
virtual IlsBoolean onUpdate (IlsRpAttributeId id, long value)
 Requests the server to set the long attribute id to value. More...
 
virtual IlsBoolean onUpdate (IlsRpAttributeId id, float value)
 Requests the server to set the float attribute id to value. More...
 
virtual IlsBoolean onUpdate (IlsRpAttributeId id, double value)
 Requests the server to set the double attribute id to value. More...
 
virtual IlsBoolean onUpdate (IlsRpAttributeId id, const IlsString &value)
 Requests the server to set the IlsString attribute id to value. More...
 
virtual IlsBoolean onUpdate (IlsRpAttributeId id, IlsAny value)
 Requests the server to set the IlsAny attribute id to value. More...
 
virtual IlsBoolean onUpdate (IlsRpAttributeId id, const IlsMvUserType &value)
 Requests the server to set the IlsMvUserType attribute id to value. More...
 
virtual IlsBoolean onUpdate (IlsRpAttributeId id, const IlsRpObject &objRef)
 Requests the server to set the attribute id of a reference to another representation object. More...
 
virtual IlsBoolean onUpdate (IlsRpAttributeId id, const IlsRpObject &newHRefOwner, IlsRpAttributeId newHRef)
 Requests the server to replace the target object of a Server relation with another object. More...
 
virtual IlsBoolean onNullifyRef (IlsRpAttributeId id)
 Requests the server to reset the reference attribute id to null, so as to notify the server about this modification. More...
 
virtual IlsBoolean isMatchingRef (IlsRpAttributeId id, const IlsRpObject *newTarget)
 Tests whether the id attribute can be assigned the value of the object pointed to by newTarget. More...
 
virtual IlsBoolean isMatchingHRef (IlsRpAttributeId id, const IlsRpObject *newHRefOwner, IlsRpAttributeId newHRef)
 Tests whether the id attribute can be assigned the hyper-reference identified by newHRef and belonging to newHRefOwner. More...
 
virtual IlsBoolean onDereference (IlsRpAttributeId id, IlsMvValue *argv=0, IlsCbArgNb argc=0, IlsBoolean force=IlsFalse)
 Opens a view by dereferencing a hyper-reference (see Hyper-References). More...
 
virtual IlsBoolean onDereference (IlsRpAttributeId id, IlsMvValue *argv, IlsCbArgNb argc, IlsMvValue *ackArgv, IlsCbArgNb ackArgc, IlsCbArgNb resultIndex, IlsBoolean force=IlsFalse)
 Opens a view by dereferencing a hyper-reference (see Hyper-References) with aknowledgement. More...
 
Editing Collections
virtual IlsBoolean onAddToCollection (const IlsRpObject &collectorOwner, IlsRpAttributeId collectorId)
 Requests the server to set or add a target to a relation (usually a n-ary relation). More...
 
virtual IlsBoolean onRmFromCollection (const IlsRpObject &collectorOwner, IlsRpAttributeId collectorId, IlsBoolean isDestroyed=IlsFalse)
 Requests the server to remove a target in a relation (usually a n-ary relation). More...
 
virtual IlsBoolean testCollection (const IlsRpObject &collectorOwner, IlsRpAttributeId collectorId)
 Tests whether the representation object can be added to the collection of objects designated by the attribute collectorId and owned by the representation object collectorOwner. More...
 
Callbacks to Member Functions

These callbacks are used to execute functions on the Server object to which a representation object is bound.

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)
 Executes an asynchronous call to the function funNm on the Server object that matches the current representation object. More...
 
virtual IlsBoolean execSyncCallback (const IlsString &funNm, IlsMvValue *args, IlsCbArgNb argsNb, IlsMvValue &result, IlsBoolean freeArgs=IlsFalse)
 Executes a synchronous call to the callback function funNm on the server object that matches the current representation object. More...
 
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)
 Executes an asynchronous call to the function funNm on the server object, the representation object is bound to. More...
 

Protected Member Functions

 IlsRpObject (const IlsRpObject &collectorOwner, IlsRpAttributeId collectorAttrId, const IlsRpObjModel *model=0, IlsBoolean endUpdate=IlsTrue)
 Constructor used to create object from a collector. More...
 
 IlsRpObject (IlsRepresentation &rp, const IlsRpObjModel &model)
 Constructor used by the notification engine. More...
 
virtual ~IlsRpObject ()
 Destructor. More...
 
Transaction Control from Server to Component
virtual IlsBoolean beginS2CUpdate (IlsS2CTransStatus transStatus, IlsTransactionId transId)
 Called by the member function IlsRepresentation::beginS2CTransaction() on any representation object involved in the transaction. More...
 
virtual void beforeDeletion (IlsTransactionId id)
 Called between the beginS2CUpdate() and theendS2CUpdate()` in the transaction that deletes the RpObject. More...
 
virtual void endS2CUpdate (IlsS2CTransStatus transStatus, IlsTransactionId transId)
 Called when the server has finished updating a representation object after a server-to-component transaction. More...
 
virtual IlsBoolean ackAttrUpdate (IlsRpAttributeId attrId, IlsS2CTransStatus transStatus, IlsTransactionId transId)
 Called for each attribute involved in a server-to-component transaction, except if the propagation has been aborted (see beginS2CUpdate() above). More...
 

Friends

class IlsMvComponent
 
class IlsRepresentation
 
class IlsRpModelInterpreter
 

Detailed Description

Base class for component side representation objects.

Library: mvserver
and mvcomp

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.

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.

Constructor & Destructor Documentation

◆ IlsRpObject() [1/2]

IlsRpObject::IlsRpObject ( IlsRepresentation rp,
const IlsRpObjModel model 
)
protected

Constructor used by the notification engine.

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.

Even though the preferable way to create a new representation object is through a collector using the constructor described below, you can also use this constructor instead. To notify the server that a new representation object, hence a new server object, has been created, do the following:

  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 when a representation object is created on the component side.
  3. Call the member function endC2SUpdate() to commit the component-to-server transaction.
Parameters
rpreference to the representation into which the representation object will be inserted.
modelreference to the associated representation object model.

◆ IlsRpObject() [2/2]

IlsRpObject::IlsRpObject ( const IlsRpObject collectorOwner,
IlsRpAttributeId  collectorAttrId,
const IlsRpObjModel model = 0,
IlsBoolean  endUpdate = IlsTrue 
)
protected

Constructor used to create object from a collector.

This constructor must be used when an application component creates a representation object to be inserted into a set of epresentation objects – called a collection – and this collection is owned by another representation object.

Parameters
collectorOwnerthe owner of the collection
collectorAttrIdthe identifier of the attribute that defines the collection
modela 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.

Parameters
endUpdateWhen 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.

◆ ~IlsRpObject()

virtual IlsRpObject::~IlsRpObject ( )
protectedvirtual

Destructor.

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 Function Documentation

◆ ackAttrUpdate()

virtual IlsBoolean IlsRpObject::ackAttrUpdate ( IlsRpAttributeId  attrId,
IlsS2CTransStatus  transStatus,
IlsTransactionId  transId 
)
protectedvirtual

Called for each attribute involved in a server-to-component transaction, except if the propagation has been aborted (see beginS2CUpdate() above).

The transStatus and transId parameters are the same as those passed to the beginS2CUpdate() function.

Parameters
attrIdthe attribute involved
transStatustransaction status
transIdtransaction identifier
Returns
always IlsTrue unless redefined. 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.

◆ ackOpenView()

virtual void IlsRpObject::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).

The default implementation does nothing. It can be overridden.

Reimplemented in IlsSwTable, and IlsSwRow.

◆ afterInit()

virtual void IlsRpObject::afterInit ( )
virtual

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.

Reimplemented in IlsSwTable, IlsSwRow, and IlsSwRepresentation.

◆ beforeDeletion()

virtual void IlsRpObject::beforeDeletion ( IlsTransactionId  id)
protectedvirtual

Called between the beginS2CUpdate() and theendS2CUpdate()` in the transaction that deletes the RpObject.

The RpObject will be effectively destroyed just after the endS2CUpdate() in the same transaction.

The default implementation do nothing.

◆ beginC2SUpdate() [1/2]

void IlsRpObject::beginC2SUpdate ( )

Initializes a set of updates on the representation object.

This 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).

◆ beginC2SUpdate() [2/2]

virtual void IlsRpObject::beginC2SUpdate ( IlsRpUpdateType  )
virtual

Initializes a set of updates on the representation object.

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.

◆ beginS2CUpdate()

virtual IlsBoolean IlsRpObject::beginS2CUpdate ( IlsS2CTransStatus  transStatus,
IlsTransactionId  transId 
)
protectedvirtual

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.

Reimplemented in IlsSwTable, IlsSwRow, and IlsSwRepresentation.

◆ endC2SUpdate()

virtual void IlsRpObject::endC2SUpdate ( )
virtual

Commits updates performed on the representation object.

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.

◆ endS2CUpdate()

virtual void IlsRpObject::endS2CUpdate ( IlsS2CTransStatus  transStatus,
IlsTransactionId  transId 
)
protectedvirtual

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().

The default implementation does nothing.

Reimplemented in IlsSwTable, IlsSwRow, and IlsSwRepresentation.

◆ execAsyncCallback()

virtual IlsBoolean IlsRpObject::execAsyncCallback ( const IlsString funNm,
IlsMvValue args = 0,
IlsCbArgNb  argsNb = 0,
IlsBoolean  inTrans = IlsTrue,
IlsBoolean  freeArgs = IlsFalse 
)
virtual

Executes an asynchronous call to the function funNm on the Server object that matches the current representation object.

Parameters
funNmfunction name
argsan array of IlsMvValue objects.
argsNbthe dimension of the args array.
inTransan IlsBoolean 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.
freeArgsindicates whether the argument args must be freed by Rogue Wave Server or not. If set to:
  • IlsFalse: the array is copied by Rogue Wave Server to build the request.
  • IlsTrue: the array is directly used in the request and freed by Rogue Wave Server when the request is completed.
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.

◆ execDuplexCallback()

virtual IlsBoolean IlsRpObject::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 
)
virtual

Executes an asynchronous call to the function funNm on the server object, the representation object is bound to.

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.
Parameters
funNmfunction name.
argsarguments to be passed to the function funNm.
argsNbthe dimension of the args array.
duplexFunNmduplex function name.
duplexArgsarguments to be passed to the function duplexFunNm.
duplexNbArgsthe dimension of the duplexArgs array.
resultIndexthe index of the arguments of the function duplexFunNm,which will contain the result of the function funNm.
inTransindicates 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.
freeArgsindicates whether the argument args must be freed by Rogue Wave Server or not. If set to:
  • IlsFalse: the array is copied by Rogue Wave Server to build the request.
  • IlsTrue: the array is directly used in the request and freed by Rogue Wave Server when the request is completed.
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.

◆ execSyncCallback()

virtual IlsBoolean IlsRpObject::execSyncCallback ( const IlsString funNm,
IlsMvValue args,
IlsCbArgNb  argsNb,
IlsMvValue result,
IlsBoolean  freeArgs = IlsFalse 
)
virtual

Executes a synchronous call to the callback function funNm on the server object that matches the current representation object.

Parameters
funNmfunction name.
argsan array of IlsMvValue objects.
argsNbthe dimension of the args array.
resulta reference assigned by Server to the result of the member function.
freeArgsindicates whether the argument args must be freed by Rogue Wave Server or not. If set to:
  • IlsFalse: the array is copied by Rogue Wave Server to build the request.
  • IlsTrue: the array is directly used in the request and freed by Rogue Wave Server when the request is completed.
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.

◆ getAttributeId() [1/2]

IlsRpAttributeId IlsRpObject::getAttributeId ( const IlsString label) const

Returns an attribute identifier from its name.

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.

◆ getAttributeId() [2/2]

IlsRpAttributeId IlsRpObject::getAttributeId ( const IlsString label,
int  index 
) const

Returns an indexed attribute identifier from its name and its index.

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.
Parameters
labelidentifier of an attribute attached to a representation object.
indexposition of this attribute.
Returns
the identifier of the representation attribute

◆ getAttributeType()

IlsMvDataType IlsRpObject::getAttributeType ( IlsRpAttributeId  ) const

Returns the attribute type of a given attribute.

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.

◆ getId()

IlsRpObjectId IlsRpObject::getId ( ) const

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.

◆ getLabel()

virtual IlsString IlsRpObject::getLabel ( ) const
virtual

Returns the label of the representation object.

This label is unique.

This virtual member function is mainly used by trace mode.

Reimplemented in IlsRepresentation.

◆ getModel()

const IlsRpObjModel * IlsRpObject::getModel ( ) const

Returns a pointer to the runtime representation object model associated with the representation object.

This pointer is never null, except when the process exits.

◆ getReference()

IlsMvRef IlsRpObject::getReference ( ) const

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.

◆ getRepresentation()

IlsRepresentation * IlsRpObject::getRepresentation ( ) const

Returns a pointer to the representation that owns the representation object.

This pointer is never null, except when the process exits.

◆ isMatchingHRef()

virtual IlsBoolean IlsRpObject::isMatchingHRef ( IlsRpAttributeId  id,
const IlsRpObject newHRefOwner,
IlsRpAttributeId  newHRef 
)
virtual

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.

◆ isMatchingRef()

virtual IlsBoolean IlsRpObject::isMatchingRef ( IlsRpAttributeId  id,
const IlsRpObject newTarget 
)
virtual

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.

◆ onAddToCollection()

virtual IlsBoolean IlsRpObject::onAddToCollection ( const IlsRpObject collectorOwner,
IlsRpAttributeId  collectorId 
)
virtual

Requests the server to set or add a target to a relation (usually a n-ary relation).

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.

If a new representation object is inserted into a collector using the appropriate IlsRpObject constructor, this function must not be called.

Parameters
collectorOwnercollector owner
collectorIdcollector id of the relation
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()).

◆ onDereference() [1/2]

virtual IlsBoolean IlsRpObject::onDereference ( IlsRpAttributeId  id,
IlsMvValue argv,
IlsCbArgNb  argc,
IlsMvValue ackArgv,
IlsCbArgNb  ackArgc,
IlsCbArgNb  resultIndex,
IlsBoolean  force = IlsFalse 
)
virtual

Opens a view by dereferencing a hyper-reference (see Hyper-References) with aknowledgement.

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.

Parameters
idthe attribute identifier, which must be a hyper-reference.
argvan 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).
argcthe number of values set in the array.
ackArgvarray of IlsMvValue objects that can be null.
ackArgcnumber of arguments in ackArgv array.
resultIndexindex 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).
  • 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 representation object during the acknowledgement or rollback of the transaction, onCreation() is called on the representation itself during the notification phase.
forceWhen set to:
  • IlsTrue: a new view is opened even if the same view has already been opened by the component.
  • IlsFalse: no new view is created and only the member function IlsRepresentation::setSelection is called on the representation associated with the view opened.
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.

◆ onDereference() [2/2]

virtual IlsBoolean IlsRpObject::onDereference ( IlsRpAttributeId  id,
IlsMvValue argv = 0,
IlsCbArgNb  argc = 0,
IlsBoolean  force = IlsFalse 
)
virtual

Opens a view by dereferencing a hyper-reference (see Hyper-References).

Parameters
idthe attribute identifier, which must be a hyper-reference.
argvan 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).
argcthe number of values set in the array.
forceWhen set to:
  • IlsTrue: a new view is opened even if the same view has already been opened by the component.
  • IlsFalse: no new view is created and only the member function IlsRepresentation::setSelection is called on the representation associated with the view opened.
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.

◆ onNullifyRef()

virtual IlsBoolean IlsRpObject::onNullifyRef ( IlsRpAttributeId  id)
virtual

Requests the server 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.

◆ onRmFromCollection()

virtual IlsBoolean IlsRpObject::onRmFromCollection ( const IlsRpObject collectorOwner,
IlsRpAttributeId  collectorId,
IlsBoolean  isDestroyed = IlsFalse 
)
virtual

Requests the server to remove a target in a relation (usually a n-ary relation).

The target to be removed is referenced by the representation object to which the function applies.

Parameters
collectorOwnercollector owner
collectorIdcollector id of the relation
isDestroyedwhen set to:
  • IlsTrue: the representation object is destroyed locally by the component.
  • IlsFalse: the destruction must be notified by the server.
Returns
IlsFalse if the attribute is not a collector or is not editable. See the member function IlsRpObject::isEditable().

◆ onRmRepresentation()

virtual void IlsRpObject::onRmRepresentation ( )
virtual

Called when the representation that owns the representation object is destroyed and invokes in turn the representation object destructor.

This function can be overridden.

◆ onSuppress()

virtual void IlsRpObject::onSuppress ( IlsBoolean  isDestroyed = IlsFalse)
virtual

This member function notifies the object destruction to the server.

This member function should be called before the representation object is destroyed when the object destruction is triggered locally by the application component.

Parameters
isDestroyedset to IlsTrue if the representation object is destroyed locally by the component or to IlsFalse if not.

◆ onUpdate() [1/11]

virtual IlsBoolean IlsRpObject::onUpdate ( IlsRpAttributeId  id,
char  value 
)
virtual

Requests the server to set the char attribute id to value.

Parameters
idattribute id
valuevalue to be set
Returns
IlsFalse if the modification is not allowed (see isEditable() for details).

◆ onUpdate() [2/11]

virtual IlsBoolean IlsRpObject::onUpdate ( IlsRpAttributeId  id,
const IlsMvUserType value 
)
virtual

Requests the server to set the IlsMvUserType attribute id to value.

Parameters
idattribute id
valuevalue to be set
Returns
IlsFalse if the modification is not allowed (see isEditable() for details).

◆ onUpdate() [3/11]

virtual IlsBoolean IlsRpObject::onUpdate ( IlsRpAttributeId  id,
const IlsRpObject newHRefOwner,
IlsRpAttributeId  newHRef 
)
virtual

Requests the server to replace the target object of a Server relation with another object.

The new target object is identified by a hyper-reference.

Before using it, make certain that the resulting changes on the server side are valid. For further details, see the member function IlsRpObject::isMatchingHRef().

Parameters
idthe identifier of an attribute attached to the representation object. This attribute must be a reference or a hyper-reference. See the member functions IlsRpObject::isMatchingRef() and IlsRpObject::isMatchingHRef() for details. On the server side, the path associated with the reference or the hyper-reference indicates the relation whose target must be modified.
newHRefOwnera reference to a representation object.
newHRefthe 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.
Returns
IlsFalse if the modification is not allowed.

◆ onUpdate() [4/11]

virtual IlsBoolean IlsRpObject::onUpdate ( IlsRpAttributeId  id,
const IlsRpObject objRef 
)
virtual

Requests the server 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().

◆ onUpdate() [5/11]

virtual IlsBoolean IlsRpObject::onUpdate ( IlsRpAttributeId  id,
const IlsString value 
)
virtual

Requests the server to set the IlsString attribute id to value.

Parameters
idattribute id
valuevalue to be set
Returns
IlsFalse if the modification is not allowed (see isEditable() for details).

◆ onUpdate() [6/11]

virtual IlsBoolean IlsRpObject::onUpdate ( IlsRpAttributeId  id,
double  value 
)
virtual

Requests the server to set the double attribute id to value.

Parameters
idattribute id
valuevalue to be set
Returns
IlsFalse if the modification is not allowed (see isEditable() for details).

◆ onUpdate() [7/11]

virtual IlsBoolean IlsRpObject::onUpdate ( IlsRpAttributeId  id,
float  value 
)
virtual

Requests the server to set the float attribute id to value.

Parameters
idattribute id
valuevalue to be set
Returns
IlsFalse if the modification is not allowed (see isEditable() for details).

◆ onUpdate() [8/11]

virtual IlsBoolean IlsRpObject::onUpdate ( IlsRpAttributeId  id,
IlsAny  value 
)
virtual

Requests the server to set the IlsAny attribute id to value.

Parameters
idattribute id
valuevalue to be set
Returns
IlsFalse if the modification is not allowed (see isEditable() for details).

◆ onUpdate() [9/11]

virtual IlsBoolean IlsRpObject::onUpdate ( IlsRpAttributeId  id,
IlsBoolean  value 
)
virtual

Requests the server to set the IlsBoolean attribute id to value.

Parameters
idattribute id
valuevalue to be set
Returns
IlsFalse if the modification is not allowed (see isEditable() for details).

◆ onUpdate() [10/11]

virtual IlsBoolean IlsRpObject::onUpdate ( IlsRpAttributeId  id,
long  value 
)
virtual

Requests the server to set the long attribute id to value.

Parameters
idattribute id
valuevalue to be set
Returns
IlsFalse if the modification is not allowed (see isEditable() for details).

◆ onUpdate() [11/11]

virtual IlsBoolean IlsRpObject::onUpdate ( IlsRpAttributeId  id,
short  value 
)
virtual

Requests the server to set the short attribute id to value.

Parameters
idattribute id
valuevalue to be set
Returns
IlsFalse if the modification is not allowed (see isEditable() for details).

◆ openView() [1/2]

virtual void IlsRpObject::openView ( const IlsString viewName,
IlsMvValue argv,
IlsCbArgNb  argc,
IlsMvValue ackArgv,
IlsCbArgNb  ackArgc,
IlsCbArgNb  resultIndex,
IlsBoolean  force = IlsFalse 
)
virtual

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().

Parameters
viewNameview name.
argvarray 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).
argcnumber of values set in the array.
ackArgvarray of IlsMvValue objects that can be null.
ackArgcnumber of arguments in ackArgv array.
resultIndexindex 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).
  • 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 representation object during the acknowledgement or rollback of the transaction, onCreation() is called on the representation itself during the notification phase.
forcewhen 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.

◆ openView() [2/2]

virtual void IlsRpObject::openView ( const IlsString viewName,
IlsMvValue argv = 0,
IlsCbArgNb  argc = 0,
IlsBoolean  force = IlsFalse 
)
virtual

Requests the server to open the view viewName on the server object associated with its corresponding representation object.

Parameters
viewNameview name.
argvarray 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).
argcnumber of values set in the array.
forcewhen 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.

◆ setAny()

virtual void IlsRpObject::setAny ( IlsRpAttributeId  id,
IlsAny  value 
)
virtual

Called by the server when the attribute id of type IlsAny has no associated modifier and must be set to value.

The default implemetation does nothing.

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().

◆ setBoolean()

virtual void IlsRpObject::setBoolean ( IlsRpAttributeId  id,
IlsBoolean  value 
)
virtual

Called by the server when the Boolean attribute id has no associated modifier and must be set to value.

The default implemetation does nothing.

For details on representation attribute modifiers, see the macros ILS_RP_ATTR_BOOLEAN(), ILS_RP_INDEXED_ATTR_BOOLEAN(), ILS_RP_DEFAULT_BOOLEAN(), ILS_RP_INDEXED_DEFAULT_BOOLEAN().

◆ setChar()

virtual void IlsRpObject::setChar ( IlsRpAttributeId  id,
char  value 
)
virtual

Called by the server when the attribute id of type char has no associated modifier and must be set to value.

The default implemetation does nothing.

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().

◆ setConstAttribute()

IlsBoolean IlsRpObject::setConstAttribute ( IlsRpAttributeId  )

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.

◆ setConstAttributes()

void IlsRpObject::setConstAttributes ( )

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.

◆ setDouble()

virtual void IlsRpObject::setDouble ( IlsRpAttributeId  id,
double  value 
)
virtual

Called by the server when the attribute id of type double has no associated modifier and must be set to value.

The default implemetation does nothing.

For details on representation attribute modifiers, see the macros ILS_RP_ATTR_DOUBLE(), ILS_RP_INDEXED_ATTR_DOUBLE(), ILS_RP_DEFAULT_DOUBLE(), ILS_RP_INDEXED_DEFAULT_DOUBLE().

◆ setFloat()

virtual void IlsRpObject::setFloat ( IlsRpAttributeId  id,
float  value 
)
virtual

Called by the server when the attribute id of type float has no associated modifier and must be set to value.

The default implemetation does nothing.

For details on representation attribute modifiers, see the macros ILS_RP_ATTR_FLOAT(), ILS_RP_INDEXED_ATTR_FLOAT(), ILS_RP_DEFAULT_FLOAT(), ILS_RP_INDEXED_DEFAULT_FLOAT().

◆ setHRef()

virtual void IlsRpObject::setHRef ( IlsRpAttributeId  id,
const IlsString hrefLabel 
)
virtual

called by the server when the label of the hyper-reference id has no associated modifier and must be set to hrefLabel.

The default implemetation does nothing.

For details on representation attribute modifiers, see the macros ILS_RP_ATTR_HREF(), ILS_RP_INDEXED_ATTR_HREF(), ILS_RP_DEFAULT_HREF(), ILS_RP_INDEXED_DEFAULT_HREF().

◆ setLong()

virtual void IlsRpObject::setLong ( IlsRpAttributeId  id,
long  value 
)
virtual

Called by the server when the attribute id of type long has no associated modifier and must be set to value.

The default implemetation does nothing.

For details on representation attribute modifiers, see the macros ILS_RP_ATTR_LONG(), ILS_RP_INDEXED_ATTR_LONG(), ILS_RP_DEFAULT_LONG(), ILS_RP_INDEXED_DEFAULT_LONG().

◆ setMapping()

virtual IlsBoolean IlsRpObject::setMapping ( const IlsRpObject cousin)
virtual

Associates 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 onAddToCollection() and getId()).

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.

◆ setReference()

virtual void IlsRpObject::setReference ( IlsRpAttributeId  id,
const IlsRpObject objectPtr 
)
virtual

Called by the server when the id attribute has no associated modifier and must reference the object pointed to by objectPtr.

The default implemetation does nothing.

For details on representation attribute modifiers, see the macros ILS_RP_ATTR_REF(), ILS_RP_INDEXED_ATTR_REF(), ILS_RP_DEFAULT_REF(), ILS_RP_INDEXED_DEFAULT_REF().

◆ setShort()

virtual void IlsRpObject::setShort ( IlsRpAttributeId  id,
short  value 
)
virtual

Called by the server when the id attribute of type short has no associated modifier and must be set to value.

The default implemetation does nothing.

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().

◆ setString()

virtual void IlsRpObject::setString ( IlsRpAttributeId  id,
const IlsString value 
)
virtual

Called by the server when the attribute id of type IlsString has no associated modifier and must be set to value.

The default implemetation does nothing.

For details on representation attribute modifiers, see the macros ILS_RP_ATTR_STRING(), ILS_RP_INDEXED_ATTR_STRING(), ILS_RP_DEFAULT_STRING(), ILS_RP_INDEXED_DEFAULT_STRING().

◆ setUserTypeValue()

virtual void IlsRpObject::setUserTypeValue ( IlsRpAttributeId  id,
IlsMvUserType value 
)
virtual

Called by the server when the attribute id of type IlsMvUserType (or derived) has no associated modifier and must be set to value.

The default implemetation does nothing.

For details on representation attribute modifiers, see the macros ILS_RP_ATTR_USERTYPE(), ILS_RP_INDEXED_ATTR_USERTYPE(), ILS_RP_DEFAULT_USERTYPE(), ILS_RP_INDEXED_DEFAULT_USERTYPE().

Reimplemented in IlsSwTable, and IlsSwRow.

◆ testCollection()

virtual IlsBoolean IlsRpObject::testCollection ( const IlsRpObject collectorOwner,
IlsRpAttributeId  collectorId 
)
virtual

Tests whether the representation object can be added to the collection of objects designated by the attribute collectorId 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.

IlsSwRow
Defines a Rogue Wave Server representation object that is a row.
Definition: row.h:124