1 // Created on: 1993-02-04
2 // Created by: Christian CAILLET
3 // Copyright (c) 1993-1999 Matra Datavision
4 // Copyright (c) 1999-2014 OPEN CASCADE SAS
6 // This file is part of Open CASCADE Technology software library.
8 // This library is free software; you can redistribute it and/or modify it under
9 // the terms of the GNU Lesser General Public License version 2.1 as published
10 // by the Free Software Foundation, with special exception defined in the file
11 // OCCT_LGPL_EXCEPTION.txt. Consult the file LICENSE_LGPL_21.txt included in OCCT
12 // distribution for complete text of the license and disclaimer of any warranty.
14 // Alternatively, this file may be used under the terms of Open CASCADE
15 // commercial license or contractual agreement.
17 #ifndef _Interface_FileReaderTool_HeaderFile
18 #define _Interface_FileReaderTool_HeaderFile
20 #include <Standard.hxx>
21 #include <Standard_DefineAlloc.hxx>
22 #include <Standard_Handle.hxx>
24 #include <Standard_Integer.hxx>
25 #include <Standard_Boolean.hxx>
26 #include <TColStd_HArray1OfTransient.hxx>
27 class Interface_Protocol;
28 class Interface_FileReaderData;
29 class Interface_InterfaceModel;
30 class Message_Messenger;
31 class Standard_DomainError;
32 class Standard_NoSuchObject;
33 class Interface_Check;
34 class Standard_Transient;
35 class Interface_GeneralLib;
36 class Interface_ReaderLib;
39 //! Defines services which are required to load an InterfaceModel
40 //! from a File. Typically, it may firstly transform a system
41 //! file into a FileReaderData object, then work on it, not longer
42 //! considering file contents, to load an Interface Model.
43 //! It may also work on a FileReaderData already loaded.
45 //! FileReaderTool provides, on one hand, some general services
46 //! which are common to all read operations but can be redefined,
47 //! plus general actions to be performed specifically for each
48 //! Norm, as deferred methods to define.
50 //! In particular, FileReaderTool defines the Interface's Unknown
51 //! and Error entities
52 class Interface_FileReaderTool
59 //! Sets Data to a FileReaderData. Works with a Protocol
60 Standard_EXPORT void SetData (const Handle(Interface_FileReaderData)& reader, const Handle(Interface_Protocol)& protocol);
62 //! Returns the Protocol given at creation time
63 Standard_EXPORT Handle(Interface_Protocol) Protocol() const;
65 //! Returns the FileReaderData which is used to work
66 Standard_EXPORT Handle(Interface_FileReaderData) Data() const;
68 //! Stores a Model. Used when the Model has been loaded
69 Standard_EXPORT void SetModel (const Handle(Interface_InterfaceModel)& amodel);
71 //! Returns the stored Model
72 Standard_EXPORT Handle(Interface_InterfaceModel) Model() const;
74 //! Sets Messenger used for outputting messages
75 Standard_EXPORT void SetMessenger (const Handle(Message_Messenger)& messenger);
77 //! Returns Messenger used for outputting messages.
78 //! The returned object is guaranteed to be non-null;
79 //! default is Message::Messenger().
80 Standard_EXPORT Handle(Message_Messenger) Messenger() const;
82 //! Sets trace level used for outputting messages
83 //! - 0: no trace at all
85 //! - 2: errors and warnings
87 //! Default is 1 : Errors traced
88 Standard_EXPORT void SetTraceLevel (const Standard_Integer tracelev);
90 //! Returns trace level used for outputting messages.
91 Standard_EXPORT Standard_Integer TraceLevel() const;
93 //! Allows controlling whether exception raisings are handled
94 //! If err is False, they are not (hence, dbx can take control)
95 //! If err is True, they are, and they are traced
96 //! (by putting on messenger Entity's Number and file record num)
97 //! Default given at Model's creation time is True
98 Standard_EXPORT void SetErrorHandle (const Standard_Boolean err);
100 //! Returns ErrorHandle flag
101 Standard_EXPORT Standard_Boolean ErrorHandle() const;
103 //! Fills records with empty entities; once done, each entity can
104 //! ask the FileReaderTool for any entity referenced through an
105 //! identifier. Calls Recognize which is specific to each specific
106 //! type of FileReaderTool
107 Standard_EXPORT void SetEntities();
109 //! Recognizes a record, given its number. Specific to each
110 //! Interface; called by SetEntities. It can call the basic method
112 //! Returns False if recognition has failed, True else.
113 //! <ach> has not to be filled if simply Recognition has failed :
114 //! it must record true error messages : RecognizeByLib can
115 //! generate error messages if NewRead is called
117 //! Note that it works thru a Recognizer (method Evaluate) which
118 //! has to be memorized before starting
119 Standard_EXPORT virtual Standard_Boolean Recognize (const Standard_Integer num, Handle(Interface_Check)& ach, Handle(Standard_Transient)& ent) = 0;
121 //! Recognizes a record with the help of Libraries. Can be used
122 //! to implement the method Recognize.
123 //! <rlib> is used to find Protocol and CaseNumber to apply
124 //! <glib> performs the creation (by service NewVoid, or NewRead
125 //! if NewVoid gave no result)
126 //! <ach> is a check, which is transmitted to NewRead if it is
127 //! called, gives a result but which is false
128 //! <ent> is the result
129 //! Returns False if recognition has failed, True else
130 Standard_EXPORT Standard_Boolean RecognizeByLib (const Standard_Integer num, Interface_GeneralLib& glib, Interface_ReaderLib& rlib, Handle(Interface_Check)& ach, Handle(Standard_Transient)& ent) const;
132 //! Provides an unknown entity, specific to the Interface
133 //! called by SetEntities when Recognize has failed (Unknown alone)
134 //! or by LoadModel when an Entity has caused a Fail on reading
135 //! (to keep at least its literal description)
136 //! Uses Protocol to do it
137 Standard_EXPORT Handle(Standard_Transient) UnknownEntity() const;
139 //! Creates an empty Model of the norm. Uses Protocol to do it
140 Standard_EXPORT Handle(Interface_InterfaceModel) NewModel() const;
142 //! Reads and fills Entities from the FileReaderData set by
143 //! SetData to an InterfaceModel.
144 //! It enchains required operations, the specific ones correspond
145 //! to deferred methods (below) to be defined for each Norm.
146 //! It manages also error recovery and trace.
147 //! Remark : it calls SetModel.
148 //! It Can raise any error which can occur during a load
149 //! operation, unless Error Handling is set.
150 //! This method can also be redefined if judged necessary.
151 Standard_EXPORT void LoadModel (const Handle(Interface_InterfaceModel)& amodel);
153 //! Reads, Fills and Returns one Entity read from a Record of the
154 //! FileReaderData. This Method manages also case of Fail or
155 //! Warning, by producing a ReportEntyty plus , for a Fail, a
156 //! literal Content (as an UnknownEntity). Performs also Trace
157 Standard_EXPORT Handle(Standard_Transient) LoadedEntity (const Standard_Integer num);
159 //! Fills model's header; each Interface defines for its Model its
160 //! own file header; this method fills it from FileReaderTool.+
161 //! It is called by AnalyseFile from InterfaceModel
162 Standard_EXPORT virtual void BeginRead (const Handle(Interface_InterfaceModel)& amodel) = 0;
164 //! Fills an Entity, given record no; specific to each Interface,
165 //! called by AnalyseFile from InterfaceModel (which manages its
166 //! calling arguments)
167 //! To work, each Interface can define a method in its proper
168 //! Transient class, like this (given as an example) :
169 //! AnalyseRecord (me : mutable; FR : in out FileReaderTool;
170 //! num : Integer; acheck : in out Check)
172 //! and call it from AnalyseRecord
174 //! Returned Value : True if the entity could be loaded, False
175 //! else (in case of syntactic fail)
176 Standard_EXPORT virtual Standard_Boolean AnalyseRecord (const Standard_Integer num, const Handle(Standard_Transient)& anent, Handle(Interface_Check)& acheck) = 0;
178 Standard_EXPORT virtual ~Interface_FileReaderTool();
180 //! Ends file reading after reading all the entities
181 //! default is doing nothing; redefinable as necessary
182 Standard_EXPORT virtual void EndRead (const Handle(Interface_InterfaceModel)& amodel);
185 Standard_EXPORT void Clear();
193 //! Constructor; sets default fields
194 Standard_EXPORT Interface_FileReaderTool();
203 Handle(Interface_Protocol) theproto;
204 Handle(Interface_FileReaderData) thereader;
205 Handle(Interface_InterfaceModel) themodel;
206 Handle(Message_Messenger) themessenger;
207 Standard_Integer thetrace;
208 Standard_Boolean theerrhand;
209 Standard_Integer thenbrep0;
210 Standard_Integer thenbreps;
211 Handle(TColStd_HArray1OfTransient) thereports;
222 #endif // _Interface_FileReaderTool_HeaderFile