IlsOwnsList
 
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 
<server>
Header File 
#include <ilserver/model.h>
Synopsis 
template<class OwnerType, class OwnedType>
class IlsOwnsList
{
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);
 
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.
*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, 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:
*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.
*IlsOwnershipCycle if a cycle has been detected among ownership relations.
*IlsAlreadyInserted if the supplied object is already owned.
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.
*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 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.