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/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 
/// SBE-encoded block of memory. Class represents an 
/// abstraction, instance construction available through 
/// descendants implementing actual access to encoded data. 
template
<
    class Block,
    class BlockSize
>
class BinaryFields
{
    /// Instance of block providing 
    /// actual access to encoded data.
    const Block& block() const
    {
        return *static_cast<const Block*>(this);
    }

protected:
    /// Initializes blank instance.
    BinaryFields()
    {
    }

    /// Cleans everything up.
    ~BinaryFields()
    {
    }

    /// Returns value of a field by its offset. 
    template
    <
        class FieldValue
    >
    const 
    FieldValue&
    ordinary(
        BlockSize offset) const
    {
        assert(
            block().bodySize() >=
            (offset + sizeof(FieldValue)));

        const void* 
        const fieldValue = 
            advanceByBytes(
                block().body(),
                offset);

        return 
            *static_cast
             <const FieldValue*>
             (fieldValue);
    }

    /// 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 FieldValue,
        class NullValue
    >
    bool 
    ordinary(
        FieldValue& value,
        BlockSize offset,
        const NullValue& null) const
    {
        const FieldValue& fieldValue = 
            ordinary<FieldValue>(offset);

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

            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 FieldValue,
        class NullValue
    >
    bool 
    ordinary(
        FieldValue& value,
        BlockSize offset,
        const NullValue& null,
        SchemaVersion since) const
    {
        return (
            since <= block().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(
        BlockSize 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, 
        BlockSize offset,
        const NullValue& null) const
    {
        typedef 
        typename 
        Enumeration::Base
        Base;

        typedef 
        typename 
        Enumeration::Enum
        Enum;

        const Base& fieldValue = 
            ordinary<Base>(offset);

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

            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, 
        BlockSize offset,
        const NullValue& null, 
        SchemaVersion since) const
    {
        return (
            since <= block().version()
            && 
            enumeration(value, offset, null)
        );
    }

    /// Returns value of a field by its 
    /// offset converted into a decimal. 
    template
    <
        class FieldValue
    >
    Decimal
    decimal(
        BlockSize offset) const
    {
        return Decimal
        (
            ordinary
            <FieldValue>
            (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,
        BlockSize offset,
        const NullValue& null) const
    {
        typedef 
        typename 
        NullValue::Value 
        FieldValue;

        const FieldValue& fieldValue = 
            ordinary<FieldValue>(offset);

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

            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,
        BlockSize offset,
        const NullValue& null,
        SchemaVersion since) const
    {
        return (
            since <= block().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
    <
        BlockSize Size
    >
    StrRef
    fixedStr(
        BlockSize offset) const
    {
        typedef Char Str[Size];

        const Str& str = 
            ordinary<Str>(offset);

        return 
            StrRef
            (
                str, 
                strnlen(str, Size)
            );
    }

    /// 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
    <
        BlockSize Size
    >
    StrRef
    fixedStr(
        BlockSize offset,
        SchemaVersion since) const
    {
        return (
            since >= 
            block().version()
            
            ? fixedStr<Size>(offset)
            : StrRef()
        );
    }
};

/// 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 BodySizeType
>
class 
BinaryGroupEntry 
: public BinaryFields
<
    BinaryGroupEntry
    <
        BodySizeType
    >,
    BodySizeType
>
{
    const void* body_;
    BodySizeType size_;

    SchemaVersion version_;

public:
    /// Type to present length of binary 
    /// data of given repeating group entry. 
    typedef 
    BodySizeType 
    BodySize;

    /// Initializes instance referring to nothing. 
    BinaryGroupEntry()
      : body_(NULL)
      , size_(0)
      , version_(0)
    {
    }

    /// Initializes instance from memory 
    /// block of given SBE-encoded message.
    BinaryGroupEntry(
        const void* body, 
        BodySize size,
        SchemaVersion version)
        : body_(body)
        , size_(size)
        , version_(version)
    {
        assert(NULL != body);

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

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

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

    /// Indicates beginning of group entry body. 
    const void* body() const
    {
        return body_;
    }

    /// Indicates end of group entry body. 
    BodySize bodySize() const
    {
        return size_;
    }

    /// 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)
    {
        body_ = other.body_;
        size_ = other.size_;

        version_ = other.version_;

        return *this;
    }
};

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

/// Encapsulates operations over SBE-encoded repeating group. 
template
<
    class EntryType,
    class DimensionType,
    class GroupSizeType
>
class BinaryGroup
{
public:
    /// Aliases type of repeating group entry.
    typedef EntryType Entry;

    /// Aliases repeating group dimension type. 
    typedef DimensionType Dimension;

    /// Length of group data.
    typedef GroupSizeType BinarySize;

    /// Length of group entry data. 
    typedef
    typename 
    DimensionType::BlockLength 
    EntrySize;


    /// Size of group (number of entries). 
    typedef 
    typename
    Dimension::NumInGroup
    Size;

    /// Provides iterating facilities 
    /// over SBE-encoded group entries. 
    class Iterator
    {
        const void* entry_;
        EntrySize size_;
        
        SchemaVersion version_;

    public:
        /// Aliases type of object referenced by iterator. 
        typedef EntryType Entry;

        /// 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()
          : entry_(NULL)
          , size_(0)
          , version_(0)
        {
        }

        /// Initializes instance for given repeating group.
        Iterator(
            const void* entry,
            EntrySize size,
            SchemaVersion version)
            : entry_(entry)
            , size_(size)
            , version_(version)
        {
        }

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

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

            return 
                Entry(
                    entry_, 
                    size_,
                    version_);
        }

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

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

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

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

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

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

            return *this;
        }

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

            return *this;
        }

        /// Advances instance by given number of entries. 
        Iterator 
        operator +(
            difference_type distance) const
        {
            return 
                Iterator(
                    advanceByBytes(
                        entry_, 
                        distance * size_),
                    size_,
                    version_);
        }

        /// Advances instance by given number of entries. 
        Iterator 
        operator -(
            difference_type distance) const
        {
            return 
                Iterator(
                    advanceBackByBytes(
                        entry_, 
                        distance * size_),
                    size_,
                    version_);
        }

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

            version_ = other.version_;

            return *this;
        }
    };

    /// Initializes blank instance referencing to nothing. 
    BinaryGroup()
      : entries_(NULL)
      , entrySize_(0)
      , entryCount_(0)
      , version_(0)
      , size_(0)
    {
    }

    /// Initializes instance referencing 
    /// to a valid group of a given message. 
    BinaryGroup(
        const void* data, 
        BinarySize size,
        SchemaVersion version)
        : entries_(
            advanceByBytes(
                data, 
                Dimension::Size))
        , entrySize_(0)
        , entryCount_(0)
        , version_(version)
        , size_(Dimension::Size)
    {
        if (size < size_)
            throwBadBinaryGroup();

        const 
        Dimension* 
        group = 
            static_cast
            <const Dimension*>
            (data);

        entrySize_ = 
            group->blockLength();

        entryCount_ = 
            group->numInGroup();

        size_ += 
            (
                static_cast
                <BinarySize>
                (entrySize_) * 
                static_cast
                <BinarySize>
                (entryCount_)
            );

        if (size < size_)
            throwBadBinaryGroup();
    }

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

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

    /// 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 entryCount_;
    }

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

    /// Returns iterator pointing to the entry behind the end of the group. 
    Iterator end() const
    {
        return 
            Iterator(
                advanceByBytes(
                    binary(), 
                    binarySize()),
                entrySize_,
                version_);
    }

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

        return 
            Entry(
                advanceByBytes(
                    entries(),
                    index * entrySize_), 
                entrySize_,
                version_);
    }

    /// SBE-encoded data representing repeating group.
    const void* binary() const
    {
        return 
            entries_ 
            ? advanceBackByBytes(
                entries_, Dimension::Size) 
            : NULL;
    }

    /// Size of SBE-encoded data representing repeating group. 
    BinarySize binarySize() const
    {
        return size_;
    }

    /// Location of repeating group entries.
    const void* entries() const
    {
        return entries_;
    }

    /// Size in bytes of single repeating group entry. 
    EntrySize entrySize() const
    {
        return entrySize_;
    }

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

        entrySize_ = other.entrySize_;
        entryCount_ = other.entryCount_;

        version_ = other.version_;
        size_ = other.size_;

        return *this;
    }

private:
    const void* entries_;

    EntrySize entrySize_;
    Size entryCount_;

    SchemaVersion version_;
    BinarySize size_;
};

/// Encapsulates services for manipulating SBE-encoded 
/// groups stored sequentially in SBE-encoded message.
template
<
    class BinarySize
>
class BinaryGroupList
{
    const void* binary_;
    BinarySize size_;
    SchemaVersion version_;

public:
    /// Initializes empty list. 
    BinaryGroupList()
      : binary_(NULL)
      , size_(0)
      , version_(0)
    {
    }

