BinaryMessage.h

Go to the documentation of this file.

// Copyright Onix Solutions Limited [OnixS]. All rights reserved.
//
// This software owned by Onix Solutions Limited [OnixS] and is
// protected by copyright law and international copyright treaties.
//
// Access to and use of the software is governed by the terms of the applicable
// OnixS Software Services Agreement (the Agreement) and Customer end user license
// agreements granting a non-assignable, non-transferable and non-exclusive license
// to use the software for it's own data processing purposes under the terms defined
// in the Agreement.
//
// Except as otherwise granted within the terms of the Agreement, copying or
// reproduction of any part of this source code or associated reference material
// to any other location for further reproduction or redistribution, and any
// amendments to this copyright notice, are expressly prohibited.
//
// Any reproduction or redistribution for sale or hiring of the Software not in
// accordance with the terms of the Agreement is a violation of copyright law.
//

#pragma once

#include <cassert>
#include <stdexcept>

#include <OnixS/CME/MDH/Assertion.h>

#include <OnixS/CME/MDH/String.h>
#include <OnixS/CME/MDH/Memory.h>

#include <OnixS/CME/MDH/Composites.h>
#include <OnixS/CME/MDH/SchemaTraits.h>

ONIXS_CMEMDH_NAMESPACE_BEGIN

/// Exposes base services to access fields stored
/// in a SBE-encoded block of fixed-length fields.
///
/// The given class represents an abstraction to be used
/// by descendants as a base class with static polymorphism.
template <class Container, class BlockLength>
class BinaryBlock
{
protected:
    /// Initializes the blank instance.
    BinaryBlock() {}

    /// Ends life of the instance.
    ~BinaryBlock() {}

    /// Returns value of a field by its offset.
    template <class Value>
    Value ordinary(BlockLength offset) const
    {
        const size_t sizeOfValue = sizeof(Value);

        assert((offset + sizeOfValue) <= container().blockLength());

        const void* const location = advanceByBytes(container().block(), offset);

        Value result;

        memcpy(&result, location, sizeOfValue);

        return result;
    }

    /// Provides access to a value of
    /// an optional field by its offset.
    ///
    /// Returned result indicates whether field is
    /// present in given field block and its value
    /// was copied into a given parameter-variable.
    template <class Value, class NullValue>
    bool ordinary(Value& value, BlockLength offset, const NullValue& null) const
    {
        const Value optional = ordinary<Value>(offset);

        if (null != optional)
        {
            value = optional;

            return true;
        }

        return false;
    }

    /// Provides access to a value of
    /// an optional field by its offset.
    ///
    /// Returned result indicates whether field is
    /// present in given field block and its value
    /// was copied into a given parameter-variable.
    ///
    /// Field may not be present in earlier versions
    /// of binary message and thus its value may not be
    /// available. For this reason, parameter indicating
    /// version of data assumed is required to access
    /// the field.
    template <class Value, class NullValue>
    bool ordinary(Value& value, BlockLength offset, const NullValue& null, SchemaVersion since) const
    {
        return (since <= container().version() && ordinary(value, offset, null));
    }

    /// Returns value of a field by its offset.
    ///
    /// Given function serves as specialization of
    /// general case for fields of enumeration type.
    template <class Enumeration>
    typename Enumeration::Enum enumeration(BlockLength offset) const
    {
        typedef typename Enumeration::Base Base;

        typedef typename Enumeration::Enum Enum;

        return static_cast<Enum>(ordinary<Base>(offset));
    }

    /// Provides access to value of
    /// an optional field by its offset.
    ///
    /// Given function serves as specialization of
    /// general case for fields of enumeration type.
    template <class Enumeration, class NullValue>
    bool enumeration(typename Enumeration::Enum& value, BlockLength offset, const NullValue& null) const
    {
        typedef typename Enumeration::Base Base;

        typedef typename Enumeration::Enum Enum;

        const Base optional = ordinary<Base>(offset);

        if (null != optional)
        {
            value = static_cast<Enum>(optional);

            return true;
        }

        return false;
    }

