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 Interface_Check;
32 class Standard_Transient;
33 class Interface_GeneralLib;
34 class Interface_ReaderLib;
37 //! Defines services which are required to load an InterfaceModel
38 //! from a File. Typically, it may firstly transform a system
39 //! file into a FileReaderData object, then work on it, not longer
40 //! considering file contents, to load an Interface Model.
41 //! It may also work on a FileReaderData already loaded.
43 //! FileReaderTool provides, on one hand, some general services
44 //! which are common to all read operations but can be redefined,
45 //! plus general actions to be performed specifically for each
46 //! Norm, as deferred methods to define.
48 //! In particular, FileReaderTool defines the Interface's Unknown
49 //! and Error entities
50 class Interface_FileReaderTool
57 //! Sets Data to a FileReaderData. Works with a Protocol
58 Standard_EXPORT void SetData (const Handle(Interface_FileReaderData)& reader, const Handle(Interface_Protocol)& protocol);
60 //! Returns the Protocol given at creation time
61 Standard_EXPORT Handle(Interface_Protocol) Protocol() const;
63 //! Returns the FileReaderData which is used to work
64 Standard_EXPORT Handle(Interface_FileReaderData) Data() const;
66 //! Stores a Model. Used when the Model has been loaded
67 Standard_EXPORT void SetModel (const Handle(Interface_InterfaceModel)& amodel);
69 //! Returns the stored Model
70 Standard_EXPORT Handle(Interface_InterfaceModel) Model() const;
72 //! Sets Messenger used for outputting messages
73 Standard_EXPORT void SetMessenger (const Handle(Message_Messenger)& messenger);
75 //! Returns Messenger used for outputting messages.
76 //! The returned object is guaranteed to be non-null;
77 //! default is Message::Messenger().
78 Standard_EXPORT Handle(Message_Messenger) Messenger() const;
80 //! Sets trace level used for outputting messages
81 //! - 0: no trace at all
83 //! - 2: errors and warnings
85 //! Default is 1 : Errors traced
86 Standard_EXPORT void SetTraceLevel (const Standard_Integer tracelev);
88 //! Returns trace level used for outputting messages.
89 Standard_EXPORT Standard_Integer TraceLevel() const;
91 //! Allows controlling whether exception raisings are handled
92 //! If err is False, they are not (hence, dbx can take control)
93 //! If err is True, they are, and they are traced
94 //! (by putting on messenger Entity's Number and file record num)
95 //! Default given at Model's creation time is True
96 Standard_EXPORT void SetErrorHandle (const Standard_Boolean err);
98 //! Returns ErrorHandle flag
99 Standard_EXPORT Standard_Boolean ErrorHandle() const;
101 //! Fills records with empty entities; once done, each entity can
102 //! ask the FileReaderTool for any entity referenced through an
103 //! identifier. Calls Recognize which is specific to each specific
104 //! type of FileReaderTool
105 Standard_EXPORT void SetEntities();
107 //! Recognizes a record, given its number. Specific to each
108 //! Interface; called by SetEntities. It can call the basic method
110 //! Returns False if recognition has failed, True else.
111 //! <ach> has not to be filled if simply Recognition has failed :
112 //! it must record true error messages : RecognizeByLib can
113 //! generate error messages if NewRead is called
115 //! Note that it works thru a Recognizer (method Evaluate) which
116 //! has to be memorized before starting
117 Standard_EXPORT virtual Standard_Boolean Recognize (const Standard_Integer num, Handle(Interface_Check)& ach, Handle(Standard_Transient)& ent) = 0;
119 //! Recognizes a record with the help of Libraries. Can be used
120 //! to implement the method Recognize.
121 //! <rlib> is used to find Protocol and CaseNumber to apply
122 //! <glib> performs the creation (by service NewVoid, or NewRead
123 //! if NewVoid gave no result)
124 //! <ach> is a check, which is transmitted to NewRead if it is
125 //! called, gives a result but which is false
126 //! <ent> is the result
127 //! Returns False if recognition has failed, True else
128 Standard_EXPORT Standard_Boolean RecognizeByLib (const Standard_Integer num, Interface_GeneralLib& glib, Interface_ReaderLib& rlib, Handle(Interface_Check)& ach, Handle(Standard_Transient)& ent) const;
130 //! Provides an unknown entity, specific to the Interface
131 //! called by SetEntities when Recognize has failed (Unknown alone)
132 //! or by LoadModel when an Entity has caused a Fail on reading
133 //! (to keep at least its literal description)
134 //! Uses Protocol to do it
135 Standard_EXPORT Handle(Standard_Transient) UnknownEntity() const;
137 //! Creates an empty Model of the norm. Uses Protocol to do it
138 Standard_EXPORT Handle(Interface_InterfaceModel) NewModel() const;
140 //! Reads and fills Entities from the FileReaderData set by
141 //! SetData to an InterfaceModel.
142 //! It enchains required operations, the specific ones correspond
143 //! to deferred methods (below) to be defined for each Norm.
144 //! It manages also error recovery and trace.
145 //! Remark : it calls SetModel.
146 //! It Can raise any error which can occur during a load
147 //! operation, unless Error Handling is set.
148 //! This method can also be redefined if judged necessary.
149 Standard_EXPORT void LoadModel (const Handle(Interface_InterfaceModel)& amodel);
151 //! Reads, Fills and Returns one Entity read from a Record of the
152 //! FileReaderData. This Method manages also case of Fail or
153 //! Warning, by producing a ReportEntyty plus , for a Fail, a
154 //! literal Content (as an UnknownEntity). Performs also Trace
155 Standard_EXPORT Handle(Standard_Transient) LoadedEntity (const Standard_Integer num);
157 //! Fills model's header; each Interface defines for its Model its
158 //! own file header; this method fills it from FileReaderTool.+
159 //! It is called by AnalyseFile from InterfaceModel
160 Standard_EXPORT virtual void BeginRead (const Handle(Interface_InterfaceModel)& amodel) = 0;
162 //! Fills an Entity, given record no; specific to each Interface,
163 //! called by AnalyseFile from InterfaceModel (which manages its
164 //! calling arguments)
165 //! To work, each Interface can define a method in its proper
166 //! Transient class, like this (given as an example) :
167 //! AnalyseRecord (me : mutable; FR : in out FileReaderTool;
168 //! num : Integer; acheck : in out Check)
170 //! and call it from AnalyseRecord
172 //! Returned Value : True if the entity could be loaded, False
173 //! else (in case of syntactic fail)
174 Standard_EXPORT virtual Standard_Boolean AnalyseRecord (const Standard_Integer num, const Handle(Standard_Transient)& anent, Handle(Interface_Check)& acheck) = 0;
176 Standard_EXPORT virtual ~Interface_FileReaderTool();
178 //! Ends file reading after reading all the entities
179 //! default is doing nothing; redefinable as necessary
180 Standard_EXPORT virtual void EndRead (const Handle(Interface_InterfaceModel)& amodel);
183 Standard_EXPORT void Clear();
191 //! Constructor; sets default fields
192 Standard_EXPORT Interface_FileReaderTool();
201 Handle(Interface_Protocol) theproto;
202 Handle(Interface_FileReaderData) thereader;
203 Handle(Interface_InterfaceModel) themodel;
204 Handle(Message_Messenger) themessenger;
205 Standard_Integer thetrace;
206 Standard_Boolean theerrhand;
207 Standard_Integer thenbrep0;
208 Standard_Integer thenbreps;
209 Handle(TColStd_HArray1OfTransient) thereports;
220 #endif // _Interface_FileReaderTool_HeaderFile