baltzo_zoneinfocache.h

Go to the documentation of this file.

/// @file baltzo_zoneinfocache.h
///
/// The content of this file has been pre-processed for Doxygen.
///
 
 
// baltzo_zoneinfocache.h                                             -*-C++-*-
#ifndef INCLUDED_BALTZO_ZONEINFOCACHE
#define INCLUDED_BALTZO_ZONEINFOCACHE
 
#include <bsls_ident.h>
BSLS_IDENT("$Id: $")
 
/// @defgroup baltzo_zoneinfocache baltzo_zoneinfocache
/// @brief  Provide a cache for time-zone information.
/// @addtogroup bal
/// @{
/// @addtogroup baltzo
/// @{
/// @addtogroup baltzo_zoneinfocache
/// @{
///
/// <h1> Outline </h1>
/// * <a href="#baltzo_zoneinfocache-purpose"> Purpose</a>
/// * <a href="#baltzo_zoneinfocache-classes"> Classes </a>
/// * <a href="#baltzo_zoneinfocache-description"> Description </a>
///   * <a href="#baltzo_zoneinfocache-thread-safety"> Thread Safety </a>
///   * <a href="#baltzo_zoneinfocache-usage"> Usage </a>
///     * <a href="#baltzo_zoneinfocache-example-1-creating-a-concrete-baltzo-loader"> Example 1: Creating a Concrete baltzo::Loader </a>
///     * <a href="#baltzo_zoneinfocache-example-2-creating-and-using-a-baltzo-zoneinfocache"> Example 2: Creating and Using a baltzo::ZoneinfoCache </a>
///
/// # Purpose {#baltzo_zoneinfocache-purpose}
/// Provide a cache for time-zone information.
///
/// # Classes {#baltzo_zoneinfocache-classes}
///
/// -  baltzo::ZoneinfoCache: a cache for time-zone information
///
/// @see  baltzo_zoneinfo, baltzo_defaultzoneinfocache
///
/// # Description {#baltzo_zoneinfocache-description}
/// This component defines a class, `baltzo::ZoneinfoCache`, that
/// serves as a cache of `baltzo::Zoneinfo` objects.  A time-zone cache is
/// supplied, on construction, with a `baltzo::Loader` object to obtain
/// time-zone information objects from some data source.  Invocation of the
/// `getZoneinfo` method for a specified time zone returns the address of either
/// previously cached data, or if that data is not cache-resident, a new loaded
/// `baltzo::Zoneinfo` object, which is cached for use in subsequent calls to
/// `getZoneinfo` and `lookupZoneinfo`.  Addresses returned by either of these
/// methods are valid for the lifetime of the cache.
///
/// ## Thread Safety {#baltzo_zoneinfocache-thread-safety}
///
///
/// `baltzo::ZoneinfoCache` is fully *thread-safe*, meaning that all non-creator
/// operations on an object can be safely invoked simultaneously from multiple
/// threads.
///
/// ## Usage {#baltzo_zoneinfocache-usage}
///
///
/// In this section, we demonstrate creating a `baltzo::ZoneinfoCache` object
/// and using it to access time zone information.
///
/// ### Example 1: Creating a Concrete baltzo::Loader {#baltzo_zoneinfocache-example-1-creating-a-concrete-baltzo-loader}
///
///
/// A `baltzo::ZoneinfoCache` object is provided a `baltzo::Loader` on
/// construction.  The `loader` is used to populate the cache per user requests
/// via the `getZoneinfo` method.  In this example, we use a `TestLoader`
/// implementation of the `baltzo::Loader` protocol, based on the
/// @ref baltzo_testloader  component.  In this example, our test loader is
/// explicitly primed with responses for requests for certain time-zone
/// identifiers.  Note that, in practice, a `loader` typically obtains time-zone
/// information from some external data store (e.g., see
/// @ref baltzo_datafileloader ).
///
/// We start by creating and initializing a couple of example time zone
/// information objects.  Note that the `baltzo::Zoneinfo` objects below are
/// illustrative, and contain no actual time zone information:
/// @code
/// baltzo::Zoneinfo newYorkZoneinfo;
/// newYorkZoneinfo.setIdentifier("America/New_York");
///
/// baltzo::Zoneinfo londonZoneinfo;
/// londonZoneinfo.setIdentifier("Europe/London");
/// @endcode
/// Next we create a description of Eastern Standard Time (EST) and Greenwich
/// Mean Time (GMT):
/// @code
/// baltzo::LocalTimeDescriptor est(-5 * 60 * 60, false, "EST");
/// baltzo::LocalTimeDescriptor gmt(           0, false, "GMT");
/// @endcode
/// Then we set the initial transition for `newYorkZoneinfo` to Eastern Standard
/// Time, and the initial transition for `londonZoneinfo` to Greenwich Mean
/// Time.  Note that such an initial transition is required for a
/// `baltzo::Zoneinfo` object to be considered Well-Formed (see `isWellFormed`):
/// @code
/// bsls::Types::Int64 firstTime = bdlt::EpochUtil::convertToTimeT64(
///                                                   bdlt::Datetime(1, 1, 1));
/// newYorkZoneinfo.addTransition(firstTime, est);
/// londonZoneinfo.addTransition(firstTime, gmt);
/// @endcode
/// Next we create a `TestLoader`, and then populate it with our example time
/// zone information objects:
/// @code
/// TestLoader testLoader;
/// testLoader.setTimeZone(newYorkZoneinfo);
/// testLoader.setTimeZone(londonZoneinfo);
/// @endcode
/// Finally, we verify that `testLoader` contains the configured
/// `baltzo::Zoneinfo` objects for New York and London:
/// @code
/// baltzo::Zoneinfo newYorkResult;
/// int rc = testLoader.loadTimeZone(&newYorkResult, "America/New_York");
/// assert(0 == rc);
/// assert(newYorkZoneinfo == newYorkResult);
///
/// baltzo::Zoneinfo londonResult;
/// rc = testLoader.loadTimeZone(&londonResult, "Europe/London");
/// assert(0 == rc);
/// assert(londonZoneinfo == londonResult);
/// @endcode
///
/// ### Example 2: Creating and Using a baltzo::ZoneinfoCache {#baltzo_zoneinfocache-example-2-creating-and-using-a-baltzo-zoneinfocache}
///
///
/// In this example, we create a `baltzo::ZoneinfoCache`, and use it to access
/// time zone information for several time zones.
///
/// We start by creating a `baltzo::ZoneinfoCache` object supplied with the
/// address of the `TestLoader` we populated in the preceding example:
/// @code
/// baltzo::ZoneinfoCache cache(&testLoader);
/// @endcode
/// Next, we verify the newly constructed cache does not contain either New York
/// or London:
/// @code
/// assert(0 == cache.lookupZoneinfo("America/New_York"));
/// assert(0 == cache.lookupZoneinfo("Europe/London"));
/// @endcode
/// Then, we call `getZoneinfo` to obtain the data for the New York time zone.
/// Note that, because this is the first `getZoneinfo` operation on the class,
/// the time-zone data has not previously been retrieved, and the data must be
/// loaded using the loader supplied at construction:
/// @code
/// const baltzo::Zoneinfo *newYork = cache.getZoneinfo(&rc,
///                                                     "America/New_York");
///
/// assert(0 == rc);
/// assert(0 != newYork);
/// assert("America/New_York" == newYork->identifier());
/// @endcode
/// Next, we verify that a subsequent call `lookupZoneinfo` for New York,
/// returns the previously cached value.  However, a call to `lookupZoneinfo`
/// for London will return 0 because the value has not been cached:
/// @code
/// assert(newYork == cache.lookupZoneinfo("America/New_York"));
/// assert(0       == cache.lookupZoneinfo("Europe/London"));
/// @endcode
/// Next, we call `getZoneinfo` for London and verify that it returns the
/// expected value:
/// @code
/// const baltzo::Zoneinfo *london = cache.getZoneinfo(&rc, "Europe/London");
/// assert(0 == rc);
/// assert(0 != london);
/// assert("Europe/London" == london->identifier());
/// @endcode
/// Finally, we call `getZoneinfo` with time zone identifier unknown to our
/// `TestLoader`.  The call to `getZoneinfo` returns 0 because the time zone
/// information cannot be loaded.  Examination of `rc` shows indicates that the
/// identifier is not supported:
/// @code
/// assert(0 == cache.getZoneinfo(&rc, "badId"));
/// assert(baltzo::ErrorCode::k_UNSUPPORTED_ID == rc);
/// @endcode
/// @}
/** @} */
/** @} */
 
