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 #include <boost/filesystem.hpp>
33 #include <boost/shared_ptr.hpp>
34 #include <boost/function.hpp>
35 #include <boost/signals2/signal.hpp>
36 
37 #include "../common/WSharedSequenceContainer.h"
38 #include "../common/WThreadedRunner.h"
39 
40 #include "../common/WProjectFileIO.h"
41 
43 class WModule;
44 
45 /**
46  * 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
47  * WProjectFileIO instances which then do their job.
48  */
50  public boost::enable_shared_from_this< WProjectFile >
51 {
52 public:
53  /**
54  * Abbreviation for a shared pointer.
55  */
56  typedef boost::shared_ptr< WProjectFile > SPtr;
57 
58  /**
59  * Abbreviation for const shared pointer.
60  */
61  typedef boost::shared_ptr< const WProjectFile > ConstSPtr;
62 
63  /**
64  * A callback function type reporting bach a finished load job. The given string vector contains a list of errors if any.
65  */
66  typedef boost::function< void( boost::filesystem::path, std::vector< std::string >, std::vector< std::string > ) > ProjectLoadCallback;
67 
68  /**
69  * A callback function signal type reporting bach a finished load job. The given string vector contains a list of errors if any.
70  */
71  typedef boost::signals2::signal< void( boost::filesystem::path, std::vector< std::string >, std::vector< std::string > ) >
73 
74  /**
75  * Default constructor. It does NOT parse the file. Parsing is done by using load.
76  *
77  * \param project the project file to load or save.
78  */
79  explicit WProjectFile( boost::filesystem::path project );
80 
81  /**
82  * Default constructor. It does NOT parse the file. Parsing is done by using load.
83  *
84  * \param project the project file to load.
85  * \param doneCallback gets called whenever the load thread finishes.
86  */
87  WProjectFile( boost::filesystem::path project, ProjectLoadCallback doneCallback );
88 
89  /**
90  * Destructor.
91  */
92  virtual ~WProjectFile();
93 
94  /**
95  * Parses the project file and applies it. It applies the project file asynchronously!
96  */
97  virtual void load();
98 
99  /**
100  * Saves the current state to the file specified in the constructor.
101  */
102  virtual void save();
103 
104  /**
105  * Saves the current state to the file specified in the constructor. This also supports a custom list of writers. This is useful to only
106  * write some parts of the state.
107  *
108  * \param writer the list of writers to use.
109  */
110  virtual void save( const std::list< boost::shared_ptr< WProjectFileIO > >& writer );
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::vector< boost::shared_ptr< WProjectFileIO > >& writer );
119 
120  /**
121  * Returns an instance of the Camera writer.
122  *
123  * \return the writer able to output the camera configuration to a stream.
124  */
125  static boost::shared_ptr< WProjectFileIO > getCameraWriter();
126 
127  /**
128  * Returns an instance of the module writer.
129  *
130  * \return the writer able to output the module configuration to a stream.
131  */
132  static boost::shared_ptr< WProjectFileIO > getModuleWriter();
133 
134  /**
135  * Returns an instance of the ROI writer.
136  *
137  * \return the writer able to output the ROI configuration to a stream.
138  */
139  static boost::shared_ptr< WProjectFileIO > getROIWriter();
140 
141  /**
142  * Register a custom project file parser. Use this to add and re-read information from project files. The change takes effect when creating a
143  * new instance of WProjectFile. The custom parser needs to implement \ref WProjectFileIO::clone as this is used for instancing the parser
144  * for each project file.
145  *
146  * \note: See \ref WQtNetworkEditorProjectFileIO for a working example.
147  *
148  * \param parser the parser. Can be added multiple times.
149  */
150  static void registerParser( WProjectFileIO::SPtr parser );
151 
152  /**
153  * Remove parser from registry. The change takes effect when creating a new instance of WProjectFile.
154  *
155  * \param parser the parser to remove. If not existing, nothing happens.
156  */
157  static void deregisterParser( WProjectFileIO::SPtr parser );
158 
159  /**
160  * Map a given project file ID to a module. This method must not be used by WModuleProjectFileCombiner, as it builds this mapping. All other
161  * \ref WProjectFileIO implementations are allowed to use it in their save and apply methods (NOT in parse()).
162  *
163  * \param id the id
164  *
165  * \return the module, or NULL if ID is not known.
166  */
167  boost::shared_ptr< WModule > mapToModule( unsigned int id ) const;
168 
169  /**
170  * Map a given module to project file ID. This method must not be used by WModuleProjectFileCombiner, as it builds this mapping. All other
171  * \ref WProjectFileIO implementations are allowed to use it in their save and apply methods (NOT in parse()).
172  *
173  * \param module the module to map
174  *
175  * \return the ID, or numeric_limits< unisigned int >::max() if module not known.*
176  */
177  unsigned int mapFromModule( boost::shared_ptr< WModule > module ) const;
178 
179 protected:
180  /**
181  * Function that has to be overwritten for execution. It gets executed in a separate thread after run()
182  * has been called.
183  */
184  virtual void threadMain();
185 
186  /**
187  * The project file to parse.
188  */
189  boost::filesystem::path m_project;
190 
191  /**
192  * The parser instances. They are used to parse the file.
193  */
194  std::list< boost::shared_ptr< WProjectFileIO > > m_parsers;
195 
196  /**
197  * The writer instances. They are used to write the file.
198  */
199  std::list< boost::shared_ptr< WProjectFileIO > > m_writers;
200 
201  /**
202  * Do custom exception handling.
203  *
204  * \param e the exception
205  */
206  virtual void onThreadException( const WException& e );
207 
208 private:
209  /**
210  * Type used for returning lists of parser prototypes.
211  */
213 
214  /**
215  * Signal used to callback someone that the loader was finished.
216  */
218 
219  /**
220  * Connection managing the signal m_signalLoadDone. This is the one and only connection allowed and will be disconnected upon thread has
221  * finished.
222  */
223  boost::signals2::connection m_signalLoadDoneConnection;
224 
225  /**
226  * List of all additional parser prototypes. Handled as singleton.
227  */
228  static ParserList m_additionalParsers;
229 
230  /**
231  * This is the only WProjectFileIO instance which is needed. It is used to map ID to module.
232  */
233  boost::shared_ptr< WModuleProjectFileCombiner > m_moduleIO;
234 };
235 
236 #endif // WPROJECTFILE_H
237 
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:72
boost::shared_ptr< WModuleProjectFileCombiner > m_moduleIO
This is the only WProjectFileIO instance which is needed.
Definition: WProjectFile.h:233
boost::shared_ptr< WProjectFile > SPtr
Abbreviation for a shared pointer.
Definition: WProjectFile.h:56
std::list< boost::shared_ptr< WProjectFileIO > > m_writers
The writer instances.
Definition: WProjectFile.h:199
static void deregisterParser(WProjectFileIO::SPtr parser)
Remove parser from registry.
boost::filesystem::path m_project
The project file to parse.
Definition: WProjectFile.h:189
Class representing a single module of OpenWalnut.
Definition: WModule.h:71
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:66
Base class for all classes needing to be executed in a separate thread.
Class loading project files.
Definition: WProjectFile.h:49
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:194
boost::signals2::connection m_signalLoadDoneConnection
Connection managing the signal m_signalLoadDone.
Definition: WProjectFile.h:223
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:228
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:212
ProjectLoadCallbackSignal m_signalLoadDone
Signal used to callback someone that the loader was finished.
Definition: WProjectFile.h:217
Basic exception handler.
Definition: WException.h:38
boost::shared_ptr< const WProjectFile > ConstSPtr
Abbreviation for const shared pointer.
Definition: WProjectFile.h:61