Dynamic view-related class (server side)

Instances of the class IlsMvView or of a derived class are called dynamic views. Each instance of IlsMvView is configured by a dynamic view type specification and has an associated representation on the component side (see IlsRepresentation). The class IlsMvView is generally transparent to the user. It serves as an internal interface between the object system managed by the server and a representation managed by a component. It is documented to make it possible for you to subtype it (see the macros ILS_MVVIEW_DECL and ILS_MVVIEW_BEGIN/ILS_MVVIEW_END).

The class IlsMvView implements notification functions whose purpose is to update the associated representation according to the contents of the dynamic view type specification. Notification functions use internal tables that map server objects to representation objects. IlsMvView also handles the runtime parameters attached to the view, as well as the representation status of each Server object the view subscribes to.

Usually, the IlsMvView constructor is not called directly by the user. It is called by Rogue Wave Server when a new dynamic view is opened either explicitly or implicitly when a hyper-reference is selected.

(See the functions IlsMvComponent::openView, IlsMvServer::OpenView, IlsRpObject::openView, and IlsRpObject::onDereference) for details.

However, Rogue Wave Server allows you to associate an IlsMvView subtype with a dynamic view type specification (see Dynamic View Types and C++ View Types in Semantics of Dynamic View Type Specifications). In this case, the constructor of the IlsMvView subtype must include the same parameters as above and pass their values to the IlsMvView constructor, as follows:

The destructor of this class or of a derived class should never be called explicitly.

The following functions handle the parameters of a dynamic view type. Note that these parameters are indexed starting from 0.

This member function takes a view parameter’s label as its argument and returns the view parameter’s index (the label of a view parameter is the one that appears in the dynamic view type specification). It returns -1 if no parameter was specified.

This member function returns IlsTrue if the parameter idx has been modified since the last notification phase. Otherwise, it returns IlsFalse.

This member function takes the parameter index idx as its argument and returns the value of idx. The return value is empty if idx corresponds to no parameter.

This member function sets the value of parameter idx to a copy of v.

This member function returns the identifier of the representation associated with the view.

This member function returns a pointer to the dynamic representation model associated with the view. This pointer is never null, unless the view is being deleted.

This member function returns a pointer to the user object associated with the application component that opened the view.

This member function returns the interface of the component that owns the representation associated with the view.

This member function returns the main origin of the view. It is used to return the value of the runtime attribute origin, which is defined for any dynamic views. See View Specification in Semantics of Dynamic View Type Specifications.

This member function takes two parameters:

This member function returns IlsTrue if the argument o is the view main origin. Otherwise, it returns IlsFalse.

This member function adds the viewed object to the set of origins defined for the view. The view will notify its associated application component about the creation of a new origin during the next notification phase. This function always returns IlsTrue unless it is called at exit. This member function has no effect if it is called within a transaction that is rolled back.

This member function removes the viewed object from the set of origins defined for the view. The view will notify its associated application component about the deletion of this origin during the next notification phase. This member function always returns IlsTrue unless it is called at exit. This function has no effect if it is called within a transaction that is rolled back.

This member function returns IlsTrue if the viewed object currently belongs to the set of origins defined for the view. Otherwise, it returns IlsFalse.

This member function returns an array of smart pointers to the origins of the view.
The argument nb returns the size of this array. You must explicitly destroy this array when you no longer need it. To do so, use delete with square brackets [].

This member function returns a reference to the reference of the representation object that provoked the current editing operation. This reference can be used as a parameter for a callback to a function previously declared on representation objects. See Callbacks to Member Functions and Callbacks to Global Functions in the class IlsMvEndPoint, as well as the macro ILS_RP_MEMBER_FUNCTION for details.

When no representation object is found, this function returns a null reference (see IlsMvRef::isNull.)

This function returns the reference of the representation object that is mapped to the server object srvObj and that has modelId as its representation object model identifier. It returns a null reference is no mapping has been declared.

This function returns the identifier of the representation object model associated with the Server object type identified by the parameter objTypeId and whose name is rpModelNm in the specification of the view type. This function returns 0 if no such model is found.

This function browses through the view specification abstract structure. Since this may noticeably affect the runtime cost, it is recommended to store the returned value rather that re-execute this function again and again with the same arguments.

This member function returns the identifier of the representation object associated with the Server object obj and the representation object model identifier modelId. It returns 0 if no association is found.

This member function returns the Server object associated with the representation object identifier rpId and with the object model identifier modelId. It returns 0 if no association is found.

This member function retrieves the Server object associated with an attribute of type reference or hyper-reference attached to a representation object. It takes the following three parameters:

This member function returns IlsTrue if the view subscribes to the object either directly or through relations.

This member function returns IlsTrue if the view subscribes to the relation.

This member function cancels the subscription of the view to the object.

This member function cancels the subscription of the view to the relation and to its target objects, if these objects are not subscribed to directly or through another relation.

