IlsOwnsList
Category
Modeling class template
Inheritance Path
IlsViewedRel➥ IlsOwnsList Description
Rogue Wave Server lets you declare ownership relations among object classes. Ownership relations are relations in which one particular object is owned by, or belongs to, at most one other object. 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 owner class as instances of the class template IlsOwnsList.
The
OwnerType must derive directly or transitively from
IlsObject or
IlsEntity. The
OwnedType must derive directly or transitively from
IlsObject. Derivation must be public.
Library
Synopsis
template<class OwnerType, class OwnedType>
class IlsOwnsList
{
IlsRelationId identifier=IlsDefaultRelationId,
IlsActivity activity=IlsModel::GetDefaultActivity(),
IlsCardinality mincard=0,
IlsCardinality maxcard=ILS_UNLIMITED_MAXCARD,
Initial& owned=newInitial(),
IlsBoolean check_card=IlsTrue);
virtual ~IlsOwnsList();
static Initial& NewInitial();
IlsActivity getActivity() const;
OwnerType& getOwner();
IlsRelationId getIdentifier();
IlsCardinality getMinCard() const;
IlsCardinality getMaxCard()const;
unsigned int getLength() const;
virtual void cut(Partial&, ILS_CUT_DIRECTIVE=ILS_ALL);
void remove(Partial&, ILS_CUT_DIRECTIVE=ILS_ALL);
COwnedTypePR getFirst();
COwnedTypePR getLast();
IlsBoolean isIn(COwnedTypePR);
Myself& cons(COwnedTypePR newe);
Myself& remove(COwnedTypePR olde, ILS_CUT_DIRECTIVE d=ILS_ALL);
Myself& clear();
Myself& operator<<(COwnedTypePR);
Myself& operator>>(COwnedTypePR);
COwnedTypePR operator[](int);
IlsBoolean isModified();
IlsBoolean isLengthModified();
OwnedType** getAdded(int& how_many);
OwnedType** getRemoved(int& how_many);
};
Constructor
IlsOwnsList(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 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, which can be an unsigned integer or indeterminate. This argument is optional and defaults to
ILS_UNLIMITED_MAXCARD.
The argument
owned is a list of objects. Its default value,
NewInitial, creates an empty list. If the value of
owned 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 last argument
check_card specifies whether cardinalities should be checked at object construction.
Destructor
virtual ~IlsOwnsList();
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 owned.
OwnerType& getOwner();
This member function returns a reference to the owner object. This function is useful especially in the case of derived relations.
IlsRelationId getIdentifier();
This member function returns the relation identifier.
unsigned int getLength() const;
This member function returns the number of items in the list.
[virtual] void cut(Partial&, ILS_CUT_DIRECTIVE=ILS_ALL);
This virtual member function is called when a cut is applied to the target of the relation.
void remove(Partial&, ILS_CUT_DIRECTIVE=ILS_ALL);
This member function removes the argument
Partial from the list. It throws the same exceptions as the member function
Myself remove(COwnedTypePR olde,ILS_CUT_DIRECTIVE d=ILS_ALL); documented below.
COwnedTypePR getFirst();
This member function returns the first item of the list. If the list is empty, the exception
IlsForbiddenOnEmptyList is thrown.
COwnedTypePR getLast();
This member function returns the last item of the list. If the list is empty, the exception IlsForbiddenOnEmptyList is thrown.
IlsBoolean isIn(COwnedTypePR);
This member function returns IlsTrue if the object pointed to belongs to the list.
Myself& cons(COwnedTypePR newe);
This member function adds an object to the list. It throws the following exceptions:
IlsUpdateForbidden if the member function
isUpdateAllowed returns
IlsFalse for the type in which the relation is declared.
Myself remove(COwnedTypePR olde,ILS_CUT_DIRECTIVE d=ILS_ALL);
This member function removes an object from the list according to the cut instruction specified. It throws the following exceptions:
IlsUpdateForbidden if the function
isUpdateAllowed returns
IlsFalse for the type in which the relation is declared.
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 member function
isUpdateAllowed returns
IlsFalse for the type in which the relation is declared.
Cardinality
IlsCardinality getMinCard()const;
This member function returns the minimal cardinality specified for the list.
IlsCardinality getMaxCard() const;
This member function returns the maximal cardinality specified for the list.
Notification
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 or 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.
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 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 [].
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 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<<(COwnedTypePR);
The operator << adds an item to the list. It throws the same exceptions as the member function IlsOwnsList::cons.
Myself& operator>>(COwnedTypePR);
The operator >> removes an item from the list. It throws the same exceptions as the member function IlsOwnsList::remove.
COwnedTypePR operator[](int);
This operator returns the i-th list item.
See Also
Exceptions,
IlsDefaultRelationId,
IlsDerived,
IlsEntity,
IlsMoveDirective,
IlsObject,
IlsOwns,
IlsOwnsDynamicArray,
IlsOwnsFixedArray,
IlsOwnsList::Initial,
IlsOwnsList::ConstIterator,
IlsOwnsList::Iterator,
IlsOwnsList::Partial,
IlsOwnsList::Position,
IlsOwnsSet,
IlsRelationId
Version 5.8
Copyright © 2014, Rogue Wave Software, Inc. All Rights Reserved.