APEX_CompatibilityMap.h

Go to the documentation of this file.

/*
 * PROPRIETARY INFORMATION.  This software is proprietary to
 * Side Effects Software Inc., and is not to be reproduced,
 * transmitted, or disclosed in any way without written permission.
 *
 * NAME:        APEX_CompatibilityMap.h (APEX Library, C++)
 *
 * COMMENTS: Implements the compatibility map used by APEX_Registry.
 *           The map stores name changes, as well as various update
 *           actions to make limited backwards compatible changes to a type
 *           (without needing to create a new incremented namespace version).
 *           It shares some similarities to the internal versioning of HDAs,
 *           with the update actions playing the role of the SyncNodeVersion
 *           script.
 */

#ifndef __APEX_COMPATIBILITYMAP_H__
#define __APEX_COMPATIBILITYMAP_H__

#include "APEX_API.h"
#include "APEX_Callback.h"

#include <UT/UT_Array.h>
#include <UT/UT_Assert.h>
#include <UT/UT_ErrorManager.h>
#include <UT/UT_StringHolder.h>
#include <UT/UT_UniquePtr.h>
#include <SYS/SYS_Types.h>

class UT_IStream;
class UT_StringArray;

namespace apex
{

class APEX_Graph;


/// APEX_CompatibilityMap tracks backwards compatible transformations to
/// callback and subgraph node types.
///
/// The map is stored in json format with the following schema:
///
/// "oldname" : {
///     "remap" : ["newname", "oldname start version", "newname start version"],
///     "updates" : {
///         "product version string": [
///           [ "renameport", "old[in]", "new" ],
///           [ "renameport", "mesh[out]", "geo" ],
///           [ "insertport", "name[in]", 2 ],
///           [ "moveport",   "success[out]", -1 ]
///         ],
///         "21.0.20": [
///           [ "insertport", "value[in]", 2 ]
///         ]
///     }
/// }
///
/// Users do not need to provide the "update" or "remap" entries if it is not
/// applicable to their type.
///
class APEX_API APEX_CompatibilityMap
{
public:
    APEX_CompatibilityMap();
    ~APEX_CompatibilityMap();

    /// Loads the json representation of the compatibility map.
    bool load(UT_IStream &is);
    bool load(const char *filepath);

    /// Returns the current name associated with @a name at @a version.
    /// When @a name is not found in the compatibility map, the empty string is
    /// returned. When @a version is null, the current name is always returned.
    /// In most scenarios, this function should be called with a null @a
    /// version argument in order to find the current name of the node. The
    /// version is useful for tracking the history of a name for the purpose of
    /// creating a set of candidate nodes at a particular version (e.g. deciding
    /// which namespace versioned nodes existed at a particular product version
    /// so that their precedence order can be reconstructed at that version).
    /// When version is "", it is interpreted as version "0".
    const UT_StringHolder &findName(
            const UT_StringRef &name,
            const char *version = nullptr) const;

    /// Returns the keys of the compatibility map which were current node types
    /// at @a version. If a version is not provided, then all keys are returned.
    /// When version is "", it is interpreted as version "0".
    UT_StringArray getKeys(const char *version = nullptr) const;

    class CompatibilityResolver;

    /// Creates a Resolver which builds a mapping from the type definition
    /// of @a name at @a version to its current type @a nodetype. If @a version
    /// is an empty string, then it is assumed to be the original version and
    /// all compatibility entries are used.
    template <typename NodeTypeT>
    UT_UniquePtr<CompatibilityResolver> createCompatibilityResolver(
            const UT_StringRef &name,
            const UT_StringRef &version,
            const NodeTypeT &nodetype) const;

private:
    class Impl;
    UT_UniquePtr<Impl> myImpl;
};

/// A CompatibilityResolver builds the mapping between an old type
/// definition and a new type definition based on the updates recorded in a
/// compatibility map.
class APEX_API APEX_CompatibilityMap::CompatibilityResolver
{
public:
    const UT_StringHolder &oldName() const { return myOldName; }
    const UT_StringHolder &newName() const { return myNewName; }

    const APEX_Signature &oldSignature() const { return myOldSig; }
    const APEX_Signature &newSignature() const { return myNewSig; }

    exint numInputs() const { return myInputMap.size(); };
    exint numOutputs() const { return myOutputMap.size(); };

