[occt.git] / src / Message / Message_Algorithm.cdl

-- Created on: 2007-07-06
-- Created by: Pavel TELKOV
-- Copyright (c) 2007-2012 OPEN CASCADE SAS
--
-- The content of this file is subject to the Open CASCADE Technology Public
-- License Version 6.5 (the "License"). You may not use the content of this file
-- except in compliance with the License. Please obtain a copy of the License
-- at http://www.opencascade.org and read it completely before using this file.
--
-- The Initial Developer of the Original Code is Open CASCADE S.A.S., having its
-- main offices at: 1, place des Freres Montgolfier, 78280 Guyancourt, France.
--
-- The Original Code and all software distributed under the License is
-- distributed on an "AS IS" basis, without warranty of any kind, and the
-- Initial Developer hereby disclaims all such warranties, including without
-- limitation, any warranties of merchantability, fitness for a particular
-- purpose or non-infringement. Please see the License for the specific terms
-- and conditions governing the rights and limitations under the License.

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