src/Message/Message_Algorithm.cdl

   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 -- The original implementation copyright (c) RINA S.p.A
  17
  18 class Algorithm from Message inherits TShared from MMgt
  19
  20     ---Purpose: Class Message_Algorithm is intended to be the base class for
  21     --          classes implementing algorithms or any operations that need
  22     --          to provide extended information on its execution to the
  23     --          caller / user.
  24     --
  25     --          It provides generic mechanism for management of the execution
  26     --          status, collection and output of messages.
  27     --
  28     --          The algorithm uses methods SetStatus() to set an execution status.
  29     --          It is possible to associate a status with a number or a string
  30     --          (second argument of SetStatus() methods) to indicate precisely
  31     --          the item (object, element etc.) in the input data which caused
  32     --          the problem.
  33     --
  34     --          Each execution status generated by the algorithm has associated
  35     --          text message that should be defined in the resouce file loaded
  36     --          with call to Message_MsgFile::LoadFile().
  37     --
  38     --          The messages corresponding to the statuses generated during the
  39     --          algorithm execution are output to Message_Messenger using
  40     --          methods SendMessages(). If status have associated numbers
  41     --          or strings, they are included in the message body in place of
  42     --          "%s" placeholder which should be present in the message text.
  43     --
  44     --          The name of the message text in the resource file is constructed
  45     --          from name of the class and name of the status, separated by dot,
  46     --          for instance:
  47     --
  48     --          .TObj_CheckModel.Alarm2
  49     --          Error: Some objects (%s) have references to dead object(s)
  50     --
  51     --          If message for the status is not found with prefix of
  52     --          the current class type, the same message is searched for the base
  53     --          class(es) recursively.
  54     --
  55     --          Message can be set explicitly for the status; in this case the
  56     --          above procedure is not used and supplied message is used as is.
  57     --
  58     --          The messages are output to the messenger, stored in the field;
  59     --          though messenger can be changed, it is guaranteed to be non-null.
  60     --          By default, Message::DefaultMessenger() is used.
  61
  62 uses
  63
  64     TShared                    from MMgt,
  65     HArrayOfMsg                from Message,
  66     Msg                        from Message,
  67     Messenger                  from Message,
  68     Gravity                    from Message,
  69     Status                     from Message,
  70     ExecStatus                 from Message,
  71     AsciiString                from TCollection,
  72     HAsciiString               from TCollection,
  73     ExtendedString             from TCollection,
  74     HExtendedString            from TCollection,
  75     SequenceOfInteger          from TColStd,
  76     HSequenceOfInteger         from TColStd,
  77     HArray1OfTransient         from TColStd,
  78     HPackedMapOfInteger        from TColStd,
  79     SequenceOfHExtendedString  from TColStd,
  80     HSequenceOfHExtendedString from TColStd
  81
  82 is
  83
  84     Create returns Algorithm from Message;
  85         ---Purpose: Empty constructor
  86
  87     SetStatus(me: mutable; theStat : Status from Message);
  88         ---Purpose: Sets status with no parameter
  89
  90     SetStatus(me: mutable; theStat : Status from Message;
  91                            theInt  : Integer);
  92         ---Purpose: Sets status with integer parameter
  93
  94     SetStatus(me: mutable; theStat : Status from Message;
  95                            theStr  : CString;
  96                            noRepetitions : Boolean = Standard_True);
  97         ---Purpose: Sets status with string parameter.
  98         --          If noRepetitions is True, the parameter will be added only
  99         --          if it has not been yet recorded for the same status flag
 100         ---C++: inline
 101
 102     SetStatus(me: mutable; theStat : Status from Message;
 103                            theStr  : AsciiString from TCollection;
 104                            noRepetitions : Boolean = Standard_True);
 105         ---Purpose: Sets status with string parameter
 106         --          If noRepetitions is True, the parameter will be added only
 107         --          if it has not been yet recorded for the same status flag
 108         ---C++: inline
 109
 110     SetStatus(me: mutable; theStat : Status from Message;
 111                            theStr  : HAsciiString from TCollection;
 112                            noRepetitions : Boolean = Standard_True);
 113         ---Purpose: Sets status with string parameter
 114         --          If noRepetitions is True, the parameter will be added only
 115         --          if it has not been yet recorded for the same status flag
 116         ---C++: inline
 117
 118     SetStatus(me: mutable; theStat : Status from Message;
 119                            theStr  : ExtendedString from TCollection;
 120                            noRepetitions : Boolean = Standard_True);
 121         ---Purpose: Sets status with string parameter
 122         --          If noRepetitions is True, the parameter will be added only
 123         --          if it has not been yet recorded for the same status flag
 124         ---C++: inline
 125
 126     SetStatus(me: mutable; theStat : Status from Message;
 127                            theStr  : HExtendedString from TCollection;
 128                            noRepetitions : Boolean = Standard_True);
 129         ---Purpose: Sets status with string parameter
 130         --          If noRepetitions is True, the parameter will be added only
 131         --          if it has not been yet recorded for the same status flag
 132
 133     SetStatus(me: mutable; theStat : Status from Message;
 134                            theMsg  : Msg    from Message);
 135     ---Purpose: Sets status with preformatted message. This message will be
 136     --          used directly to report the status; automatic generation of
 137     --          status messages will be disabled for it.
 138
 139     GetStatus(me) returns ExecStatus from Message;
 140         ---Purpose: Returns copy of exec status of algorithm
 141         ---C++: inline
 142         ---C++: return const &
 143
 144     ChangeStatus(me: mutable) returns ExecStatus from Message;
 145         ---Purpose: Returns exec status of algorithm
 146         ---C++: inline
 147         ---C++: return &
 148
 149     ClearStatus(me: mutable);
 150         ---Purpose: Clear exec status of algorithm
 151
 152     -- Message management
 153
 154     SetMessenger(me: mutable; theMsgr : Messenger from Message);
 155         ---Purpose: Sets messenger to algorithm
 156
 157     GetMessenger(me)
 158     returns Messenger from Message;
 159         ---Purpose: Returns messenger of algorithm.
 160         --          The returned handle is always non-null and can
 161         --          be used for sending messages.
 162         ---C++: inline
 163
 164     SendStatusMessages(me; theFilter : ExecStatus from Message;
 165                            theTraceLevel: Gravity from Message = Message_Warning;
 166                            theMaxCount: Integer = 20)
 167     is virtual;
 168         ---Purpose: Print messages for all status flags that have been set during
 169         --          algorithm execution, excluding statuses that are NOT set
 170         --          in theFilter.
 171         --
 172         --          The messages are taken from resource file, names being
 173         --          constructed as {dynamic class type}.{status name},
 174         --          for instance, "Message_Algorithm.Fail5".
 175         --          If message is not found in resources for this class and all
 176         --          its base types, surrogate text is printed.
 177         --
 178         --          For the statuses having number or string parameters,
 179         --          theMaxCount defines maximal number of numbers or strings to be
 180         --          included in the message
 181         --
 182         --          Note that this method is virtual; this allows descendant
 183         --          classes to customize message output (e.g. by adding
 184         --          messages from other sub-algorithms)
 185
 186     SendMessages(me; theTraceLevel: Gravity from Message = Message_Warning;
 187                      theMaxCount: Integer = 20);
 188         ---Purpose: Convenient variant of SendStatusMessages() with theFilter
 189         --          having defined all WARN, ALARM, and FAIL (but not DONE)
 190         --          status flags
 191
 192     AddStatus(me: mutable; theOther : Algorithm from Message);
 193         ---Purpose: Add statuses to this algorithm from other algorithm
 194         --          (including messages)
 195
 196     AddStatus(me: mutable; theStatus : ExecStatus from Message;
 197                            theOther : Algorithm from Message);
 198         ---Purpose: Add statuses to this algorithm from other algorithm, but
 199         --          only those items are moved that correspond to statuses
 200         --          set in theStatus
 201
 202     GetMessageNumbers(me; theStatus : Status from Message)
 203     returns HPackedMapOfInteger from TColStd;
 204         ---Purpose: Return the numbers associated with the indicated status;
 205         --          Null handle if no such status or no numbers associated with it
 206
 207     GetMessageStrings(me; theStatus : Status from Message)
 208     returns HSequenceOfHExtendedString from TColStd;
 209         ---Purpose: Return the strings associated with the indicated status;
 210         --          Null handle if no such status or no strings associated with it
 211
 212     PrepareReport(myclass; theError : HPackedMapOfInteger from TColStd;
 213                            theMaxCount: Integer)
 214     returns ExtendedString from TCollection;
 215         ---Purpose: Prepares a string containing a list of integers contained
 216         --          in theError map, but not more than theMaxCount
 217
 218     PrepareReport(myclass; theReportSeq : SequenceOfHExtendedString from TColStd;
 219                            theMaxCount: Integer)
 220     returns ExtendedString from TCollection;
 221         ---Purpose: Prepares a string containing a list of names contained
 222         --          in theReportSeq sequence, but not more than theMaxCount
 223
 224 fields
 225
 226     myStatus         : ExecStatus         from Message is protected;
 227     myMessenger      : Messenger          from Message is protected;
 228     myReportIntegers : HArray1OfTransient from TColStd;
 229     myReportStrings  : HArray1OfTransient from TColStd;
 230     myReportMessages : HArrayOfMsg        from Message;
 231
 232 end Algorithm;