Macros for Runtime Access

Tutorial: Building an Rogue Wave Server Application > Designing the Server Object Model > Enabling Runtime Access to the Object Model > Macros for Runtime Access

The macros described further on are defined in the header file include/ilserver/rtmodel.h of the Rogue Wave® Server standard distribution. Therefore, you must include this file in the network.h file as follows:

#include <ilserver/rtmodel.h>

Declaring Server Model Classes

The macro ILS_ENTITY_DECL is added to each class in the model that derives from IlsEntity. This macro takes the name of the related class as its argument. For example:

class Network: public IlsEntity

{

...

ILS_ENTITY_DECL(Network)

};

Similarly, the macro ILS_OBJECT_DECL is added to each class in the model that derives from IlsObject. This macro takes the name of the related class as its argument.
For example:

class Domain: public IlsObject

{

...

ILS_OBJECT_DECL(Domain)

};

In addition to these header file macros, you must also add the following macros to the source file where your classes are defined:

ILS_ENTITY_BEGIN(Network)

ILS_ENTITY_END(Network)

ILS_OBJECT_BEGIN(Domain)

ILS_OBJECT_END(Domain)


Note: Users of the previous versions of Rogue Wave Server should note that these macros replace and extend the macros ILS_VIEWED_DECL and ILS_VIEWED_DEF.

These macros expand into a set of static variables. At initialization, these variables automatically create a runtime type associated with the Network and Domain classes in the server model interpreter.

The macros ILS_ENTITY_XXX and ILS_OBJECT_XXX are very similar. The main difference, though, is the following:

The macros ILS_ENTITY_XXX register the data member identifier as a runtime attribute of the Network runtime type. This type then requires a constructor that takes the identifier value as a parameter.

On the other hand, the macro ILS_OBJECT_DECL requires a default constructor for the class Domain.

These constructors are registered with their respective runtime types and are used implicitly to create new instances of this class in the server when requested via component transactions.

Additional macros are supplied to declare server model subclasses to the server model interpreter. Using these macros, the interpreter supports polymorphism and inheritance of runtime attributes, relations, and functions. See the Rogue Wave Server Reference Manual for more information.

Declaring Relations

Each relation that needs to be referenced in a dynamic view type specification must be declared as a relation of a runtime type. This is done by using macros that are specific to the type of the relation (uses, owns, inverted) and the arity of the relation (unary or n-ary).


Note: Relation-related macros do not indicate the precise nature of the relation they specify (that is, list, array, or set).

These macros must be enclosed between the BEGIN and END macros declared for the type that defines the relations.

For instance, for the type Domain:

ILS_OBJECT_BEGIN(Domain)

ILS_OWNS_N(Domain,Node,nodes)

ILS_OWNS_N(Domain,Line,lines)

ILS_INVERTED_1(Domain,Network,network,domains)

ILS_OBJECT_END(Domain)

The ILS_OWNS_N macros declare nodes and lines as n-ary ownership relations for the type Domain with Node and Line as target types respectively.

The ILS_INVERTED_1 macro declares network as a unary inverted relation for the type Domain with Network as target type. The argument domains specifies the name of the original direct relation.

These macros register the relations in the Domain runtime type with their default accessor and modifier. These functions will be used by the view interpreter to get and set the target(s) of the relations as kept by the Domain objects that are represented and edited through dynamic views. Other macros are supplied to declare user-defined accessors and modifiers for relations.

See the macros ILS_RW_RELATION_XXX and ILS_R_RELATION_XXX in the Rogue Wave Server Reference Manual.

Declaring Attributes

Like relations, any attribute that needs to be referenced in a dynamic view type specification must be declared as an attribute of a runtime type. To do so, you will use different macros depending on whether the attributes are entry data members or derived data members.

These macros must be enclosed between the BEGIN and END macros declared for the type that defines the attributes.

For instance, for the type Node (relations are omitted):

ILS_OBJECT_BEGIN(Node)

ILS_ENTRY_STRING(Node,name)

ILS_ENTRY_INT(Node,x)

ILS_ENTRY_INT(Node,y)

ILS_DERIVED_INT(Node,inputCapacity)

ILS_DERIVED_INT(Node,outputCapacity)

ILS_OBJECT_END(Node)

The ILS_ENTRY_STRING macro declares the attribute name as a string entry data member for the type Domain.

The ILS_ENTRY_INT macros declare the attributes x and y as integer entry data members for the type Domain.

The ILS_DERIVED_INT macros declare the attributes inputCapacity and outputCapacity as integer derived data members for the type Domain.

These macros declare the attributes in the Domain runtime type with the default accessors and modifiers of the associated data members. These functions are used by the view interpreter to get and set the values of the data members attached to the Domain objects that are represented and edited through dynamic views. Other macros are supplied to declare user-defined accessors and modifiers for runtime attributes.

See the macros ILS_RW_ATTRIBUTE_XXX, ILS_R_ATTRIBUTE_XXX and ILS_W_ENTRY_XXX in the Rogue Wave Server Reference Manual.

Macros for the Network Model

Here is the full set of macros that should be added to the network.cpp file to allow runtime access to the Network object model:

ILS_ENTITY_BEGIN(Network)

ILS_OWNS_N(Network,Domain,domains)

ILS_ENTITY_END(Network)

ILS_OBJECT_BEGIN(Domain)

ILS_ENTRY_STRING(Domain,name)

ILS_OWNS_N(Domain,Node,nodes)

ILS_OWNS_N(Domain,Line,lines)

ILS_INVERTED_1(Domain,Network,network,domains)

ILS_OBJECT_END(Domain)

ILS_OBJECT_BEGIN(Node)

ILS_ENTRY_STRING(Node,name)

ILS_ENTRY_INT(Node,x)

ILS_ENTRY_INT(Node,y)

ILS_INVERTED_1(Node,Domain,domain,nodes)

ILS_INVERTED_N(Node,Line,inputLines,input)

ILS_INVERTED_N(Node,Line,outputLines,output)

ILS_DERIVED_INT(Node,inputCapacity)

ILS_DERIVED_INT(Node,outputCapacity)

ILS_OBJECT_END(Node)

ILS_OBJECT_BEGIN(Line)

ILS_ENTRY_STRING(Line,name)

ILS_ENTRY_INT(Line,capacity)

ILS_USES_1(Line,Node,input)

ILS_USES_1(Line,Node,output)

ILS_INVERTED_1(Line,Domain,domain,lines)

ILS_OBJECT_END(Line)

Summary

In this section, you have learned how to declare server classes, relations, and attributes for runtime access to the Network object model using a specific set of macros. The server view interpreter will use these declarations to validate the dynamic view type specifications and to access the data and function members of the server objects to which views have subscribed.

Version 5.8