    /// Provides access to value of
    /// an optional field by its offset.
    ///
    /// Given function serves as specialization of
    /// general case for fields of enumeration type.
    template <class Enumeration, class NullValue>
    bool
    enumeration(typename Enumeration::Enum& value, BlockLength offset, const NullValue& null, SchemaVersion since) const
    {
        return (since <= container().version() && enumeration<Enumeration, NullValue>(value, offset, null));
    }

    /// Returns value of a field by its
    /// offset converted into a decimal.
    template <class Value>
    Decimal decimal(BlockLength offset) const
    {
        return Decimal(ordinary<Value>(offset));
    }

    /// Provides access to a value of
    /// an optional field by its offset.
    /// The result is converted into decimal.
    ///
    /// Returned result indicates whether field is
    /// present in given field block and its value
    /// was copied into a given parameter-variable.
    template <class NullValue>
    bool decimal(Decimal& value, BlockLength offset, const NullValue& null) const
    {
        typedef typename NullValue::Value Value;

        const Value optional = ordinary<Value>(offset);

        if (null != optional)
        {
            value = optional;

            return true;
        }

        return false;
    }

    /// Provides access to a value of
    /// an optional field by its offset.
    /// The result is converted into decimal.
    ///
    /// Returned result indicates whether field is
    /// present in given field block and its value
    /// was copied into a given parameter-variable.
    ///
    /// Field may not be present in earlier versions
    /// of binary message and thus its value may not be
    /// available. For this reason, parameter indicating
    /// version of data assumed is required to access
    /// the field.
    template <class NullValue>
    bool decimal(Decimal& value, BlockLength offset, const NullValue& null, SchemaVersion since) const
    {
        return (since <= container().version() && decimal(value, offset, null));
    }

    /// Provides access to string field by its offset.
    ///
    /// Given function serves as specialization
    /// of general case for fields of string type.
    template <BlockLength Length>
    StrRef fixedStr(BlockLength offset) const
    {
        assert((offset + Length) <= container().blockLength());

        const Char* const text = reinterpret_cast<const Char*>(advanceByBytes(container().block(), offset));

        return StrRef(text, strnlen(text, Length));
    }

    /// Provides access to an optional
    /// field of string type by its offset.
    ///
    /// Given function serves as specialization
    /// of general case for fields of string type.
    template <BlockLength Length>
    StrRef fixedStr(BlockLength offset, SchemaVersion since) const
    {
        return (since <= container().version() ? fixedStr<Length>(offset) : StrRef());
    }

private:
    /// The block container providing
    /// actual access to the encoded data.
    const Container& container() const
    {
        return *static_cast<const Container*>(this);
    }

};

/// Throws exception on bad repeating group entry.
ONIXS_CMEMDH_EXPORTED
void throwBadBinaryData(const Char* className);

/// Encapsulates operations over SBE-encoded
/// repeating group entry instance.
template <class Length>
class BinaryGroupEntry : public BinaryBlock<BinaryGroupEntry<Length>, Length>
{
public:
    /// Represents the length of binary data
    /// occupied by the given group entry.
    typedef Length EncodedLength;

    /// Represents the length of binary block storing
    /// fixed-length fields of the group entry.
    typedef Length BlockLength;

    /// Initializes instance referring to nothing.
    BinaryGroupEntry()
        : encoded_(ONIXS_CMEMDH_NULLPTR)
        , length_(0)
        , version_(0)
    {
    }

    /// Initializes instance from memory
    /// block of given SBE-encoded message.
    BinaryGroupEntry(const void* encoded, BlockLength length, SchemaVersion version)
        : encoded_(encoded)
        , length_(length)
        , version_(version)
    {
        assert(ONIXS_CMEMDH_NULLPTR != encoded);

        assert(version >= SchemaTraits::minimalVersion());
    }

    /// Initializes instance as a copy of the other one.
    BinaryGroupEntry(const BinaryGroupEntry& other)
        : encoded_(other.encoded_)
        , length_(other.length_)
        , version_(other.version_)
    {
    }

    /// Indicates whether instance refers to a valid content.
    operator bool() const
    {
        return (ONIXS_CMEMDH_NULLPTR != encoded_);
    }

    /// Pointer to the binary data
    /// referring to the given entry.
    const void* encoded() const
    {
        return encoded_;
    }

    /// Length of the SBE-encoded data
    /// referring to the given entry.
    EncodedLength encodedLength() const
    {
        return length_;
    }

