IlsMvProcess

Category

Dynamic view-related class (component and server)

Inheritance Path

IlsMvProcess

Description

The class IlsMvProcess implements a set of functions needed by any Rogue Wave Server component or server process. This class lets you define a linked Rogue Wave Server application —that is, an application in which server and component(s) are implemented within the same process. It is also used as the base class for the implementation of distributed server process classes. These derived classes are specific to the communication layer and event loop used:

The class IlsTcpMvProcess initializes an Rogue Wave Server process that uses the underlying Rogue Wave Server MvTCP (TCP/IP) communication layer.

The class IlsIlvTcpMvProcess initializes an Rogue Wave Server/Rogue Wave Views process that uses the underlying Rogue Wave Server TCP/IP communication layer and execute the graphical event loop.

The class IlsCorbaMvProcess is the base class for all Rogue Wave Server processes that use a Corba Object Request Broker.

The class IlsOrbixMvProcess initializes an Rogue Wave Server process that uses IONA’s Orbix.

The class IlsIlvOrbixMvProcess initializes an Rogue Wave Server/Rogue Wave Views process that uses IONA’s Orbix to communicate and executes the Rogue Wave Views event loop.

The class IlsMvProcess defines a set of virtual functions whose purpose is to initialize and execute a Server process and which are overridden in the derived subclasses.

Libraries

Header File

#include <ilserver/mvproc.h>

Synopsis

class IlsMvProcess{

public:

IlsMvProcess();

virtual ~IlsMvProcess();

IlsMvProcess* GetSingletonPtr();

Initialization

public:

static IlsBoolean Initialize(int& argc,char** argv);

static IlsBoolean IsInitialized();

protected:

IlsBoolean initialize(int& argc,char** argv);

virtual IlsBoolean localInitialize(int& argc,char** argv);

Connection/Disconnection

public:

static IlsMvEndPoint* Connect(const IlsString& procName,

const IlsString& hostName,

IlsBoolean toServer=IlsTrue);

static int DoConnect();

static IlsMvEndPoint* GetEndPoint(const IlsString& procName,

const IlsString& hostName,

IlsBoolean isComp);

IlsMvEndPoint* const* getEndPoints(int& dim);

static IlsMvComponent* GetComponent

(const IlsString& serverName,

const IlsString& hostName);

static IlsBoolean DisconnectOnComError();

static void DisconnectOnComError(IlsBoolean b);

Execution

static IlsBoolean Run(int nb=0,IlsTime* t=0);

virtual IlsBoolean processRequest(IlsTime* timeOut);

static IlsBoolean ProcessRequest(IlsTime* timeOut);

virtual void beforeRequest();

virtual void afterRequest();

static void Stop();

Process Name

static IlsBoolean SetName(const IlsString& name);

static const IlsString& GetName();

};

Constructor

IlsMvProcess();

This default constructor is invoked by the Initialize static member function or by the constructor of a derived class. Only one instance of IlsMvProcess can be created within a process.

Destructor

virtual ~IlsMvProcess();

The instance of IlsMvProcess is automatically destroyed by Rogue Wave Server when the process ends.

Member Functions

[static] IlsMvProcess* GetSingletonPtr();

This static member function returns the single instance of IlsMvProcess that has been initialized or null if none has been initialized. The return value points to an instance of IlsTcpMvProcess or of another actual type of process depending on the initialization done.

Initialization

[static] IlsBoolean Initialize(int& argc,char** argv);

This static member function initializes a linked Server process —that is, a process including both server and component(s). This function —or one of the Initialize member functions of a derived class— must be called once at the beginning of the process before any other server or component is initialized. The arguments argc and argv are those of the main function. See the initialize member function below for more information about the options supported.

[static] IlsBoolean IsInitialized();

This static member function returns IlsTrue if the process has already been initialized or IlsFalse otherwise.

IlsBoolean initialize(int& argc,char** argv);

This member function initializes an instance of IlsMvProcess.

It is invoked by the static member functions IlsTcpMvProcess::Initialize and IlsOrbixMvProcess::Initialize. It must be invoked by any initialization member function belonging to a subtype of IlsMvProcess. It takes the arguments of the command line as its parameters. It first initializes the process by calling the virtual member function localInitialize. If that member function returns IlsTrue, it then parses and interprets the command line arguments:

-ilsname serverName or -ilsn serverName

This option is used by a distributed server to register the process with the name serverName in the communication layer. This name will be used by the component to connect to this server.

-ilsconnect serverName[@hostName] or -ilsc serverName[@hostName]

This option requests the connection of a component process to the server process serverName running on the machine hostName, or on the local host if no host name is specified.

-ilsview objLabel.viewName or -ilsv objLabel.viewName

This option requests the opening of the dynamic view viewName for the Server object objLabel in asynchronous mode. The request is sent to the server that is specified in the option -ilsconnect or is executed locally when there is no such previous option.

-ilspath directory or ilsp directory

This option adds the directory at the beginning of the ILSPATH environment variable. This ILSPATH variable is used to find the dynamic-view specification or resource files. You may want to refer to the member functions IlsMvServer::Initialize, IlsMvServer::LoadViewSpec, and IlsMvServer::LoadResources.

-ilshome directory or ilsh directory

This option sets the environment variable ILSHOME to the directory path. This environment variable is used by Server/Views components to find general data files.

-ilstimeout nbSec or ilst nbSec