/** @addtogroup bal
 * @{
 */
/** @addtogroup baltzo
 * @{
 */
/** @addtogroup baltzo_zoneinfocache
 * @{
 */
 
#include <balscm_version.h>
 
#include <baltzo_loader.h>
#include <baltzo_zoneinfo.h>
 
#include <bdlb_cstringless.h>
 
#include <bslma_bslallocator.h>
#include <bslma_usesbslmaallocator.h>
 
#include <bslmf_nestedtraitdeclaration.h>
 
#include <bslmt_rwmutex.h>
 
#include <bsls_assert.h>
#include <bsls_atomic.h>
#include <bsls_review.h>
 
#include <bsl_map.h>
 
 
namespace baltzo {
 
                            // ===================
                            // class ZoneinfoCache
                            // ===================
 
/// This class provides an efficient mechanism for retrieving information
/// about a given time zone.  The first time a client requests information
/// for some time-zone identifier, that information is loaded (using the
/// `Loader` supplied at construction), returned to the client (via a
/// `const` pointer value), and cached for future use.  Subsequent requests
/// for the same time-zone return the cached information.  The returned
/// values are valid for the lifetime of this object.
///
/// This class:
/// * is *exception-neutral*
/// * is *fully* *thread-safe*
/// For terminology see @ref bsldoc_glossary .
///
/// See @ref baltzo_zoneinfocache 
class ZoneinfoCache {
 
