42cf5bc1 |
1 | // Created on: 2007-07-06 |
2 | // Created by: Pavel TELKOV |
3 | // Copyright (c) 2007-2014 OPEN CASCADE SAS |
4 | // |
5 | // This file is part of Open CASCADE Technology software library. |
6 | // |
7 | // This library is free software; you can redistribute it and/or modify it under |
8 | // the terms of the GNU Lesser General Public License version 2.1 as published |
9 | // by the Free Software Foundation, with special exception defined in the file |
10 | // OCCT_LGPL_EXCEPTION.txt. Consult the file LICENSE_LGPL_21.txt included in OCCT |
11 | // distribution for complete text of the license and disclaimer of any warranty. |
12 | // |
13 | // Alternatively, this file may be used under the terms of Open CASCADE |
14 | // commercial license or contractual agreement. |
15 | |
16 | #ifndef _Message_Algorithm_HeaderFile |
17 | #define _Message_Algorithm_HeaderFile |
18 | |
19 | #include <Standard.hxx> |
20 | #include <Standard_Type.hxx> |
21 | |
22 | #include <Message_ExecStatus.hxx> |
23 | #include <TColStd_HArray1OfTransient.hxx> |
25e59720 |
24 | #include <Standard_Transient.hxx> |
42cf5bc1 |
25 | #include <Message_Status.hxx> |
26 | #include <Standard_Integer.hxx> |
27 | #include <Standard_CString.hxx> |
28 | #include <Standard_Boolean.hxx> |
29 | #include <Message_Gravity.hxx> |
5b111128 |
30 | #include <TCollection_HAsciiString.hxx> |
31 | #include <TCollection_HExtendedString.hxx> |
42cf5bc1 |
32 | #include <TColStd_HSequenceOfHExtendedString.hxx> |
33 | #include <TColStd_SequenceOfHExtendedString.hxx> |
5b111128 |
34 | #include <Message_HArrayOfMsg.hxx> |
35 | |
42cf5bc1 |
36 | class Message_Messenger; |
37 | class TCollection_AsciiString; |
38 | class TCollection_HAsciiString; |
39 | class TCollection_ExtendedString; |
40 | class TCollection_HExtendedString; |
41 | class Message_Msg; |
42 | class TColStd_HPackedMapOfInteger; |
43 | |
44 | |
45 | class Message_Algorithm; |
25e59720 |
46 | DEFINE_STANDARD_HANDLE(Message_Algorithm, Standard_Transient) |
42cf5bc1 |
47 | |
48 | //! Class Message_Algorithm is intended to be the base class for |
49 | //! classes implementing algorithms or any operations that need |
50 | //! to provide extended information on its execution to the |
51 | //! caller / user. |
52 | //! |
53 | //! It provides generic mechanism for management of the execution |
54 | //! status, collection and output of messages. |
55 | //! |
56 | //! The algorithm uses methods SetStatus() to set an execution status. |
57 | //! It is possible to associate a status with a number or a string |
58 | //! (second argument of SetStatus() methods) to indicate precisely |
59 | //! the item (object, element etc.) in the input data which caused |
60 | //! the problem. |
61 | //! |
62 | //! Each execution status generated by the algorithm has associated |
a25d5aaa |
63 | //! text message that should be defined in the resource file loaded |
42cf5bc1 |
64 | //! with call to Message_MsgFile::LoadFile(). |
65 | //! |
66 | //! The messages corresponding to the statuses generated during the |
67 | //! algorithm execution are output to Message_Messenger using |
68 | //! methods SendMessages(). If status have associated numbers |
69 | //! or strings, they are included in the message body in place of |
70 | //! "%s" placeholder which should be present in the message text. |
71 | //! |
72 | //! The name of the message text in the resource file is constructed |
73 | //! from name of the class and name of the status, separated by dot, |
74 | //! for instance: |
75 | //! |
76 | //! .TObj_CheckModel.Alarm2 |
77 | //! Error: Some objects (%s) have references to dead object(s) |
78 | //! |
79 | //! If message for the status is not found with prefix of |
80 | //! the current class type, the same message is searched for the base |
81 | //! class(es) recursively. |
82 | //! |
83 | //! Message can be set explicitly for the status; in this case the |
84 | //! above procedure is not used and supplied message is used as is. |
85 | //! |
86 | //! The messages are output to the messenger, stored in the field; |
87 | //! though messenger can be changed, it is guaranteed to be non-null. |
88 | //! By default, Message::DefaultMessenger() is used. |
25e59720 |
89 | class Message_Algorithm : public Standard_Transient |
42cf5bc1 |
90 | { |
91 | |
92 | public: |
93 | |
94 | |
95 | //! Empty constructor |
96 | Standard_EXPORT Message_Algorithm(); |
97 | |
98 | //! Sets status with no parameter |
99 | Standard_EXPORT void SetStatus (const Message_Status& theStat); |
100 | |
101 | //! Sets status with integer parameter |
102 | Standard_EXPORT void SetStatus (const Message_Status& theStat, const Standard_Integer theInt); |
103 | |
104 | //! Sets status with string parameter. |
105 | //! If noRepetitions is True, the parameter will be added only |
106 | //! if it has not been yet recorded for the same status flag |
107 | void SetStatus (const Message_Status& theStat, const Standard_CString theStr, const Standard_Boolean noRepetitions = Standard_True); |
108 | |
109 | //! Sets status with string parameter |
110 | //! If noRepetitions is True, the parameter will be added only |
111 | //! if it has not been yet recorded for the same status flag |
112 | void SetStatus (const Message_Status& theStat, const TCollection_AsciiString& theStr, const Standard_Boolean noRepetitions = Standard_True); |
113 | |
114 | //! 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 |
117 | void SetStatus (const Message_Status& theStat, const Handle(TCollection_HAsciiString)& theStr, const Standard_Boolean noRepetitions = Standard_True); |
118 | |
119 | //! Sets status with string parameter |
120 | //! If noRepetitions is True, the parameter will be added only |
121 | //! if it has not been yet recorded for the same status flag |
122 | void SetStatus (const Message_Status& theStat, const TCollection_ExtendedString& theStr, const Standard_Boolean noRepetitions = Standard_True); |
123 | |
124 | //! Sets status with string parameter |
125 | //! If noRepetitions is True, the parameter will be added only |
126 | //! if it has not been yet recorded for the same status flag |
127 | Standard_EXPORT void SetStatus (const Message_Status& theStat, const Handle(TCollection_HExtendedString)& theStr, const Standard_Boolean noRepetitions = Standard_True); |
128 | |
129 | //! Sets status with preformatted message. This message will be |
130 | //! used directly to report the status; automatic generation of |
131 | //! status messages will be disabled for it. |
132 | Standard_EXPORT void SetStatus (const Message_Status& theStat, const Message_Msg& theMsg); |
133 | |
134 | //! Returns copy of exec status of algorithm |
135 | const Message_ExecStatus& GetStatus() const; |
136 | |
137 | //! Returns exec status of algorithm |
138 | Message_ExecStatus& ChangeStatus(); |
139 | |
140 | //! Clear exec status of algorithm |
141 | Standard_EXPORT void ClearStatus(); |
142 | |
143 | //! Sets messenger to algorithm |
144 | Standard_EXPORT void SetMessenger (const Handle(Message_Messenger)& theMsgr); |
145 | |
146 | //! Returns messenger of algorithm. |
147 | //! The returned handle is always non-null and can |
148 | //! be used for sending messages. |
149 | Handle(Message_Messenger) GetMessenger() const; |
150 | |
151 | //! Print messages for all status flags that have been set during |
152 | //! algorithm execution, excluding statuses that are NOT set |
153 | //! in theFilter. |
154 | //! |
155 | //! The messages are taken from resource file, names being |
156 | //! constructed as {dynamic class type}.{status name}, |
157 | //! for instance, "Message_Algorithm.Fail5". |
158 | //! If message is not found in resources for this class and all |
159 | //! its base types, surrogate text is printed. |
160 | //! |
161 | //! For the statuses having number or string parameters, |
162 | //! theMaxCount defines maximal number of numbers or strings to be |
163 | //! included in the message |
164 | //! |
165 | //! Note that this method is virtual; this allows descendant |
166 | //! classes to customize message output (e.g. by adding |
167 | //! messages from other sub-algorithms) |
168 | Standard_EXPORT virtual void SendStatusMessages (const Message_ExecStatus& theFilter, const Message_Gravity theTraceLevel = Message_Warning, const Standard_Integer theMaxCount = 20) const; |
169 | |
170 | //! Convenient variant of SendStatusMessages() with theFilter |
171 | //! having defined all WARN, ALARM, and FAIL (but not DONE) |
172 | //! status flags |
173 | Standard_EXPORT void SendMessages (const Message_Gravity theTraceLevel = Message_Warning, const Standard_Integer theMaxCount = 20) const; |
174 | |
175 | //! Add statuses to this algorithm from other algorithm |
176 | //! (including messages) |
177 | Standard_EXPORT void AddStatus (const Handle(Message_Algorithm)& theOther); |
178 | |
179 | //! Add statuses to this algorithm from other algorithm, but |
180 | //! only those items are moved that correspond to statuses |
181 | //! set in theStatus |
182 | Standard_EXPORT void AddStatus (const Message_ExecStatus& theStatus, const Handle(Message_Algorithm)& theOther); |
183 | |
184 | //! Return the numbers associated with the indicated status; |
185 | //! Null handle if no such status or no numbers associated with it |
186 | Standard_EXPORT Handle(TColStd_HPackedMapOfInteger) GetMessageNumbers (const Message_Status& theStatus) const; |
187 | |
188 | //! Return the strings associated with the indicated status; |
189 | //! Null handle if no such status or no strings associated with it |
190 | Standard_EXPORT Handle(TColStd_HSequenceOfHExtendedString) GetMessageStrings (const Message_Status& theStatus) const; |
191 | |
192 | //! Prepares a string containing a list of integers contained |
193 | //! in theError map, but not more than theMaxCount |
194 | Standard_EXPORT static TCollection_ExtendedString PrepareReport (const Handle(TColStd_HPackedMapOfInteger)& theError, const Standard_Integer theMaxCount); |
195 | |
196 | //! Prepares a string containing a list of names contained |
197 | //! in theReportSeq sequence, but not more than theMaxCount |
198 | Standard_EXPORT static TCollection_ExtendedString PrepareReport (const TColStd_SequenceOfHExtendedString& theReportSeq, const Standard_Integer theMaxCount); |
199 | |
200 | |
201 | |
202 | |
25e59720 |
203 | DEFINE_STANDARD_RTTIEXT(Message_Algorithm,Standard_Transient) |
42cf5bc1 |
204 | |
205 | protected: |
206 | |
207 | |
208 | Message_ExecStatus myStatus; |
209 | Handle(Message_Messenger) myMessenger; |
210 | |
211 | |
212 | private: |
213 | |
214 | |
215 | Handle(TColStd_HArray1OfTransient) myReportIntegers; |
216 | Handle(TColStd_HArray1OfTransient) myReportStrings; |
217 | Message_HArrayOfMsg myReportMessages; |
218 | |
219 | |
220 | }; |
221 | |
222 | |
223 | #include <Message_Algorithm.lxx> |
224 | |
225 | |
226 | |
227 | |
228 | |
229 | #endif // _Message_Algorithm_HeaderFile |