0031939: Coding - correction of spelling errors in comments [part 3]
[occt.git] / src / Message / Message_Algorithm.hxx
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>
24 #include <Standard_Transient.hxx>
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>
30 #include <TCollection_HAsciiString.hxx>
31 #include <TCollection_HExtendedString.hxx>
32 #include <TColStd_HSequenceOfHExtendedString.hxx>
33 #include <TColStd_SequenceOfHExtendedString.hxx>
34 #include <Message_HArrayOfMsg.hxx>
35
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;
46 DEFINE_STANDARD_HANDLE(Message_Algorithm, Standard_Transient)
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
63 //! text message that should be defined in the resource file loaded
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.
89 class Message_Algorithm : public Standard_Transient
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
203   DEFINE_STANDARD_RTTIEXT(Message_Algorithm,Standard_Transient)
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