    /// Returns pointer to the block containing
    /// fixed-length fields of the given entry.
    const void* block() const
    {
        return encoded_;
    }

    /// Returns length of the block containing
    /// fixed-length fields of the given entry.
    BlockLength blockLength() const
    {
        return length_;
    }

    /// Version of message containing
    /// given repeating group instance.
    SchemaVersion version() const
    {
        return version_;
    }

    /// Re-initializes instance as a copy of the other one.
    BinaryGroupEntry& operator=(const BinaryGroupEntry& other)
    {
        encoded_ = other.encoded_;
        length_ = other.length_;

        version_ = other.version_;

        return *this;
    }

private:
    const void* encoded_;
    Length length_;

    SchemaVersion version_;
};

/// Encapsulates operations over SBE-encoded repeating group entries.
template <class EntryType, class BlockLength, class NumInGroup, class Length>
class BinaryGroupEntries
{
public:
    /// Represents the length of binary data
    /// occupied by the given group entries.
    typedef Length EncodedLength;

    /// The type of repeating group entry.
    typedef EntryType Entry;

    /// Number of entries in the collection.
    typedef NumInGroup Size;

    /// Provides iterating facilities
    /// over SBE-encoded group entries.
    class Iterator
    {
    public:
        /// Aliases entry for STL conformance.
        typedef const Entry value_type;

        /// Aliases pointer to entry for STL conformance.
        typedef const Entry* pointer;

        /// Aliases entry reference for STL conformance.
        typedef const Entry& reference;

        /// Iterator difference type.
        typedef ptrdiff_t difference_type;

        /// Identifies iterator category.
        typedef std::random_access_iterator_tag iterator_category;

        /// Initializes instance referring to nothing.
        Iterator()
            : encoded_(ONIXS_CMEMDH_NULLPTR)
            , length_(0)
            , version_(0)
        {
        }

        /// Initializes instance for given repeating group.
        Iterator(const void* block, BlockLength length, SchemaVersion version)
            : encoded_(block)
            , length_(length)
            , version_(version)
        {
        }

        /// Initializes instance as copy of the other one.
        Iterator(const Iterator& other)
            : encoded_(other.encoded_)
            , length_(other.length_)
            , version_(other.version_)
        {
        }

        /// Repeating group entry referenced by the instance.
        const Entry get() const
        {
            assert(ONIXS_CMEMDH_NULLPTR != encoded_);

            return Entry(encoded_, length_, version_);
        }

        /// Repeating group block referenced by the iterator.
        const Entry operator*() const
        {
            return get();
        }

        /// Compares the given iterator with the other instance.
        bool operator==(const Iterator& other) const
        {
            return encoded_ == other.encoded_;
        }

        /// Compares the given iterator with the other instance.
        bool operator!=(const Iterator& other) const
        {
            return encoded_ != other.encoded_;
        }

        /// Established order between two iterators.
        bool operator<(const Iterator& other) const
        {
            return encoded_ < other.encoded_;
        }

        /// Established order between two iterators.
        bool operator>(const Iterator& other) const
        {
            return encoded_ > other.encoded_;
        }

        /// Advances instance to the next repeating group entry.
        Iterator& operator++()
        {
            encoded_ = advanceByBytes(encoded_, length_);

            return *this;
        }

        /// Advances instance to the next repeating group entry.
        Iterator& operator--()
        {
            encoded_ = advanceBackByBytes(encoded_, length_);

            return *this;
        }

        /// Advances instance by given number of entries.
        Iterator operator+(difference_type distance) const
        {
            return Iterator(
                advanceByBytes(encoded_, distance * static_cast<difference_type>(length_)), length_, version_
            );
        }

        /// Advances instance by given number of entries.
        Iterator operator-(difference_type distance) const
        {
            return Iterator(
                advanceBackByBytes(encoded_, distance * static_cast<difference_type>(length_)), length_, version_
            );
        }

        /// Re-initializes instance as copy of the other one.
        Iterator& operator=(const Iterator& other)
        {
            encoded_ = other.encoded_;
            length_ = other.length_;
            version_ = other.version_;

            return *this;
        }

    private:
        const void* encoded_;
        BlockLength length_;

        SchemaVersion version_;
    };