  public:
    // TYPES
    typedef bsl::allocator<char> allocator_type;
 
  private:
    // PRIVATE TYPES
    typedef bsl::map<const char *, Zoneinfo *, bdlb::CStringLess> ZoneinfoMap;
 
    // DATA
    ZoneinfoMap             d_cache;      // cached time-zone info, indexed by
                                          // time-zone id
 
    Loader                 *d_loader_p;   // loader used to obtain time-zone
                                          // information (held, not owned)
 
    mutable bslmt::RWMutex  d_lock;       // cache access synchronization
 
    allocator_type          d_allocator;  // allocator used to supply memory
 
  private:
    // NOT IMPLEMENTED
    ZoneinfoCache(const ZoneinfoCache&);
    ZoneinfoCache& operator=(const ZoneinfoCache&);
 
  public:
    // TRAITS
    BSLMF_NESTED_TRAIT_DECLARATION(ZoneinfoCache,
                                   bslma::UsesBslmaAllocator);
 
    // CREATORS
 
    /// Create an empty cache of time-zone information that will use the
    /// specified `loader` to populate the cache, as-needed, with time zone
    /// information.  Optionally specify an `allocator` (e.g., the address
    /// of a `bslma::Allocator` object) to supply memory; otherwise, the
    /// default allocator is used.  In order the populate the cache for a
    /// time zone identifier, `loader` must return a `Zoneinfo` object that
    /// is well-formed (see `ZoneinfoUtil::isWellFormed`) and whose
    /// `identifier` matches the supplied time zone identifier.
    explicit ZoneinfoCache(
                          Loader                *loader,
                          const allocator_type&  allocator = allocator_type());
 
    /// Destroy this object.
    ~ZoneinfoCache();
 
    // MANIPULATORS
 
    /// Return the address of the non-modifiable `Zoneinfo` object
    /// describing the time zone identified by the specified `timeZoneId`,
    /// or 0 if the operation does not succeed.  If the information for
    /// `timeZoneId` has not been previously cached, then attempt to
    /// populate this object using the `loader` supplied at construction.
    /// Optionally specify the address of an integer, `rc`, in which to load
    /// the return code for this operation.  If `rc` is specified, load 0
    /// into `rc` if the operation succeeds, `ErrorCode::k_UNSUPPORTED_ID`
    /// if the time-zone identifier is not supported, and a negative value
    /// if the operation does not succeed for any other reason.  If the
    /// returned address is non-zero, the Zoneinfo object returned is
    /// guaranteed to be well-formed (i.e., `ZoneinfoUtil::isWellFormed`
    /// will return `true` if called with the returned value), and remain valid for the lifetime of this object.  
    /// 
    /// \pre The behavior is undefined   if
    /// `rc` is 0.
    const Zoneinfo *getZoneinfo(const char *timeZoneId);
    const Zoneinfo *getZoneinfo(int *rc, const char *timeZoneId);
 
    // ACCESSORS
 
    /// Return the address of the non-modifiable cached description of the
    /// time zone identified by the specified `timeZoneId`, and 0 if
    /// information for `timeZoneId` has not previously been cached (by a
    /// call to `getZoneinfo`).  If the returned address is non-zero, the
    /// Zoneinfo object returned is guaranteed to be well-formed (i.e.,
    /// `ZoneinfoUtil::isWellFormed will return `true' if called with the
    /// returned value), and remain valid for the lifetime of this object.
    const Zoneinfo *lookupZoneinfo(const char *timeZoneId) const;
 
    /// Return the allocator used by this object to supply memory.  
    /// 
    /// \note Note that   if no allocator was supplied at construction the default
    /// allocator in effect at construction is used.
    allocator_type get_allocator() const;
};
 
// ============================================================================
//                            INLINE DEFINITIONS
// ============================================================================
 
                            // -------------------
                            // class ZoneinfoCache
                            // -------------------
 
// CREATORS
inline
ZoneinfoCache::ZoneinfoCache(Loader *loader, const allocator_type&  allocator)
: d_cache(allocator)
, d_loader_p(loader)
, d_allocator(allocator)
{
    BSLS_ASSERT(0 != loader);
}
 
// MANIPULATORS
inline
const Zoneinfo *ZoneinfoCache::getZoneinfo(const char *timeZoneId)
{
    BSLS_ASSERT(0 != timeZoneId);
 
    int rc;
    return getZoneinfo(&rc, timeZoneId);
}
 
inline
ZoneinfoCache::allocator_type ZoneinfoCache::get_allocator() const
{
    return d_allocator;
}
 
}  // close package namespace
 
 
#endif
 
// ----------------------------------------------------------------------------
// Copyright 2020 Bloomberg Finance L.P.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
// ----------------------------- END-OF-FILE ----------------------------------
 
/** @} */
/** @} */
/** @} */