-- File: Message_Algorithm.cdl -- Created: Fri Jul 6 09:22:36 2007 -- Author: Pavel TELKOV -- -- Copyright: Open CASCADE S.A. 2007 -- The original implementation copyright (c) RINA S.p.A class Algorithm from Message inherits TShared from MMgt ---Purpose: Class Message_Algorithm is intended to be the base class for -- classes implementing algorithms or any operations that need -- to provide extended information on its execution to the -- caller / user. -- -- It provides generic mechanism for management of the execution -- status, collection and output of messages. -- -- The algorithm uses methods SetStatus() to set an execution status. -- It is possible to associate a status with a number or a string -- (second argument of SetStatus() methods) to indicate precisely -- the item (object, element etc.) in the input data which caused -- the problem. -- -- Each execution status generated by the algorithm has associated -- text message that should be defined in the resouce file loaded -- with call to Message_MsgFile::LoadFile(). -- -- The messages corresponding to the statuses generated during the -- algorithm execution are output to Message_Messenger using -- methods SendMessages(). If status have associated numbers -- or strings, they are included in the message body in place of -- "%s" placeholder which should be present in the message text. -- -- The name of the message text in the resource file is constructed -- from name of the class and name of the status, separated by dot, -- for instance: -- -- .TObj_CheckModel.Alarm2 -- Error: Some objects (%s) have references to dead object(s) -- -- If message for the status is not found with prefix of -- the current class type, the same message is searched for the base -- class(es) recursively. -- -- The messages are output to the messenger, stored in the field; -- though messenger can be changed, it is guaranteed to be non-null. -- By default, Message::DefaultMessenger() is used. uses TShared from MMgt, Messenger from Message, Gravity from Message, Status from Message, ExecStatus from Message, AsciiString from TCollection, HAsciiString from TCollection, ExtendedString from TCollection, HExtendedString from TCollection, SequenceOfInteger from TColStd, HSequenceOfInteger from TColStd, HArray1OfTransient from TColStd, HPackedMapOfInteger from TColStd, SequenceOfHExtendedString from TColStd, HSequenceOfHExtendedString from TColStd is Create returns Algorithm from Message; ---Purpose: Empty constructor SetStatus(me: mutable; theStat : Status from Message); ---Purpose: Sets status with no parameter SetStatus(me: mutable; theStat : Status from Message; theInt : Integer); ---Purpose: Sets status with integer parameter SetStatus(me: mutable; theStat : Status from Message; theStr : CString; noRepetitions : Boolean = Standard_True); ---Purpose: Sets status with string parameter. -- If noRepetitions is True, the parameter will be added only -- if it has not been yet recorded for the same status flag ---C++: inline SetStatus(me: mutable; theStat : Status from Message; theStr : AsciiString from TCollection; noRepetitions : Boolean = Standard_True); ---Purpose: Sets status with string parameter -- If noRepetitions is True, the parameter will be added only -- if it has not been yet recorded for the same status flag ---C++: inline SetStatus(me: mutable; theStat : Status from Message; theStr : HAsciiString from TCollection; noRepetitions : Boolean = Standard_True); ---Purpose: Sets status with string parameter -- If noRepetitions is True, the parameter will be added only -- if it has not been yet recorded for the same status flag ---C++: inline SetStatus(me: mutable; theStat : Status from Message; theStr : ExtendedString from TCollection; noRepetitions : Boolean = Standard_True); ---Purpose: Sets status with string parameter -- If noRepetitions is True, the parameter will be added only -- if it has not been yet recorded for the same status flag ---C++: inline SetStatus(me: mutable; theStat : Status from Message; theStr : HExtendedString from TCollection; noRepetitions : Boolean = Standard_True); ---Purpose: Sets status with string parameter -- If noRepetitions is True, the parameter will be added only -- if it has not been yet recorded for the same status flag GetStatus(me) returns ExecStatus from Message; ---Purpose: Returns copy of exec status of algorithm ---C++: inline ---C++: return const & ChangeStatus(me: mutable) returns ExecStatus from Message; ---Purpose: Returns exec status of algorithm ---C++: inline ---C++: return & ClearStatus(me: mutable); ---Purpose: Clear exec status of algorithm -- Message management SetMessenger(me: mutable; theMsgr : Messenger from Message); ---Purpose: Sets messenger to algorithm GetMessenger(me) returns Messenger from Message; ---Purpose: Returns messenger of algorithm. -- The returned handle is always non-null and can -- be used for sending messages. ---C++: inline SendStatusMessages(me; theFilter : ExecStatus from Message; theTraceLevel: Gravity from Message = Message_Warning; theMaxCount: Integer = 20) is virtual; ---Purpose: Print messages for all status flags that have been set during -- algorithm execution, excluding statuses that are NOT set -- in theFilter. -- -- The messages are taken from resource file, names being -- constructed as {dynamic class type}.{status name}, -- for instance, "Message_Algorithm.Fail5". -- If message is not found in resources for this class and all -- its base types, surrogate text is printed. -- -- For the statuses having number or string parameters, -- theMaxCount defines maximal number of numbers or strings to be -- included in the message -- -- Note that this method is virtual; this allows descendant -- classes to customize message output (e.g. by adding -- messages from other sub-algorithms) SendMessages(me; theTraceLevel: Gravity from Message = Message_Warning; theMaxCount: Integer = 20); ---Purpose: Convenient variant of SendStatusMessages() with theFilter -- having defined all WARN, ALARM, and FAIL (but not DONE) -- status flags AddStatus(me: mutable; theOther : Algorithm from Message); ---Purpose: Add statuses to this algorithm from other algorithm -- (including messages) AddStatus(me: mutable; theStatus : ExecStatus from Message; theOther : Algorithm from Message); ---Purpose: Add statuses to this algorithm from other algorithm, but -- only those items are moved that correspond to statuses -- set in theStatus GetMessageNumbers(me; theStatus : Status from Message) returns HPackedMapOfInteger from TColStd; ---Purpose: Return the numbers associated with the indicated status; -- Null handle if no such status or no numbers associated with it GetMessageStrings(me; theStatus : Status from Message) returns HSequenceOfHExtendedString from TColStd; ---Purpose: Return the strings associated with the indicated status; -- Null handle if no such status or no strings associated with it PrepareReport(myclass; theError : HPackedMapOfInteger from TColStd; theMaxCount: Integer) returns ExtendedString from TCollection; ---Purpose: Prepares a string containing a list of integers contained -- in theError map, but not more than theMaxCount PrepareReport(myclass; theReportSeq : SequenceOfHExtendedString from TColStd; theMaxCount: Integer) returns ExtendedString from TCollection; ---Purpose: Prepares a string containing a list of names contained -- in theReportSeq sequence, but not more than theMaxCount fields myStatus : ExecStatus from Message is protected; myMessenger : Messenger from Message is protected; myReportIntegers : HArray1OfTransient from TColStd; myReportStrings : HArray1OfTransient from TColStd; end Algorithm;