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 resouce 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