IlsUsesList

Category

Modeling class template

Inheritance Path

Description

Rogue Wave Server lets you declare use relations among object classes. Use relations are relations in which one particular object can be used by any number of other objects. The user object can also use one or more other objects. One-to-many relations can be defined as list-relations or as set-relations. Unlike set-relations, target objects in list-relations are listed in sequential order. Such relations are declared within the user class as instances of the class template IlsUsesList.

UserType and UsedType must derive publicly and directly or transitively from IlsEntity or IlsObject. Derivation must be public.

Library

Header File

#include <ilserver/model.h>

Synopsis

template<class UserType, class UsedType>

class IlsUsesList

{

public:

IlsUsesList

(UserType& user,

IlsRelationId identifier=IlsDefaultRelationId,

IlsActivity activity=IlsModel::GetDefaultActivity(),

IlsCardinality mincard=0,

IlsCardinality maxcard=ILS_UNLIMITED_MAXCARD,

Initials& used=NewInitial(),

IlsBoolean check_card=IlsTrue);

virtual ~IlsUsesList();

static Initial& NewInitial();

UserType& getUser();

IlsActivity getActivity() const;

IlsRelationId getIdentifier();

IlsCardinality getMinCard();

IlsCardinality getMaxCard();

unsigned int getLength() const;

virtual void cut(Partial&);

Myself& remove(Partial&);

Myself& operator<<(CUsedTypePR newe);

Myself& operator>>(CUsedTypePR olde);

Myself& cons(CUsedTypePR newe);

Myself& remove(CUsedTypePR olde);

Myself& clear();

CUsedTypePR operator[](int);

CUsedTypePR getFirst();

CUsedTypePR getLast();

IlsBoolean isIn(CUsedTypePR);

UsedType** getAdded(int& how_many);

UsedType** getRemoved(int& how_many);

IlsBoolean isLengthModified();

IlsBoolean isModified();

};

Constructor

IlsUsesList(UserType& user,

IlsRelationId identifier=IlsDefaultRelationId,

IlsActivity activity=IlsModel::GetDefaultActivity(),

IlsCardinality mincard=0,

IlsCardinality maxcard=ILS_UNLIMITED_MAXCARD,

Initials& used=NewInitial(),

IlsBoolean check_card=IlsTrue);

This constructor takes the following arguments:

A reference to the user object.

A relation identifier of type IlsRelationId. This argument defaults to IlsDefaultRelationId. It is generally used to invert relations.

The argument activity specifies whether the relation is active or not. A relation is active if its modification sets off the recomputation of derived data members. The default value is the one returned by the function IlsModel::GetDefaultActivity, which is ILS_INACTIVE by default.

The minimal cardinality of the list. This argument is optional and defaults to zero.

The maximal cardinality, which can be an unsigned integer or indeterminate. This argument is optional and defaults to ILS_UNLIMITED_MAXCARD.

The argument used is a list of objects. Its default value, newInitial, creates an empty list. If the value of used is less than the value assigned to mincard, the exception IlsMinCardViolated is thrown. If it is greater than the value of maxcard, the exception IlsMaxCardViolated is thrown.

The argument check_card specifies whether cardinalities should be checked at object construction.

Destructor

virtual ~IlsUsesList();

This destructor breaks all relations in the list.

Member Functions

IlsActivity getActivity() const;

This member function returns ILS_ACTIVE if the relation has been set as active. Otherwise, it returns ILS_INACTIVE. For details, see the constructor.

[static] Initial& NewInitial();

This static member function builds an empty list which is used by the constructor as the default value of the argument used.

UserType& getUser();

This member function returns a reference to the user object. This function is useful especially in the case of derived relations.

IlsRelationId getIdentifier();

This function returns the relation identifier.

unsigned int getLength() const;

This member function returns the number of objects in the list.

[virtual] void cut(Partial&);

This virtual member function is called when a cut is applied to the target of the relation.

void remove(Partial&);

This member function removes the argument Partial from the list. This function throws the same exceptions as the other member function IlsUsesList::remove described below.

CUsedTypePR getFirst();

This member function returns the first item of the list. If the list is empty, the exception IlsForbiddenOnEmptyList is thrown.

CUsedTypePR getLast();

This member function returns the last item of the list. If the list is empty, the exception IlsForbiddenOnEmptyList is thrown.

IlsBoolean isIn(CUsedTypePR);

This member function returns IlsTrue if the object pointed to belongs to the list.

Myself& cons(CUsedTypePR newe);

This member function adds an object to the list. It throws the following exceptions:

IlsMaxCardViolated if the maximal cardinality has been reached.

IlsUnOwnedUse if the specified object is neither an owned object nor an entity, and if the member function IlsModel::IsIntegrityChecked returns IlsTrue.

IlsUpdateForbidden if the member function isUpdateAllowed returns IlsFalse for the type in which the relation is declared.

void remove(CUsedTypePR olde);

This member function removes an object from the list according to the specified cut instruction. It throws the following exceptions:

IlsUpdateForbidden if the member function isUpdatedAllowed returns IlsFalse for the type in which the relation is declared.

IlsMinCardViolated if the minimal cardinality has been reached.

IlsNotFound if the item to be removed does not belong to the list.

Myself& clear();

This member function empties the list. If the minimal cardinality is different from zero, the exception IlsMinCardViolated is thrown. The number of items remaining in the list will be equal to the minimal cardinality specified.

This member function throws the exception IlsUpdateForbidden if the function isUpdateAllowed returns IlsFalse for the type in which the relation is declared.

Cardinality

IlsCardinality getMinCard();

This member function returns the minimal cardinality specified for the list.

IlsCardinality getMaxCard();

This member function returns the maximal cardinality specified for the list.

Notification Member Functions

IlsBoolean isModified();

During a notification phase, this member function returns IlsTrue if the relation has been modified since the last notification phase, that is, if one ore more items have been added to the relation or removed from the relation.

IlsBoolean isLengthModified();

During a notification phase, this member function returns IlsTrue if the number of items in the list has been modified since the last notification phase.

UsedType** getAdded(int& how_many);

During a notification phase, this member function returns an array of pointers to the items that have been added to the list since the last notification phase. It returns an empty array if no object has been added to the list-relation. The argument how_many accepts the size of the array as a return value. You must explicitly destroy this array when you no longer need it. To do so, use delete with square brackets [].

UsedType** getRemoved(int& how_many);

During a notification phase, this member function returns an array of pointers to the items that have been removed from the list since the last notification phase. It returns an empty array if no object has been removed from the list-relation. The argument how_many accepts the size of the array as a return value. You must explicitly destroy this array when you no longer need it. To do so, use delete with square brackets [].

Operators

Myself& operator<<(CUsedTypePR);

The operator << adds an item to the list. This operator throws the same exceptions as the member function IlsUsesList::cons.

Myself& operator>>(CUsedTypePR);

The operator >> removes an item from the list. This operator throws the same exceptions as the member function IlsUsesList::remove.

CUsedTypePR operator[](int);

This operator returns the i-th list element.