    /// Initializes blank instance referencing to nothing.
    BinaryGroupEntries()
        : encoded_(ONIXS_CMEMDH_NULLPTR)
        , blockLength_(0)
        , size_(0)
        , version_(0)
    {
    }

    /// Initializes the instance referencing to a real data.
    BinaryGroupEntries(const void* encoded, BlockLength blockLength, Size groupSize, SchemaVersion version)
        : encoded_(encoded)
        , blockLength_(blockLength)
        , size_(groupSize)
        , version_(version)
    {
    }

    /// Initializes instance as a copy of the other one.
    template <class OtherEntry, class OtherBlockLength, class OtherNumInGroup, class OtherLength>
    BinaryGroupEntries(const BinaryGroupEntries<OtherEntry, OtherBlockLength, OtherNumInGroup, OtherLength>& other)
        : encoded_(other.encoded_)
        , blockLength_(other.blockLength_)
        , size_(other.size_)
        , version_(other.version_)
    {
        // Dimension types may vary for the different
        // instantiations of the template. Therefore,
        // truncation of the dimensions must be avoided.

        assert(blockLength_ == other.blockLength_);

        assert(size_ == other.size_);
    }

    /// Indicates whether given instance
    /// refers to a valid repeating group.
    operator bool() const
    {
        return (ONIXS_CMEMDH_NULLPTR != encoded_);
    }

    /// Indicates whether a repeating
    /// group being referenced is empty.
    bool empty() const
    {
        return (0 == size_);
    }

    /// Returns number of blocks.
    Size size() const
    {
        return size_;
    }

    /// Returns iterator pointing to the first repeating group entry.
    Iterator begin() const
    {
        return Iterator(encoded_, blockLength_, version_);
    }

    /// Returns iterator pointing to the entry behind the end of the group.
    Iterator end() const
    {
        return Iterator(
            advanceByBytes(encoded_, static_cast<ptrdiff_t>(blockLength_) * static_cast<ptrdiff_t>(size_)),
            blockLength_,
            version_
        );
    }

    /// Provides access to the group
    /// entry by its index in the group.
    ///
    /// Index validness is not checked
    /// due to performance considerations.
    const Entry operator[](Size index) const
    {
        assert(index < size_);

        return Entry(
            advanceByBytes(encoded_, static_cast<ptrdiff_t>(blockLength_) * static_cast<ptrdiff_t>(index)),
            blockLength_,
            version_
        );
    }

    /// Binary data occupied by the given group entries.
    const void* encoded() const
    {
        return encoded_;
    }

    /// Length of the binary data occupied
    /// by the given collection of entries.
    EncodedLength encodedLength() const
    {
        return (static_cast<EncodedLength>(blockLength_) * static_cast<EncodedLength>(size_));
    }

    /// Re-initializes instance as copy of the other one.
    /// Initializes instance as a copy of the other one.
    template <class OtherEntry, class OtherBlockLength, class OtherNumInGroup, class OtherLength>
    BinaryGroupEntries&
    operator=(const BinaryGroupEntries<OtherEntry, OtherBlockLength, OtherNumInGroup, OtherLength>& other)
    {
        encoded_ = other.encoded_;

        blockLength_ = other.blockLength_;

        assert(blockLength_ == other.blockLength_);

        size_ = other.size_;

        assert(size_ == other.size_);

        version_ = other.version_;

        return *this;
    }

private:
    // Allows coping and cloning
    // for different instantiations.
    template <class OtherEntry, class OtherBlockLength, class OtherNumInGroup, class OtherLength>
    friend class BinaryGroupEntries;

    // Actual parameters.

    const void* encoded_;

    BlockLength blockLength_;
    NumInGroup size_;

    SchemaVersion version_;
};

/// Throws exception on bad repeating group.
ONIXS_CMEMDH_EXPORTED
void throwBadBinaryGroup();

/// Encapsulates operations over SBE-encoded repeating group.
template <class EntryType, class DimensionType, class LengthType>
class BinaryGroup
{
public:
    /// Binary group dimensions (actual
    /// length, number of entries, etc).
    typedef DimensionType Dimension;

    /// Binary group blocks.
    typedef BinaryGroupEntries<EntryType, typename Dimension::BlockLength, typename Dimension::NumInGroup, LengthType>
        Entries;

