Changes between Version 1 and Version 2 of HowToImplementNewFiller

Timestamp:

08/05/10 12:23:47 (14 years ago)

Author:

Takeshi Nakazato

Comment:

--

HowToImplementNewFiller

@@ -21 +21 @@
    
 == Design ==
-
+The !FillerBase class is defined as the above description. All Filler classes must inherit this class.
+Constructor of the class takes Scantable object as its argument. The Scantable given will be filled by the Filler.
+The !FillerBase is an abstract class that have three pure abstract methods: 
+
+   * open()  --- open data file (via Reader object)
+   * fill()  --- get information from the Reader object, and fill Scantable
+   * close() --- close data file (via Reader object)
+
+These methods must be implemented in the derived classes.
+
+The !FillerBase is designed to fill Scantable in row-by-row manner. To do this, it has an attribute that represents a single row of the main table in Scantable. The fill() method should 1) fill that row and 2) add that row to target Scantable over all rows. The !FillerBase implements common methods that help to implement fill() method.  
+
+   * setHeader() --- fill header 
+   * 'setter' methods for cells --- fill certain cells in the current row
+      * setIndex() --- fill SCANNO, CYCLENO, IFNO, POLNO, and BEAMNO
+      * setSpectrum() --- fill SPECTRA, FLAGTRA, and TSYS
+      * setFlagrow() --- fill FLAGROW
+      * setDirection() --- fill DIRECTION, AZIMUTH, and ELEVATION
+      * setTime() --- fill TIME and INTERVAL
+      * setReferenceBeam() --- fill REFBEAMNO
+      * setSource() --- fill SRCNAME, SRCTYPE, FIELDNAME, SRCDIRECTION, SRCPROPERMOTION, and SRCVELOCITY
+      * setScanRate() --- fill SCANRATE
+      * setOpacity() --- fill OPACITY
+      * setFrequency() --- add row to FREQUENCIES subtable if necessary, and fill FREQ_ID
+      * setMolecule() --- add row to MOLECULES subtable if necessary, and fill MOLECULE_ID
+      * setFocus() --- add row to FOCUS subtable if necessary, and fill FOCUS_ID
+      * setWeather() --- add row to WEATHER subtable if necessary, and fill WEATHER_ID
+      * setTcal() --- add row to TCAL subtable if necessary, and fill TCAL_ID
+   * commitRow() --- add row to Scantable
+
+The 'setter' methods including setHeader() method take some arguments that is used to fill corresponding cells. Some arguments have their default values. It means that the corresponding cell is an optional one that may not be given explicitly. On the other hand, cells without default values are mandatory. Their values must be given explicitly.
 
 
 == Implementation ==
-If you want to define new filler, it must inherit !FillerBase class.
+To define new filler, you should go through the following steps:
+
+ 1. define your filler as a derived class of !FillerBase
+
+{{{
+#!cpp
+class MyFiller : public FillerBase
+{
+   ...
+}; 
+}}}
+
+ 2. define constructor
+
+ Default constructor and copy constructor should be disabled from outside. 
+ So, they should be explicitly declared in the private section.
+ The only public constructor is the one that takes Scantable object as its argument.
+
+{{{
+#!cpp
+class MyFiller : public FillerBase
+{
+   public:
+      MyFiller( CountedPtr<Scantable> stable );
+      ...
+   private:
+      MyFiller();
+      MyFiller( const MyFiller& );
+      MyFiller &operator=( const MyFiller& );
+      ...
+}; 
+}}}
+
+ You probably need to have Reader object as an attribute.
+
+{{{
+#!cpp
+class MyFiller : public FillerBase
+{
+   public:
+      MyFiller( CountedPtr<Scantable> stable );
+      ...
+   private:
+      CountedPtr<MyReader> reader_;
+
+      MyFiller();
+      MyFiller( const MyFiller& );
+      MyFiller &operator=( const MyFiller& );
+      ...
+}; 
+}}}
+
+ At least, the constructor must call the constructor of !FillerBase class.
+
+{{{
+#!cpp
+MyFiller::MyFiller( CountedPtr<Scantable> stable )
+   : FillerBase( stable )
+{
+   ...
+}
+}}}
+
+ The constructor of !FillerBase class sets Scantable object given as a target.
+
+ 3. implement open() method
+
+ You must implement open() method that gets an access to the data file. 
+ In almost case, it will be realized by the open() method of Reader object.
+ You can call setHeader() to fill header of target Scantable.
+
+{{{
+#!cpp
+bool MyFiller::open( const string &filename )
+{
+   ...
+   // open file
+   if ( reader_->open( filename ) ) {
+      return False ;
+   }
+   ...
+   // get header information
+   ...
+   // set header 
+   setHeader( header ) ;
+}
+}}}
+
+ The header variable must be set in the method.
+
+ 4. implement fill() method
+
+ You must implement fill() method that performs 1) to fill row and 2) to add row to target Scantable.
+ As mentioned above, a lot of useful methods are available.
+
+{{{
+#!cpp
+void MyFiller::fill()
+{
+   // get row information
+   // e.g. reader_->read(...) ;
+   ...
+   // loop on all rows
+   for ( int i = 0 ; i < nrow ; i++ ) {
+      // fill row
+      setIndex( ... ) ;
+      setSpectrum( ... ) ;
+      setFlagrow( ... ) ;
+      setDirection( ... ) ;
+      setTime( ... ) ;
+      setReferenceBeam( ... ) ;
+      setSource( ... ) ;
+      setScanRate( ... ) ;
+      setOpacity( ... ) ;
+      setFrequency( ... ) ;
+      setMolecule( ... ) ;
+      setFocus( ... ) ;
+      setWeather( ... ) ;
+      setTcal( ... ) ;
+
+      // add row
+      commitRow() ;
+   }
+}
+}}} 
+
+ 5. implement close() method
+
+ You must implement close() method. Normally, it just closes the file.
+
+{{{
+#!cpp
+void MyFiller::close()
+{
+   if ( reader_.null() != False ) {
+      reader_ = 0 ;
+   }
+   table_ = 0 ;
+}
+}}}
+
+ In this example, the method doesn't close the file explicitly. 
+ Instead, the file is closed when the Reader object is destructed.
+
+== Miscellaneous ==
+
+See existing Filler implementation (PKSFiller, NROFiller) for more detail.
+