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

Go to the SVN repository for this file.

1 #ifndef CONNECT_SERVICES__COMPOUND_ID__HPP
2 #define CONNECT_SERVICES__COMPOUND_ID__HPP
3 
4 /* $Id: compound_id.hpp 84663 2018-11-27 18:22:00Z ucko $
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: Dmitry Kazimirov
30  *
31  * File Description:
32  * Compound IDs are Base64-encoded string that contain application-specific
33  * information to identify and/or locate objects.
34  *
35  */
36 
37 /// @file compound_id.hpp
38 /// Declarations of CCompoundIDPool, CCompoundID, and CCompoundIDField.
39 
40 #include "netcomponent.hpp"
41 
43 
44 struct SCompoundIDPoolImpl; ///< @internal
45 struct SCompoundIDImpl; ///< @internal
46 struct SCompoundIDFieldImpl; ///< @internal
47 
48 
49 // Registered CompoundID Classes
54  eCIC_NetStorageObjectLocV1, ///< Old version of NetStorageObjectLoc
56 
58 };
59 
60 
61 // Compound ID Field Types
63  eCIT_ID, /* 64-bit natural number: counter, ID, size, offset */
64  eCIT_Integer, /* General-purpose 64-bit signed integer */
65  eCIT_ServiceName, /* LBSM service name */
66  eCIT_DatabaseName, /* Database name (NetSchedule queue, cache name, etc) */
67  eCIT_Timestamp, /* POSIX time_t value (time in seconds since Epoch) */
68  eCIT_Random, /* 32-bit random integer */
69  eCIT_IPv4Address, /* 32-bit IPv4 address */
70  eCIT_Host, /* Host name or literal IPv4 or IPv6 address */
71  eCIT_Port, /* 16-bit port number */
72  eCIT_IPv4SockAddr, /* 32-bit IPv4 address followed by 16-bit port number */
73  eCIT_ObjectRef, /* Object or resource: URI (URL, URN), OID, pathname */
74  eCIT_String, /* Arbitrary single-byte character string */
75  eCIT_Boolean, /* Boolean value */
76  eCIT_Flags, /* Combination of binary flags stored as a number */
77  eCIT_Label, /* Application-specific field prefix, tag, label */
78  eCIT_Cue, /* Application-specific numeric field prefix or tag */
79  eCIT_SeqID, /* Sequence identifier (string) */
80  eCIT_TaxID, /* Taxon identifier (unsigned integer) */
81  eCIT_NestedCID, /* Nested CompoundID */
82 
83  eCIT_NumberOfTypes /* Must be the last element of the enumeration. */
84 };
85 
86 
87 /// Exception class for use by CCompoundIDPool, CCompoundID, and
88 /// CCompoundIDField.
89 ///
91 {
92 public:
93  enum EErrCode {
94  eInvalidType, ///< Field type mismatch.
95  eIDTooLong, ///< ID exceeds length restrictions.
96  eInvalidFormat, ///< Format of the packed ID is not recognized.
97  eInvalidDumpSyntax, ///< Dump parsing error.
98  };
99  virtual const char* GetErrCodeString() const override;
101 };
102 
103 class CCompoundID;
104 
105 /// Compound ID field -- an element of the compound ID that
106 /// has a type and a value.
107 ///
109 {
110  NCBI_NET_COMPONENT(CompoundIDField);
111 
112  /// Return the type of this field.
114 
115  /// Return the next immediately adjacent field.
116  CCompoundIDField GetNextNeighbor();
117 
118  /// Return the next field of the same type.
119  CCompoundIDField GetNextHomogeneous();
120 
121  /// Remove this field from the compound ID that contains it.
122  /// This will cause the GetNext*() methods to always return NULL.
123  void Remove();
124 
125  /// Return the ID value that this field contains.
126  /// @throw CCompoundIDException if GetType() != eCIT_ID.
127  Uint8 GetID() const;
128 
129  /// Return the integer value that this field contains.
130  /// @throw CCompoundIDException if GetType() != eCIT_Integer.
131  Int8 GetInteger() const;
132 
133  /// Return the LBSM service name that this field contains.
134  /// @throw CCompoundIDException if GetType() != eCIT_ServiceName.
135  string GetServiceName() const;
136 
137  /// Return the database name that this field contains.
138  /// @throw CCompoundIDException if GetType() != eCIT_DatabaseName.
139  string GetDatabaseName() const;
140 
141  /// Return the UNIX timestamp that this field contains.
142  /// @throw CCompoundIDException if GetType() != eCIT_Timestamp.
143  Int8 GetTimestamp() const;
144 
145  /// Return the random number value that this field contains.
146  /// @throw CCompoundIDException if GetType() != eCIT_Random
147  Uint4 GetRandom() const;
148 
149  /// Return the 32-bit IP address that this field contains.
150  /// @throw CCompoundIDException if GetType() is neither
151  /// eCIT_IPv4Address nor eCIT_IPv4SockAddr.
152  Uint4 GetIPv4Address() const;
153 
154  /// Return the host name or address that this field contains.
155  /// @throw CCompoundIDException if GetType() != eCIT_Host.
156  string GetHost() const;
157 
158  /// Return the network port number that this field contains.
159  /// @throw CCompoundIDException if GetType() is neither
160  /// eCIT_Port nor eCIT_IPv4SockAddr.
161  Uint2 GetPort() const;
162 
163  /// Return the object or resource ID that this field contains.
164  /// @throw CCompoundIDException if GetType() != eCIT_ObjectRef.
165  string GetObjectRef() const;
166 
167  /// Return the string value that this field contains.
168  /// @throw CCompoundIDException if GetType() != eCIT_String.
169  string GetString() const;
170 
171  /// Return the Boolean value that this field contains.
172  /// @throw CCompoundIDException if GetType() != eCIT_Boolean.
173  bool GetBoolean() const;
174 
175  /// Return the combination of binary flags stored in this field.
176  /// @throw CCompoundIDException if GetType() != eCIT_Flags.
177  Uint8 GetFlags() const;
178 
179  /// Return the application-specific tag that this field contains.
180  /// @throw CCompoundIDException if GetType() != eCIT_Label.
181  string GetLabel() const;
182 
183  /// Return the application-specific numeric tag value
184  /// that this field contains.
185  /// @throw CCompoundIDException if GetType() != eCIT_Cue.
186  Uint8 GetCue() const;
187 
188  /// Return the Sequence ID that this field contains.
189  /// @throw CCompoundIDException if GetType() != eCIT_SeqID.
190  string GetSeqID() const;
191 
192  /// Return the Taxonomy ID that this field contains.
193  /// @throw CCompoundIDException if GetType() != eCIT_TaxID.
194  Uint8 GetTaxID() const;
195 
196  /// Return the nested compound ID that this field contains.
197  /// @throw CCompoundIDException if GetType() != eCIT_NestedCID.
198  const CCompoundID& GetNestedCID() const;
199 };
200 
201 
202 /// Base64-encoded ID string that contains extractable typed fields.
203 ///
205 {
206  NCBI_NET_COMPONENT(CompoundID);
207 
208  /// One of the registered ID classes.
209  ECompoundIDClass GetClass() const;
210 
211  /// Return TRUE if this compound ID contains no fields.
212  bool IsEmpty() const;
213 
214  /// Return the number of fields this ID contains.
215  unsigned GetLength() const;
216 
217  /// Return the first field or NULL if this ID is empty.
218  CCompoundIDField GetFirstField();
219 
220  /// Return the first field of the specified type or NULL
221  /// if this compound ID contains no fields of such type.
222  CCompoundIDField GetFirst(ECompoundIDFieldType field_type);
223 
224  /// Append an eCIT_ID field at the end of this compound ID.
225  void AppendID(Uint8 id);
226 
227  /// Append an eCIT_Integer field at the end of this compound ID.
228  void AppendInteger(Int8 number);
229 
230  /// Append an eCIT_ServiceName field at the end of this compound ID.
231  void AppendServiceName(const string& service_name);
232 
233  /// Append an eCIT_DatabaseName field at the end of this compound ID.
234  void AppendDatabaseName(const string& db_name);
235 
236  /// Append an eCIT_Timestamp field at the end of this compound ID.
237  void AppendTimestamp(Int8 timestamp);
238 
239  /// Get the current time and append it as an eCIT_Timestamp field
240  /// at the end of this compound ID.
241  void AppendCurrentTime();
242 
243  /// Append an eCIT_Random field at the end of this compound ID.
244  void AppendRandom(Uint4 random_number);
245 
246  /// Generate a 32-bit pseudo-random number and append it as an
247  /// eCIT_Random field at the end of this compound ID.
248  void AppendRandom();
249 
250  /// Append an eCIT_IPv4Address field at the end of this compound ID.
251  void AppendIPv4Address(Uint4 ipv4_address);
252 
253  /// Append an eCIT_Host field at the end of this compound ID.
254  void AppendHost(const string& host);
255 
256  /// Append an eCIT_Port field at the end of this compound ID.
257  void AppendPort(Uint2 port_number);
258 
259  /// Append an eCIT_IPv4SockAddr field at the end of this compound ID.
260  void AppendIPv4SockAddr(Uint4 ipv4_address, Uint2 port_number);
261 
262  /// Append an eCIT_ObjectRef field at the end of this compound ID.
263  void AppendObjectRef(const string& loc);
264 
265  /// Append an eCIT_String field at the end of this compound ID.
266  void AppendString(const string& string_value);
267 
268  /// Append an eCIT_Boolean field at the end of this compound ID.
269  void AppendBoolean(bool boolean_value);
270 
271  /// Append an eCIT_Flags field at the end of this compound ID.
272  void AppendFlags(Uint8 flags);
273 
274  /// Append an eCIT_Label field at the end of this compound ID.
275  void AppendLabel(const string& tag);
276 
277  /// Append an eCIT_Cue field at the end of this compound ID.
278  void AppendCue(Uint8 tag);
279 
280  /// Append an eCIT_SeqID field at the end of this compound ID.
281  void AppendSeqID(const string& seq_id);
282 
283  /// Append an eCIT_TaxID field at the end of this compound ID.
284  void AppendTaxID(Uint8 tax_id);
285 
286  /// Append an eCIT_NestedCID field at the end of this compound ID.
287  void AppendNestedCID(const CCompoundID& cid);
288 
289  /// Get the field that was added last.
290  CCompoundIDField GetLastField();
291 
292  /// Pack the ID and return its string representation.
293  string ToString();
294 
295  /// Dump the contents of the ID in the human-readable format that
296  /// can also be parsed by CCompoundIDPool::FromDump().
297  string Dump();
298 };
299 
300 
301 /// Pool of recycled CCompoundID objects. On some systems, this pool
302 /// also contains the shared pseudo-random number generator used by
303 /// CCompoundID::AppendRandom().
304 ///
306 {
307  NCBI_NET_COMPONENT_IMPL(CompoundIDPool);
308 
309  /// Construct a new pool of CompoundID objects.
310  CCompoundIDPool();
311 
312  /// Create and return a new CCompoundID objects.
313  CCompoundID NewID(ECompoundIDClass new_id_class);
314 
315  /// Unpack the base64-encoded ID and return a CCompoundID
316  /// object for field extraction.
317  CCompoundID FromString(const string& cid);
318 
319  /// Restore the compound ID from its textual representation
320  /// created by CCompoundID::Dump().
321  CCompoundID FromDump(const string& cid_dump);
322 };
323 
324 
326 
327 #endif /* CONNECT_SERVICES__COMPOUND_ID__HPP */
Exception class for use by CCompoundIDPool, CCompoundID, and CCompoundIDField.
Definition: compound_id.hpp:91
@ eInvalidDumpSyntax
Dump parsing error.
Definition: compound_id.hpp:97
@ eInvalidFormat
Format of the packed ID is not recognized.
Definition: compound_id.hpp:96
@ eIDTooLong
ID exceeds length restrictions.
Definition: compound_id.hpp:95
@ eInvalidType
Field type mismatch.
Definition: compound_id.hpp:94
NCBI_EXCEPTION_DEFAULT(CCompoundIDException, CException)
Compound ID field – an element of the compound ID that has a type and a value.
Pool of recycled CCompoundID objects.
Base64-encoded ID string that contains extractable typed fields.
ECompoundIDFieldType
Definition: compound_id.hpp:62
@ eCIT_Timestamp
Definition: compound_id.hpp:67
@ eCIT_Host
Definition: compound_id.hpp:70
@ eCIT_Cue
Definition: compound_id.hpp:78
@ eCIT_SeqID
Definition: compound_id.hpp:79
@ eCIT_IPv4SockAddr
Definition: compound_id.hpp:72
@ eCIT_Port
Definition: compound_id.hpp:71
@ eCIT_ObjectRef
Definition: compound_id.hpp:73
@ eCIT_String
Definition: compound_id.hpp:74
@ eCIT_Integer
Definition: compound_id.hpp:64
@ eCIT_DatabaseName
Definition: compound_id.hpp:66
@ eCIT_Label
Definition: compound_id.hpp:77
@ eCIT_Random
Definition: compound_id.hpp:68
@ eCIT_Boolean
Definition: compound_id.hpp:75
@ eCIT_ID
Definition: compound_id.hpp:63
@ eCIT_TaxID
Definition: compound_id.hpp:80
@ eCIT_Flags
Definition: compound_id.hpp:76
@ eCIT_IPv4Address
Definition: compound_id.hpp:69
@ eCIT_ServiceName
Definition: compound_id.hpp:65
@ eCIT_NumberOfTypes
Definition: compound_id.hpp:83
@ eCIT_NestedCID
Definition: compound_id.hpp:81
ECompoundIDClass
Definition: compound_id.hpp:50
@ eCIC_NumberOfClasses
Definition: compound_id.hpp:57
@ eCIC_NetScheduleJobKey
Definition: compound_id.hpp:53
@ eCIC_GenericID
Definition: compound_id.hpp:51
@ eCIC_NetCacheBlobKey
Definition: compound_id.hpp:52
@ eCIC_NetStorageObjectLocV1
Old version of NetStorageObjectLoc.
Definition: compound_id.hpp:54
@ eCIC_NetStorageObjectLoc
Definition: compound_id.hpp:55
static uch flags
bool GetSeqID(const CRef< CSeq_align > &seqAlign, CRef< CSeq_id > &SeqID, bool getSlave=true)
Definition: cuAlign.cpp:55
static char * string_value(const struct col_t *pcol)
Definition: dbpivot.c:302
virtual const char * GetType(void) const
Get class name as a string.
Definition: ncbiexpt.cpp:268
const string & GetClass(void) const
Get class name used for reporting.
Definition: ncbiexpt.hpp:1023
virtual const char * GetErrCodeString(void) const
Get error code interpreted as text.
Definition: ncbiexpt.cpp:444
string GetLabel(const CSeq_id &id)
TSeqPos GetLength(const CSeq_id &id, CScope *scope)
Get sequence length if scope not null, else return max possible TSeqPos.
uint32_t Uint4
4-byte (32-bit) unsigned integer
Definition: ncbitype.h:103
uint16_t Uint2
2-byte (16-bit) unsigned integer
Definition: ncbitype.h:101
int64_t Int8
8-byte (64-bit) signed integer
Definition: ncbitype.h:104
uint64_t Uint8
8-byte (64-bit) unsigned integer
Definition: ncbitype.h:105
#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 char * tag
#define NCBI_NET_COMPONENT(component)
#define NCBI_NET_COMPONENT_IMPL(component)
static BOOL number
Definition: pcregrep.c:193
void Dump(CSplitCacheApp *app, const C &obj, ESerialDataFormat format, const string &key, const string &suffix=kEmptyStr)
static bool GetInteger(wxSpinCtrl *spinctrl, int *value)
string ToString(const wxRect &rc)
Definition: wx_utils.cpp:773
Modified on Thu Mar 28 17:10:48 2024 by modify_doxy.py rev. 669887