This option sets nbSec as the timeout to be passed to the processRequest member function.

-ilstrace

This option sets the trace mode for dynamic views either on the server side or on the component side. It is equivalent to setting the environment variable ILS_TRACE.

This member function returns IlsFalse if localInitialize returns IlsFalse or if one of the -ilsconnect options fails. Otherwise, it returns IlsTrue.

[virtual] IlsBoolean localInitialize(int& argc,char** argv);

This virtual member function is invoked by the member function initialize. It takes the arguments of the command line as its parameters. It has an empty body but is overridden in subclasses of IlsMvProcess.

Connection/Disconnection

[static] IlsMvEndPoint* Connect(const IlsString& procName,

const IlsString& hostName,

IlsBoolean toServer=IlsTrue);

This static member function enables connection to the process procName running on the host hostName. When hostName is an empty string, the local host is selected.

The parameter procName can identify either a distributed server or a distributed component.

If the connection is successful, the function returns a pointer to the connection end point created. You can narrow the result to the derived type IlsMvComponent in case of a connection to a server or to the derived type IlsMvComponentItf in case of a connection to a component. See the member functions IlsMvComponent::Narrow and IlsMvComponentItf::Narrow for details. If the connection fails, the function returns the null pointer.


Note: For a connection to a server, you can use the function IlsMvComponent::Connect instead of IlsMvProcess::Connect.

[static] int DoConnect();

This static member function executes the connection to the server(s) specified in the command line using one of the -ilsc or -ilsconnect options. It returns 0 if all connections succeed. Otherwise, it returns the number of unsuccessful connections.

[static] IlsMvEndPoint* GetEndPoint(const IlsString& procName,

const IlsString& hostName,

IlsBoolean isComp);

This static member function returns a pointer to the local end point of the connection established with the process procName on host hostName. When hostName is an empty string, the local host is selected. The Boolean parameter isComp indicates whether the connected process has to be a component (if it is set to IlsFalse) or a server (if it is set to IlsTrue).

The functions returns the null pointer if no connection is found.

IlsMvEndPoint* const* getEndPoints(int& dim);

This member function returns an array of all the end points created in the process. The dim argument is the number of end points in the array. You can use the function IlsMvEndPoint::isComponent to check that an end point is an instance of IlsMvComponent or of a derived class.

[static] IlsMvComponent* GetComponent(const IlsString& serverName,

const IlsString& hostName);

This static member function is similar to the function GetEndPoint, except that it explicitly looks for a component connected to the server named serverName on host hostName.

[static] IlsBoolean DisconnectOnComError();

This static member function returns the value of the disconnectOnError property. When this property is set, a connection to a peer process will be broken if a low-level error occurs while data is being sent. If the server-to-component connection is broken but the disconnect event has not been received from the communication layer, an error is raised when the process tries to send data. By default, this property is IlsTrue and, in this case, the connection is closed.

[static] void SetDisconnectOnComError(IlsBoolean b);

This static member function sets the value of the disconnectOnError property.

Execution

[static] IlsBoolean Run(int nb=0,IlsTime* t=0);

This static member function implements the default event loop for dynamic-view based processes. Its main purpose is to provide an abstract interface to execute a distributed component that does not run any other event loop. This function requires that the virtual function processRequest be overridden in the actual type of the IlsMvProcess singleton, as is the case for IlsTcpMvProcess or IlsOrbixMvProcess.

The argument nb specifies the number of requests to execute. A negative or null value means an infinite number.

The argument t specifies the timeout to be passed to the function processRequest. If it is null, no timeout is considered.

The Run function stops when it has finished processing the number of requests set by nb (if this number is greater than 0), or if the timeout has been reached during processRequest, or if the function Stop has been called. It returns IlsTrue if the number of processed requests is equal to nb or IlsFalse if a timeout occurred.


Note: If this function is called with a null or negative value for the nb argument, then the only possible return value is false when a timeout occurs.

[virtual] IlsBoolean processRequest(IlsTime* timeOut);

This virtual member function is called by IlsMvServer::Run to execute a request issued by a component. To be effective, it must be overridden in a subtype of IlsMvProcess, as in the classes IlsTcpMvProcess and IlsOrbixMvProcess. The parameter timeOut defines the maximum time during which the function must wait for an incoming component request. If no request is input after this lapse, the function should return IlsFalse, thus causing the view-server execution loop to stop. Otherwise, it returns IlsTrue. As implemented by an IlsMvProcess object, this function does nothing except return IlsFalse.

[static] IlsBoolean ProcessRequest(IlsTime* timeOut);

This static member function calls the virtual function processRequest on the IlsMvProcess singleton.

[virtual] void beforeRequest();

This virtual member function is called by the subclass of IlsMvProcess before it a request received on the communication layer is processed. If you override this method, you must call the base class method.

[virtual] void afterRequest();

This virtual member function is called by the subclass of IlsMvProcess after a request received on the communication layer has been processed. If you override this method, you must call the base class method.

[static] void Stop();

This static member function stops the Run event loop.

Process Name

[static] IlsBoolean SetName(const IlsString& name);

This static member function assigns a name to the current process to enable distributed applications to connect to the process. See the function IlsMvProcess::Connect and IlsMvComponent::Connect.

This function is implicitly used by Rogue Wave Server when the command line option

-ilsname (or -ilsn)

is used.

[static] const IlsString& GetName();

This static member function returns the name assigned to the process or by default the null string.