During an interaction cycle, Rogue Wave Server calls this virtual member function before the first notification is executed by the view. This function must be called by the notifyBegin overloaded function of any class derived from IlsMvView before its own processing. If this function is not called at the beginning of the derived class overloaded function, the behavior is undefined.

During an interaction cycle, Rogue Wave Server calls this virtual member function after the last notification operation has been executed by the view. This function must be called by the notifyEnd overloaded function of any class derived from IlsMvView after its own processing. If this function is not called at the end of the derived class overloaded function, the behavior is undefined.

A notification cycle performs a set of steps and loops until all object updates are notified to the components (see IlsMvServer::Notify). Rogue Wave Server calls this virtual member function before the first notification operation is executed by the view in a notification subcycle. This function is empty but it can be overridden.

This virtual member function is called by Rogue Wave Server after the last notification operation is executed by the view in a notification subcycle.

This function is empty but it can be overridden. It is useful if you have set view priorities (see IlsMvView::setPriority). It lets you complete a logical set of feedbacks on a representation without waiting for the end of the notification phase.

This member function prevents the notification engine from calling the specific notification functions defined for the view. However, subscription to objects is updated as if the notification functions had been executed and had returned IlsTrue.

This member function enables the notification engine to call the specific notification functions defined for the view. By default, notification is enabled.

This member function returns IlsTrue if notification is enabled.

This member function sets the priority level of a view for notification. This priority level must range from PriorityMin to PriorityMax. The default value for a view is PriorityDefault. The priority is used by the notification engine to determine the notification precedence order among views.

Let us assume we have three views V1, V2, V3 with respective priorities P1, P2, P3 such as P1 > P2 > P3. Notification takes place as follows:

Since assigning priority levels increases the number of notification subcycles, it is recommended that this be done only when necessary.

This function returns the current priority level of a view.

The representation status is used to modify the representation of a Server object in a view. It can be referenced in a dynamic view type specification via the rpStatus runtime attribute, which is implicitly declared in each class of a Server object model. However, this status is not stored as a data member of these classes since it varies from one instance of a view to another and is therefore handled by each view.

This member function returns the representation status of a Server object in a view.
By default, it returns 0 if the view does not subscribe to the object or 1 otherwise.

This member function assigns value to the representation status of a Server object.
If value equals 0, subscription to the Server object is canceled automatically and the representations associated with this object is destroyed.

This member function returns IlsTrue if the representation status of object has been modified since the last notification phase.

This member function puts the dynamic view in buffer mode. It means that all subsequent updates will be stored by the view until buffer mode is canceled by a call to the function resetBufferMode or synchronize. If the incremental argument is set to IlsTrue, only the latest update is kept. Otherwise, all updates are stored.

This function always returns IlsTrue.

This member function returns IlsTrue if the view is in buffer mode.

This member function cancels buffer mode when it has been previously set for the view. Buffered updates will be sent to the component at the end of the next notification cycle concerning this view. If the notify argument is set to IlsTrue, the view is marked as modified so that a notification cycle for this view will be triggered during the next interaction cycle. This function always returns IlsTrue.

This member function cancels the buffer mode until the end of the next notification cycle for this view. The view is marked as modified so that a notification cycle for this view will be triggered during the next interaction cycle.

This member function returns the number of buffered updates for this view.

The following member functions enable a component to be notified in several messages instead of a single message at the end of the cycle. This is especially interesting to prevent the size of the server process from increasing significantly when notifying a view with a huge number of objects (especially during creation notification).

This member function sets the maximum number of object updates and attribute updates that can be buffered in the view during a notification cycle. When that limit is reached, the updates are automatically sent, triggering a notification transaction on the component side. The default value of 0 means no limit.

This member function returns the maximum number of object updates and attribute updates that can be buffered in the view during a notification cycle.

This static member functions sets the default number of object updates and attribute updates that can be buffered in views during a notification cycle. This number is used at view creation.

This static member function returns the default maximum number of object updates and attribute updates that can be buffered in a view during a notification cycle.

This member function requests that the view be closed.

If the close member function is called during a transaction that has its notify argument set to IlsTrue and the transaction is rolled back, the member function has no effect. A view that is closed is automatically stopped.

This virtual function is called when the last origin of a view has been removed. If it returns IlsTrue—its default value—the view is closed.

This member function returns true if the view is opened, which means that a first notification cycle has been performed for this view.

This virtual member function is called after the view has been instantiated. It receives the contextual arguments ackArgv and ackArgc passed to the member function IlsMvComponent::openView on the component side. Rogue Wave Server resets these parameters after the method has been called. You should therefore override the method and copy the parameters if you want to keep them.

This member function puts the view in trace mode if the status argument is true, otherwise, its cancels the trace mode.

These virtual member functions are called by Rogue Wave Server when the view begins and finishes to process incoming requests from its associated component.

This virtual member function is called after the view has been closed. By default, it does nothing. For example, you can redefine this function to destroy a view after it has been closed, unless the view is running in its own thread. In this case, you can delete the view by overriding the virtual function onStop.

If you wish to override the function IlsMvView::onClose, you must call it from the overriding function.