OidHighWriter.h

// OidHighWriter.h
//
// Author David Barrett-Lennard
// (C)opyright Cedanet Pty Ltd 2011

@import "OidSpace.h"
@import "cxPersistStore.h"
#include <set>

/*
OidHighWriter and OidHighReader are intended to be used on the sender/receiver respectively
in order to translate OidHighs on the basis of local mappings between OidSpaceGuid and
OidHigh recorded in a local persistent OidSpaceMap.

Both the OidHighWriter and OidHighReader are state machines that keep track of what guids have
been sent so far - so a guid is sent at most once during the session.

Sending of (OidHigh, OidSpaceGuid) pairs
------------------------------------------

It is not possible for the (OidHigh,OidSpaceGuid) pairs to be sent at the end of the overall 
message.  The problem is that although the receiver can detect a new OidHigh (because it won't 
be found in its OidHigh to OidHigh conversion map), the receiver may need to map the incoming 
OidHigh to a OidHigh that already exists on the receiver, and only the guid allows that to be 
achieved.

Buffering the sender's output is undesirable.  Our solution is to allow for optionally sending
the guid each time a OidHigh is sent.  This is achieved with zero space overhead in the normal
case where no guid is required, and only 1 byte overhead when a guid must be sent, by making use 
of the support for up to 15 escape codes when sending an integer (see VariableLengthSerialise.h).

So we assume a byte 0xFF indicates that the guid will be sent after the OidHigh.

Usage
-----

OidHighWriter implements IItemSerialiser in order to be plugged into an Archive.  From that point 
the Archive will automatically send OidSpaceGuids as required as oids are sent.

    struct IItemSerialiser
    {
        virtual void SerialiseItem(Archive& ar, const void* pItem) = 0;
    };

    class BaseArchiveOut
    {
        ...
    public:
        IItemSerialiser* m_oidHighSerialiser;
    };

Alternatively,  SerialiseOidHigh() and SerialiseOid() can be called directly.
*/

namespace ceda
{
class OidSpaceMap;

///////////////////////////////////////////////////////////////////////////////////////////////////
// OidHighWriter

class @api OidHighWriter : public IItemSerialiser
{
public:
    OidHighWriter(OidSpaceMap* oidSpaceMap);

    void SetOidSpaceMap(OidSpaceMap* oidSpaceMap) { m_oidSpaceMap = oidSpaceMap; }

    void SerialiseOidHigh(Archive& ar, OidHigh oidHigh);
    void SerialiseOid(Archive& ar, OID oid);

    // Implementation of IItemSerialiser
    virtual void SerialiseItem(Archive& ar, const void* pItem);
    
    // For stats about the connection - corresponds to the number of distinct OidHighs that have
    // been sent so far.
    int64 GetNumGuidsSent() const { return m_countSendOidSpaceGuid; }

private:
    OidSpaceMap* m_oidSpaceMap;
    
    // This sender must keep track of the set of OidHighs that have been sent to the remote computer.
    // New ones need to have an (OidHigh,OidSpaceGuid) pair sent to allow the receiver to update its OidHigh 
    // conversion map
    std::set<OidHigh> m_sentOidHighs;
    
    int64 m_countSendOidSpaceGuid;

    @if (CEDA_VALIDATE_OID_READER_WRITER_ORDER)
    {
        int32 m_order;
    }
};

} // namespace ceda