src/Message/Message_Algorithm.cdl

   1 -- File:        Message_Algorithm.cdl
   2 -- Created:     Fri Jul  6 09:22:36 2007
   3 -- Author:      Pavel TELKOV
   4 --              <ptv@valenox>
   5 -- Copyright:   Open CASCADE S.A. 2007
   6 -- The original implementation copyright (c) RINA S.p.A
   7
   8 class Algorithm from Message inherits TShared from MMgt
   9
  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
  13     --          caller / user.
  14     --
  15     --          It provides generic mechanism for management of the execution
  16     --          status, collection and output of messages.
  17     --
  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
  22     --          the problem.
  23     --
  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().
  27     --
  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.
  33     --
  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,
  36     --          for instance:
  37     --
  38     --          .TObj_CheckModel.Alarm2
  39     --          Error: Some objects (%s) have references to dead object(s)
  40     --
  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.
  44     --
  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.
  48
  49 uses
  50
  51     TShared                    from MMgt,
  52     Messenger                  from Message,
  53     Gravity                    from Message,
  54     Status                     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
  66
  67 is
  68
  69     Create returns Algorithm from Message;
  70         ---Purpose: Empty constructor
  71
  72     SetStatus(me: mutable; theStat : Status from Message);
  73         ---Purpose: Sets status with no parameter
  74
  75     SetStatus(me: mutable; theStat : Status from Message;
  76                            theInt  : Integer);
  77         ---Purpose: Sets status with integer parameter
  78
  79     SetStatus(me: mutable; theStat : Status from Message;
  80                            theStr  : CString;
  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
  85         ---C++: inline
  86
  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
  93         ---C++: inline
  94
  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
 101         ---C++: inline
 102
 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
 109         ---C++: inline
 110
 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
 117
 118     GetStatus(me) returns ExecStatus from Message;
 119         ---Purpose: Returns copy of exec status of algorithm
 120         ---C++: inline
 121         ---C++: return const &
 122
 123     ChangeStatus(me: mutable) returns ExecStatus from Message;
 124         ---Purpose: Returns exec status of algorithm
 125         ---C++: inline
 126         ---C++: return &
 127
 128     ClearStatus(me: mutable);
 129         ---Purpose: Clear exec status of algorithm
 130
 131     -- Message management
 132
 133     SetMessenger(me: mutable; theMsgr : Messenger from Message);
 134         ---Purpose: Sets messenger to algorithm
 135
 136     GetMessenger(me)
 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.
 141         ---C++: inline
 142
 143     SendStatusMessages(me; theFilter : ExecStatus from Message;
 144                            theTraceLevel: Gravity from Message = Message_Warning;
 145                            theMaxCount: Integer = 20)
 146     is virtual;
 147         ---Purpose: Print messages for all status flags that have been set during
 148         --          algorithm execution, excluding statuses that are NOT set
 149         --          in theFilter.
 150         --
 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.
 156         --
 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
 160         --
 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)
 164
 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)
 169         --          status flags
 170
 171     AddStatus(me: mutable; theOther : Algorithm from Message);
 172         ---Purpose: Add statuses to this algorithm from other algorithm
 173         --          (including messages)
 174
 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
 179         --          set in theStatus
 180
 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
 185
 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
 190
 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
 196
 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
 202
 203 fields
 204
 205     myStatus         : ExecStatus         from Message is protected;
 206     myMessenger      : Messenger          from Message is protected;
 207     myReportIntegers : HArray1OfTransient from TColStd;
 208     myReportStrings  : HArray1OfTransient from TColStd;
 209
 210 end Algorithm;