    /// Defines type of iterator for group entries.
    typedef typename Entries::Iterator Iterator;

    /// Aliases type of the group entry.
    typedef typename Entries::Entry Entry;

    /// Type representing a number of entries in the group.
    typedef typename Entries::Size Size;

    /// Measures binary length of the group.
    typedef LengthType EncodedLength;

    /// Initializes blank instance referencing to nothing.
    BinaryGroup()
        : header_(ONIXS_CMEMDH_NULLPTR)
    {
    }

    /// Initializes instance referencing
    /// to a valid group of a given message.
    BinaryGroup(const void* encoded, EncodedLength length, SchemaVersion version)
        : header_(static_cast<const Dimension*>(encoded))
    {
        if (length < Dimension::Size)
        {
            throwBadBinaryGroup();
        }
        else
        {
            entries_ = Entries(
                advanceByBytes(header_, Dimension::Size), header_->blockLength(), header_->numInGroup(), version
            );

            if (length < encodedLength())
            {
                throwBadBinaryGroup();
            }
        }
    }

    /// Initializes instance as a copy of the other one.
    BinaryGroup(const BinaryGroup& other)
        : header_(other.header_)
        , entries_(other.entries_)
    {
    }

    /// Indicates whether given instance
    /// refers to a valid repeating group.
    operator bool() const
    {
        return (ONIXS_CMEMDH_NULLPTR != header_);
    }

    /// Indicates whether a repeating
    /// group being referenced is empty.
    bool empty() const
    {
        return (0 == size());
    }

    /// Returns number of entries in a
    /// repeating group being referenced.
    Size size() const
    {
        return entries_.size();
    }

    /// Returns iterator pointing to
    /// the first repeating group entry.
    Iterator begin() const
    {
        return entries_.begin();
    }

    /// Returns iterator pointing to the
    /// entry behind the end of the group.
    Iterator end() const
    {
        return entries_.end();
    }

    /// Provides access to the repeating
    /// group entry by its index in the group.
    ///
    /// Index validness is not checked due
    /// to performance considerations.
    Entry operator[](Size index) const
    {
        return entries_[index];
    }

    /// Location of repeating group entries.
    const Entries& entries() const
    {
        return entries_;
    }

    /// SBE-encoded data representing
    /// the given repeating group.
    const void* encoded() const
    {
        return header_;
    }

    /// Length of the SBE-encoded data
    /// representing the given group.
    EncodedLength encodedLength() const
    {
        return (Dimension::Size + entries_.encodedLength());
    }

    /// Re-initializes instance as copy of the other one.
    BinaryGroup& operator=(const BinaryGroup& other)
    {
        header_ = other.header_;
        entries_ = other.entries_;

        return *this;
    }

private:
    const Dimension* header_;
    Entries entries_;
};

/// Encapsulates services for manipulating SBE-encoded
/// groups stored sequentially in SBE-encoded message.
template <class Length>
class BinaryGroups
{
public:
    /// Represents the length of binary data
    /// occupied by the given list of groups.
    typedef Length EncodedLength;

    /// Initializes empty list.
    BinaryGroups()
        : encoded_(ONIXS_CMEMDH_NULLPTR)
        , length_(0)
        , version_(0)
    {
    }

    /// Initializes list over memory block,
    /// where given message is stored.
    BinaryGroups(const void* encoded, EncodedLength length, SchemaVersion version)
        : encoded_(encoded)
        , length_(length)
        , version_(version)
    {
    }

    /// Initializes as copy of other list.
    BinaryGroups(const BinaryGroups& other)
        : encoded_(other.encoded_)
        , length_(other.length_)
        , version_(other.version_)
    {
    }

    /// Indicates whether group list is empty.
    bool empty() const
    {
        return (0 == length_);
    }

    /// Provides access to the head group of the list.
    template <class Group>
    Group head() const
    {
        return Group(encoded_, length_, version_);
    }

    /// Returns the groups following the head.
    template <class Group>
    BinaryGroups tail() const
    {
        const EncodedLength headLength = head<Group>().encodedLength();

        assert(length_ >= headLength);

        return BinaryGroups(advanceByBytes(encoded_, headLength), length_ - headLength, version_);
    }

