IlsOwnsSet
 
IlsOwnsSet
Category 
Modeling class template
Inheritance Path 
IlsSetContext
IlsOwnsSet
Description 
Rogue Wave Server lets you declare ownership relations among object classes. Ownership relations are relations in which one particular object is owned by at most one other object. The owner object, on the other hand, can own 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 by a key. Such relations are declared within the owner class as instances of the class template IlsOwnsSet.
OwnerType must derive directly or transitively from IlsObject or IlsEntity. OwnedType must derive from IlsObject. Derivation must be public. 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 the three following static member functions:
static KeyType GetKey(OwnedType&);
static IlsBoolean Match(KeyType lhs, KeyType rhs);
static long Hash(KeyType key, int size);
Library 
<server>
Header File 
#include <ilserver/model.h>
Synopsis 
template <class OwnerType,
class OwnedType,
class KeyType,
class KeyManager>
class IlsOwnsSet:
public IlsSetContext<KeyType>
{
public:
IlsOwnsSet(OwnerType& owner,
IlsRelationId identifier=IlsDefaultRelationId,
IlsActivity activity=IlsModel::GetDefaultActivity(),
IlsCardinality mincard=0,
IlsCardinality maxcard=ILS_UNLIMITED_MAXCARD,
Initial& owned=NewInitial(),
IlsBoolean check_card=IlsTrue);
virtual ~IlsOwnsSet();
IlsRelationId getIdentifier() const;
IlsCardinality getMinCard() const;
IlsCardinality getMaxCard() const;
unsigned int getCount();
IlsActivity getActivity() const;
IlsBoolean isCountModified();
IlsBoolean isModified();
static Initial& NewInitial();
OwnerType getOwner();
IlsBoolean isIn(CKeyTypeR identifier);
Myself& operator<<(COwnedTypePR v);
Myself& put(COwnedTypePR);
virtual void cut(Partial&, ILS_CUT_DIRECTIVE d=ILS_ALL);
Myself& operator>>(COwnedTypePR v);
Myself& suppress(CKeyTypeR identifier,
ILS_CUT_DIRECTIVE=ILS_ALL);
Myself& clear();
OwnedTypeP get(CKeyType identifier);
OwnedTypeP operator[](CKeyTypeR identifier);
OwnedType** getAdded(int& how_many);
OwnedType** getRemoved(int& how_many);
};
Constructor 
IlsOwnsSet(OwnerType& owner,
IlsRelationId identifier=IlsDefaultRelationId,
IlsActivity activity=IlsModel::GetDefaultActivity(),
IlsCardinality mincard=0,
IlsCardinality maxcard=ILS_UNLIMITED_MAXCARD,
Initial& owned=NewInitial(),
IlsBoolean check_card=IlsTrue);
This constructor takes the following arguments:
*A reference to the owner 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 of the list. This argument is optional and defaults to ILS_UNLIMITED_MAXCARD.
*The argument owned 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 ~IlsOwnsSet();
This destructor breaks all the relations in the set.
Member Functions 
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.
IlsActivity getActivity() const;
This member function indicates whether the set is active or not, that is, if derived data members are recomputed when the set is modified.
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 member function builds an empty set which is used by the constructor as the default value of the argument owned.
OwnerType getOwner();
This member function returns a reference to the owner object. It is especially useful in the case of derived relations.
IlsBoolean isIn(CKeyTypeR identifier);
This member function indicates whether the set holds an object associated with the key specified.
Myself& put(COwnedTypePR);
This member function puts an object in the set. A set cannot contain two objects associated with the same key. This member function throws the following exceptions:
*IlsMaxCardViolated if the maximal cardinality has been reached.
*IlsUpdateForbidden if the function isUpdateAllowed returns IlsFalse for the type in which the relation is declared.
*IlsOwnershipCycle if a cycle has been detected among ownership relations.
*IlsAlreadyInserted if the supplied object is already owned.
*IlsAlreadyInSet if the supplied object is already in the set.
[virtual] void cut(Partial&, ILS_CUT_DIRECTIVE d=ILS_ALL);
This virtual member function is called when a cut is applied to one of the owned objects.
Myself& suppress(CKeyTypeR identifier, ILS_CUT_DIRECTIVE=ILS_ALL);
This member function removes the object associated with the specified key according to the specified cut instruction. It throws the following exceptions:
*IlsUpdateForbidden if the 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 specified key.
Myself& clear();
This member function empties 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 function isUpdatedAllowed returns IlsFalse for the type in which the relation is declared.
OwnedTypeP get(CKeyType identifier);
This member function returns the object associated with the specified key; otherwise, it returns 0.
Notification
OwnedType** 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 set 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 [].
OwnedType** 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 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<<(COwnedTypePR v);
This operator adds an object to the set. It throws the same exceptions as the member function put.
Myself& operator>>(COwnedTypePR v);
This operator removes an object from the set. It throws the same exceptions as the member function suppress.
OwnedTypeP operator[](CKeyTypeR identifier);
This operator is identical to the function 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.
See Also 
IlsEntity, IlsHashKeyManager, IlsObject, IlsOwnsList, IlsOwnsSet::Iterator, IlsUsesSet

Version 5.8
Copyright © 2014, Rogue Wave Software, Inc. All Rights Reserved.