IlsOwnsSet
Category
Modeling class template
Inheritance Path
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
Synopsis
template <class OwnerType,
class OwnedType,
class KeyType,
class KeyManager>
class IlsOwnsSet:
public IlsSetContext<KeyType>
{
public:
IlsRelationId identifier=IlsDefaultRelationId,
IlsActivity activity=IlsModel::GetDefaultActivity(),
IlsCardinality mincard=0,
IlsCardinality maxcard=ILS_UNLIMITED_MAXCARD,
Initial& owned=NewInitial(),
IlsBoolean check_card=IlsTrue);
virtual ~IlsOwnsSet();
IlsBoolean
isIn(CKeyTypeR identifier);
Myself&
put(COwnedTypePR);
virtual void
cut(Partial&, ILS_CUT_DIRECTIVE d=ILS_ALL);
ILS_CUT_DIRECTIVE=ILS_ALL);
OwnedTypeP
get(CKeyType identifier);
};
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.
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 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:
IlsUpdateForbidden if the function
isUpdateAllowed returns
IlsFalse for the type in which the relation is declared.
[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.
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
Version 5.8
Copyright © 2014, Rogue Wave Software, Inc. All Rights Reserved.