-- Created on: 2007-07-06 -- Created by: Pavel TELKOV -- Copyright (c) 2007-2014 OPEN CASCADE SAS -- -- This file is part of Open CASCADE Technology software library. -- -- This library is free software; you can redistribute it and/or modify it under -- the terms of the GNU Lesser General Public License version 2.1 as published -- by the Free Software Foundation, with special exception defined in the file -- OCCT_LGPL_EXCEPTION.txt. Consult the file LICENSE_LGPL_21.txt included in OCCT -- distribution for complete text of the license and disclaimer of any warranty. -- -- Alternatively, this file may be used under the terms of Open CASCADE -- commercial license or contractual agreement. -- 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. -- -- Message can be set explicitly for the status; in this case the -- above procedure is not used and supplied message is used as is. -- -- 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, HArrayOfMsg from Message, Msg from Message, 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 SetStatus(me: mutable; theStat : Status from Message; theMsg : Msg from Message); ---Purpose: Sets status with preformatted message. This message will be -- used directly to report the status; automatic generation of -- status messages will be disabled for it. 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; myReportMessages : HArrayOfMsg from Message; end Algorithm;