1 #ifndef CONN___NETCACHE_KEY__HPP
2 #define CONN___NETCACHE_KEY__HPP
3
4 /* $Id: netcache_key.hpp 438761 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
49 BEGIN_NCBI_SCOPE
50
51
52 /** @addtogroup NetCacheClient
53 *
54 * @{
55 */
56
57
58 /// Meaningful information encoded in the NetCache key
59 ///
60 ///
61 struct NCBI_XCONNECT_EXPORT CNetCacheKey
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,
74 CCompoundIDPool::TInstance id_pool = NULL);
75
76 /// Create an empty object for later use with ParseBlobKey() or Assign().
CNetCacheKeyCNetCacheKey77 CNetCacheKey() {}
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,
82 CCompoundIDPool::TInstance id_pool = NULL);
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,
87 CCompoundIDPool::TInstance id_pool = NULL);
88
HasExtensionsCNetCacheKey89 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
GetFlagsCNetCacheKey100 TNCKeyFlags GetFlags() const {return m_Flags;}
GetFlagCNetCacheKey101 bool GetFlag(ENCKeyFlag flag) const {return (m_Flags & flag) != 0;}
SetFlagCNetCacheKey102 void SetFlag(ENCKeyFlag flag) {m_Flags |= (TNCKeyFlags) flag;}
ClearFlagCNetCacheKey103 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
IsValidKeyCNetCacheKey129 static bool IsValidKey(const char* key_str, size_t key_len,
130 CCompoundIDPool::TInstance id_pool = NULL)
131 { return ParseBlobKey(key_str, key_len, NULL, id_pool); }
132
IsValidKeyCNetCacheKey133 static bool IsValidKey(const string& key,
134 CCompoundIDPool::TInstance id_pool = NULL)
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
155 time_t m_CreationTime;
156 Uint4 m_Random;
157
158 // Key extensions
159 string m_ServiceName;
160 TNCKeyFlags m_Flags;
161 };
162
163
164 //////////////////////////////////////////////////////////////////////////
165 // Inline functions
166 //////////////////////////////////////////////////////////////////////////
167
StripKeyExtensions() const168 inline string CNetCacheKey::StripKeyExtensions() const
169 {
170 return m_PrimaryKey;
171 }
172
GetKey() const173 inline const string& CNetCacheKey::GetKey() const
174 {
175 return m_Key;
176 }
177
178 inline unsigned int
GetId(void) const179 CNetCacheKey::GetId(void) const
180 {
181 return m_Id;
182 }
183
184 inline const string&
GetHost(void) const185 CNetCacheKey::GetHost(void) const
186 {
187 return m_Host;
188 }
189
190 inline unsigned short
GetPort(void) const191 CNetCacheKey::GetPort(void) const
192 {
193 return m_Port;
194 }
195
GetHostPortCRC32() const196 inline unsigned CNetCacheKey::GetHostPortCRC32() const
197 {
198 return m_HostPortCRC32;
199 }
200
201 inline unsigned int
GetVersion(void) const202 CNetCacheKey::GetVersion(void) const
203 {
204 return m_Version;
205 }
206
GetCreationTime() const207 inline time_t CNetCacheKey::GetCreationTime() const
208 {
209 return m_CreationTime;
210 }
211
GetRandomPart() const212 inline Uint4 CNetCacheKey::GetRandomPart() const
213 {
214 return m_Random;
215 }
216
GetServiceName() const217 inline const string& CNetCacheKey::GetServiceName() const
218 {
219 return m_ServiceName;
220 }
221
222
223 /* @} */
224
225
226 END_NCBI_SCOPE
227
228 #endif /* CONN___NETCACHE_KEY__HPP */
229