1 -- File: Message_Algorithm.cdl
2 -- Created: Fri Jul 6 09:22:36 2007
3 -- Author: Pavel TELKOV
5 -- Copyright: Open CASCADE S.A. 2007
6 -- The original implementation copyright (c) RINA S.p.A
8 class Algorithm from Message inherits TShared from MMgt
10 ---Purpose: Class Message_Algorithm is intended to be the base class for
11 -- classes implementing algorithms or any operations that need
12 -- to provide extended information on its execution to the
15 -- It provides generic mechanism for management of the execution
16 -- status, collection and output of messages.
18 -- The algorithm uses methods SetStatus() to set an execution status.
19 -- It is possible to associate a status with a number or a string
20 -- (second argument of SetStatus() methods) to indicate precisely
21 -- the item (object, element etc.) in the input data which caused
24 -- Each execution status generated by the algorithm has associated
25 -- text message that should be defined in the resouce file loaded
26 -- with call to Message_MsgFile::LoadFile().
28 -- The messages corresponding to the statuses generated during the
29 -- algorithm execution are output to Message_Messenger using
30 -- methods SendMessages(). If status have associated numbers
31 -- or strings, they are included in the message body in place of
32 -- "%s" placeholder which should be present in the message text.
34 -- The name of the message text in the resource file is constructed
35 -- from name of the class and name of the status, separated by dot,
38 -- .TObj_CheckModel.Alarm2
39 -- Error: Some objects (%s) have references to dead object(s)
41 -- If message for the status is not found with prefix of
42 -- the current class type, the same message is searched for the base
43 -- class(es) recursively.
45 -- The messages are output to the messenger, stored in the field;
46 -- though messenger can be changed, it is guaranteed to be non-null.
47 -- By default, Message::DefaultMessenger() is used.
52 Messenger from Message,
55 ExecStatus from Message,
56 AsciiString from TCollection,
57 HAsciiString from TCollection,
58 ExtendedString from TCollection,
59 HExtendedString from TCollection,
60 SequenceOfInteger from TColStd,
61 HSequenceOfInteger from TColStd,
62 HArray1OfTransient from TColStd,
63 HPackedMapOfInteger from TColStd,
64 SequenceOfHExtendedString from TColStd,
65 HSequenceOfHExtendedString from TColStd
69 Create returns Algorithm from Message;
70 ---Purpose: Empty constructor
72 SetStatus(me: mutable; theStat : Status from Message);
73 ---Purpose: Sets status with no parameter
75 SetStatus(me: mutable; theStat : Status from Message;
77 ---Purpose: Sets status with integer parameter
79 SetStatus(me: mutable; theStat : Status from Message;
81 noRepetitions : Boolean = Standard_True);
82 ---Purpose: Sets status with string parameter.
83 -- If noRepetitions is True, the parameter will be added only
84 -- if it has not been yet recorded for the same status flag
87 SetStatus(me: mutable; theStat : Status from Message;
88 theStr : AsciiString from TCollection;
89 noRepetitions : Boolean = Standard_True);
90 ---Purpose: Sets status with string parameter
91 -- If noRepetitions is True, the parameter will be added only
92 -- if it has not been yet recorded for the same status flag
95 SetStatus(me: mutable; theStat : Status from Message;
96 theStr : HAsciiString from TCollection;
97 noRepetitions : Boolean = Standard_True);
98 ---Purpose: Sets status with string parameter
99 -- If noRepetitions is True, the parameter will be added only
100 -- if it has not been yet recorded for the same status flag
103 SetStatus(me: mutable; theStat : Status from Message;
104 theStr : ExtendedString from TCollection;
105 noRepetitions : Boolean = Standard_True);
106 ---Purpose: Sets status with string parameter
107 -- If noRepetitions is True, the parameter will be added only
108 -- if it has not been yet recorded for the same status flag
111 SetStatus(me: mutable; theStat : Status from Message;
112 theStr : HExtendedString from TCollection;
113 noRepetitions : Boolean = Standard_True);
114 ---Purpose: Sets status with string parameter
115 -- If noRepetitions is True, the parameter will be added only
116 -- if it has not been yet recorded for the same status flag
118 GetStatus(me) returns ExecStatus from Message;
119 ---Purpose: Returns copy of exec status of algorithm
121 ---C++: return const &
123 ChangeStatus(me: mutable) returns ExecStatus from Message;
124 ---Purpose: Returns exec status of algorithm
128 ClearStatus(me: mutable);
129 ---Purpose: Clear exec status of algorithm
131 -- Message management
133 SetMessenger(me: mutable; theMsgr : Messenger from Message);
134 ---Purpose: Sets messenger to algorithm
137 returns Messenger from Message;
138 ---Purpose: Returns messenger of algorithm.
139 -- The returned handle is always non-null and can
140 -- be used for sending messages.
143 SendStatusMessages(me; theFilter : ExecStatus from Message;
144 theTraceLevel: Gravity from Message = Message_Warning;
145 theMaxCount: Integer = 20)
147 ---Purpose: Print messages for all status flags that have been set during
148 -- algorithm execution, excluding statuses that are NOT set
151 -- The messages are taken from resource file, names being
152 -- constructed as {dynamic class type}.{status name},
153 -- for instance, "Message_Algorithm.Fail5".
154 -- If message is not found in resources for this class and all
155 -- its base types, surrogate text is printed.
157 -- For the statuses having number or string parameters,
158 -- theMaxCount defines maximal number of numbers or strings to be
159 -- included in the message
161 -- Note that this method is virtual; this allows descendant
162 -- classes to customize message output (e.g. by adding
163 -- messages from other sub-algorithms)
165 SendMessages(me; theTraceLevel: Gravity from Message = Message_Warning;
166 theMaxCount: Integer = 20);
167 ---Purpose: Convenient variant of SendStatusMessages() with theFilter
168 -- having defined all WARN, ALARM, and FAIL (but not DONE)
171 AddStatus(me: mutable; theOther : Algorithm from Message);
172 ---Purpose: Add statuses to this algorithm from other algorithm
173 -- (including messages)
175 AddStatus(me: mutable; theStatus : ExecStatus from Message;
176 theOther : Algorithm from Message);
177 ---Purpose: Add statuses to this algorithm from other algorithm, but
178 -- only those items are moved that correspond to statuses
181 GetMessageNumbers(me; theStatus : Status from Message)
182 returns HPackedMapOfInteger from TColStd;
183 ---Purpose: Return the numbers associated with the indicated status;
184 -- Null handle if no such status or no numbers associated with it
186 GetMessageStrings(me; theStatus : Status from Message)
187 returns HSequenceOfHExtendedString from TColStd;
188 ---Purpose: Return the strings associated with the indicated status;
189 -- Null handle if no such status or no strings associated with it
191 PrepareReport(myclass; theError : HPackedMapOfInteger from TColStd;
192 theMaxCount: Integer)
193 returns ExtendedString from TCollection;
194 ---Purpose: Prepares a string containing a list of integers contained
195 -- in theError map, but not more than theMaxCount
197 PrepareReport(myclass; theReportSeq : SequenceOfHExtendedString from TColStd;
198 theMaxCount: Integer)
199 returns ExtendedString from TCollection;
200 ---Purpose: Prepares a string containing a list of names contained
201 -- in theReportSeq sequence, but not more than theMaxCount
205 myStatus : ExecStatus from Message is protected;
206 myMessenger : Messenger from Message is protected;
207 myReportIntegers : HArray1OfTransient from TColStd;
208 myReportStrings : HArray1OfTransient from TColStd;