include/opencascade/Message_Report.hxx

0001 // Created on: 2017-06-26
0002 // Created by: Andrey Betenev
0003 // Copyright (c) 2017 OPEN CASCADE SAS
0004 //
0005 // This file is part of Open CASCADE Technology software library.
0006 //
0007 // This library is free software; you can redistribute it and/or modify it under
0008 // the terms of the GNU Lesser General Public License version 2.1 as published
0009 // by the Free Software Foundation, with special exception defined in the file
0010 // OCCT_LGPL_EXCEPTION.txt. Consult the file LICENSE_LGPL_21.txt included in OCCT
0011 // distribution for complete text of the license and disclaimer of any warranty.
0012 //
0013 // Alternatively, this file may be used under the terms of Open CASCADE
0014 // commercial license or contractual agreement.
0015
0016 #ifndef _Message_Report_HeaderFile
0017 #define _Message_Report_HeaderFile
0018
0019 #include <Message_Level.hxx>
0020 #include <Message_Alert.hxx>
0021 #include <NCollection_List.hxx>
0022 #include <Message_MetricType.hxx>
0023 #include <NCollection_IndexedMap.hxx>
0024 #include <NCollection_Sequence.hxx>
0025
0026 #include <mutex>
0027
0028 class Message_CompositeAlerts;
0029 class Message_Messenger;
0030
0031 //! Container for alert messages, sorted according to their gravity.
0032 //!
0033 //! For each gravity level, alerts are stored in simple list.
0034 //! If alert being added can be merged with another alert of the same
0035 //! type already in the list, it is merged and not added to the list.
0036 //!
0037 //! This class is intended to be used as follows:
0038 //!
0039 //! - In the process of execution, algorithm fills report by alert objects
0040 //!   using methods AddAlert()
0041 //!
0042 //! - The result can be queried for presence of particular alert using
0043 //!   methods HasAlert()
0044 //!
0045 //! - The reports produced by nested or sequentially executed algorithms
0046 //!   can be collected in one using method Merge()
0047 //!
0048 //! - The report can be shown to the user either as plain text with method
0049 //!   Dump() or in more advanced way, by iterating over lists returned by GetAlerts()
0050 //!
0051 //! - Report can be cleared by methods Clear() (usually after reporting)
0052 //!
0053 //! Message_PrinterToReport is a printer in Messenger to convert data sent to messenger into report
0054 class Message_Report : public Standard_Transient
0055 {
0056 public:
0057   //! Empty constructor
0058   Standard_EXPORT Message_Report();
0059
0060   //! Add alert with specified gravity.
0061   //! This method is thread-safe, i.e. alerts can be added from parallel threads safely.
0062   Standard_EXPORT void AddAlert(Message_Gravity                   theGravity,
0063                                 const occ::handle<Message_Alert>& theAlert);
0064
0065   //! Returns list of collected alerts with specified gravity
0066   Standard_EXPORT const NCollection_List<occ::handle<Message_Alert>>& GetAlerts(
0067     Message_Gravity theGravity) const;
0068
0069   //! Returns true if specific type of alert is recorded
0070   Standard_EXPORT bool HasAlert(const occ::handle<Standard_Type>& theType);
0071
0072   //! Returns true if specific type of alert is recorded with specified gravity
0073   Standard_EXPORT bool HasAlert(const occ::handle<Standard_Type>& theType,
0074                                 Message_Gravity                   theGravity);
0075
0076   //! Returns true if a report printer for the current report is registered in the messenger
0077   //! @param theMessenger the messenger. If it's NULL, the default messenger is used
0078   Standard_EXPORT bool IsActiveInMessenger(
0079     const occ::handle<Message_Messenger>& theMessenger = nullptr) const;
0080
0081   //! Creates an instance of Message_PrinterToReport with the current report and register it in
0082   //! messenger
0083   //! @param toActivate if true, activated else deactivated
0084   //! @param theMessenger the messenger. If it's NULL, the default messenger is used
0085   Standard_EXPORT void ActivateInMessenger(
0086     const bool                            toActivate,
0087     const occ::handle<Message_Messenger>& theMessenger = nullptr);
0088
0089   //! Updates internal flag IsActiveInMessenger.
0090   //! It becomes true if messenger contains at least one instance of Message_PrinterToReport.
0091   //! @param theMessenger the messenger. If it's NULL, the default messenger is used
0092   Standard_EXPORT void UpdateActiveInMessenger(
0093     const occ::handle<Message_Messenger>& theMessenger = nullptr);
0094
0095   //! Add new level of alerts
0096   //! @param theLevel a level
0097   Standard_EXPORT void AddLevel(Message_Level* theLevel, const TCollection_AsciiString& theName);
0098
0099   //! Remove level of alerts
0100   Standard_EXPORT void RemoveLevel(Message_Level* theLevel);
0101
0102   //! Clears all collected alerts
0103   Standard_EXPORT void Clear();
0104
0105   //! Clears collected alerts with specified gravity
0106   Standard_EXPORT void Clear(Message_Gravity theGravity);
0107
0108   //! Clears collected alerts with specified type
0109   Standard_EXPORT void Clear(const occ::handle<Standard_Type>& theType);
0110
0111   //! Returns computed metrics when alerts are performed
0112   const NCollection_IndexedMap<Message_MetricType>& ActiveMetrics() const
0113   {
0114     return myActiveMetrics;
0115   }
0116
0117   //! Sets metrics to compute when alerts are performed
0118   //! @param theMetrics container of metrics
0119   Standard_EXPORT void SetActiveMetric(const Message_MetricType theMetricType,
0120                                        const bool               theActivate);
0121
0122   //! Removes all activated metrics
0123   void ClearMetrics() { myActiveMetrics.Clear(); }
0124
0125   //! Returns maximum number of collecting alerts. If the limit is achieved,
0126   //! first alert is removed, the new alert is added in the container.
0127   //! @return the limit value
0128   int Limit() const { return myLimit; }
0129
0130   //! Sets maximum number of collecting alerts.
0131   //! @param theLimit limit value
0132   void SetLimit(const int theLimit) { myLimit = theLimit; }
0133
0134   //! Dumps all collected alerts to stream
0135   Standard_EXPORT void Dump(Standard_OStream& theOS);
0136
0137   //! Dumps collected alerts with specified gravity to stream
0138   Standard_EXPORT void Dump(Standard_OStream& theOS, Message_Gravity theGravity);
0139
0140   //! Sends all collected alerts to messenger.
0141   Standard_EXPORT virtual void SendMessages(const occ::handle<Message_Messenger>& theMessenger);
0142
0143   //! Dumps collected alerts with specified gravity to messenger.
0144   //! Default implementation creates Message_Msg object with a message
0145   //! key returned by alert, and sends it in the messenger.
0146   Standard_EXPORT virtual void SendMessages(const occ::handle<Message_Messenger>& theMessenger,
0147                                             Message_Gravity                       theGravity);
0148
0149   //! Merges data from theOther report into this
0150   Standard_EXPORT void Merge(const occ::handle<Message_Report>& theOther);
0151
0152   //! Merges alerts with specified gravity from theOther report into this
0153   Standard_EXPORT void Merge(const occ::handle<Message_Report>& theOther,
0154                              Message_Gravity                    theGravity);
0155
0156   //! Dumps the content of me into the stream
0157   Standard_EXPORT void DumpJson(Standard_OStream& theOStream, int theDepth = -1) const;
0158
0159   // OCCT RTTI
0160   DEFINE_STANDARD_RTTIEXT(Message_Report, Standard_Transient)
0161
0162 protected:
0163   //! Returns class provided hierarchy of alerts if created or create if the parameter is true
0164   //! @param isCreate if composite alert has not been created for this alert, it should be created
0165   //! @return instance or NULL
0166   Standard_EXPORT const occ::handle<Message_CompositeAlerts>& compositeAlerts(
0167     const bool isCreate = false);
0168
0169   //! Sends alerts to messenger
0170   Standard_EXPORT void sendMessages(const occ::handle<Message_Messenger>&       theMessenger,
0171                                     Message_Gravity                             theGravity,
0172                                     const occ::handle<Message_CompositeAlerts>& theCompositeAlert);
0173
0174   //! Dumps collected alerts with specified gravity to stream
0175   Standard_EXPORT void dumpMessages(Standard_OStream&                           theOS,
0176                                     Message_Gravity                             theGravity,
0177                                     const occ::handle<Message_CompositeAlerts>& theCompositeAlert);
0178
0179 protected:
0180   std::mutex myMutex;
0181
0182   occ::handle<Message_CompositeAlerts> myCompositAlerts; //!< container of alerts
0183
0184   // clang-format off
0185   NCollection_Sequence<Message_Level*> myAlertLevels;   //!< container of active levels, new alerts are added below the latest level
0186   // clang-format on
0187   NCollection_IndexedMap<Message_MetricType> myActiveMetrics; //!< metrics to compute on alerts
0188
0189   int  myLimit;               //!< Maximum number of collected alerts on the top level
0190   bool myIsActiveInMessenger; //! state whether the report is activated in messenger
0191 };
0192
0193 #endif // _Message_Report_HeaderFile