IlsMvServer
 
IlsMvServer
Category 
Dynamic view-related class (server side)
Inheritance Path 
IlsMvServer
Description 
This class lets you define dynamic view servers. In a dynamic view server, views are loaded at runtime from dynamic view type specifications.
Library 
<mvserver>
Header File 
#include <ilserver/mvserver.h>
Synopsis 
class IlsMvServer: public IlsViewServer
{
protected:
IlsMvServer(int threadMode = IlsMvServer::ILS_THREADED_DEFAULT);
 
virtual ~IlsMvServer();
 
virtual IlsBoolean processRequest(IlsTime* timeout=0);
 
public:
Initialization
static IlsBoolean Initialize
(int& argc,
char** argv,
int threadMode =
IlsMvServer::ILS_THREADED_DEFAULT);
Loading Dynamic View Type Specifications
static IlsBoolean LoadResources(IlsString resourceFile);
static IlsBoolean LoadViewSpec
(IlsString ilsFile,
IlsBoolean useXmlParser = IlsFalse);
static IlsBoolean InterpretViewSpec
(IlsString viewSpec,
IlsMvComponentItf* =0,
IlsBoolean useXmlParser = IlsFalse);
Opening Views
static IlsMvView* OpenView(const IlsString& objId,
const IlsString& viewId,
IlsMvComponentItf* compItfPtr=0,
const IlsMvValue* params=0,
unsigned long paramsNb=0,
IlsBoolean force=IlsFalse,
IlsOpenViewStatus* statusP=0);
static IlsMvView* OpenView(IlsViewed* obj,
const IlsString& viewId,
IlsMvComponentItf* compItfPtr=0,
const IlsMvValue* params=0,
unsigned long paramsNb=0,
IlsBoolean force=IlsFalse,
IlsOpenViewStatus* statusP=0);
Execution Loop
static IlsBoolean Run(int nb=0,IlsTime* timeOut=0);
static void Notify();
virtual void beginNotification();
virtual void endNotification();
void registerEndCycleTask(IlsCallbackFunc cb, IlsAny arg);
static void Stop();
Transaction Control
virtual IlsBoolean beginTransaction(IlsMvComponentItf& comp,
IlsTransactionId tId,
IlsC2STransStatus tStat);
virtual IlsBoolean endTransaction(IlsMvComponentItf& comp,
IlsTransactionId tId,
IlsC2STransStatus tStat,
IlsBoolean result);
Identifying Objects
static IlsBoolean DeclObjectLabel(IlsViewed& obj,
IlsString label);
static IlsString GetLabelOfObject(IlsViewed& object);
static IlsViewed* GetObjectFromLabel(IlsString label);
static IlsBoolean UndeclObjectLabel(IlsViewed& object);
static IlsBoolean UndeclObjectLabel(IlsString label);
Interactors
static IlsMvComponentItf* GetInteractor();
static IlsMvComponentItf* GetDefaultComp();
static IlsMvUser* GetInteractingUser();
virtual IlsMvUser* getInteractingUser();
static IlsMvUser* GetDefaultUser();
Trace Mode
static void SetTrace();
static void SetTraceTime(IlsBoolean t=IlsTrue);
static IlsBoolean IsTraced();
static IlsBoolean IsTracedTime();
Component Connection
virtual void onConnect(IlsMvComponentItf& comptItf);
virtual void onDisconnect(IlsMvComponentItf& compItf);
static IlsMvComponentItf* GetComponent(IlsMvComponentId);
static IlsMvComponentItf*const* GetComponents(int& dim);
View Handling
virtual void onOpenView(IlsMvView&);
virtual void onCloseView(IlsMvView&);
Other Functions
virtual IlsBoolean acceptConnection(IlsMvComponentItf&,
+IlsString& cause);
static void ReplyMessage(const IlsMvMessage::SvMsg& msg);
static IlsBoolean AbortTransaction();
static void SetCatchExceptionMode();
static void UnsetCatchExceptionMode();
static void CreateDefaultCompAtStartup(IlsBoolean b);
static IlsMvServer& GetSingleton();
static IlsMvView* GetInteractingView()
Member Functions 
IlsMvServer(int threadMode = IlsMvServer::ILS_THREADED_DEFAULT);
This protected constructor is implicitly called when the dynamic view server is initialized (see the function IlsMvServerFactory::newInstance documented later in this class). The dynamic view server is actually created during this initialization phase by the current instance of IlsMvServerFactory. Only one dynamic view server can exist at a given time. The threadMode parameter specifies the execution mode of the server.
The primitive values are:
*IlsMvServer::ILS_SINGLE_THREAD
The server runs in a single thread and is not multithread safe.
*IlsMvServer::ILS_THREADED_SEND
The server is multithread safe. A thread is started for each component to send representation updates to the component. This mode is interesting if the server interacts with remote components because the server does not have to wait for the communication layer to send updates.
*IlsMvServer::ILS_THREAD_SAFE_TRANS
This mode tells Rogue Wave Server to create a Server transaction systematically each time a component transaction is processed, so as to allow concurrent transactions to be safely processed in other threads (see the member function beginTransaction). As the use of Server transactions impacts the performance of object access and modifications, this mode should be selected only when really necessary.
*IlsMvServer::ILS_THREADED_DEFAULT
When the threadMode parameter is set to this value, the mode IlsMvServer::ILS_SINGLE_THREAD is automatically selected, unless one of the environment variables ILS_THREADED_SEND or ILS_THREADED_SAFE_TRANS is set. Each of these variables selects the corresponding mode.
It is possible to combine the modes ILS_THREADED_SEND and ILS_THREAD_SAFE_TRANS. The value of the threadMode parameter is then obtained by a binary OR between the selected values.
Important: The modes ILS_THREADED_VIEW and ILS_THREADED_COMPONENT are deprecated.
Member Functions 
Initialization
[static] IlsBoolean Initialize(int& argc,
char** argv,
int threadMode=ILS_THREADED_DEFAULT);
A dynamic view server must be initialized before it can make use of other functions provided by the IlsMvServer API. Initialization must take place after the static member function IlsMvProcess::Initialize, or that of a derived class, has been called. This static member function takes the arguments of the command line as its parameters. It extracts and parses the following arguments:
*ilsr or –ilsres filename
These options load a resource file by executing the member function IlsMvServer::LoadResources, which takes the name of the resource file as its parameter.
*ilsd or –ilsdef
These options load a dynamic view type specification file by executing the member function IlsMvServer::LoadViewSpec, which takes the name of the view specification file as its parameter.
The threadMode parameter specifies the execution mode of the server. Refer to the protected IlsMvServer constructor for details about the various execution modes.
Note: The function IlsMvServer::Initialize calls the member function IlsModel::SetActive with ILS_ACTIVE as its parameter value.
Loading Dynamic View Type Specifications
[static] IlsBoolean LoadResources(IlsString resourceFile);
This static member function loads a resource file that contains a list of dynamic view type specification files. For each one of these files, it executes the member function IlsMvServer::LoadViewSpec by passing the specification file name as a parameter. The resource file is located by means of the access paths specified by the environment variable ILSPATH. This member function returns IlsTrue if the file is found. Otherwise, it returns IlsFalse.
[static] IlsBoolean LoadViewSpec(IlsString ilsFile,
IlsBoolean useXmlParser = IlsFalse);
This static member function loads a dynamic-view type specification file on the server. If a dynamic-view type specification with the same name has already been loaded, it is replaced with the new one. The dynamic-view type specification file is located by means of the access paths specified by the environment variable ILSPATH. This member function returns IlsTrue if the file is found and the dynamic-view type specification is valid. Otherwise, it returns IlsFalse. The parameter useXmlParser specifies to use the XML parser.
[static] IlsBoolean InterpretViewSpec(IlsString viewSpec,
IlsMvComponentItf* =0,
IlsBoolean useXmlParser = IlsFalse);
This static member function interprets the dynamic-view type specification passed by the viewSpec parameter. If the specification is valid, it is registered with the server. If another specification with the same name has already been registered, it is replaced by the new one.
The argument compItf is a pointer to a component interface. If this pointer is non-null, the error or information messages produced by the view interpreter are sent to the component (see the function IlsMvComponent::recvMessage).
The parameter useXmlParser specifies to use the XML parser.
This function returns IlsTrue if the string viewSpec contains a valid dynamic-view type specification. Otherwise, it returns IlsFalse.
Opening Views
Dynamic views are generally opened from an application component (see the function IlsMvComponent::openView). The following static member functions let you open a view from the server.
[static] IlsMvView* OpenView(const IlsString& objId,
const IlsString& viewId,
IlsMvComponentItf* compItfPtr=0,
const IlsMvValue* params=0,
unsigned long paramsNb=0,
IlsBoolean force=IlsFalse,
IlsOpenViewStatus* statusP=0);
This static member function opens the dynamic view whose label is passed as its second parameter on the object whose label is provided as its first parameter. A representation of the view is created in the component identified by the interface address compItfPtr. If the address is null, the representation of the view is created in a default local component created by the server.
*params is an array of IlsMvValue. It can be null. The values, if any, contained in this array are assigned to the dynamic view parameters on a sequential basis. When a value is void, it is discarded.
*paramsNb is the number of parameters in the params value array.
*If set to IlsTrue, the Boolean argument force forces the opening of the view, even if this view has already been opened by the component (and is still opened). The default value is IlsFalse, which means that the view is not duplicated.
*When the value pointed to by the parameter statusP is a non-null pointer, that value is assigned the status of the view-opening action. See the type definition IlsOpenViewStatus for more information on the possible values.
This member function returns a pointer to the new view or to the existing view if the following conditions are met:
*objId is associated with a Server object.
*viewId is the name of a view specification loaded in the server.
*The type of the Server object is compatible with the type specified as the view origin.
Otherwise, the function returns the null pointer.
[static] IlsMvView* OpenView(IlsViewed* obj,
const IlsString& viewId,
IlsMvComponentItf* compItfPtr=0,
const IlsMvValue* params=0,
unsigned long paramsNb=0,
IlsBoolean force=IlsFalse,
IlsOpenViewStatus* statusP=0);
This static member function is similar to the previous one, except that it takes a pointer to a Server object, instead of an object identifier, as its first argument. If the pointer is null, the view is created with no origin.
When the value pointed to by the parameter statusP is a non-null pointer, that value is assigned the status of the view-opening action. See the type definition IlsOpenViewStatus for more information on the possible values.
Execution Loop
[static] IlsBoolean Run(int nb=0,IlsTime* timeOut=0);
This static member function runs the execution loop of a dynamic view server.
*It takes the number of interaction cycles to be performed as its first argument. If nb equals 0, the loop will never stop.
*The timeOut argument specifies how long the server will wait for a request to be issued by a component. If the pointer timeout is null, the function loops indefinitely. If no request arrives during this lapse of time, the execution loop exits. Otherwise, the function stops once the specified number of interaction cycles has been executed if nb is a number strictly greater than 0.
The execution loop is also interrupted if the member function processRequest executed during an interaction cycle returns IlsFalse.
An interaction cycle executes the following phases sequentially:
1. Begin the interaction cycle: The interaction cycle starts with a call to the virtual function IlsViewServer::beginInteractionCycle. If this member function returns IlsFalse, the execution loop ends.
2. Execute an action: The member function processRequest is called to execute an action. Any viewed object or viewed list of objects modified by an action is marked as requiring notification.
The reference counter of every viewed object that has been marked is incremented to prevent these objects from being deleted before the notification phase. If the function processRequest returns IlsFalse, the interaction cycle is stopped before the notification phase is executed, and the execution loop terminates.
3. Re-evaluate and notify: These two phases are performed within the member function Notify, provided automatic notification mode is selected.
*First, all eager derived data members that are marked out-of-date are reevaluated.
*Then notification is carried out.
At the end of notification, the reference counter of each marked object is decremented, and the objects are unmarked. Every object with a null reference counter is destroyed. Viewed objects that are the target of relations owned by destroyed objects are thus modified. They are marked in turn as requiring notification. Consequently, the reevaluation/notification phase loops until all eager derived members are updated and no new viewed object requires notification.
4. Ends a cycle: A call to the virtual function IlsViewServer::endInteractionCycle terminates an interaction cycle. If this member function returns IlsFalse, the execution loop stops.
Another technique is to execute an interaction cycle manually. To do so, you have to call the static member function Notify explicitly after any action performed on viewed objects and after creating or closing a view.
[static] void Notify();
This static member function performs notification and/or re-evaluation during an interaction cycle. You can use it to start a notification cycle manually for a dynamic view server— for instance, when some actions are performed on the model outside any transaction, because in that case, notification is not automatic.
This function carries out the following steps sequentially:
1. It reevaluates each derived data member that is marked as out-of-date.
2. It synchronizes the beginning of notification for all views and components running in their own threads.
3. It notifies the component that origins and other objects to which the associated view subscribes have been updated since the last notification phase. Notification follows the order in which updates occurred.
4. It synchronizes the end of notification for all views and components running in their own threads.
5. It deletes smart pointers created by the notification engine to point to the server objects that were updated during the interaction cycle. If the notification engine is the last one to keep a smart pointer to an object, deleting this smart pointer will destroy the object to which it points. This may cause relations to break and consequently it may requires updates of other objects. In this case, the notification phase loops until all updates are performed.
[virtual] void beginNotification();
If you override this virtual member function, you must call the inherited function.
[virtual] void endNotification();
If you override this virtual member function, you must call the inherited function.
void registerEndCycleTask(IlsCallbackFunc cb, IlsAny arg);
This member function allows you to register a callback which will be executed at the end of the notification cycle. These callbacks are executed only once and are unregistered after execution. If such callbacks modify the server model, you should restart a new notification cycle by calling the static member function IlsMvServer::Notify.
[static] void Stop();
This static member function interrupts the execution loop once the current interaction cycle is over.
Transaction Control
The way a dynamic view server processes a component transaction can be controlled both on the component side and on the server side.
*On the component side, the status passed to the function IlsMvComponent::commitC2STransaction allows you to indicate whether the server must:
*acknowledge the transaction or not;
*roll back the transaction or not when an update fails;
*execute a notification cycle or not if the transaction is successful.
*On the server side, the virtual functions beginTransaction and endTransaction are called before and after the component transaction request has been executed. These functions interpret the status of the component transaction along with the thread mode that was used to initialize the server. The resulting decisions are:
*First, whether a Server transaction will be created or not;
*Then, whether a notification cycle will take place or not if the transaction is created and successful.
[virtual] IlsBoolean beginTransaction(IlsMvComponentItf& comp,
IlsTransactionId tId,
IlsC2STransStatus tStat);
This virtual member function is executed by Server at the beginning of a transaction that was opened by the component. This function takes the following parameters:
*The comp parameter identifies the component interface.
*The tId parameter is the identifier of the transaction.
*The tStat parameter is the status of the transaction as assigned by the component (see the member function IlsMvComponent::commitC2STransaction).
When this function is not overridden, it implicitly creates a Server transaction, except if:
*The flag ILS_C2S_NO_ROLLBACK is set in the parameter tStat, and
*The thread-safe transaction mode has not been selected at server initialization. (See the IlsMvServer constructor.)
When this function returns IlsFalse, the transaction is not executed. Instead, it is rolled back on the component side.
[virtual] IlsBoolean endTransaction(IlsMvComponentItf& comp,
IlsTransactionId tId,
IlsC2STransStatus tStat);
IlsBoolean result);
This virtual member function is executed by Server at the end of a transaction that was opened by the component. This function takes the following parameters:
*The comp parameter identifies the component interface.
*The tId parameter is the identifier of the transaction.
*The tStat parameter is the status of the transaction as assigned by the component. (See the member function IlsMvComponent::commitC2STransaction.)
*The parameter result specifies the results of the transaction execution.
When this function is not overridden, it executes the following instructions, depending on the values of the tStat and result parameters:
*When result is set to IlsTrue or ILS_C2S_NO_ROLLBACK: is set in tStat parameter:
*If a Server transaction was implicitly created in beginTransaction, this transaction is committed.
*If the value ILS_C2S_NO_NOTIFY is not set in the tStat parameter, a notification cycle is executed.
*Otherwise, if a transaction was implicitly created in the function beginTransaction, this transaction is rolled back. No notification cycle is executed.
*In any other case, nothing happens.
In all cases, this function returns the value of the parameter result.
*When this function returns IlsFalse and the tStat parameter is not set to ILS_C2S_NO_ROLLBACK, the transaction is rolled back on the component side.
*When this function returns IlsTrue and the tStat parameter is not set to ILS_C2S_NO_ACKNOWLEDGE, the transaction is acknowledged on the component side.
Identifying Objects
[static] IlsBoolean DeclObjectLabel(IlsViewed& obj,IlsString label);
This static member function associates a label with a server object and stores the association in the server. Using this association, an application component can open a view by using the object label as a parameter. The application component can also query the server to obtain a list of labels that match a given pattern. For details, see the functions IlsMvComponent::openView and IlsMvComponent::getObjectIds.
This member function returns IlsFalse if the object has already an associated label or if the specified label already has been assigned to another object. If at least one view has subscribed to the object, the association is automatically broken when the server object is suppressed or cut. It is up to the user to undeclare and redeclare the association each time the label has to be changed.
[static] IlsString GetLabelOfObject(IlsViewed& object);
This static member function returns the label assigned to an object. If object has no label, it returns the null string.
[static] IlsViewed* GetObjectFromLabel(IlsString label);
This static member function returns the Server object with which the string label is associated.
[static] IlsBoolean UndeclObjectLabel(IlsViewed& object);
This static member function breaks the association established between the Server object object and a label, if any. It returns IlsTrue if an association was found. Otherwise, it returns IlsFalse.
[static] IlsBoolean UndeclObjectLabel(IlsString label);
This static member function breaks any association established between label and a server object. It returns IlsTrue if an association was found. Otherwise, it returns IlsFalse. As objects are maintained in the association table through smart pointers, this method may delete any object that is
Interactors
[static] IlsMvComponentItf* GetInteractor();
This static member function returns a pointer to the interface of the component that issued the request handled during the current interaction cycle. It returns a null pointer if no interaction cycle is in progress.
[static] IlsMvComponentItf* GetDefaultComp();
This static member function returns a pointer to the interface of the default component that is implicitly created by Server when a view is opened with no associated component. The default component is local to the server. See the member functions OpenView for more information. By default this function returns a null pointer.
[static] IlsMvUser* GetInteractingUser();
This static member function returns the current interacting user by calling the virtual function getInteractingUser.
[virtual] IlsMvUser* getInteractingUser();
This virtual member function returns the user associated with the interface of the component that issued the request handled during the current interaction cycle. It returns a null pointer if no interaction cycle is in progress.
[static] IlsMvUser* GetDefaultUser();
This static member function returns the user associated with the default component that is linked to the server. This function return null if the default component has not yet been initialized. See also the static member function GetDefaultComp.
Trace Mode
[static] void SetTrace();
This static member function activates the trace mode of the server. Trace mode can also be activated by the ILS_TRACE_TIME environment variable.
[static] void SetTraceTime(IlsBoolean t=IlsTrue);
Use this static member function to enable or disable time-tracing mode. In this mode, timing information are collected and displayed. The following durations are collected:
*Process Request: time to process an incoming request
*receiving: time to receive a message on the communication layer. (This duration may not be available for all communication layers.)
*decoding: time to decode a message and begin to execute the transaction.
*user transaction: time spent between the call to IlsMvServer::beginTransaction and the call to IlsMvServer::endTransaction.
*Notification: duration of the notification cycle. This duration includes the time needed to send messages to the communication layer if ILS_THREADED_SEND mode is not active. However, if this mode is active, Send traces may be interlaced with Notification traces.
*Send: time to send a message to the communication layer
*encoding: time to encode the message.
*Interaction Cycle: duration of the whole interaction cycle. Corresponds to the time when the server cannot handle a request.
See the ILS_TRACE_TIME environment variable.
[static] IlsBoolean IsTraced();
This static member function returns IlsTrue if the server is operating in trace mode.
[static] IlsBoolean IsTracedTime();
This static member function returns IlsTrue if time tracing-mode is enabled.
Component Connection
[virtual] void onConnect(IlsMvComponentItf& compItf);
This virtual member function is called each time a new component connects to the server. It takes the interface of this component compItf as its parameter. If the server execution mode is set to IlsMvServer::ILS_THREADED_SEND, this function creates a thread that sends the updates to the component.
This function can be overridden. See the IlsMvServer constructor for details about the various execution modes.
[virtual] void onDisconnect(IlsMvComponentItf& compItf);
This virtual member function is called when a component disconnects from the server —that is, when the component interface compItf is deleted. It does nothing but can be overridden.
[static] IlsMvComponentItf* GetComponent(IlsMvComponentId id);
This static member function returns the component identified by id, or null if the component has already been disconnected.
[static] IlsMvComponentItf*const* GetComponents(int& dim);
This static member function returns an array of all the components that are currently connected to the server. The argument dim receives the size of the array. The array may contain holes (that is, null entries) corresponding to components that have already been disconnected. This array is managed by Rogue Wave Server internally. You must not delete it.
View Handling
[virtual] void onOpenView(IlsMvView&);
This virtual member function is called each time a new dynamic view is opened. By default, this function has no effect. It can be overridden.
[virtual] void onCloseView(IlsMvView&);
This virtual member function is executed each time a view is closed on the server. It does nothing, but can be overridden.
Other Functions
[virtual] IlsBoolean acceptConnection(IlsMvComponentItf&, IlsString& cause);
This virtual member function is called before the method onConnect but after the user has been created and bound (see IlsMvUsr::onBind). At this point, you can accept the connection by returning true or reject it by returning false. If you reject the connection, the component is disconnected and a connection error message is sent to the component (see IlsMvComponent::connectionDenied). In this case, you should set the cause parameter to explain why you rejected the connection. If you accept the connection, you can set the cause parameter that will be given back to the component (see IlsMvComponent::connectionAllowed).
Note that this method is not called for the default component. A default linked component is automatically created when a server starts handling linked views opened on the server.
[static] void ReplyMessage(const IlsMvMessage::SvMsg& msg);
This static member function is used to send a message of type IlsMvMessage::SvMsg to the component that sent the transaction currently processed by the server (see the GetInteractor function documented above for details). The virtual member function IlsMvComponent::recvMessage will be executed on the component side.
[static] IlsBoolean AbortTransaction();
This static member function instructs the server to abort a component transaction handled by the server. This transaction will be rolled back both on the server side and on the component side. This function returns IlsTrue, unless the server was not processing a component transaction.
[static] void SetCatchExceptionMode();
[static] void UnsetCatchExceptionMode();
Each time a transaction is committed by a component (see the member function IlsMvComponent::commitC2STransaction), a transaction is executed at the server level (see the class IlsTransaction).
By default, any instance of IlsException raised by the Server when this transaction is executed is caught and results in the transaction being rolled back both at server and component levels. The static member function UnsetCatchExceptionMode disables exception-catching mode for subsequent transactions, while the SetCatchExceptionMode static member function enables the mode again.
[static] void CreateDefaultCompAtStartup(IlsBoolean b);
By default, Server instantiates the default component used for linked views at startup. Use this function if you need to change the default behavior.
[static] IlsMvServer& GetSingleton();
This static member function retrieves a reference of the unique instance of the dynamic view server that has been initialized in the application. An error message is issued if this method is invoked before the server has been initialized.
[static] IlsMvView* GetInteractingView();
This static member function retrieves the interacting view while an update request from a component is processed by the server. The interactive view is set if the update is initialized at representation-object level (see IlsRpObject::onUpdate or execCallback).
Protected Member Functions 
[virtual] IlsBoolean processRequest(IlsTime* timeout=0);
This protected virtual member function handles a request. It calls the virtual function IlsMvProcess::Request.
See Also 
IlsMvComponent, IlsMvComponentItf, IlsMvMessage, IlsTransaction

Version 5.8
Copyright © 2014, Rogue Wave Software, Inc. All Rights Reserved.