IlsUsesSet

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 list-relations, target objects in set-relations are not listed in sequential order but are grouped together in a non-ordered set and are directly accessible using a key. Such relations are declared within the user class as instances of the class template IlsUsesSet.

UserType and UsedType must derive directly or transitively from IlsObject or IlsEntity. KeyType is the type of the key used to store objects in a set and retrieve objects from a set. KeyManager is a class that specifies how to handle keys. This class must contain these three public static member functions:

static long Hash(KeyType key, int size);

static KeyType GetKey(UsedType&);

static IlsBoolean Match(KeyType lhs, KeyType rhs);

Library

Header File

#include <ilserver/model.h>

Synopsis

template <class UserType,

class UsedType,

class KeyType,

class KeyManager>

class IlsUsesSet:

public IlsSetContext<KeyType>

{

public:

IlsUsesSet(UserType& user,

IlsRelationId identifier=IlsDefaultRelationId,

IlsActivity activity=IlsModel::GetDefaultActivity(),

IlsCardinality mincard=0,

IlsCardinality maxcard=ILS_UNLIMITED_MAXCARD,

Initial& used=NewInitial(),

IlsBoolean check_card=IlsTrue);

virtual ~IlsUsesSet();

IlsActivity getActivity() const;

IlsRelationId getIdentifier() const;

IlsCardinality getMinCard() const;

IlsCardinality getMaxCard() const;

unsigned int getCount();

IlsBoolean isCountModified();

IlsBoolean isModified();

static Initial& NewInitial();

UserType getUser();

IlsBoolean isIn(CKeyTypeR identifier);

Myself& operator<<(CUsedTypePR v);

Myself& put(CUsedTypePR);

virtual void cut(Partial&, ILS_CUT_DIRECTIVE d=ILS_ALL);

Myself& operator>>(CUsedTypePR v);

Myself& suppress(CKeyTypeR identifier,

ILS_CUT_DIRECTIVE=ILS_ALL);

Myself& clear();

UsedTypeP get(CKeyType identifier);

UsedTypeP operator[](CKeyTypeR identifier);

UsedType** getAdded(int&);

UsedType** getRemoved(int);

};

Constructor

IlsUsesSet(UserType& user,

IlsRelationId identifier=IlsDefaultRelationId,

IlsActivity activity=IlsModel::GetDefaultActivity(),

IlsCardinality mincard=0,

IlsCardinality maxcard=ILS_UNLIMITED_MAXCARD,

Initial& 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 member 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 of the list. This argument is optional and defaults to ILS_UNLIMITED_MAXCARD.

The argument used is a list of objects. Its creates an empty list when set to its default value.

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

Destructor

virtual ~IlsUsesSet();

This destructor breaks all the relations in the set.

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.

IlsRelationId getIdentifier() const;

This member function returns the relation identifier.

IlsCardinality getMinCard() const;

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

IlsCardinality getMaxCard() const;

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

unsigned int getCount();

This member function returns the number of objects in the set at a given time.

IlsBoolean isCountModified();

This member function indicates whether the number of objects in the set has changed. The return value will be IlsTrue even if one object has been removed from the set and then put back into the set.

IlsBoolean isModified();

This member function indicates whether the set has been modified.

[static] Initial& NewInitial();

This static member function builds an empty set 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. It is useful especially in the case of derived relations.

IlsBoolean isIn(CKeyTypeR identifier);

This member function indicates whether the set contains the object associated with the key specified.

Myself& put(CUsedTypePR);

This member function puts an object in the set. A set cannot contain two objects associated with the same key. It throws the following exceptions:

IlsMaxCardViolated if the maximal cardinality has been reached.

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

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

[virtual] void cut(Partial&, ILS_CUT_DIRECTIVE d=ILS_ALL);

This static member function is called when a cut is applied to one of the used objects.

Myself& suppress(CKeyTypeR identifier, ILS_CUT_DIRECTIVE=ILS_ALL);

This member function removes the object associated with the key specified according to the cut instruction specified. 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 no object is associated with the key specified.

Myself& clear();

This member function clears the list. It throws the following exceptions:

IlsMinCardViolated if the minimal cardinality is different from zero. The
number of objects left in the set will be equal to the minimal cardinality specified.

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

UsedTypeP get(CKeyType identifier);

This member function returns the object associated with the key specified; otherwise, it returns 0.

Notification Functions

IlsBoolean isModified();

This member function indicates whether the set has been modified.

UsedType** getAdded(int&);

During a notification phase, this member function returns an array of pointers to the elements that have been added to the set since the last notification phase. It returns an empty array if no object has been added to the set-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);

During a notification phase, this member function returns an array of pointers to the elements that have been removed from the set since the last notification phase. It returns an empty array if no object has been removed from the set-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 v);

This operator adds an object to the set. It throws the same exceptions as the member function IlsUsesSet::put.

Myself& operator>>(CUsedTypePR v);

This operator removes an object from the set. It throws the same exceptions as the member function IlsUsesSet::suppress.

UsedTypeP operator[](CKeyTypeR identifier);

This operation is identical to the member function IlsUsesSet::get.

Implementation

To compile with a program written for Rogue Wave Server 2.X or 3.0, you must change the name of the KeyManager static functions from hash, getKey and match to Hash, GetKey and Match.