    /// SBE-encoded content referenced by the list.
    const void* encoded() const
    {
        return encoded_;
    }

    /// Length of SBE-encoded content
    /// referenced by the given group list.
    EncodedLength encodedLength() const
    {
        return length_;
    }

    /// Re-initializes instance as copy of the other one.
    BinaryGroups& operator=(const BinaryGroups& other)
    {
        encoded_ = other.encoded_;
        length_ = other.length_;

        version_ = other.version_;

        return *this;
    }

private:
    const void* encoded_;

    Length length_;

    SchemaVersion version_;
};

/// Raises exception on bad binary message.
inline void throwBadBinaryMessage()
{
    throw std::runtime_error("Cannot construct message instance. Memory "
                             "block is too small to access SBE message header. ");
}

/// Raises exception on bad message version.
ONIXS_CMEMDH_EXPORTED
void throwBadMessageVersion(const Char*, SchemaVersion, SchemaVersion);

/// Aliases message type (template) identification.
typedef MessageHeader::TemplateId MessageTemplateId;

/// Aliases message length type.
typedef UInt16 MessageSize;

/// Encapsulates services for manipulating SBE-encoded messages.
class ONIXS_CMEMDH_LTWT BinaryMessage : public BinaryBlock<BinaryMessage, MessageSize>
{
public:
    /// Length of message binary data.
    typedef MessageSize EncodedLength;

    /// Length of message body representing
    /// a block of fixed-length fields.
    typedef MessageSize BlockLength;

    /// Repeating groups.
    typedef BinaryGroups<MessageSize> Groups;

    /// Initializes the instance referencing to nothing.
    BinaryMessage()
        : header_(ONIXS_CMEMDH_NULLPTR)
        , length_(0)
    {
    }

    /// Initializes instance over the given encoded data.
    BinaryMessage(const void* encoded, EncodedLength length)
        : header_(static_cast<const MessageHeader*>(encoded))
        , length_(length)
    {
        assert(ONIXS_CMEMDH_NULLPTR != encoded);

        if (length < MessageHeader::Size || length < (MessageHeader::Size + header_->blockLength()))
        {
            throwBadBinaryMessage();
        }
    }

    /// Initializes instance as copy of the other one.
    BinaryMessage(const BinaryMessage& other)
        : header_(other.header_)
        , length_(other.length_)
    {
    }

    /// Indicates whether instance refers to a valid message.
    operator bool() const
    {
        return (ONIXS_CMEMDH_NULLPTR != header_);
    }

    /// Template identifier of message being referenced.
    MessageTemplateId templateId() const
    {
        assert(ONIXS_CMEMDH_NULLPTR != header_);

        return header_->templateId();
    }

    /// Version of message being referenced.
    SchemaVersion version() const
    {
        assert(ONIXS_CMEMDH_NULLPTR != header_);

        return header_->version();
    }

    /// SBE-encoded message content.
    const void* encoded() const
    {
        return header_;
    }

    /// Size of SBE-encoded message.
    EncodedLength encodedLength() const
    {
        return length_;
    }

    /// Indicates beginning of message body.
    const void* block() const
    {
        assert(ONIXS_CMEMDH_NULLPTR != header_);

        return advanceByBytes(header_, MessageHeader::Size);
    }

    /// Length of the message body (
    /// block of fixed-length fields).
    BlockLength blockLength() const
    {
        assert(ONIXS_CMEMDH_NULLPTR != header_);

        return header_->blockLength();
    }

    /// Collection of repeating groups
    /// of the message being referenced.
    Groups groups() const
    {
        assert(ONIXS_CMEMDH_NULLPTR != header_);

        return Groups(
            advanceByBytes(block(), blockLength()),
            length_ - MessageHeader::Size - header_->blockLength(),
            header_->version()
        );
    }

    /// Re-initializes instance as a copy of the other one.
    BinaryMessage& operator=(const BinaryMessage& other)
    {
        header_ = other.header_;
        length_ = other.length_;

        return *this;
    }

private:
    typedef BinaryBlock<BinaryMessage, MessageSize> Base;

    const MessageHeader* header_;
    MessageSize length_;
};

ONIXS_CMEMDH_NAMESPACE_END