NCBI C++ ToolKit
netcache_key.hpp
Go to the documentation of this file.

Go to the SVN repository for this file.

1 #ifndef CONN___NETCACHE_KEY__HPP
2 #define CONN___NETCACHE_KEY__HPP
3 
4 /* $Id: netcache_key.hpp 63358 2014-06-19 18:47:24Z kazimird $
5  * ===========================================================================
6  *
7  * PUBLIC DOMAIN NOTICE
8  * National Center for Biotechnology Information
9  *
10  * This software/database is a "United States Government Work" under the
11  * terms of the United States Copyright Act. It was written as part of
12  * the author's official duties as a United States Government employee and
13  * thus cannot be copyrighted. This software/database is freely available
14  * to the public for use. The National Library of Medicine and the U.S.
15  * Government have not placed any restriction on its use or reproduction.
16  *
17  * Although all reasonable efforts have been taken to ensure the accuracy
18  * and reliability of the software and data, the NLM and the U.S.
19  * Government do not and cannot warrant the performance or results that
20  * may be obtained by using this software or data. The NLM and the U.S.
21  * Government disclaim all warranties, express or implied, including
22  * warranties of performance, merchantability or fitness for any particular
23  * purpose.
24  *
25  * Please cite the author in any work or product based on this material.
26  *
27  * ===========================================================================
28  *
29  * Authors: Anatoliy Kuznetsov, Maxim Didenko
30  *
31  * File Description:
32  * Net cache client API.
33  *
34  */
35 
36 /// @file netcache_key.hpp
37 /// NetCache client specs.
38 ///
39 
40 #include "compound_id.hpp"
41 
42 #include <connect/connect_export.h>
43 
44 #include <corelib/ncbistl.hpp>
45 #include <corelib/ncbitype.h>
46 
47 #include <string>
48 
50 
51 
52 /** @addtogroup NetCacheClient
53  *
54  * @{
55  */
56 
57 
58 /// Meaningful information encoded in the NetCache key
59 ///
60 ///
62 {
63 public:
64  /// Blob and blob key features.
65  enum ENCKeyFlag {
66  fNCKey_SingleServer = 1 << 0, ///< Mark this blob as not mirrored.
67  fNCKey_NoServerCheck = 1 << 1, ///< Disable the check for whether
68  ///< the server IP is still in service.
69  };
70  typedef unsigned TNCKeyFlags; ///< Binary OR of ENCKeyFlag.
71 
72  /// Create the key out of string
73  explicit CNetCacheKey(const string& key_str,
75 
76  /// Create an empty object for later use with ParseBlobKey() or Assign().
78 
79  /// Parse the specified blob ID and initializes this object.
80  /// @throws CNetCacheException if key format is not recognized.
81  void Assign(const string& key_str,
83 
84  /// Parse blob key string into a CNetCacheKey structure
85  static bool ParseBlobKey(const char* key_str,
86  size_t key_len, CNetCacheKey* key_obj,
88 
89  bool HasExtensions() const {return m_PrimaryKey.length() < m_Key.length();}
90 
91  /// If the blob key has been parsed successfully,
92  /// this method returns a trimmed "base" version
93  /// of the key with "0MetA0" extensions removed.
94  string StripKeyExtensions() const;
95 
96  /// Unconditionally append a service name to the specified string.
97  static void AddExtensions(string& blob_id, const string& service_name,
98  TNCKeyFlags flags, unsigned ver = 1);
99 
100  TNCKeyFlags GetFlags() const {return m_Flags;}
101  bool GetFlag(ENCKeyFlag flag) const {return (m_Flags & flag) != 0;}
102  void SetFlag(ENCKeyFlag flag) {m_Flags |= (TNCKeyFlags) flag;}
103  void ClearFlag(ENCKeyFlag flag) {m_Flags &= ~(TNCKeyFlags) flag;}
104 
105  /// Calculate and return the CRC32 checksum generated from the
106  /// string "host:port".
107  static Uint4 CalculateChecksum(const string& host, unsigned short port);
108 
109  /// Generate blob key string
110  ///
111  /// Please note that "id" is an integer issued by the NetCache server.
112  /// Clients should not use this function with custom ids.
113  static
114  void GenerateBlobKey(string* key,
115  unsigned int id,
116  const string& host,
117  unsigned short port,
118  unsigned int ver,
119  unsigned int rnd_num,
120  time_t creation_time = 0);
121 
122  static string KeyToCompoundID(
123  const string& key_str,
124  CCompoundIDPool id_pool);
125 
126  /// Parse blob key, extract id
127  static unsigned int GetBlobId(const string& key_str);
128 
129  static bool IsValidKey(const char* key_str, size_t key_len,
131  { return ParseBlobKey(key_str, key_len, NULL, id_pool); }
132 
133  static bool IsValidKey(const string& key,
135  { return IsValidKey(key.c_str(), key.length(), id_pool); }
136 
137  const string& GetKey() const;
138  unsigned GetId() const;
139  const string& GetHost() const;
140  unsigned short GetPort() const;
141  unsigned GetHostPortCRC32() const;
142  unsigned GetVersion() const;
143  time_t GetCreationTime() const;
144  Uint4 GetRandomPart() const;
145  const string& GetServiceName() const;
146 
147 private:
148  string m_Key;
149  string m_PrimaryKey;
150  unsigned int m_Id; ///< BLOB id
151  string m_Host; ///< server name
152  unsigned short m_Port; ///< TCP/IP port number
153  unsigned m_HostPortCRC32; ///< CRC32 checksum of the host:port combination
154  unsigned m_Version; ///< Key version
157 
158  // Key extensions
161 };
162 
163 
164 //////////////////////////////////////////////////////////////////////////
165 // Inline functions
166 //////////////////////////////////////////////////////////////////////////
167 
168 inline string CNetCacheKey::StripKeyExtensions() const
169 {
170  return m_PrimaryKey;
171 }
172 
173 inline const string& CNetCacheKey::GetKey() const
174 {
175  return m_Key;
176 }
177 
178 inline unsigned int
180 {
181  return m_Id;
182 }
183 
184 inline const string&
186 {
187  return m_Host;
188 }
189 
190 inline unsigned short
192 {
193  return m_Port;
194 }
195 
196 inline unsigned CNetCacheKey::GetHostPortCRC32() const
197 {
198  return m_HostPortCRC32;
199 }
200 
201 inline unsigned int
203 {
204  return m_Version;
205 }
206 
207 inline time_t CNetCacheKey::GetCreationTime() const
208 {
209  return m_CreationTime;
210 }
211 
213 {
214  return m_Random;
215 }
216 
217 inline const string& CNetCacheKey::GetServiceName() const
218 {
219  return m_ServiceName;
220 }
221 
222 
223 /* @} */
224 
225 
227 
228 #endif /* CONN___NETCACHE_KEY__HPP */
Pool of recycled CCompoundID objects.
Declarations of CCompoundIDPool, CCompoundID, and CCompoundIDField.
static uch flags
#define NULL
Definition: ncbistd.hpp:225
static bool IsValidKey(const string &key, CCompoundIDPool::TInstance id_pool=NULL)
ENCKeyFlag
Blob and blob key features.
void ClearFlag(ENCKeyFlag flag)
time_t m_CreationTime
void SetFlag(ENCKeyFlag flag)
unsigned TNCKeyFlags
Binary OR of ENCKeyFlag.
string m_ServiceName
bool GetFlag(ENCKeyFlag flag) const
unsigned GetHostPortCRC32() const
static bool IsValidKey(const char *key_str, size_t key_len, CCompoundIDPool::TInstance id_pool=NULL)
unsigned GetId() const
bool HasExtensions() const
CNetCacheKey()
Create an empty object for later use with ParseBlobKey() or Assign().
unsigned short m_Port
TCP/IP port number.
unsigned short GetPort() const
Uint4 GetRandomPart() const
const string & GetKey() const
unsigned m_HostPortCRC32
CRC32 checksum of the host:port combination.
unsigned m_Version
Key version.
string m_Host
server name
unsigned GetVersion() const
TNCKeyFlags GetFlags() const
const string & GetHost() const
time_t GetCreationTime() const
const string & GetServiceName() const
string StripKeyExtensions() const
If the blob key has been parsed successfully, this method returns a trimmed "base" version of the key...
unsigned int m_Id
BLOB id.
TNCKeyFlags m_Flags
string m_PrimaryKey
const CSeq_id & GetId(const CSeq_loc &loc, CScope *scope)
If all CSeq_ids embedded in CSeq_loc refer to the same CBioseq, returns the first CSeq_id found,...
uint32_t Uint4
4-byte (32-bit) unsigned integer
Definition: ncbitype.h:103
#define END_NCBI_SCOPE
End previously defined NCBI scope.
Definition: ncbistl.hpp:103
#define BEGIN_NCBI_SCOPE
Define ncbi namespace.
Definition: ncbistl.hpp:100
unsigned short GetPort() const
Get the listening port number back.
#define NCBI_XCONNECT_EXPORT
Uint4 GetHost(TEndpointKey key)
const struct ncbi::grid::netcache::search::fields::KEY key
The NCBI C++/STL use hints.
Defines Limits for the types used in NCBI C/C++ toolkit.
Meaningful information encoded in the NetCache key.
Modified on Thu Mar 28 17:12:02 2024 by modify_doxy.py rev. 669887