Basic Macros

Dynamic View Services > Defining Runtime Access to the Server Model > Declaring Model Classes > Basic Macros

Basic Macros

Entity classes and object classes are declared using different sets of macros:

ILS_ENTITY_DECL for an entity class, such as Company.

ILS_OBJECT_DECL or an object class, such as Employee.

These macros are generally appended at end of the declaration. However, if you want to insert them somewhere else in the declarations, notice that they end with the private access control directive.

Let us assume that our server object model for the Company example is declared in a header file named company.h and defined in a source file named company.cpp. Company.h contains the following code:

#include<ilserver/model.h>

#include<ilserver/rtmodel.h>

class Company: public IlsEntity {

...

ILS_ENTITY_DECL(Company)

};

class Employee: public IlsObject {

...

ILS_OBJECT_DECL(Employee)

};

Symmetrically, you must write, for each of these macros, the corresponding block of macros in the file company.cpp or in another source file that can “see” the classes, as follows:

#include <company.h>

ILS_ENTITY_BEGIN(Company)

...

ILS_ENTITY_END(Company)

ILS_OBJECT_BEGIN(Employee)

...

ILS_OBJECT_END(Employee)

Between each pair of BEGIN/END macros, you must insert the macros for those members of the corresponding class that you want to declare as runtime data members, as explained in the following sections.

Once expanded, both kinds of macros (ILS_ENTITY_XXX and ILS_OBJECT_XXX) declare a global variable. As a side effect of the initialization of this variable, an internal object of type IlsObjectType is created in the server model interpreter (see the class IlsModelInterpreter). This object implements the runtime type associated with the C++ type that appears as the argument to the macros. This type includes the C++ class information required by the server model interpreter, that is, a name, a constructor and a set of named attributes, relations and functions with accessors and optional modifiers.


Note: We will refer to the runtime type T as the object inside the model interpreter that describes the C++ class named T.

Both kinds of class-declaration macros implicitly declare a narrowing function that allows you to safely downcast the base type IlsViewed, which is used in the signature of many functions of the server API, to its application type. In our example, the following narrowing functions are declared:

Company* Company::Narrow(IlsViewed&)

Employee* Employee::Narrow(IlsViewed&)

The following code sample illustrates the semantics of these narrowing functions:

Company& c=...;

IlsViewed& v=c;

Company* cp=Company::Narrow(v);

Employee* ep=Employee::Narrow(v);

assert(cp==&c);

assert(ep==0);

The macros ILS_ENTITY_XXX and ILS_OBJECT_XXX differ in several aspects:

The ILS_ENTITY_XXX macros implicitly declare identifier as a string attribute of the runtime type with an accessor, a modifier, and a modification test. In our example, the attribute identifier is declared on the runtime type Company. It is associated with the following functions:

Accessor: IlsEntity::getIdentifier

Modifier: IlsEntity::rename

Modification test: IlsEntity::isIdentifierModified

The macros ILS_OBJECT_XXX require a default constructor for the class whereas the macros ILS_ENTITY_XXX require a constructor that can be called with an argument of type IlsString. In our example, the classes Company and Employee must declare the following constructors:

Company::Company(IlsString id)

Employee::Employee()

These constructors are automatically used on the server side when a new representation object is created and added within a collector on the component side (see “Collectors”.). In the Company example, the identifier of the new company is passed as an argument to the constructor, provided some operational conditions are fulfilled, as detailed in the description of the macro ILS_ENTITY_DECL in the Rogue Wave® Server Reference Manual.


Note: It is not mandatory to use the macros ILS_ENTITY_XXX to declare an entity class to the server model interpreter. You can use the macros ILS_OBJECT_XXX. If you do so, no attribute identifier is implicitly declared and a default constructor is required.

Version 5.8