    /// Initializes list over memory block,
    /// where given message is stored.
    BinaryGroupList(
        const void* binary, 
        BinarySize size,
        SchemaVersion version)
        : binary_(binary)
        , size_(size)
        , version_(version)
    {
    }

    /// Initializes as copy of other list. 
    BinaryGroupList(
        const BinaryGroupList& other)
        : binary_(
            other.binary_)
        , size_(
            other.size_)
        , version_(
            other.version_)
    {
    }

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

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

    /// Returns list of groups following the head. 
    template
    <
        class Group
    >
    BinaryGroupList tail() const
    {
        const 
        BinarySize 
        headSize = 
            head<Group>().
                binarySize();

        assert(headSize <= size_);

        return 
            BinaryGroupList(
                advanceByBytes(
                    binary_, headSize), 
                size_ - headSize,
                version_);
    }

    /// SBE-encoded content referenced by given list. 
    const void* binary() const
    {
        return binary_;
    }

    /// Size of SBE-encoded content referenced by the list. 
    BinarySize binarySize() const
    {
        return size_;
    }

    /// Re-initializes instance as copy of the other one. 
    BinaryGroupList&
    operator =(
        const BinaryGroupList& other)
    {
        binary_ = other.binary_;
        size_ = other.size_;

        version_ = other.version_;

        return *this;
    }
};

/// 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(
    SchemaVersion messageVersion);

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

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