    /// @name InputPortMappings
    /// Functions to map input ports from the old signature to the new
    /// signature.
    /// @{
    exint inputIndex(exint old_index) const;
    exint inputIndex(const UT_StringRef &old_name) const;
    const UT_StringHolder &inputName(exint old_index) const;
    const UT_StringHolder &inputName(const UT_StringRef &old_name) const;
    /// @}

    /// @name OutputPortMappings
    /// Functions to map output ports from the old signature to the new
    /// signature.
    /// @{
    exint outputIndex(exint old_index) const;
    exint outputIndex(const UT_StringRef &old_name) const;
    const UT_StringHolder &outputName(exint old_index) const;
    const UT_StringHolder &outputName(const UT_StringRef &old_name) const;
    /// @}

    /// Returns false if the resolver encountered an error. Errors can be
    /// retrieved with errorManager().
    bool isValid() const { return myIsValid; }

    /// Returns the error manager.
    UT_ErrorManager &errorManager() { return myErrMgr; }

private:
    struct PassKey{};

public:
    CompatibilityResolver(
              const UT_StringRef &name,
              const UT_StringRef &version,
              const APEX_FunctionBase &callback,
              const APEX_CompatibilityMap &map,
              const PassKey &);

    CompatibilityResolver(
            const UT_StringRef &name,
            const UT_StringRef &version,
            const APEX_Graph &subgraph,
            const APEX_CompatibilityMap &map,
            const PassKey &);

private:
    friend class APEX_CompatibilityMap;

    bool resolve(
            const UT_StringRef &name,
            const UT_StringRef &version,
            const UT_StringRef &min_version,
            const APEX_CompatibilityMap &map);

    bool myIsValid = true;
    UT_StringHolder myOldName;
    UT_StringHolder myNewName;
    APEX_Signature  myOldSig;
    APEX_Signature  myNewSig;
    UT_Array<exint> myInputMap;
    UT_Array<exint> myOutputMap;
    UT_ErrorManager myErrMgr;
};


//
// APEX_CompatibilityMap
//
template <typename NodeTypeT>
UT_UniquePtr<APEX_CompatibilityMap::CompatibilityResolver>
APEX_CompatibilityMap::createCompatibilityResolver(
        const UT_StringRef &name,
        const UT_StringRef &version,
        const NodeTypeT &nodetype) const
{
    return UTmakeUnique<CompatibilityResolver>(
            name, version, nodetype, *this, CompatibilityResolver::PassKey());
}

//
// APEX_CompatibilityMap::CompatibilityResolver
//
inline exint
APEX_CompatibilityMap::CompatibilityResolver::inputIndex(exint old_index) const
{
    UT_ASSERT(myIsValid);
    UT_ASSERT(old_index >= 0 && old_index < myInputMap.size());
    return myInputMap[old_index];
}

inline exint
APEX_CompatibilityMap::CompatibilityResolver::inputIndex(
        const UT_StringRef &old_name) const
{
    const exint old_index = myOldSig.findInputIndex(old_name);
    return inputIndex(old_index);
}

inline const UT_StringHolder &
APEX_CompatibilityMap::CompatibilityResolver::inputName(exint old_index) const
{
    const exint new_index = inputIndex(old_index);
    return myNewSig.myInputs[new_index].name();
}

inline const UT_StringHolder &
APEX_CompatibilityMap::CompatibilityResolver::inputName(
        const UT_StringRef &old_name) const
{
    const exint new_index = inputIndex(old_name);
    return myNewSig.myInputs[new_index].name();
}

inline exint
APEX_CompatibilityMap::CompatibilityResolver::outputIndex(
        exint old_index) const
{
    UT_ASSERT(myIsValid);
    UT_ASSERT(old_index >= 0 && old_index < myOutputMap.size());
    return myOutputMap[old_index];
}

inline exint
APEX_CompatibilityMap::CompatibilityResolver::outputIndex(
        const UT_StringRef &old_name) const
{
    const exint old_index = myOldSig.findOutputIndex(old_name);
    return outputIndex(old_index);
}

inline const UT_StringHolder &
APEX_CompatibilityMap::CompatibilityResolver::outputName(exint old_index) const
{
    const exint new_index = outputIndex(old_index);
    return myNewSig.myOutputs[new_index].name();
}

inline const UT_StringHolder &
APEX_CompatibilityMap::CompatibilityResolver::outputName(
        const UT_StringRef &old_name) const
{
    const exint new_index = outputIndex(old_name);
    return myNewSig.myOutputs[new_index].name();
}

} // namespace apex

#endif //__APEX_COMPATIBILITYMAP_H__