Line data    Source code

       1             : 
       2             : /*
       3             :  * ALMA - Atacama Large Millimeter Array
       4             :  * (c) European Southern Observatory, 2002
       5             :  * (c) Associated Universities Inc., 2002
       6             :  * Copyright by ESO (in the framework of the ALMA collaboration),
       7             :  * Copyright by AUI (in the framework of the ALMA collaboration),
       8             :  * All rights reserved.
       9             :  * 
      10             :  * This library is free software; you can redistribute it and/or
      11             :  * modify it under the terms of the GNU Lesser General Public
      12             :  * License as published by the Free software Foundation; either
      13             :  * version 2.1 of the License, or (at your option) any later version.
      14             :  * 
      15             :  * This library 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 GNU
      18             :  * Lesser General Public License for more details.
      19             :  * 
      20             :  * You should have received a copy of the GNU Lesser General Public
      21             :  * License along with this library; if not, write to the Free Software
      22             :  * Foundation, Inc., 59 Temple Place, Suite 330, Boston,
      23             :  * MA 02111-1307  USA
      24             :  *
      25             :  * Warning!
      26             :  *  -------------------------------------------------------------------- 
      27             :  * | This is generated code!  Do not modify this file.                  |
      28             :  * | If you do, all changes will be lost when the file is re-generated. |
      29             :  *  --------------------------------------------------------------------
      30             :  *
      31             :  * File AnnotationTable.h
      32             :  */
      33             :  
      34             : #ifndef AnnotationTable_CLASS
      35             : #define AnnotationTable_CLASS
      36             : 
      37             : #include <string>
      38             : #include <vector>
      39             : #include <map>
      40             : 
      41             : 
      42             : 
      43             :         
      44             : #include <alma/ASDM/ArrayTime.h>
      45             :         
      46             : 
      47             :         
      48             : #include <alma/ASDM/Tag.h>
      49             :         
      50             : 
      51             :         
      52             : #include <alma/ASDM/Interval.h>
      53             :         
      54             : 
      55             : 
      56             : 
      57             : 
      58             :         
      59             : 
      60             :         
      61             : 
      62             :         
      63             : 
      64             :         
      65             : 
      66             :         
      67             : 
      68             :         
      69             : #include <alma/Enumerations/CBasebandName.h>
      70             :         
      71             : 
      72             :         
      73             : 
      74             :         
      75             : 
      76             :         
      77             : 
      78             :         
      79             : 
      80             :         
      81             : 
      82             :         
      83             : 
      84             :         
      85             : 
      86             :         
      87             : 
      88             :         
      89             : 
      90             : 
      91             : 
      92             : #include <alma/ASDM/ConversionException.h>
      93             : #include <alma/ASDM/DuplicateKey.h>
      94             : #include <alma/ASDM/UniquenessViolationException.h>
      95             : #include <alma/ASDM/NoSuchRow.h>
      96             : #include <alma/ASDM/DuplicateKey.h>
      97             : 
      98             : 
      99             : #ifndef WITHOUT_ACS
     100             : #include <asdmIDLC.h>
     101             : #endif
     102             : 
     103             : #include <alma/ASDM/Representable.h>
     104             : 
     105             : #include <pthread.h>
     106             : 
     107             : namespace asdm {
     108             : 
     109             : //class asdm::ASDM;
     110             : //class asdm::AnnotationRow;
     111             : 
     112             : class ASDM;
     113             : class AnnotationRow;
     114             : /**
     115             :  * The AnnotationTable class is an Alma table.
     116             :  * <BR>
     117             :  * 
     118             :  * \par Role
     119             :  * The Annotation Table is intended to offer space for unexpected data to be  added in the software development process at short notice, without  redefining the data model.
     120             :  * <BR>
     121             :  
     122             :  * Generated from model's revision "-1", branch ""
     123             :  *
     124             :  * <TABLE BORDER="1">
     125             :  * <CAPTION> Attributes of Annotation </CAPTION>
     126             :  * <TR BGCOLOR="#AAAAAA"> <TH> Name </TH> <TH> Type </TH> <TH> Expected shape  </TH> <TH> Comment </TH></TR>
     127             :  
     128             :  * <TR> <TH BGCOLOR="#CCCCCC" colspan="4" align="center"> Key </TD></TR>
     129             :         
     130             :  * <TR>
     131             :                 
     132             :  * <TD><I> annotationId </I></TD>
     133             :                  
     134             :  * <TD> Tag</TD>
     135             :  * <TD> &nbsp; </TD>
     136             :  * <TD> &nbsp;identifies a unique row in the table. </TD>
     137             :  * </TR>
     138             :         
     139             : 
     140             : 
     141             :  * <TR> <TH BGCOLOR="#CCCCCC"  colspan="4" valign="center"> Value <br> (Mandatory) </TH></TR>
     142             :         
     143             :  * <TR>
     144             :  * <TD> time </TD> 
     145             :  * <TD> ArrayTime </TD>
     146             :  * <TD>  &nbsp;  </TD> 
     147             :  * <TD> &nbsp;mid point of the interval of time on which the recorded information is pertinent. </TD>
     148             :  * </TR>
     149             :         
     150             :  * <TR>
     151             :  * <TD> issue </TD> 
     152             :  * <TD> std::string </TD>
     153             :  * <TD>  &nbsp;  </TD> 
     154             :  * <TD> &nbsp;name of this annotation. </TD>
     155             :  * </TR>
     156             :         
     157             :  * <TR>
     158             :  * <TD> details </TD> 
     159             :  * <TD> std::string </TD>
     160             :  * <TD>  &nbsp;  </TD> 
     161             :  * <TD> &nbsp;details of this annotation. </TD>
     162             :  * </TR>
     163             :         
     164             : 
     165             : 
     166             :  * <TR> <TH BGCOLOR="#CCCCCC"  colspan="4" valign="center"> Value <br> (Optional) </TH></TR>
     167             :         
     168             :  * <TR>
     169             :  * <TD> numAntenna(numAntenna)</TD> 
     170             :  * <TD> int </TD>
     171             :  * <TD>  &nbsp; </TD>
     172             :  * <TD>&nbsp; number of antennas. </TD>
     173             :  * </TR>
     174             :         
     175             :  * <TR>
     176             :  * <TD> basebandName</TD> 
     177             :  * <TD> std::vector<BasebandNameMod::BasebandName > </TD>
     178             :  * <TD>  numBaseband  </TD>
     179             :  * <TD>&nbsp; an array of numBaseband baseband names. </TD>
     180             :  * </TR>
     181             :         
     182             :  * <TR>
     183             :  * <TD> numBaseband(numBaseband)</TD> 
     184             :  * <TD> int </TD>
     185             :  * <TD>  &nbsp; </TD>
     186             :  * <TD>&nbsp; number of basebands. </TD>
     187             :  * </TR>
     188             :         
     189             :  * <TR>
     190             :  * <TD> interval</TD> 
     191             :  * <TD> Interval </TD>
     192             :  * <TD>  &nbsp; </TD>
     193             :  * <TD>&nbsp; time interval </TD>
     194             :  * </TR>
     195             :         
     196             :  * <TR>
     197             :  * <TD> dValue</TD> 
     198             :  * <TD> double </TD>
     199             :  * <TD>  &nbsp; </TD>
     200             :  * <TD>&nbsp; scalar data. </TD>
     201             :  * </TR>
     202             :         
     203             :  * <TR>
     204             :  * <TD> vdValue</TD> 
     205             :  * <TD> std::vector<double > </TD>
     206             :  * <TD>    </TD>
     207             :  * <TD>&nbsp; useful to store an array of double values. </TD>
     208             :  * </TR>
     209             :         
     210             :  * <TR>
     211             :  * <TD> vvdValues</TD> 
     212             :  * <TD> std::vector<std::vector<double > > </TD>
     213             :  * <TD>  ,   </TD>
     214             :  * <TD>&nbsp; useful to store an array of array(s) of double values. </TD>
     215             :  * </TR>
     216             :         
     217             :  * <TR>
     218             :  * <TD> llValue</TD> 
     219             :  * <TD> int64_t </TD>
     220             :  * <TD>  &nbsp; </TD>
     221             :  * <TD>&nbsp; useful to record a long long data. </TD>
     222             :  * </TR>
     223             :         
     224             :  * <TR>
     225             :  * <TD> vllValue</TD> 
     226             :  * <TD> std::vector<int64_t > </TD>
     227             :  * <TD>    </TD>
     228             :  * <TD>&nbsp; useful to store an array of array(s) of long long values. </TD>
     229             :  * </TR>
     230             :         
     231             :  * <TR>
     232             :  * <TD> vvllValue</TD> 
     233             :  * <TD> std::vector<std::vector<int64_t > > </TD>
     234             :  * <TD>  ,   </TD>
     235             :  * <TD>&nbsp; useful to store an array of array(s) long long values. </TD>
     236             :  * </TR>
     237             :         
     238             :  * <TR>
     239             :  * <TD> sValue</TD> 
     240             :  * <TD> std::string </TD>
     241             :  * <TD>  &nbsp; </TD>
     242             :  * <TD>&nbsp; details of this annotation. </TD>
     243             :  * </TR>
     244             :         
     245             :  * <TR>
     246             :  * <TD> antennaId</TD> 
     247             :  * <TD> std::vector<Tag>  </TD>
     248             :  * <TD>  numAntenna  </TD>
     249             :  * <TD>&nbsp; refers to a collection of rows in the AntennaTable. </TD>
     250             :  * </TR>
     251             :         
     252             : 
     253             :  * </TABLE>
     254             :  */
     255             : class AnnotationTable : public Representable {
     256             :         friend class ASDM;
     257             : 
     258             : public:
     259             : 
     260             : 
     261             :         /**
     262             :          * Return the list of field names that make up key key
     263             :          * as an array of strings.
     264             :          * @return a vector of string.
     265             :          */     
     266             :         static const std::vector<std::string>& getKeyName();
     267             : 
     268             : 
     269             :         virtual ~AnnotationTable();
     270             :         
     271             :         /**
     272             :          * Return the container to which this table belongs.
     273             :          *
     274             :          * @return the ASDM containing this table.
     275             :          */
     276             :         ASDM &getContainer() const;
     277             :         
     278             :         /**
     279             :          * Return the number of rows in the table.
     280             :          *
     281             :          * @return the number of rows in an unsigned int.
     282             :          */
     283             :         unsigned int size() const;
     284             :         
     285             :         /**
     286             :          * Return the name of this table.
     287             :          *
     288             :          * This is a instance method of the class.
     289             :          *
     290             :          * @return the name of this table in a string.
     291             :          */
     292             :         std::string getName() const;
     293             :         
     294             :         /**
     295             :          * Return the name of this table.
     296             :          *
     297             :          * This is a static method of the class.
     298             :          *
     299             :          * @return the name of this table in a string.
     300             :          */
     301             :         static std::string name() ;     
     302             :         
     303             :         /**
     304             :          * Return the version information about this table.
     305             :          *
     306             :          */
     307             :          std::string getVersion() const ;
     308             :         
     309             :         /**
     310             :          * Return the names of the attributes of this table.
     311             :          *
     312             :          * @return a vector of string
     313             :          */
     314             :          static const std::vector<std::string>& getAttributesNames();
     315             : 
     316             :         /**
     317             :          * Return the default sorted list of attributes names in the binary representation of the table.
     318             :          *
     319             :          * @return a const reference to a vector of string
     320             :          */
     321             :          static const std::vector<std::string>& defaultAttributesNamesInBin();
     322             :          
     323             :         /**
     324             :          * Return this table's Entity.
     325             :          */
     326             :         Entity getEntity() const;
     327             : 
     328             :         /**
     329             :          * Set this table's Entity.
     330             :          * @param e An entity. 
     331             :          */
     332             :         void setEntity(Entity e);
     333             :                 
     334             :         /**
     335             :          * Produces an XML representation conform
     336             :          * to the schema defined for Annotation (AnnotationTable.xsd).
     337             :          *
     338             :          * @returns a string containing the XML representation.
     339             :          * @throws ConversionException
     340             :          */
     341             :         std::string toXML()  ;
     342             : 
     343             : #ifndef WITHOUT_ACS
     344             :         // Conversion Methods
     345             :         /**
     346             :          * Convert this table into a AnnotationTableIDL CORBA structure.
     347             :          *
     348             :          * @return a pointer to a AnnotationTableIDL
     349             :          */
     350             :         asdmIDL::AnnotationTableIDL *toIDL() ;
     351             :         
     352             :         /**
     353             :          * Fills the CORBA data structure passed in parameter
     354             :          * with the content of this table.
     355             :          *
     356             :          * @param x a reference to the asdmIDL::AnnotationTableIDL to be populated
     357             :          * with the content of this.
     358             :          */
     359             :          void toIDL(asdmIDL::AnnotationTableIDL& x) const;
     360             :          
     361             : #endif
     362             : 
     363             : #ifndef WITHOUT_ACS
     364             :         /**
     365             :          * Populate this table from the content of a AnnotationTableIDL Corba structure.
     366             :          *
     367             :          * @throws DuplicateKey Thrown if the method tries to add a row having a key that is already in the table.
     368             :          * @throws ConversionException
     369             :          */     
     370             :         void fromIDL(asdmIDL::AnnotationTableIDL x) ;
     371             : #endif
     372             :         
     373             :         //
     374             :         // ====> Row creation.
     375             :         //
     376             :         
     377             :         /**
     378             :          * Create a new row with default values.
     379             :          * @return a pointer on a AnnotationRow
     380             :          */
     381             :         AnnotationRow *newRow();
     382             :         
     383             :         
     384             :         /**
     385             :          * Create a new row initialized to the specified values.
     386             :          * @return a pointer on the created and initialized row.
     387             :         
     388             :          * @param time
     389             :         
     390             :          * @param issue
     391             :         
     392             :          * @param details
     393             :         
     394             :      */
     395             :         AnnotationRow *newRow(ArrayTime time, std::string issue, std::string details);
     396             :         
     397             : 
     398             : 
     399             :         /**
     400             :          * Create a new row using a copy constructor mechanism.
     401             :          * 
     402             :          * The method creates a new AnnotationRow owned by this. Each attribute of the created row 
     403             :          * is a (deep) copy of the corresponding attribute of row. The method does not add 
     404             :          * the created row to this, its simply parents it to this, a call to the add method
     405             :          * has to be done in order to get the row added (very likely after having modified
     406             :          * some of its attributes).
     407             :          * If row is null then the method returns a new AnnotationRow with default values for its attributes. 
     408             :          *
     409             :          * @param row the row which is to be copied.
     410             :          */
     411             :          AnnotationRow *newRow(AnnotationRow *row); 
     412             : 
     413             :         //
     414             :         // ====> Append a row to its table.
     415             :         //
     416             : 
     417             :         
     418             :         
     419             :         
     420             :         /** 
     421             :          * Add a row.
     422             :          * If there table contains a row whose key's fields are equal
     423             :          * to x's ones then return a pointer on this row (i.e. no actual insertion is performed) 
     424             :          * otherwise add x to the table and return x.
     425             :          * @param x . A pointer on the row to be added.
     426             :          * @returns a pointer to a AnnotationRow.        
     427             :          */      
     428             :          
     429             :          AnnotationRow* add(AnnotationRow* x) ;
     430             : 
     431             : 
     432             : 
     433             :         //
     434             :         // ====> Methods returning rows.
     435             :         //
     436             :                 
     437             :         /**
     438             :          * Get a collection of pointers on the rows of the table.
     439             :          * @return Alls rows in a vector of pointers of AnnotationRow. The elements of this vector are stored in the order 
     440             :          * in which they have been added to the AnnotationTable.
     441             :          */
     442             :         std::vector<AnnotationRow *> get() ;
     443             :         
     444             :         /**
     445             :          * Get a const reference on the collection of rows pointers internally hold by the table.
     446             :          * @return A const reference of a vector of pointers of AnnotationRow. The elements of this vector are stored in the order 
     447             :          * in which they have been added to the AnnotationTable.
     448             :          *
     449             :          */
     450             :          const std::vector<AnnotationRow *>& get() const ;
     451             :         
     452             : 
     453             : 
     454             :  
     455             :         
     456             :         /**
     457             :          * Returns a AnnotationRow* given a key.
     458             :          * @return a pointer to the row having the key whose values are passed as parameters, or 0 if
     459             :          * no row exists for that key.
     460             :         
     461             :          * @param annotationId
     462             :         
     463             :          *
     464             :          */
     465             :         AnnotationRow* getRowByKey(Tag annotationId);
     466             : 
     467             :                 
     468             : 
     469             : 
     470             : 
     471             :         /**
     472             :          * Look up the table for a row whose all attributes  except the autoincrementable one 
     473             :          * are equal to the corresponding parameters of the method.
     474             :          * @return a pointer on this row if any, null otherwise.
     475             :          *
     476             :                         
     477             :          * @param time
     478             :                         
     479             :          * @param issue
     480             :                         
     481             :          * @param details
     482             :                          
     483             :          */
     484             :         AnnotationRow* lookup(ArrayTime time, std::string issue, std::string details); 
     485             : 
     486             : 
     487             :         void setUnknownAttributeBinaryReader(const std::string& attributeName, BinaryAttributeReaderFunctor* barFctr);
     488             :         BinaryAttributeReaderFunctor* getUnknownAttributeBinaryReader(const std::string& attributeName) const;
     489             : 
     490             : private:
     491             : 
     492             :         /**
     493             :          * Create a AnnotationTable.
     494             :          * <p>
     495             :          * This constructor is private because only the
     496             :          * container can create tables.  All tables must know the container
     497             :          * to which they belong.
     498             :          * @param container The container to which this table belongs.
     499             :          */ 
     500             :         AnnotationTable (ASDM & container);
     501             : 
     502             :         ASDM & container;
     503             :         
     504             :         bool archiveAsBin; // If true archive binary else archive XML
     505             :         bool fileAsBin ; // If true file binary else file XML   
     506             :         
     507             :         std::string version ; 
     508             :         
     509             :         Entity entity;
     510             :         
     511             : 
     512             :         
     513             :         
     514             : 
     515             :         // A map for the autoincrementation algorithm
     516             :         std::map<std::string,int>  noAutoIncIds;
     517             :         void autoIncrement(std::string key, AnnotationRow* x);
     518             : 
     519             : 
     520             :         /**
     521             :          * If this table has an autoincrementable attribute then check if *x verifies the rule of uniqueness and throw exception if not.
     522             :          * Check if *x verifies the key uniqueness rule and throw an exception if not.
     523             :          * Append x to its table.
     524             :          * @throws DuplicateKey
     525             :          
     526             :          * @throws UniquenessViolationException
     527             :          
     528             :          */
     529             :         AnnotationRow* checkAndAdd(AnnotationRow* x, bool skipCheckUniqueness=false) ;
     530             :         
     531             :         /**
     532             :          * Brutally append an AnnotationRow x to the collection of rows already stored in this table. No uniqueness check is done !
     533             :          *
     534             :          * @param AnnotationRow* x a pointer onto the AnnotationRow to be appended.
     535             :          */
     536             :          void append(AnnotationRow* x) ;
     537             :          
     538             :         /**
     539             :          * Brutally append an AnnotationRow x to the collection of rows already stored in this table. No uniqueness check is done !
     540             :          *
     541             :          * @param AnnotationRow* x a pointer onto the AnnotationRow to be appended.
     542             :          */
     543             :          void addWithoutCheckingUnique(AnnotationRow* x) ;
     544             :          
     545             :          
     546             : 
     547             : 
     548             : 
     549             : // A data structure to store the pointers on the table's rows.
     550             : 
     551             : // In all cases we maintain a private vector of AnnotationRow s.
     552             :    std::vector<AnnotationRow * > privateRows;
     553             :    
     554             : 
     555             :                         
     556             :         std::vector<AnnotationRow *> row;
     557             : 
     558             :         
     559             :         void error() ; //throw(ConversionException);
     560             : 
     561             :         
     562             :         /**
     563             :          * Populate this table from the content of a XML document that is required to
     564             :          * be conform to the XML schema defined for a Annotation (AnnotationTable.xsd).
     565             :          * @throws ConversionException
     566             :          * 
     567             :          */
     568             :         void fromXML(std::string& xmlDoc) ;
     569             :                 
     570             :         std::map<std::string, BinaryAttributeReaderFunctor *> unknownAttributes2Functors;
     571             : 
     572             :         /**
     573             :           * Private methods involved during the build of this table out of the content
     574             :           * of file(s) containing an external representation of a Annotation table.
     575             :           */
     576             :         void setFromMIMEFile(const std::string& directory);
     577             :         /*
     578             :         void openMIMEFile(const std::string& directory);
     579             :         */
     580             :         void setFromXMLFile(const std::string& directory);
     581             :         
     582             :                  /**
     583             :          * Serialize this into a stream of bytes and encapsulates that stream into a MIME message.
     584             :          * @returns a string containing the MIME message.
     585             :          *
     586             :          * @param byteOrder a const pointer to a static instance of the class ByteOrder.
     587             :          * 
     588             :          */
     589             :         std::string toMIME(const asdm::ByteOrder* byteOrder=asdm::ByteOrder::Machine_Endianity);
     590             :   
     591             :         
     592             :    /** 
     593             :      * Extracts the binary part of a MIME message and deserialize its content
     594             :          * to fill this with the result of the deserialization. 
     595             :          * @param mimeMsg the string containing the MIME message.
     596             :          * @throws ConversionException
     597             :          */
     598             :          void setFromMIME(const std::string & mimeMsg);
     599             :         
     600             :         /**
     601             :           * Private methods involved during the export of this table into disk file(s).
     602             :           */
     603             :         std::string MIMEXMLPart(const asdm::ByteOrder* byteOrder=asdm::ByteOrder::Machine_Endianity);
     604             :         
     605             :         /**
     606             :           * Stores a representation (binary or XML) of this table into a file.
     607             :           *
     608             :           * Depending on the boolean value of its private field fileAsBin a binary serialization  of this (fileAsBin==true)  
     609             :           * will be saved in a file "Annotation.bin" or an XML representation (fileAsBin==false) will be saved in a file "Annotation.xml".
     610             :           * The file is always written in a directory whose name is passed as a parameter.
     611             :          * @param directory The name of directory  where the file containing the table's representation will be saved.
     612             :           * 
     613             :           */
     614             :           void toFile(std::string directory);
     615             :           
     616             :           /**
     617             :            * Load the table in memory if necessary.
     618             :            */
     619             :           bool loadInProgress;
     620           0 :           void checkPresenceInMemory() {
     621           0 :                 if (!presentInMemory && !loadInProgress) {
     622           0 :                         loadInProgress = true;
     623           0 :                         setFromFile(getContainer().getDirectory());
     624           0 :                         presentInMemory = true;
     625           0 :                         loadInProgress = false;
     626             :                 }
     627           0 :           }
     628             :         /**
     629             :          * Reads and parses a file containing a representation of a AnnotationTable as those produced  by the toFile method.
     630             :          * This table is populated with the result of the parsing.
     631             :          * @param directory The name of the directory containing the file te be read and parsed.
     632             :          * @throws ConversionException If any error occurs while reading the 
     633             :          * files in the directory or parsing them.
     634             :          *
     635             :          */
     636             :          void setFromFile(const std::string& directory);    
     637             :  
     638             : };
     639             : 
     640             : } // End namespace asdm
     641             : 
     642             : #endif /* AnnotationTable_CLASS */