/// Encapsulates services for manipulating SBE-encoded messages.
ONIXS_CMEMDH_LTWT_CLASS 
BinaryMessage 
: public BinaryFields
<
    BinaryMessage,
    MessageSize
>
{
    const MessageHeader* header_;
    MessageSize size_;

protected:
    /// Binary group list instantiation.
    typedef 
    BinaryGroupList<MessageSize>
    GroupList;

    /// Returns list of repeating groups 
    /// of a message being referenced.
    GroupList groups() const
    {
        assert(NULL != header_);

        const void* 
        const list = 
            advanceByBytes(
                body(), bodySize());

        const 
        MessageSize 
        listSize = 
            size_ - 
            MessageHeader::Size - 
            header_->blockLength();

        return 
            GroupList(
                list, 
                listSize, 
                header_->version());
    }

public:
    /// Length of message binary data. 
    typedef MessageSize BinarySize;

    /// Length of message body without repeating groups. 
    typedef 
    MessageHeader::BlockLength 
    BodySize;

    /// Initializes blank instance referencing to nothing. 
    BinaryMessage()
      : header_(NULL)
      , size_(0)
    {
    }

    /// Initializes instance over given memory block.
    BinaryMessage(
        const void* data, 
        MessageSize size)
        : header_(
            static_cast
            <const MessageHeader*>
            (data))
        , size_(size)
    {
        assert(NULL != data);

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

        const 
        SchemaVersion 
        version = this->version();

        if (version <
            SchemaTraits::minimalVersion())
        {
            throwBadMessageVersion(version);
        }
    }

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

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

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

        return header_->templateId();
    }

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

        return header_->version();
    }

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

    /// Size of SBE-encoded message. 
    MessageSize binarySize() const
    {
        return size_;
    }

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

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

    /// Size of message body in bytes. 
    BodySize bodySize() const
    {
        assert(NULL != header_);

        return header_->blockLength();
    }

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

        return *this;
    }
};

ONIXS_CMEMDH_NAMESPACE_END