casacore
Notice.h
Go to the documentation of this file.
1 //# Notice.h: Classes for manipulating notices
2 //# Copyright (C) 1993,1994,1995,1999,2002
3 //# Associated Universities, Inc. Washington DC, USA.
4 //#
5 //# This library is free software; you can redistribute it and/or modify it
6 //# under the terms of the GNU Library General Public License as published by
7 //# the Free Software Foundation; either version 2 of the License, or (at your
8 //# option) any later version.
9 //#
10 //# This library is distributed in the hope that it will be useful, but WITHOUT
11 //# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
12 //# FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public
13 //# License for more details.
14 //#
15 //# You should have received a copy of the GNU Library General Public License
16 //# along with this library; if not, write to the Free Software Foundation,
17 //# Inc., 675 Massachusetts Ave, Cambridge, MA 02139, USA.
18 //#
19 //# Correspondence concerning AIPS++ should be addressed as follows:
20 //# Internet email: aips2-request@nrao.edu.
21 //# Postal address: AIPS++ Project Office
22 //# National Radio Astronomy Observatory
23 //# 520 Edgemont Road
24 //# Charlottesville, VA 22903-2475 USA
25 //#
26 //# $Id$
27 
28 #ifndef CASA_NOTICE_H
29 #define CASA_NOTICE_H
30 
31 #include <casacore/casa/aips.h>
32 #include <casacore/casa/Containers/Link.h>
33 
34 namespace casacore { //# NAMESPACE CASACORE - BEGIN
35 
36 //# Forward Declaration
37 class NoticeTarget;
38 
39 // <summary>abstract base class for notices</summary>
40 // <use visibility=export>
41 // <reviewed reviewer="Friso Olnon" date="1995/03/16" tests="" demos="">
42 // </reviewed>
43 
44 // <synopsis>
45 // A <src>Notice</src> is the piece of information passed around
46 // between a <src>NoticeSource</src> and a <src>NoticeTarget</src>. This
47 // abstract base class is only a skeleton intended to be derived from. It
48 // does not contain any relevant information -- that must be added by
49 // the derived classes --, but it enforces derived classes to implement
50 // the comparison operator <src>==</src> and the function
51 // <src>type()</src>.
52 // </synopsis>
53 
54 // <example>
55 // <linkto class=ListNotice>ListNotice</linkto>, derived from
56 // <src>Notice</src>, is the notification which is passed between
57 // <linkto class=List>List</linkto> and
58 // <linkto class=ListIter>ListIter</linkto>
59 // to keep cursors and container in sync.
60 // </example>
61 
62 class Notice {
63 public:
64  Notice() {}
65 
66  virtual ~Notice();
67 
68  // Compare two <src>Notice</src>s.
69  virtual bool operator==(const Notice &) const = 0;
70 };
71 
72 // <summary>base class for notice originators</summary>
73 // <use visibility=export>
74 // <reviewed reviewer="Friso Olnon" date="1995/03/16" tests="" demos="">
75 // </reviewed>
76 
77 // <synopsis>
78 // A <src>NoticeSource</src> maintains a list of all of the
79 // <src>NoticeTarget</src>s which are interested in <src>Notice</src>s
80 // from this <src>NoticeSource</src>. Its member function
81 // <src>notify()</src> sends the specified <src>Notice</src> to all the
82 // <src>NoticeTarget</src>s in the list.
83 //
84 // Classes which have many other dependent objects which need to be
85 // updated, should derive from this class.
86 // </synopsis>
87 
88 // <example>
89 // <linkto class=List>List</linkto>, the linked list class, is
90 // derived from <src>NoticeSource</src>. It mainly contains status
91 // information; all the manipulation functions are located in the
92 // <linkto class=ListIter>ListIter</linkto> classes. The linked
93 // list and its iterators communicate with each other via the notice
94 // system. <src>List</src> does not provide any further notice
95 // functionality; everything is taken care of by its base class
96 // <src>NoticeSource</src>.
97 // </example>
98 
99 class NoticeSource {
100 public:
101  friend class NoticeTarget;
102 
104 
105  virtual ~NoticeSource();
106 
107  // Sends the <src>note</src> to all <src>NoticeTarget</src>s in the
108  // target list.
109  void notify(const Notice & note);
110 
111 private:
112  Link<NoticeTarget*> *curIters; //# Do not Delete
113 
115 };
116 
117 // <summary>abstract base class for notice receptors</summary>
118 // <use visibility=export>
119 // <reviewed reviewer="Friso Olnon" date="1995/03/16" tests="" demos="">
120 // </reviewed>
121 
122 // <synopsis>
123 // A <src>NoticeTarget</src> receives the <src>Notice</src>s from the
124 // <src>NoticeSource</src> to which it is linked. A target can only be
125 // linked to one source.
126 //
127 // Classes which are dependent upon a particular
128 // <src>NoticeSource</src> should derive from this class.
129 // </synopsis>
130 
131 // <example>
132 // <linkto class=ListIter>ListIter</linkto> and its parent class
133 // <linkto class=ConstListIter>ConstListIter</linkto> are the iterators or
134 // "dynamic" cursors in the linked <linkto class=List>List</linkto>. They
135 // are derived from <src>NoticeTarget</src>, and the notice system ensures
136 // that multiple cursors are updated as elements are added and removed from
137 // the list, according to the following scheme:
138 // <ol>
139 // <li> An iterator changes something to the underlying list.
140 // <li> The iterator creates a <linkto class=ListNotice>ListNotice</linkto>
141 // containing all the necessary information about the change.
142 // <li> The iterator passes the notice to the <src>NoticeSource</src>
143 // <linkto class=List>List</linkto>.
144 // <li> The list relays the notice to all other iterators operating on the
145 // list (kept in the "target list").
146 // <li> Every iterator catches the notice and changes its state accordingly.
147 // </ol>
148 // </example>
149 
151 public:
152  friend class NoticeSource;
153 
154  // Destructs this <src>NoticeTarget</src>.
155  virtual ~NoticeTarget();
156 
157  // Returns a boolean value telling whether this <src>NoticeTarget</src>
158  // is still "valid".
159  Bool isValid() const {return valid;}
160 
161  // Returns a boolean value telling whether this <src>NoticeTarget</src>
162  // is still attached to a <src>NoticeSource</src> or not.
163  Bool isAttached() const {return ilink ? True : False;}
164 
165  // Makes the current <src>NoticeTarget</src> "invalid".
166  void invalidate() {valid = False;}
167 
168  // Hook through which <src>NoticeTarget</src>s are notified
169  // (by <src>NoticeSource</src>s).
170  virtual void notify(const Notice &) = 0;
171 
172 protected:
173 
177 
178  // Creates an unlinked, "invalid" <src>NoticeTarget</src>. An invalid
179  // <src>NoticeTarget</src> does not occur in the target list of any
180  // <src>NoticeSource</src>.
182 
183  // Creates a "valid" <src>NoticeTarget</src> linked to the specified
184  // <src>NoticeSource</src>. The <src>NoticeTarget</src> will be added
185  // to the target list in that <src>NoticeSource</src>.
186  // <group>
189  // </group>
190 
191  // Creates a "valid" <src>NoticeTarget</src> linked to the same
192  // <src>NoticeSource</src> as the <src>other NoticeTarget</src>.
193  // So, both <src>NoticeTarget</src>s will occur in the same target
194  // list.
195  // <group>
197  { if (other.isValid()) attach(other.container);}
199  { if (other && other->isValid()) attach( (*other).container );}
200 
201  // </group>
202 
203  // Unlinks this <src>NoticeTarget</src> from its <src>NoticeSource</src>.
204  // The <src>NoticeTarget</src> will be removed from the target list.
205  void unlink();
206 
207  // Links this <src>NoticeTarget</src> to the same <src>NoticeSource</src>
208  // as the <src>other NoticeTarget</src>. Any previous link will be undone.
209  // <group>
210  void link(const NoticeTarget &other);
211  void link(const NoticeTarget *other);
212  // </group>
213 
214  // Retrieves the next <src>NoticeTarget</src> in the target list
215  // of the associated <src>NoticeSource</src>.
216  // <group>
218  return(ilink ? (*ilink).next() : 0);
219  }
220  const Link<NoticeTarget*> *next() const {
221  return(ilink ? (*ilink).next() : 0);
222  }
223  // </group>
224 
225  // Adds this <src>NoticeTarget</src> to the target list in the
226  // specified <src>NoticeSource</src>, so that it will receive all
227  // notices sent out by that <src>NoticeSource</src>.
228  // <group>
231  // </group>
232 
233 };
234 
235 
236 } //# NAMESPACE CASACORE - END
237 
238 #endif
239 
240 
241 
242 
243 
base class for notice originators
Definition: Notice.h:99
void notify(const Notice &note)
Sends the note to all NoticeTargets in the target list.
Link< NoticeTarget * > * curIters
Definition: Notice.h:112
Link< NoticeTarget * > *& head()
Definition: Notice.h:114
abstract base class for notice receptors
Definition: Notice.h:150
Link< NoticeTarget * > * next()
Retrieves the next NoticeTarget in the target list of the associated NoticeSource.
Definition: Notice.h:217
void link(const NoticeTarget &other)
Links this NoticeTarget to the same NoticeSource as the other NoticeTarget.
void attach(NoticeSource &v)
NoticeSource * container
Definition: Notice.h:175
void attach(NoticeSource *v)
Adds this NoticeTarget to the target list in the specified NoticeSource, so that it will receive all ...
NoticeTarget(NoticeSource *v)
Creates a "valid" NoticeTarget linked to the specified NoticeSource.
Definition: Notice.h:187
NoticeTarget(NoticeTarget &other)
Creates a "valid" NoticeTarget linked to the same NoticeSource as the other NoticeTarget.
Definition: Notice.h:196
NoticeTarget(NoticeSource &v)
Definition: Notice.h:188
void invalidate()
Makes the current NoticeTarget "invalid".
Definition: Notice.h:166
const Link< NoticeTarget * > * next() const
Definition: Notice.h:220
virtual ~NoticeTarget()
Destructs this NoticeTarget.
NoticeTarget(NoticeTarget *other)
Definition: Notice.h:198
virtual void notify(const Notice &)=0
Hook through which NoticeTargets are notified (by NoticeSources).
Link< NoticeTarget * > * ilink
Definition: Notice.h:174
Bool isAttached() const
Returns a boolean value telling whether this NoticeTarget is still attached to a NoticeSource or not.
Definition: Notice.h:163
void link(const NoticeTarget *other)
void unlink()
Unlinks this NoticeTarget from its NoticeSource.
NoticeTarget()
Creates an unlinked, "invalid" NoticeTarget.
Definition: Notice.h:181
Bool isValid() const
Returns a boolean value telling whether this NoticeTarget is still "valid".
Definition: Notice.h:159
virtual bool operator==(const Notice &) const =0
Compare two Notices.
virtual ~Notice()
this file contains all the compiler specific defines
Definition: mainpage.dox:28
const Bool False
Definition: aipstype.h:44
bool Bool
Define the standard types used by Casacore.
Definition: aipstype.h:42
const Bool True
Definition: aipstype.h:43