IlsRepresentation
Category
Dynamic view-related class (component side)
Inheritance Path
IlsRpObject➥IlsRepresentation Description
This class implements in a component the representations that are associated with each dynamic view in the server. It lets you control the transactions applying to representation objects between the object server and the application component. It can be subtyped to define runtime attributes that will be used in view specifications. See the macro
ILS_REPRESENTATION_DECL.
For each dynamic view, there is one and only one instance of the IlsRepresentation class or of a derived class.
Libraries
Synopsis
class IlsRepresentation:public IlsRpObject{
protected:
IlsRepresentation(IlsMvComponent&,const IlsRpModel&);
public:
virtual ~IlsRepresentation();
Accessors
IlsRepresentationId
getId() const;
IlsRpObject** getObjects(int &count);
Transaction Control
From Server to Component
protected:
(IlsS2CTransStatus transStatus,
IlsTransactionId);
IlsTransactionId);
From Component to Server
public:
virtual void
close(IlsBoolean notify);
Callback on Associated View on Server Side
IlsBoolean keepOldOrigin=IlsFalse);
virtual void
addOrigin(const IlsRpObject& rpObj);
Selecting a Representation
Creating and Deleting Representation Objects
virtual IlsRpObject*
newRpObject (IlsRepresentation& repres,
IlsRpObjModel& model);
Creation Callback
virtual void
onCreation(const IlsMvValue* ackArgv,
IlsCbArgNb ackArgc);
Buffer Mode
};
Constructor
IlsRepresentation(IlsMvComponent&,const IlsRpModel&);
As its arguments, this protected constructor takes references to the component it belongs to and to the representation model. Each class that derives from
IlsRepresentation and that is declared as a representation class must possess 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_REPRESENTATION_BEGIN/ILS_REPRESENTATION_END and
ILS_REPRESENTATION_DECL.
This constructor is called either by the constructor of a derived class (
IlsSwRepresentation, for example) or by the virtual member function
IlsMvComponent::newRepresentation.
Destructor
virtual ~IlsRepresentation();
This destructor is automatically invoked when the server is disconnected or when the view that created the representation is closed. To close a representation and notify the server about this modification without destroying the view, a component must call the
IlsRepresentation::close member function. This destructor calls the virtual member function
IlsRpObject::onRmRepresentation on each of its objects, which by default deletes the object.
Member Functions
Accessors
IlsRepresentationId getId() const;
This member function returns the representation identifier. This identifier is unique.
It is used internally by the server-to-component protocol and also in trace mode.
IlsRpObject* getObject(IlsRpObjectId id);
This member function returns a pointer to the representation object identified by the argument id. It returns 0 if no object with the specified identifier is found in the representation.
IlsRpObject** getObjects(int &count);
This member function returns an array of all Representation Objects stored in this representation. The argument count is assigned the number of elements of the returned array. You must delete the returned array using the delete [] operator.
IlsRpModel& getModel() const;
This member function returns a reference to the dynamic representation model associated with the representation.
[virtual] IlsString getLabel();
This virtual member function returns the dynamic representation label, which is used in trace mode.
IlsMvComponent* getComponent() const;
This member function returns a pointer to the application component to which the representation belongs. It returns 0 if the application component is being closed.
Transaction Control from Server to Component
IlsBoolean isInS2CTransaction();
This member function returns IlsTrue if the representation is being updated by a server. Otherwise, it returns IlsFalse.
[virtual] IlsBoolean beginS2CTransaction(IlsS2CTransStatus transStatus,
IlsTransactionId);
This virtual member function is called by the function
IlsMvComponent::beginS2CTransaction on each representation involved in a server-to-component transaction.
This function takes the same arguments as those received by
IlsMvComponent::beginS2CTransaction. However, when the representation is created, the transaction status
transStatus is assigned the value
ILS_S2C_NOTIFY_CREATION.
If this function returns IlsTrue, the notification, acknowledgement, or rollback is propagated to each representation object touched by the transaction in this representation. If it returns IlsFalse, the transaction is aborted for this representation.
This function, which can be overridden, returns IlsTrue, unless the transaction is an acknowledgement. This means by default that an acknowledgement transaction is not propagated to the representation objects.
[virtual] void endS2CTransaction(IlsS2CTransStatus transStatus,
IlsTransactionId);
This virtual member function is called at the end of a server-to-component transaction applying to the representation. The arguments are the same as those passed to the beginS2CTransaction function described above. This function, which can be overridden, has an empty implementation.
Transaction Control from Component to Server
[virtual] void beginC2STransaction();
This virtual member function lets you create a transaction buffer where modifications performed and/or required by the application component are stored before they are sent to the server (see the function IlsRepresentation::commitC2STransaction below).
It is called either explicitly or implicitly. If it is called implicitly, the commit operation is also implicit and takes place after a representation object belonging to the representation has been updated (see
IlsRpObject::endC2SUpdate).
[virtual] void commitC2STransaction();
This virtual member function commits a transaction. By default, the updates performed during the transaction are directly sent to the server. They can also be stored in a transaction buffer at the component level (see
IlsMvComponent::beginC2STransaction).
[virtual] void rollbackC2STransaction();
This virtual member function rolls back a transaction that applies to a representation.
When asynchronous rollback mode is enabled on the component (see
IlsMvComponent::setDefaultC2STransStatus), this function sends asynchronous requests to the server. In response, the server sends back all the corresponding updates so as to restore the representation to its previous state.
When asynchronous rollback mode is disabled, the transaction is rolled back locally and synchronously. For more information, see
Transaction Control in the
IlsMvComponent class description. This member function rolls back a transaction that has been previously initialized on the representation.
IlsBoolean isInC2STransaction();
This member function returns IlsTrue if the representation is being updated by the component. Otherwise, it returns IlsFalse.
[virtual] void close(IlsBoolean notify);
This virtual member function requests that the view associated with the representation be closed.
If the Boolean argument
notify is set to
IlsTrue, the server must notify the component that the representation has been closed. In particular, the server requests the deletion of all the objects in the representation (see the member function
IlsRepresentation::deleteRpObject below) and the deletion of the representation itself (see
IlsMvComponent::delRepresentation).
If the Boolean argument
notify is set to
IlsFalse, the server does not request any deletion of the representation or of the representation objects.
Callback on Associated View on the Server Side
The following functions are used to handle the origin(s) of the view associated with the representation.
[virtual] void setMainOrigin(const IlsRpObject* rpObjP,
IlsBoolean keepOldOrigin=IlsFalse);
This virtual member function requests the server to set the server object associated with the representation object pointed to by the
rpObjP argument as the main origin of the view associated with the corresponding representation (see the member functions
IlsMvView::setMainOrigin and
IlsMvView::getMainOrigin for details).
If the argument
rpObjP is null, the view no longer has a main origin.
If the argument
keepOldOrigin is true, the previous main origin (if any) is kept as a view origin.
If the argument
keepOldOrigin is false, the previous main origin is removed from the view origins.
[virtual] void addOrigin(const IlsRpObject& rpObj);
This virtual member function requests that the server add the server object associated with the rpObj representation object as an origin of the view associated to the corresponding representation. However, it has no effect if rpObj is already an origin of this view.
[virtual] void removeOrigin(const IlsRpObject& rpObj);
This virtual member function requests that the server remove the server object associated
with the rpObj representation object as an origin of the view associated with the corresponding representation. However, it has no effect if rpObj is not an origin of the view.
Selecting a Representation
[virtual] void setSelection();
A component may request that the server open a view that is already open (see the member functions
IlsMvComponent::openView,
IlsRpObject::openView, and
IlsRpObject::onDereference for more information).
If this happens and the opening of the view is not forced, the server does not replicate the view, but merely notifies the component to select the associated representation by calling the
setSelection virtual member function on this representation. By default, this function has no effect. If the representation is a graphical one, the function can be redefined, for instance to pop up the representation, as in
IlsSwRepresentation.
Creating and Deleting Representation Objects
[virtual] IlsRpObject* newRpObject(IlsRepresentation& repres,
IlsRpObjModel& model);
This virtual member function is called to create a new representation object in the representation, based on the
model representation object model, if no constructor attachment has been declared for this model (see the macros
ILS_RP_OBJECT_BEGIN/ILS_RP_OBJECT_END for details).
The first argument,
repres, is a reference to the representation to which the new representation object is going to be inserted. This function builds an object of type
IlsRpObject. It can be overridden to build an object of a derived type.
[virtual] void deleteRpObject(IlsRpObject* obj){}
This virtual member function is called by the server when a representation object must be destroyed. It actually deletes the object. It can be overridden.
Creation Callback
[virtual] void onCreation(const IlsMvValue* ackArgv,IlsCbArgNb ackArgc);
This virtual member function is executed by Rogue Wave Server after a new representation has been created. Its arguments ackArgv and ackArgc are built from the arguments ackArgv, ackArgc, and resultIndex passed to the following member functions (in each case, the second one in a pair of functions with same names) :
See one of those member functions for more information on the use of the argument resultIndex.
If the opening of the view was requested without those arguments, ackArgv is set to the null pointer and ackArgc is set to 0.
This function has an empty implementation because it is meant to be overriden by the user when needed.
Buffer Mode
[virtual] void setBufferMode(IlsBoolean incremental = IlsTrue);
This virtual member function sets the represented view in buffer mode. See the member function
IlsMvView::setBufferMode .
[virtual] void resetBufferMode(IlsBoolean notify = IlsFalse);
This virtual member function resets the buffer-mode state on the represented view. See the member function
IlsMvView::resetBufferMode.
void synchronize();
This member function synchronizes the representation and its representation objects with updates that have been buffered on the view. See the member function
IlsMvView::synchronize.
See Also
Version 5.8
Copyright © 2014, Rogue Wave Software, Inc. All Rights Reserved.