OpenWalnut  1.4.0
WProjectFile.h
00001 //---------------------------------------------------------------------------
00002 //
00003 // Project: OpenWalnut ( http://www.openwalnut.org )
00004 //
00005 // Copyright 2009 OpenWalnut Community, BSV@Uni-Leipzig and CNCF@MPI-CBS
00006 // For more information see http://www.openwalnut.org/copying
00007 //
00008 // This file is part of OpenWalnut.
00009 //
00010 // OpenWalnut is free software: you can redistribute it and/or modify
00011 // it under the terms of the GNU Lesser General Public License as published by
00012 // the Free Software Foundation, either version 3 of the License, or
00013 // (at your option) any later version.
00014 //
00015 // OpenWalnut is distributed in the hope that it will be useful,
00016 // but WITHOUT ANY WARRANTY; without even the implied warranty of
00017 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
00018 // GNU Lesser General Public License for more details.
00019 //
00020 // You should have received a copy of the GNU Lesser General Public License
00021 // along with OpenWalnut. If not, see <http://www.gnu.org/licenses/>.
00022 //
00023 //---------------------------------------------------------------------------
00024 
00025 #ifndef WPROJECTFILE_H
00026 #define WPROJECTFILE_H
00027 
00028 #include <string>
00029 #include <list>
00030 #include <vector>
00031 
00032 #include <boost/filesystem.hpp>
00033 #include <boost/shared_ptr.hpp>
00034 #include <boost/function.hpp>
00035 #include <boost/signals2/signal.hpp>
00036 
00037 #include "../common/WSharedSequenceContainer.h"
00038 #include "../common/WThreadedRunner.h"
00039 
00040 #include "../common/WProjectFileIO.h"
00041 
00042 class WModuleProjectFileCombiner;
00043 class WModule;
00044 
00045 /**
00046  * 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
00047  * WProjectFileIO instances which then do their job.
00048  */
00049 class WProjectFile: public WThreadedRunner,
00050                     public boost::enable_shared_from_this< WProjectFile >
00051 {
00052 public:
00053     /**
00054      * Abbreviation for a shared pointer.
00055      */
00056     typedef boost::shared_ptr< WProjectFile > SPtr;
00057 
00058     /**
00059      * Abbreviation for const shared pointer.
00060      */
00061     typedef boost::shared_ptr< const WProjectFile > ConstSPtr;
00062 
00063     /**
00064      * A callback function type reporting bach a finished load job. The given string vector contains a list of errors if any.
00065      */
00066     typedef boost::function< void( boost::filesystem::path, std::vector< std::string >, std::vector< std::string > ) > ProjectLoadCallback;
00067 
00068     /**
00069      * A callback function signal type reporting bach a finished load job. The given string vector contains a list of errors if any.
00070      */
00071     typedef boost::signals2::signal< void( boost::filesystem::path, std::vector< std::string >, std::vector< std::string > ) >
00072             ProjectLoadCallbackSignal;
00073 
00074     /**
00075      * Default constructor. It does NOT parse the file. Parsing is done by using load.
00076      *
00077      * \param project the project file to load or save.
00078      */
00079     explicit WProjectFile( boost::filesystem::path project );
00080 
00081     /**
00082      * Default constructor. It does NOT parse the file. Parsing is done by using load.
00083      *
00084      * \param project the project file to load.
00085      * \param doneCallback gets called whenever the load thread finishes.
00086      */
00087     WProjectFile( boost::filesystem::path project, ProjectLoadCallback doneCallback );
00088 
00089     /**
00090      * Destructor.
00091      */
00092     virtual ~WProjectFile();
00093 
00094     /**
00095      * Parses the project file and applies it. It applies the project file asynchronously!
00096      */
00097     virtual void load();
00098 
00099     /**
00100      * Saves the current state to the file specified in the constructor.
00101      */
00102     virtual void save();
00103 
00104     /**
00105      * Saves the current state to the file specified in the constructor. This also supports a custom list of writers. This is useful to only
00106      * write some parts of the state.
00107      *
00108      * \param writer the list of writers to use.
00109      */
00110     virtual void save( const std::list< boost::shared_ptr< WProjectFileIO > >& writer );
00111 
00112     /**
00113      * Saves the current state to the file specified in the constructor. This also supports a custom list of writers. This is useful to only
00114      * write some parts of the state.
00115      *
00116      * \param writer the list of writers to use.
00117      */
00118     virtual void save( const std::vector< boost::shared_ptr< WProjectFileIO > >& writer );
00119 
00120     /**
00121      * Returns an instance of the Camera writer.
00122      *
00123      * \return the writer able to output the camera configuration to a stream.
00124      */
00125     static boost::shared_ptr< WProjectFileIO > getCameraWriter();
00126 
00127     /**
00128      * Returns an instance of the module writer.
00129      *
00130      * \return the writer able to output the module configuration to a stream.
00131      */
00132     static boost::shared_ptr< WProjectFileIO > getModuleWriter();
00133 
00134     /**
00135      * Returns an instance of the ROI writer.
00136      *
00137      * \return the writer able to output the ROI configuration to a stream.
00138      */
00139     static boost::shared_ptr< WProjectFileIO > getROIWriter();
00140 
00141     /**
00142      * Register a custom project file parser. Use this to add and re-read information from project files. The change takes effect when creating a
00143      * new instance of WProjectFile. The custom parser needs to implement \ref WProjectFileIO::clone as this is used for instancing the parser
00144      * for each project file.
00145      *
00146      * \note: See \ref WQtNetworkEditorProjectFileIO for a working example.
00147      *
00148      * \param parser the parser. Can be added multiple times.
00149      */
00150     static void registerParser( WProjectFileIO::SPtr parser );
00151 
00152     /**
00153      * Remove parser from registry.  The change takes effect when creating a new instance of WProjectFile.
00154      *
00155      * \param parser the parser to remove. If not existing, nothing happens.
00156      */
00157     static void deregisterParser( WProjectFileIO::SPtr parser );
00158 
00159     /**
00160      * Map a given project file ID to a module. This method must not be used by WModuleProjectFileCombiner, as it builds this mapping. All other
00161      * \ref WProjectFileIO implementations are allowed to use it in their save and apply methods (NOT in parse()).
00162      *
00163      * \param id the id
00164      *
00165      * \return the module, or NULL if ID is not known.
00166      */
00167     boost::shared_ptr< WModule > mapToModule( unsigned int id ) const;
00168 
00169     /**
00170      * Map a given module to project file ID. This method must not be used by WModuleProjectFileCombiner, as it builds this mapping. All other
00171      * \ref WProjectFileIO implementations are allowed to use it in their save and apply methods (NOT in parse()).
00172      *
00173      * \param module the module to map
00174      *
00175      * \return the ID, or numeric_limits< unisigned int >::max() if module not known.*
00176      */
00177     unsigned int mapFromModule( boost::shared_ptr< WModule > module ) const;
00178 
00179 protected:
00180     /**
00181      * Function that has to be overwritten for execution. It gets executed in a separate thread after run()
00182      * has been called.
00183      */
00184     virtual void threadMain();
00185 
00186     /**
00187      * The project file to parse.
00188      */
00189     boost::filesystem::path m_project;
00190 
00191     /**
00192      * The parser instances. They are used to parse the file.
00193      */
00194     std::list< boost::shared_ptr< WProjectFileIO > > m_parsers;
00195 
00196     /**
00197      * The writer instances. They are used to write the file.
00198      */
00199     std::list< boost::shared_ptr< WProjectFileIO > > m_writers;
00200 
00201     /**
00202      * Do custom exception handling.
00203      *
00204      * \param e the exception
00205      */
00206     virtual void onThreadException( const WException& e );
00207 
00208 private:
00209     /**
00210      * Type used for returning lists of parser prototypes.
00211      */
00212     typedef WSharedSequenceContainer< std::vector< WProjectFileIO::SPtr > > ParserList;
00213 
00214     /**
00215      * Signal used to callback someone that the loader was finished.
00216      */
00217     ProjectLoadCallbackSignal m_signalLoadDone;
00218 
00219     /**
00220      * Connection managing the signal m_signalLoadDone. This is the one and only connection allowed and will be disconnected upon thread has
00221      * finished.
00222      */
00223     boost::signals2::connection m_signalLoadDoneConnection;
00224 
00225     /**
00226      * List of all additional parser prototypes. Handled as singleton.
00227      */
00228     static ParserList m_additionalParsers;
00229 
00230     /**
00231      * This is the only WProjectFileIO instance which is needed. It is used to map ID to module.
00232      */
00233     boost::shared_ptr< WModuleProjectFileCombiner > m_moduleIO;
00234 };
00235 
00236 #endif  // WPROJECTFILE_H
00237