taxon1.hpp
上传用户:yhdzpy8989
上传日期:2007-06-13
资源大小:13604k
文件大小:27k
源码类别:

生物技术

开发平台:

C/C++

  1. /*
  2.  * ===========================================================================
  3.  * PRODUCTION $Log: taxon1.hpp,v $
  4.  * PRODUCTION Revision 1000.1  2004/04/12 17:24:21  gouriano
  5.  * PRODUCTION PRODUCTION: UPGRADED [CATCHUP_003] Dev-tree R1.16
  6.  * PRODUCTION
  7.  * ===========================================================================
  8.  */
  9. #ifndef NCBI_TAXON1_HPP
  10. #define NCBI_TAXON1_HPP
  11. /* $Id: taxon1.hpp,v 1000.1 2004/04/12 17:24:21 gouriano Exp $
  12.  * ===========================================================================
  13.  *
  14.  *                            PUBLIC DOMAIN NOTICE
  15.  *               National Center for Biotechnology Information
  16.  *
  17.  *  This software/database is a "United States Government Work" under the
  18.  *  terms of the United States Copyright Act.  It was written as part of
  19.  *  the author's official duties as a United States Government employee and
  20.  *  thus cannot be copyrighted.  This software/database is freely available
  21.  *  to the public for use. The National Library of Medicine and the U.S.
  22.  *  Government have not placed any restriction on its use or reproduction.
  23.  *
  24.  *  Although all reasonable efforts have been taken to ensure the accuracy
  25.  *  and reliability of the software and data, the NLM and the U.S.
  26.  *  Government do not and cannot warrant the performance or results that
  27.  *  may be obtained by using this software or data. The NLM and the U.S.
  28.  *  Government disclaim all warranties, express or implied, including
  29.  *  warranties of performance, merchantability or fitness for any particular
  30.  *  purpose.
  31.  *
  32.  *  Please cite the author in any work or product based on this material.
  33.  *
  34.  * ===========================================================================
  35.  *
  36.  * Author:  Vladimir Soussov, Michael Domrachev
  37.  *
  38.  * File Description:
  39.  *     NCBI Taxonomy information retreival library
  40.  *
  41.  */
  42. #include <objects/taxon1/taxon1__.hpp>
  43. #include <objects/seqfeat/seqfeat__.hpp>
  44. #include <serial/serialdef.hpp>
  45. #include <connect/ncbi_types.h>
  46. #include <corelib/ncbi_limits.hpp>
  47. #include <list>
  48. #include <vector>
  49. #include <map>
  50. BEGIN_NCBI_SCOPE
  51. class CObjectOStream;
  52. class CConn_ServiceStream;
  53. BEGIN_objects_SCOPE
  54. class COrgRefCache;
  55. class ITaxon1Node;
  56. class ITreeIterator;
  57. class NCBI_TAXON1_EXPORT CTaxon1 {
  58. public:
  59.     typedef list< string > TNameList;
  60.     typedef vector< int > TTaxIdList;
  61.     CTaxon1();
  62.     ~CTaxon1();
  63.     //---------------------------------------------
  64.     // Taxon1 server init
  65.     // Returns: TRUE - OK
  66.     //          FALSE - Can't open connection to taxonomy service
  67.     ///
  68.     bool Init(void);  // default:  120 sec timeout, 5 reconnect attempts,
  69.                       // cache for 10 org-refs
  70.     bool Init(unsigned cache_capacity);
  71.     bool Init(const STimeout* timeout, unsigned reconnect_attempts=5,
  72.       unsigned cache_capacity=10);
  73.     //---------------------------------------------
  74.     // Taxon1 server fini (closes connection, frees memory)
  75.     ///
  76.     void Fini(void);
  77.     //---------------------------------------------
  78.     // Get organism by tax_id
  79.     // Returns: pointer to Taxon2Data if organism exists
  80.     //          NULL - if tax_id wrong
  81.     //
  82.     // NOTE:
  83.     // Caller gets his own copy of Taxon2Data structure.
  84.     ///
  85.     CRef< CTaxon2_data > GetById(int tax_id);
  86.     //----------------------------------------------
  87.     // Get organism by OrgRef
  88.     // Returns: pointer to Taxon2Data if organism exists
  89.     //          NULL - if no such organism in taxonomy database
  90.     //
  91.     // NOTE:
  92.     // 1. These functions uses the following data from inp_orgRef to find
  93.     //    organism in taxonomy database. It uses taxname first. If no organism
  94.     //    was found (or multiple nodes found) then it tryes to find organism
  95.     //    using common name. If nothing found, then it tryes to find organism
  96.     //    using synonyms. Lookup never uses tax_id to find organism.
  97.     // 2. LookupMerge function modifies given OrgRef to correspond to the
  98.     //    found one and returns constant pointer to the Taxon2Data structure
  99.     //    stored internally.
  100.     ///
  101.     CRef< CTaxon2_data > Lookup(const COrg_ref& inp_orgRef);
  102.     CConstRef< CTaxon2_data > LookupMerge(COrg_ref& inp_orgRef);
  103.     //-----------------------------------------------
  104.     // Get tax_id by OrgRef
  105.     // Returns: tax_id - if organism found
  106.     //               0 - no organism found
  107.     //         -tax_id - if multiple nodes found
  108.     //                   (where -tax_id is id of one of the nodes)
  109.     // NOTE:
  110.     // This function uses the same information from inp_orgRef as Lookup
  111.     ///
  112.     int GetTaxIdByOrgRef(const COrg_ref& inp_orgRef);
  113.     enum EOrgRefStatus {
  114. eStatus_Ok = 0,
  115. eStatus_WrongTaxId      = 0x001,
  116. eStatus_WrongGC         = 0x002,
  117. eStatus_WrongMGC        = 0x004,
  118. eStatus_NoOrgname       = 0x008,
  119. eStatus_WrongTaxname    = 0x010,
  120. eStatus_WrongLineage    = 0x020,
  121. eStatus_WrongCommonName = 0x040,
  122. eStatus_WrongOrgname    = 0x080,
  123. eStatus_WrongDivision   = 0x100,
  124. eStatus_WrongOrgmod     = 0x200
  125.     };
  126.     typedef unsigned TOrgRefStatus;
  127.     //-----------------------------------------------
  128.     // Checks whether OrgRef is valid
  129.     // Returns: false on any error, stat_out filled with status flags
  130.     // (see above)
  131.     ///
  132.     bool CheckOrgRef( const COrg_ref& orgRef, TOrgRefStatus& stat_out );
  133.     enum ESearch {
  134. eSearch_Exact,
  135. eSearch_TokenSet,
  136. eSearch_WildCard, // shell-style wildcards, i.e. *,?,[]
  137. eSearch_Phonetic
  138.     };
  139.     //----------------------------------------------
  140.     // Get tax_id by organism name
  141.     // Returns: tax_id - if organism found
  142.     //               0 - no organism found
  143.     //         -tax_id - if multiple nodes found
  144.     //                   (where -tax_id is id of one of the nodes)
  145.     ///
  146.     int GetTaxIdByName(const string& orgname);
  147.     //----------------------------------------------
  148.     // Get tax_id by organism "unique" name
  149.     // Returns: tax_id - if organism found
  150.     //               0 - no organism found
  151.     //         -tax_id - if multiple nodes found
  152.     //                   (where -tax_id is id of one of the nodes)
  153.     ///
  154.     int FindTaxIdByName(const string& orgname);
  155.     //----------------------------------------------
  156.     // Get tax_id by organism name using fancy search modes. If given a pointer
  157.     // to the list of names then it'll return all found names (one name per 
  158.     // tax id). Previous content of name_list_out will be destroyed.
  159.     // Returns: tax_id - if organism found
  160.     //               0 - no organism found
  161.     //              -1 - if multiple nodes found
  162.     ///
  163.     int SearchTaxIdByName(const string& orgname,
  164.   ESearch mode = eSearch_TokenSet,
  165.   list< CRef< CTaxon1_name > >* name_list_out = NULL);
  166.     //----------------------------------------------
  167.     // Get ALL tax_id by organism name
  168.     // Returns: number of organisms found, id list appended with found tax ids
  169.     ///
  170.     int GetAllTaxIdByName(const string& orgname, TTaxIdList& lIds);
  171.     //----------------------------------------------
  172.     // Get organism by tax_id
  173.     // Returns: pointer to OrgRef structure if organism found
  174.     //          NULL - if no such organism in taxonomy database
  175.     // NOTE:
  176.     // This function does not make a copy of OrgRef structure but returns
  177.     // pointer to internally stored OrgRef.
  178.     ///
  179.     CConstRef< COrg_ref > GetOrgRef(int tax_id,
  180.     bool& is_species,
  181.     bool& is_uncultured,
  182.     string& blast_name);
  183.     //---------------------------------------------
  184.     // Set mode for synonyms in OrgRef
  185.     // Returns: previous mode
  186.     // NOTE:
  187.     // Default value: false (do not copy synonyms to the new OrgRef)
  188.     ///
  189.     bool SetSynonyms(bool on_off);
  190.     //---------------------------------------------
  191.     // Get parent tax_id
  192.     // Returns: tax_id of parent node or 0 if error
  193.     // NOTE:
  194.     //   Root of the tree has tax_id of 1
  195.     ///
  196.     int GetParent(int id_tax);
  197.     //---------------------------------------------
  198.     // Get genus tax_id (id_tax should be below genus)
  199.     // Returns: tax_id of genus or -1 if error or no genus in the lineage
  200.     ///
  201.     int GetGenus(int id_tax);
  202.     //---------------------------------------------
  203.     // Get superkingdom tax_id (id_tax should be below superkingdom)
  204.     // Returns: tax_id of superkingdom
  205.     //          or -1 if error or no superkingdom in the lineage
  206.     ///
  207.     int GetSuperkingdom(int id_tax);
  208.     //---------------------------------------------
  209.     // Get taxids for all children of specified node.
  210.     // Returns: number of children, id list appended with found tax ids
  211.     ///
  212.     int GetChildren(int id_tax, TTaxIdList& children_ids);
  213.     //---------------------------------------------
  214.     // Get genetic code name by genetic code id
  215.     ///
  216.     bool GetGCName(short gc_id, string& gc_name_out );
  217.     //---------------------------------------------
  218.     // Get taxonomic rank name by rank id
  219.     ///
  220.     bool GetRankName(short rank_id, string& rank_name_out );
  221.     //---------------------------------------------
  222.     // Get taxonomic division name by division id
  223.     ///
  224.     bool GetDivisionName(short div_id, string& div_name_out );
  225.     //---------------------------------------------
  226.     // Get taxonomic name class name by name class id
  227.     ///
  228.     bool GetNameClass(short nameclass_id, string& class_name_out );
  229.     //---------------------------------------------
  230.     // Get the nearest common ancestor for two nodes
  231.     // Returns: id of this ancestor (id == 1 means that root node only is
  232.     // ancestor)
  233.     int Join(int taxid1, int taxid2);
  234.     //---------------------------------------------
  235.     // Get all names for tax_id
  236.     // Returns: number of names, name list appended with ogranism's names
  237.     // NOTE:
  238.     // If unique is true then only unique names will be stored
  239.     ///
  240.     int GetAllNames(int tax_id, TNameList& lNames, bool unique);
  241.     //---------------------------------------------
  242.     // Find out is taxonomy lookup system alive or not
  243.     // Returns: TRUE - alive
  244.     //          FALSE - dead
  245.     ///
  246.     bool IsAlive(void);
  247.     //--------------------------------------------------
  248.     // Get tax_id for given gi
  249.     // Returns:
  250.     //       true   if ok
  251.     //       false  if error
  252.     // tax_id_out contains:
  253.     //       tax_id if found
  254.     //       0      if not found
  255.     ///
  256.     bool GetTaxId4GI(int gi, int& tax_id_out);
  257.     //--------------------------------------------------
  258.     // Get "blast" name for id
  259.     // Returns: false if some error (blast_name_out not changed)
  260.     //          true  if Ok
  261.     //                blast_name_out contains first blast name at or above
  262.     //                this node in the lineage or empty if there is no blast
  263.     //                name above
  264.     ///
  265.     bool GetBlastName(int tax_id, string& blast_name_out);
  266.     //--------------------------------------------------
  267.     // Get error message after latest erroneous operation
  268.     // Returns: error message, or empty string if no error occurred
  269.     ///
  270.     const string& GetLastError() const { return m_sLastError; }
  271.     //--------------------------------------------------
  272.     // This function constructs minimal common tree from the given tax id
  273.     // set (ids_in) treated as tree's leaves. It then returns a residue of 
  274.     // this tree node set and the given tax id set in ids_out.
  275.     // Returns: false if some error
  276.     //          true  if Ok
  277.     ///
  278.     bool GetPopsetJoin( const TTaxIdList& ids_in, TTaxIdList& ids_out );
  279.     //--------------------------------------------------
  280.     // This function updates cached partial tree and insures that node
  281.     // with given tax_id and all its ancestors will present in this tree.
  282.     // Returns: false if error
  283.     //          true  if Ok, *ppNode is pointing to the node
  284.     ///
  285.     bool LoadNode( int tax_id, const ITaxon1Node** ppNode = NULL )
  286.     { return LoadSubtreeEx( tax_id, 0, ppNode ); }
  287.     //--------------------------------------------------
  288.     // This function updates cached partial tree and insures that node
  289.     // with given tax_id and all its ancestors and immediate children (if any)
  290.     // will present in this tree.
  291.     // Returns: false if error
  292.     //          true  if Ok, *ppNode is pointing to the subtree root
  293.     ///
  294.     bool LoadChildren( int tax_id, const ITaxon1Node** ppNode = NULL )
  295.     { return LoadSubtreeEx( tax_id, 1, ppNode ); }
  296.     //--------------------------------------------------
  297.     // This function updates cached partial tree and insures that all nodes
  298.     // from subtree with given tax_id as a root will present in this tree.
  299.     // Returns: false if error
  300.     //          true  if Ok, *ppNode is pointing to the subtree root
  301.     ///
  302.     bool LoadSubtree( int tax_id, const ITaxon1Node** ppNode = NULL )
  303.     { return LoadSubtreeEx( tax_id, -1, ppNode ); }
  304.     enum EIteratorMode {
  305. eIteratorMode_FullTree, // Iterator in this mode traverses all tree nodes
  306. eIteratorMode_LeavesBranches, // traverses only leaves and branches
  307. eIteratorMode_Best,           // leaves and branches plus nodes right below branches
  308. eIteratorMode_Blast,          // nodes with non-empty blast names
  309. eIteratorMode_Default = eIteratorMode_FullTree
  310.     };
  311.     //--------------------------------------------------
  312.     // This function returnes an iterator of a cached partial tree positioned
  313.     // at the tree root. Please note that the tree is PARTIAL. To traverse the
  314.     // full taxonomy tree invoke LoadSubtree(1) first.
  315.     // Returns: NULL if error
  316.     ///
  317.     CRef< ITreeIterator > GetTreeIterator( EIteratorMode mode
  318.    = eIteratorMode_Default );
  319.     //--------------------------------------------------
  320.     // This function returnes an iterator of a cached partial tree positioned
  321.     // at the tree node with tax_id.
  322.     // Returns: NULL if node doesn't exist or some other error occurred
  323.     ///
  324.     CRef< ITreeIterator > GetTreeIterator( int tax_id, EIteratorMode mode
  325.    = eIteratorMode_Default );
  326.     //--------------------------------------------------
  327.     // These functions retreive the "properties" of the taxonomy nodes. Each
  328.     // "property" is a (name, value) pair where name is a string and value
  329.     // could be of integer, boolean, or string type.
  330.     // Returns: true  when success and last parameter is filled with value,
  331.     //          false when call failed
  332.     ///
  333.     bool GetNodeProperty( int tax_id, const string& prop_name,
  334.   bool& prop_val );
  335.     bool GetNodeProperty( int tax_id, const string& prop_name,
  336.   int& prop_val );
  337.     bool GetNodeProperty( int tax_id, const string& prop_name,
  338.   string& prop_val );
  339. private:
  340.     friend class COrgRefCache;
  341.     ESerialDataFormat        m_eDataFormat;
  342.     const char*              m_pchService;
  343.     STimeout*                m_timeout;  // NULL, or points to "m_timeout_value"
  344.     STimeout                 m_timeout_value;
  345.     CConn_ServiceStream*     m_pServer;
  346.     CObjectOStream*          m_pOut;
  347.     CObjectIStream*          m_pIn;
  348.     unsigned                 m_nReconnectAttempts;
  349.     COrgRefCache*            m_plCache;
  350.     bool                     m_bWithSynonyms;
  351.     string                   m_sLastError;
  352.     typedef map<short, string> TGCMap;
  353.     TGCMap                   m_gcStorage;
  354.     void             Reset(void);
  355.     bool             SendRequest(CTaxon1_req& req, CTaxon1_resp& resp);
  356.     void             SetLastError(const char* err_msg);
  357.     void             PopulateReplaced(COrg_ref& org, COrgName::TMod& lMods);
  358.     bool             LookupByOrgRef(const COrg_ref& inp_orgRef, int* pTaxid,
  359.     COrgName::TMod& hitMods);
  360.     void             OrgRefAdjust( COrg_ref& inp_orgRef,
  361.    const COrg_ref& db_orgRef,
  362.    int tax_id );
  363.     bool             LoadSubtreeEx( int tax_id, int type,
  364.     const ITaxon1Node** ppNode );
  365. };
  366. //-------------------------------------------------
  367. // This interface class represents a Taxonomy Tree node
  368. class ITaxon1Node {
  369. public:
  370.     //-------------------------------------------------
  371.     // Returns: taxonomy id of the node
  372.     virtual int              GetTaxId() const = 0;
  373.     //-------------------------------------------------
  374.     // Returns: scientific name of the node. This name is NOT unique
  375.     // To get unique name take the first one from the list after calling
  376.     // CTaxon1::GetAllNames() with parameter unique==true.
  377.     virtual const string&    GetName() const = 0;
  378.     //-------------------------------------------------
  379.     // Returns: blast name of the node if assigned or empty string otherwise.
  380.     virtual const string&    GetBlastName() const = 0;
  381.     //-------------------------------------------------
  382.     // Returns: taxonomic rank id of the node
  383.     virtual short            GetRank() const = 0;
  384.     //-------------------------------------------------
  385.     // Returns: taxonomic division id of the node
  386.     virtual short            GetDivision() const = 0;
  387.     //-------------------------------------------------
  388.     // Returns: genetic code for the node
  389.     virtual short            GetGC() const = 0;
  390.     //-------------------------------------------------
  391.     // Returns: mitochondrial genetic code for the node
  392.     virtual short            GetMGC() const = 0;
  393.                        
  394.     //-------------------------------------------------
  395.     // Returns: true if node is uncultured,
  396.     //          false otherwise
  397.     virtual bool             IsUncultured() const = 0;
  398.     //-------------------------------------------------
  399.     // Returns: true if node is root
  400.     //          false otherwise
  401.     virtual bool             IsRoot() const = 0;
  402. };
  403. //-------------------------------------------------
  404. // This interface class represents an iterator to traverse the
  405. // partial taxonomy tree build by CTaxon1 object.
  406. class NCBI_TAXON1_EXPORT ITreeIterator : public CObject {
  407. public:
  408.     //-------------------------------------------------
  409.     // Returns: iterator operating mode
  410.     //
  411.     virtual CTaxon1::EIteratorMode GetMode() const = 0;
  412.     //-------------------------------------------------
  413.     // Get node pointed by this iterator
  414.     // Returns: pointer to node
  415.     //          or NULL if error
  416.     virtual const ITaxon1Node* GetNode() const = 0;
  417.     const ITaxon1Node* operator->() const { return GetNode(); }
  418.     //-------------------------------------------------
  419.     // Returns: true if node is terminal,
  420.     //          false otherwise
  421.     // NOTE: Although node is terminal in the partial tree
  422.     // build by CTaxon object it might be NOT a terminal node
  423.     // in the full taxonomic tree !
  424.     virtual bool IsTerminal() const = 0;
  425.     //-------------------------------------------------
  426.     // Returns: true if node is last child in this partial tree,
  427.     //          false otherwise
  428.     virtual bool IsLastChild() const = 0;
  429.     //-------------------------------------------------
  430.     // Returns: true if node is last child in this partial tree,
  431.     //          false otherwise
  432.     virtual bool IsFirstChild() const = 0;
  433.     //-------------------------------------------------
  434.     // Move iterator to tree root
  435.     // Returns: true if move is sucessful,
  436.     //          false otherwise (e.g. node is root)
  437.     virtual void GoRoot() = 0;
  438.     //-------------------------------------------------
  439.     // Move iterator to parent node
  440.     // Returns: true if move is sucessful,
  441.     //          false otherwise (e.g. node is root)
  442.     virtual bool GoParent() = 0;
  443.     //-------------------------------------------------
  444.     // Move iterator to first child
  445.     // Returns: true if move is sucessful,
  446.     //          false otherwise (e.g. no children)
  447.     virtual bool GoChild() = 0;
  448.     //-------------------------------------------------
  449.     // Move iterator to sibling
  450.     // Returns: true if move is sucessful,
  451.     //          false otherwise (e.g. last child)
  452.     virtual bool GoSibling() = 0;
  453.     //-------------------------------------------------
  454.     // Move iterator to given node. Node MUST be previously obtained
  455.     // using GetNode().
  456.     // Returns: true if move is sucessful,
  457.     //          false otherwise
  458.     virtual bool GoNode(const ITaxon1Node* pNode) = 0;
  459.     //-------------------------------------------------
  460.     // Move iterator to the nearest common ancestor of the node pointed
  461.     // by iterator and given node
  462.     // Returns: true if move sucessful,
  463.     //          false otherwise
  464.     virtual bool GoAncestor(const ITaxon1Node* pNode) = 0; 
  465.     enum EAction {
  466. eOk,   // Ok - Continue traversing
  467. eStop, // Stop traversing, exit immediately
  468.        // (the iterator will stay on node which returns this code)
  469. eSkip  // Skip current node's subree and continue traversing
  470.     };
  471.     //-------------------------------------------------
  472.     // "Callback" class for traversing the tree.
  473.     // It features 3 virtual member functions: Execute(), LevelBegin(),
  474.     // and LevelEnd(). Execute() is called with pointer of a node
  475.     // to process it. LevelBegin() and LevelEnd() functions are called 
  476.     // before and after processing of the children nodes respectively with
  477.     // to-be-processed subtree root as an argument. They are called only
  478.     // when the node has children. The order of execution of 3 functions
  479.     // may differ but LevelBegin() always precedes LevelEnd().
  480.     class I4Each {
  481.     public:
  482. virtual EAction LevelBegin(const ITaxon1Node* /*pParent*/)
  483. { return eOk; }
  484. virtual EAction Execute(const ITaxon1Node* pNode)= 0;
  485. virtual EAction LevelEnd(const ITaxon1Node* /*pParent*/)
  486. { return eOk; }
  487.     };
  488.     
  489.     //--------------------------------------------------
  490.     // Here's a tree A drawing that will be used to explain trversing modes
  491.     //              /| 
  492.     //             B C
  493.     //            /| 
  494.     //           D E
  495.     //
  496.     // This function arranges 'downward' traverse mode when higher nodes are
  497.     // processed first. The sequence of calls to I4Each functions for
  498.     // iterator at the node A whould be:
  499.     //   Execute( A ), LevelBegin( A )
  500.     //     Execute( B ), LevelBegin( B )
  501.     //       Execute( D ), Execute( E )
  502.     //     LevelEnd( B )
  503.     //     Execute( C )
  504.     //   LevelEnd( A )
  505.     // The 'levels' parameter specifies the depth of traversing the tree.
  506.     // Nodes that are 'levels' levels below subtree root are considered
  507.     // terminal nodes.
  508.     // Returns: Action code (see EAction description)
  509.     EAction TraverseDownward(I4Each&, unsigned levels = kMax_UInt);
  510.     //--------------------------------------------------
  511.     // This function arranges 'upward' traverse mode when lower nodes are
  512.     // processed first. The sequence of calls to I4Each functions for
  513.     // iterator at the node A whould be:
  514.     //   LevelBegin( A )
  515.     //     LevelBegin( B )
  516.     //       Execute( D ), Execute( E )
  517.     //     LevelEnd( B ), Execute( B )
  518.     //     Execute( C )
  519.     //   LevelEnd( A ), Execute( A )
  520.     // The 'levels' parameter specifies the depth of traversing the tree.
  521.     // Nodes that are 'levels' levels below subtree root are considered
  522.     // terminal nodes.
  523.     // Returns: Action code (see EAction description)
  524.     EAction TraverseUpward(I4Each&, unsigned levels = kMax_UInt);
  525.     //--------------------------------------------------
  526.     // This function arranges 'level by level' traverse mode when nodes are 
  527.     // guarantied to be processed after its parent and all of its 'uncles'.
  528.     // The sequence of calls to I4Each functions for iterator at the node A
  529.     // whould be:
  530.     //   Execute( A ), LevelBegin( A )
  531.     //     Execute( B ), Execute( C )
  532.     //       LevelBegin( B )
  533.     //         Execute( D ), Execute( E )
  534.     //       LevelEnd( B )
  535.     //   LevelEnd( A )
  536.     // The 'levels' parameter specifies the depth of traversing the tree.
  537.     // Nodes that are 'levels' levels below subtree root are considered
  538.     // terminal nodes.
  539.     // Returns: Action code (see EAction description)
  540.     EAction TraverseLevelByLevel(I4Each&, unsigned levels = kMax_UInt);
  541.     //--------------------------------------------------
  542.     // This function arranges traverse of all ancestors of the node in  
  543.     // ascending order starting from its parent (if there is one).
  544.     // The sequence of calls to I4Each functions for iterator at the node D
  545.     // whould be:
  546.     //   Execute( B )
  547.     //   Execute( A )
  548.     // Note: The are NO LevelBegin(), levelEnd() calls performed.
  549.     EAction TraverseAncestors(I4Each&);
  550.     //--------------------------------------------------
  551.     // Checks if node is belonging to subtree with subtree_root
  552.     // Returns: true if it does,
  553.     //          false otherwise
  554.     virtual bool BelongSubtree(const ITaxon1Node* subtree_root) const = 0;
  555.     //--------------------------------------------------
  556.     // Checks if the given node belongs to subtree which root is 
  557.     // pointed by iterator
  558.     // Returns: true if it does,
  559.     //          false otherwise
  560.     virtual bool AboveNode(const ITaxon1Node* node) const = 0;
  561. private:
  562.     EAction TraverseLevelByLevelInternal(I4Each& cb, unsigned levels,
  563.  vector< const ITaxon1Node* >& skp);
  564. };
  565. END_objects_SCOPE
  566. END_NCBI_SCOPE
  567. //
  568. // $Log: taxon1.hpp,v $
  569. // Revision 1000.1  2004/04/12 17:24:21  gouriano
  570. // PRODUCTION: UPGRADED [CATCHUP_003] Dev-tree R1.16
  571. //
  572. // Revision 1.16  2004/04/01 14:14:01  lavr
  573. // Spell "occurred", "occurrence", and "occurring"
  574. //
  575. // Revision 1.15  2004/03/12 20:07:24  domrach
  576. // CheckOrgRef() function added for checking the user orgref against the orgref from Taxonomy db
  577. //
  578. // Revision 1.14  2004/02/04 16:14:43  domrach
  579. // New iterator types (modes of operation) are introduced. They include:
  580. // full tree, branches'n'leaves, best, and blast. Position inquiry f-ns
  581. // IsTerminal(), IsFirstChild(), and IsLastChild() has been moved from
  582. // ITreeNode to ITreeIterator. Node loading f-ns() now return the ITreeNode
  583. // for tax id.
  584. //
  585. // Revision 1.13  2003/12/22 19:17:29  dicuccio
  586. // Added export specifiers
  587. //
  588. // Revision 1.12  2003/07/09 15:41:31  domrach
  589. // SearchTaxIdByName(), GetNameClass(), and GetNodeProperty() functions added
  590. //
  591. // Revision 1.11  2003/05/08 15:56:42  ucko
  592. // Use kMax_UInt instead of numeric_limits<>, which still seems to have
  593. // issues on Windows. :-/
  594. //
  595. // Revision 1.10  2003/05/07 01:56:46  vakatov
  596. // Cut&Paste typo fixed
  597. //
  598. // Revision 1.9  2003/05/06 22:20:43  vakatov
  599. // + <ncbi_limits.hpp> (for MSVC++)
  600. //
  601. // Revision 1.8  2003/05/06 19:54:18  domrach
  602. // New functions and interfaces for traversing the cached partial taxonomy tree introduced. Convenience functions GetDivisionName() and GetRankName() were added
  603. //
  604. // Revision 1.7  2003/03/05 21:32:02  domrach
  605. // Enhanced orgref processing. Orgref cache capacity control added.
  606. //
  607. // Revision 1.5  2002/11/08 14:39:51  domrach
  608. // Member function GetSuperkingdom() added
  609. //
  610. // Revision 1.4  2002/02/15 16:17:24  vakatov
  611. // CTaxon1::Init() -- make "timeout" arg be mandatory
  612. //
  613. // Revision 1.3  2002/02/14 22:44:48  vakatov
  614. // Use STimeout instead of time_t.
  615. // Get rid of warnings and extraneous #include's, shuffled code a little.
  616. //
  617. // Revision 1.2  2002/01/31 00:30:11  vakatov
  618. // Get rid of "std::" which is unnecessary and sometimes un-compilable.
  619. // Also done some source identation/beautification.
  620. //
  621. // Revision 1.1  2002/01/28 19:52:20  domrach
  622. // Initial checkin
  623. //
  624. //
  625. // ===========================================================================
  626. //
  627. #endif //NCBI_TAXON1_HPP