OpenWalnut  1.4.0
WProjectFile.h
1 //---------------------------------------------------------------------------
2 //
3 // Project: OpenWalnut ( http://www.openwalnut.org )
4 //
5 // Copyright 2009 OpenWalnut Community, BSV@Uni-Leipzig and CNCF@MPI-CBS
6 // For more information see http://www.openwalnut.org/copying
7 //
8 // This file is part of OpenWalnut.
9 //
10 // OpenWalnut is free software: you can redistribute it and/or modify
11 // it under the terms of the GNU Lesser General Public License as published by
12 // the Free Software Foundation, either version 3 of the License, or
13 // (at your option) any later version.
14 //
15 // OpenWalnut is distributed in the hope that it will be useful,
16 // but WITHOUT ANY WARRANTY; without even the implied warranty of
17 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
18 // GNU Lesser General Public License for more details.
19 //
20 // You should have received a copy of the GNU Lesser General Public License
21 // along with OpenWalnut. If not, see <http://www.gnu.org/licenses/>.
22 //
23 //---------------------------------------------------------------------------
24 
25 #ifndef WPROJECTFILE_H
26 #define WPROJECTFILE_H
27 
28 #include <string>
29 #include <list>
30 #include <vector>
31 
32 #ifndef Q_MOC_RUN
33 #include <boost/filesystem.hpp>
34 #endif
35 #ifndef Q_MOC_RUN
36 #include <boost/shared_ptr.hpp>
37 #endif
38 #ifndef Q_MOC_RUN
39 #include <boost/function.hpp>
40 #endif
41 #ifndef Q_MOC_RUN
42 #include <boost/signals2/signal.hpp>
43 #endif
44 
45 #include "../common/WSharedSequenceContainer.h"
46 #include "../common/WThreadedRunner.h"
47 
48 #include "../common/WProjectFileIO.h"
49 
51 class WModule;
52 
53 /**
54  * Class loading project files. This class opens an file and reads it line by line. It delegates the actual parsing to each of the known
55  * WProjectFileIO instances which then do their job.
56  */
58  public boost::enable_shared_from_this< WProjectFile >
59 {
60 public:
61  /**
62  * Abbreviation for a shared pointer.
63  */
64  typedef boost::shared_ptr< WProjectFile > SPtr;
65 
66  /**
67  * Abbreviation for const shared pointer.
68  */
69  typedef boost::shared_ptr< const WProjectFile > ConstSPtr;
70 
71  /**
72  * A callback function type reporting bach a finished load job. The given string vector contains a list of errors if any.
73  */
74  typedef boost::function< void( boost::filesystem::path, std::vector< std::string >, std::vector< std::string > ) > ProjectLoadCallback;
75 
76  /**
77  * A callback function signal type reporting bach a finished load job. The given string vector contains a list of errors if any.
78  */
79  typedef boost::signals2::signal< void( boost::filesystem::path, std::vector< std::string >, std::vector< std::string > ) >
81 
82  /**
83  * Default constructor. It does NOT parse the file. Parsing is done by using load.
84  *
85  * \param project the project file to load or save.
86  */
87  explicit WProjectFile( boost::filesystem::path project );
88 
89  /**
90  * Default constructor. It does NOT parse the file. Parsing is done by using load.
91  *
92  * \param project the project file to load.
93  * \param doneCallback gets called whenever the load thread finishes.
94  */
95  WProjectFile( boost::filesystem::path project, ProjectLoadCallback doneCallback );
96 
97  /**
98  * Destructor.
99  */
100  virtual ~WProjectFile();
101 
102  /**
103  * Parses the project file and applies it. It applies the project file asynchronously!
104  */
105  virtual void load();
106 
107  /**
108  * Saves the current state to the file specified in the constructor.
109  */
110  virtual void save();
111 
112  /**
113  * Saves the current state to the file specified in the constructor. This also supports a custom list of writers. This is useful to only
114  * write some parts of the state.
115  *
116  * \param writer the list of writers to use.
117  */
118  virtual void save( const std::list< boost::shared_ptr< WProjectFileIO > >& writer );
119 
120  /**
121  * Saves the current state to the file specified in the constructor. This also supports a custom list of writers. This is useful to only
122  * write some parts of the state.
123  *
124  * \param writer the list of writers to use.
125  */
126  virtual void save( const std::vector< boost::shared_ptr< WProjectFileIO > >& writer );
127 
128  /**
129  * Returns an instance of the Camera writer.
130  *
131  * \return the writer able to output the camera configuration to a stream.
132  */
133  static boost::shared_ptr< WProjectFileIO > getCameraWriter();
134 
135  /**
136  * Returns an instance of the module writer.
137  *
138  * \return the writer able to output the module configuration to a stream.
139  */
140  static boost::shared_ptr< WProjectFileIO > getModuleWriter();
141 
142  /**
143  * Returns an instance of the ROI writer.
144  *
145  * \return the writer able to output the ROI configuration to a stream.
146  */
147  static boost::shared_ptr< WProjectFileIO > getROIWriter();
148 
149  /**
150  * Register a custom project file parser. Use this to add and re-read information from project files. The change takes effect when creating a
151  * new instance of WProjectFile. The custom parser needs to implement \ref WProjectFileIO::clone as this is used for instancing the parser
152  * for each project file.
153  *
154  * \note: See \ref WQtNetworkEditorProjectFileIO for a working example.
155  *
156  * \param parser the parser. Can be added multiple times.
157  */
158  static void registerParser( WProjectFileIO::SPtr parser );
159 
160  /**
161  * Remove parser from registry. The change takes effect when creating a new instance of WProjectFile.
162  *
163  * \param parser the parser to remove. If not existing, nothing happens.
164  */
165  static void deregisterParser( WProjectFileIO::SPtr parser );
166 
167  /**
168  * Map a given project file ID to a module. This method must not be used by WModuleProjectFileCombiner, as it builds this mapping. All other
169  * \ref WProjectFileIO implementations are allowed to use it in their save and apply methods (NOT in parse()).
170  *
171  * \param id the id
172  *
173  * \return the module, or NULL if ID is not known.
174  */
175  boost::shared_ptr< WModule > mapToModule( unsigned int id ) const;
176 
177  /**
178  * Map a given module to project file ID. This method must not be used by WModuleProjectFileCombiner, as it builds this mapping. All other
179  * \ref WProjectFileIO implementations are allowed to use it in their save and apply methods (NOT in parse()).
180  *
181  * \param module the module to map
182  *
183  * \return the ID, or numeric_limits< unisigned int >::max() if module not known.*
184  */
185  unsigned int mapFromModule( boost::shared_ptr< WModule > module ) const;
186 
187 protected:
188  /**
189  * Function that has to be overwritten for execution. It gets executed in a separate thread after run()
190  * has been called.
191  */
192  virtual void threadMain();
193 
194  /**
195  * The project file to parse.
196  */
197  boost::filesystem::path m_project;
198 
199  /**
200  * The parser instances. They are used to parse the file.
201  */
202  std::list< boost::shared_ptr< WProjectFileIO > > m_parsers;
203 
204  /**
205  * The writer instances. They are used to write the file.
206  */
207  std::list< boost::shared_ptr< WProjectFileIO > > m_writers;
208 
209  /**
210  * Do custom exception handling.
211  *
212  * \param e the exception
213  */
214  virtual void onThreadException( const WException& e );
215 
216 private:
217  /**
218  * Type used for returning lists of parser prototypes.
219  */
221 
222  /**
223  * Signal used to callback someone that the loader was finished.
224  */
226 
227  /**
228  * Connection managing the signal m_signalLoadDone. This is the one and only connection allowed and will be disconnected upon thread has
229  * finished.
230  */
231  boost::signals2::connection m_signalLoadDoneConnection;
232 
233  /**
234  * List of all additional parser prototypes. Handled as singleton.
235  */
236  static ParserList m_additionalParsers;
237 
238  /**
239  * This is the only WProjectFileIO instance which is needed. It is used to map ID to module.
240  */
241  boost::shared_ptr< WModuleProjectFileCombiner > m_moduleIO;
242 };
243 
244 #endif // WPROJECTFILE_H
245 
boost::signals2::signal< void(boost::filesystem::path, std::vector< std::string >, std::vector< std::string >) > ProjectLoadCallbackSignal
A callback function signal type reporting bach a finished load job.
Definition: WProjectFile.h:80
boost::shared_ptr< WModuleProjectFileCombiner > m_moduleIO
This is the only WProjectFileIO instance which is needed.
Definition: WProjectFile.h:241
boost::shared_ptr< WProjectFile > SPtr
Abbreviation for a shared pointer.
Definition: WProjectFile.h:64
std::list< boost::shared_ptr< WProjectFileIO > > m_writers
The writer instances.
Definition: WProjectFile.h:207
static void deregisterParser(WProjectFileIO::SPtr parser)
Remove parser from registry.
boost::filesystem::path m_project
The project file to parse.
Definition: WProjectFile.h:197
Class representing a single module of OpenWalnut.
Definition: WModule.h:83
boost::shared_ptr< WModule > mapToModule(unsigned int id) const
Map a given project file ID to a module.
This class provides a common interface for thread-safe access to sequence containers (list...
static void registerParser(WProjectFileIO::SPtr parser)
Register a custom project file parser.
boost::function< void(boost::filesystem::path, std::vector< std::string >, std::vector< std::string >) > ProjectLoadCallback
A callback function type reporting bach a finished load job.
Definition: WProjectFile.h:74
Base class for all classes needing to be executed in a separate thread.
Class loading project files.
Definition: WProjectFile.h:57
This class is able to parse project files and create the appropriate module graph inside a specified ...
std::list< boost::shared_ptr< WProjectFileIO > > m_parsers
The parser instances.
Definition: WProjectFile.h:202
boost::signals2::connection m_signalLoadDoneConnection
Connection managing the signal m_signalLoadDone.
Definition: WProjectFile.h:231
static boost::shared_ptr< WProjectFileIO > getROIWriter()
Returns an instance of the ROI writer.
static boost::shared_ptr< WProjectFileIO > getCameraWriter()
Returns an instance of the Camera writer.
virtual void onThreadException(const WException &e)
Do custom exception handling.
static boost::shared_ptr< WProjectFileIO > getModuleWriter()
Returns an instance of the module writer.
virtual void load()
Parses the project file and applies it.
boost::shared_ptr< WProjectFileIO > SPtr
Abbreviation for a shared pointer.
virtual ~WProjectFile()
Destructor.
WProjectFile(boost::filesystem::path project)
Default constructor.
unsigned int mapFromModule(boost::shared_ptr< WModule > module) const
Map a given module to project file ID.
virtual void threadMain()
Function that has to be overwritten for execution.
static ParserList m_additionalParsers
List of all additional parser prototypes.
Definition: WProjectFile.h:236
virtual void save()
Saves the current state to the file specified in the constructor.
WSharedSequenceContainer< std::vector< WProjectFileIO::SPtr > > ParserList
Type used for returning lists of parser prototypes.
Definition: WProjectFile.h:220
ProjectLoadCallbackSignal m_signalLoadDone
Signal used to callback someone that the loader was finished.
Definition: WProjectFile.h:225
Basic exception handler.
Definition: WException.h:38
boost::shared_ptr< const WProjectFile > ConstSPtr
Abbreviation for const shared pointer.
Definition: WProjectFile.h:69