libbmq  a5f8a06ba1d16cb5a65643e1fa7f1a1d6aadef40
Classes | Namespaces | Functions
bmqt_uri.h File Reference

Provide value-semantic type and utilities for a BlazingMQ queue URI. More...

#include <ball_log.h>
#include <bsl_cstddef.h>
#include <bsl_iosfwd.h>
#include <bsl_string.h>
#include <bslh_hash.h>
#include <bslma_usesbslmaallocator.h>
#include <bslmf_nestedtraitdeclaration.h>

Go to the source code of this file.

Classes

class  BloombergLP::bmqt::Uri
 Value semantic type representing a URI. More...
 
struct  BloombergLP::bmqt::UriParser
 Utility namespace of methods for parsing URI strings into Uri objects. More...
 
class  BloombergLP::bmqt::UriBuilder
 

Namespaces

 BloombergLP
 
 BloombergLP::bmqt
 

Functions

bool BloombergLP::bmqt::operator== (const Uri &lhs, const Uri &rhs)
 
bool BloombergLP::bmqt::operator!= (const Uri &lhs, const Uri &rhs)
 
bool BloombergLP::bmqt::operator< (const Uri &lhs, const Uri &rhs)
 
bsl::ostream & BloombergLP::bmqt::operator<< (bsl::ostream &stream, const Uri &rhs)
 
template<class HASH_ALGORITHM >
void BloombergLP::bmqt::hashAppend (HASH_ALGORITHM &hashAlgo, const Uri &uri)
 

Detailed Description

This component provides a value-semantic type, bmqt::Uri representing a URI for a BlazingMQ queue. A bmqt::Uri can be built by parsing from a string representation, using the bmqt::UriParser, or built using the bmqt::UriBuilder.

See also
https://tools.ietf.org/html/rfc3986

URI format

In a nutshell, a URI representing an application queue managed by a BlazingMQ broker on a given machine looks like one of the following:

bmq://ts.trades.myapp/my.queue
bmq://ts.trades.myapp.~bt/my.queue
bmq://ts.trades.myapp/my.queue?id=foo

where:

  • The URI scheme is always "bmq".
  • The URI authority is the name of BlazingMQ domain (such as "ts.trades.myapp") as registered with the BlazingMQ infrastructure. The domain name may contain alphanumeric characters, dots and dashes (it has to match the following regular expression: [-a-zA-Z0-9\\._]+). The domain may be followed by an optional tier, introduced by the ".~" sequence and consisting of alphanumeric characters and dashes. The ".~" sequence is not part of the tier.
  • The URI path is the name of the queue ("my.queue" above) and may contain alphanumeric characters, dashes, underscores and tild (it has to match the following regular expression: [-a-zA-Z0-9_~\\.]+). The queue name must be less than bmqt::Uri::k_QUEUENAME_MAX_LENGTH characters long.
  • The name of the queue ("my.queue" above) may contain alphanumeric characters and dots.
  • The URI may contain an optional query with a key-value pair. Currently supported keys are:
    • id: the corresponding value represents a name that will be used by BlazingMQ broker to uniquely identify the client.
  • The URI fragment part is currently unused.

Usage Example 1

First, call the initialize method of the bmqt::UriParser. This call is only needed one time; you can call it when your task starts.

Note that the bmq library takes care of that, so users of bmq don't have to explicitly do it themselves.

bmqt::UriParser::initialize();

Then, parse a URI string created on the stack to populate a bmqt::Uri object. The parse function takes an optional error string which is populated with a short error message if the URI is not formatted correctly.

bsl::string input = "bmq://my.domain/queue";
bmqt::Uri uri(allocator);
bsl::string errorDescription;
int rc = bmqt::UriParser::parse(&uri, &errorDescription, input);
if (rc != 0) {
BALL_LOG_ERROR << "Invalid URI [error: " << errorDescription << "]";
}
assert(rc == 0);
assert(error == "");
assert(uri.scheme() == "bmq");
assert(uri.domain() == "my.domain");
assert(uri.queue() == "queue");

Usage Example 2

Instantiate a bmqt::Uri object with a string representation of the URI and an allocator.

bmqt::Uri uri("bmq://my.domain/queue", allocator);
assert(uri.scheme() == "bmq");
assert(uri.domain() == "my.domain");
assert(uri.queue() == "queue");

Thread Safety