Cette page a été traduite par l'API Cloud Translation.

Espaces de noms gérés

Résumé

Introduction

Les espaces de noms gérés sont utilisés dans le SDK Weave pour fournir aux développeurs et aux intégrateurs du SDK Weave des conseils et du texte annoncés sur la désignation d'ensembles d'API particuliers dans le SDK. Ils peuvent ainsi planifier et prédire leur chemin de migration entre les versions du SDK Weave et, éventuellement, gérer plusieurs API Weave simultanées pour un module donné.

Désignation

Les espaces de noms gérés peuvent être gérés selon l'une des quatre désignations suivantes:

Développement

Tout espace de noms géré avec la désignation "Développement" indique aux développeurs et aux intégrateurs que les API qu'il contient sont en cours de développement, sont susceptibles d'être modifiées et ne sont pas officiellement compatibles. Les intégrateurs sont généralement déconseillés à l'utilisation de ces API, sauf indication contraire expresse.

Tout espace de noms géré avec la désignation Next indique aux développeurs et aux intégrateurs que les API qu'ils contiennent sont presque entièrement actives, mais qu'elles peuvent encore être modifiées et faire l'objet d'une évaluation préliminaire. Les API ainsi désignées représentent le prochain front d'évolution d'une API SDK Weave et deviendront les API par défaut actuelles lors d'un cycle de versions majeur dans un avenir proche ou immédiat.

La rétrocompatibilité, tant du point de vue de l'API que du point de vue du protocole over-the-wire, peut exister, mais elle n'est pas garantie dans les API ainsi désignées.

La désignation de l'espace de noms géré Next permet aux développeurs et aux intégrateurs de savoir où en est le SDK Weave en leur indiquant ce qui deviendra l'API par défaut actuelle dans une prochaine version.

La désignation "Espace de noms géré suivant" est facultative, de sorte qu'un espace de noms géré puisse passer par un cycle de vie sans l'utiliser (voir Cycle de vie d'un espace de noms géré).

Actuel

Tout espace de noms géré avec la désignation "Current" ou tout espace de noms non géré (c'est-à-dire sans désignation d'espace de noms géré) représente l'API officielle actuelle, par défaut et compatible avec cette partie ou ce module du SDK Weave. Même si des améliorations peuvent encore être apportées à ces API, les modifications porteront principalement sur l'incrémentalité et la rétrocompatibilité, à la fois pour les API et pour le service filaire.

La désignation de l'espace de noms géré actuel est facultative, de sorte qu'un espace de noms géré peut passer par un cycle de vie sans l'utiliser (voir Cycle de vie d'un espace de noms géré). En fait, tout espace de noms non géré est implicitement Current.

Ancien

Tout espace de noms géré avec la désignation "Legacy" indique aux développeurs et aux intégrateurs que les API qu'il contient sont obsolètes et ont été remplacées par une nouvelle API actuelle. Ces API représentent l'ancienne API actuelle.

Les API ainsi désignées disparaîtront complètement lors de la prochaine version majeure du SDK Weave. Par conséquent, les développeurs et les intégrateurs doivent planifier la migration de ces API s'ils ont l'intention de rester à la pointe des versions du SDK Weave.

Cycle de vie des espaces de noms gérés

La figure suivante illustre le cycle de vie d'un espace de noms géré lors du passage du mode "Développement" à l'ancien espace de noms:

.-------------.      .- - - .      .- - - - -.      .--------.
| Development | -.->   Next   -.->   Current   ---> | Legacy |
'-------------'  |   '- - - '  |   ' - - - - '      '--------'
                 |             |
                 '-------------'

S'il est utilisé, le cycle de vie de l'espace de noms géré commence par la désignation "Développement".

Lorsque le développement est terminé et que le code est prêt pour l'évaluation et l'intégration, la désignation passe à "Next" (Suivant) ou "Current" (En cours). La désignation peut aussi être complètement supprimée et l'espace de noms géré n'est plus utilisé, ce qui rend la désignation implicitement actuelle.

Si le code doit coïncider avec le code actuel sans le supplanter, la désignation doit migrer vers Next. Si le code doit supplanter le code actuel, la désignation doit migrer vers Current.

Avec la désignation Next, une fois que le code a passé le nombre souhaité de cycles de publication et d'évaluation, la désignation est migrée vers la désignation actuelle ou, là encore, la désignation peut être complètement supprimée.

Avec la désignation "Current", si le code doit être remplacé par un nouveau code, mais qu'il doit tout de même être conservé pendant plusieurs cycles de publication, la désignation est migrée vers l'ancien code.

À partir de l'ancienne désignation, le code est à terme complètement supprimé du SDK Weave.

Utiliser des espaces de noms gérés

Les utilisateurs du SDK Weave peuvent interagir avec les espaces de noms gérés soit en tant que développeurs, étendant et gérez du code existant, soit en tant qu'intégrateur, en intégrant Weave à leur propre application, leur propre plate-forme et leur propre code système. Les deux sections suivantes fournissent des recommandations pour traiter les espaces de noms gérés par Weave selon ces deux perspectives.

Utiliser des espaces de noms gérés en tant que développeur

L'un des principaux objectifs du développeur du SDK Weave est d'améliorer et de développer de nouvelles API et fonctionnalités du SDK Weave tout en prenant en charge, dans de nombreux cas, les déploiements d'API et de fonctionnalités existants.

Lorsqu'il n'est pas possible de satisfaire ces deux domaines d'intérêt de manière rétrocompatible au sein de la même API, les espaces de noms gérés fournissent un mécanisme permettant de gérer ces API en parallèle, sans perturber les déploiements d'API et de fonctionnalités existants.

Prenons l'exemple concret d'un profil Weave, Mercury, qui existe actuellement dans la hiérarchie d'espaces de noms non gérée suivante:

namespace nl {
namespace Weave {
namespace Profiles {
namespace Mercury {

// ...

}; // namespace Mercury
}; // namespace Profiles
}; // namespace Weave
}; // namespace nl

et les en-têtes publics suivants:

Weave/Profiles/Mercury/Mercury.hpp
Weave/Profiles/Mercury/Bar.hpp
Weave/Profiles/Mercury/Foo.hpp
Weave/Profiles/Mercury/Foobar.hpp

où Mercury.hpp est le module "umbrella" en-tête. La plupart des intégrateurs n'incluent que le module "parapluie" comme indiqué ci-dessous:

#include

Toutefois, le développement de Mercury a atteint un stade où il est nécessaire de développer une nouvelle génération d'API et, éventuellement, le protocole Over The Wire qui ne sont pas rétrocompatibles avec les déploiements existants. L'utilisation d'espaces de noms gérés peut vous aider à y parvenir sans interrompre les déploiements existants.

Déplacer l'espace de noms existant vers l'espace de noms actuel

Afin de continuer à prendre en charge la version actuelle de l'API et les fonctionnalités pour les intégrations déployées existantes, la première tâche consiste à déplacer le code actuel:

% cd src/lib/profiles/mercury
% mkdir Current
% mv Mercury.hpp Bar.hpp Foo.hpp Foobar.hpp *.cpp Current/

Notez qu'en plus de déplacer les fichiers, les protections d'inclusion d'en-tête pour les fichiers déplacés doivent également être renommées, en les décorant éventuellement avec "_CURRENT", car les nouveaux fichiers portant le même nom seront créés à leur place en dessous.

Une fois le code déplacé, l'étape suivante consiste à gérer l'espace de noms avec la désignation appropriée, ici "Current". Commencez par créer un en-tête qui définit l'espace de noms géré, "Current/MercuryManagedNamespace.hpp". La création d'un tel en-tête est préférable à la répétition et à la duplication de ce contenu dans chaque fichier d'en-tête lorsqu'il existe plusieurs fichiers d'en-tête.

% cat << EOF > Current/MercuryManagedNamespace.hpp
#ifndef _WEAVE_MERCURY_MANAGEDNAMESPACE_CURRENT_HPP
#define _WEAVE_MERCURY_MANAGEDNAMESPACE_CURRENT_HPP

#include <Weave/Support/ManagedNamespace.hpp>

#if defined(WEAVE_CONFIG_MERCURY_NAMESPACE) && WEAVE_CONFIG_MERCURY_NAMESPACE != kWeaveManagedNamespace_Current
#error Compiling Weave Mercury current-designation managed namespace file with WEAVE_CONFIG_MERCURY_NAMESPACE defined != kWeaveManagedNamespace_Current
#endif

#ifndef WEAVE_CONFIG_MERCURY_NAMESPACE
#define WEAVE_CONFIG_MERCURY_NAMESPACE kWeaveManagedNamespace_Current
#endif

namespace nl {
namespace Weave {
namespace Profiles {

namespace WeaveMakeManagedNamespaceIdentifier(Mercury, kWeaveManagedNamespaceDesignation_Current) { };

namespace Mercury = WeaveMakeManagedNamespaceIdentifier(Mercury, kWeaveManagedNamespaceDesignation_Current);

}; // namespace Profiles
}; // namespace Weave
}; // namespace nl

#endif // _WEAVE_MERCURY_MANAGEDNAMESPACE_CURRENT_HPP
EOF

Ensuite, incluez cet en-tête avant les autres instructions d'inclusion spécifiques au module dans les en-têtes existants. Exemple :

#include 

#include

Créer des en-têtes de compatibilité

Toutefois, le fait de déplacer les en-têtes existants vers un nouvel emplacement et de ne gérer que leur espace de noms ne suffit pas à garantir le bon fonctionnement des déploiements existants. En effet, ils utilisent tous des instructions include spécifiant les en-têtes que vous venez de déplacer.

Pour résoudre ce problème, vous devez créer des en-têtes de wrapper de compatibilité dont les noms correspondent à ceux que vous venez de déplacer.

% touch Mercury.hpp Bar.hpp Foo.hpp Foobar.hpp

Si seul un espace de noms géré désigné par "Current" est créé sans créer d'espace de noms géré "Development" ou "Next" pour l'accompagner, le contenu de ces fichiers peut simplement être constitué d'un en-tête include Guard et d'une directive d'inclusion spécifiant l'en-tête du même nom récemment déplacé:

#ifndef _WEAVE_MERCURY_BAR_HPP
#define _WEAVE_MERCURY_BAR_HPP

#include 

#endif // _WEAVE_MERCURY_BAR_HPP

Toutefois, si un espace de noms géré désigné "Development" ou "Next" est également créé pour permettre un nouveau développement incompatible, une action un peu plus complexe doit être effectuée.

Comme précédemment, un en-tête est créé pour la configuration de l'espace de noms géré, ici MercuryManagedNamespace.hpp. Encore une fois, il est préférable de répéter et de dupliquer ce contenu dans chaque fichier d'en-tête lorsqu'il y en a plusieurs.

% cat << EOF > MercuryManagedNamespace.hpp
#ifndef _WEAVE_MERCURY_MANAGEDNAMESPACE_HPP
#define _WEAVE_MERCURY_MANAGEDNAMESPACE_HPP

#include <Weave/Support/ManagedNamespace.hpp>

#if defined(WEAVE_CONFIG_MERCURY_NAMESPACE)                             \
  && (WEAVE_CONFIG_MERCURY_NAMESPACE != kWeaveManagedNamespace_Current) \
  && (WEAVE_CONFIG_MERCURY_NAMESPACE != kWeaveManagedNamespace_Development)
#error "WEAVE_CONFIG_MERCURY_NAMESPACE defined, but not as namespace kWeaveManagedNamespace_Current or kWeaveManagedNamespace_Development"
#endif

#if !defined(WEAVE_CONFIG_MERCURY_NAMESPACE)
#define WEAVE_CONFIG_MERCURY_NAMESPACE kWeaveManagedNamespace_Current
#endif

#endif // _WEAVE_MERCURY_MANAGEDNAMESPACE_HPP
EOF

Notez que la désignation de l'espace de noms géré est définie par défaut sur "Actuel". si aucune configuration n'a été définie.

Une fois cet en-tête en place, les en-têtes du wrapper de compatibilité peuvent désormais être modifiés pour contenir les éléments suivants:

#include 

#if WEAVE_CONFIG_MERCURY_NAMESPACE == kWeaveManagedNamespace_Development
#include 
#else
#include 
#endif // WEAVE_CONFIG_MERCURY_NAMESPACE == kWeaveManagedNamespace_Development

ou tout ce qui est approprié pour le cas d'utilisation de gestion des espaces de noms.

Créer du contenu de développement

À ce stade, l'infrastructure est maintenant en place pour commencer à développer de nouvelles fonctionnalités et API en plus des API existantes.

% mkdir Development
% touch Development/Mercury.hpp Development/Bar.hpp Development/Foo.hpp Development/Foobar.hpp
% cat << EOF > Development/MercuryManagedNamespace.hpp
#ifndef _WEAVE_MERCURY_MANAGEDNAMESPACE_DEVELOPMENT_HPP
#define _WEAVE_MERCURY_MANAGEDNAMESPACE_DEVELOPMENT_HPP

#include <Weave/Support/ManagedNamespace.hpp>

#if defined(WEAVE_CONFIG_MERCURY_NAMESPACE) && WEAVE_CONFIG_MERCURY_NAMESPACE != kWeaveManagedNamespace_Development
#error Compiling Weave Mercury development-designated managed namespace file with WEAVE_CONFIG_MERCURY_NAMESPACE defined != kWeaveManagedNamespace_Development
#endif

#ifndef WEAVE_CONFIG_MERCURY_NAMESPACE
#define WEAVE_CONFIG_MERCURY_NAMESPACE kWeaveManagedNamespace_Development
#endif

namespace nl {
namespace Weave {
namespace Profiles {

namespace WeaveMakeManagedNamespaceIdentifier(Mercury, kWeaveManagedNamespaceDesignation_Development) { };

namespace Mercury = WeaveMakeManagedNamespaceIdentifier(Mercury, kWeaveManagedNamespaceDesignation_Development);

}; // namespace Profiles
}; // namespace Weave
}; // namespace nl

#endif // _WEAVE_MERCURY_MANAGEDNAMESPACE_DEVELOPMENT_HPP
EOF

Bien entendu, si un module est beaucoup plus simple que l'exemple présenté ici et qu'il ne comporte pas beaucoup de classes, sources, fichiers ou en-têtes, vous pouvez le faire dans le même fichier d'en-tête sans avoir à déplacer les fichiers ni à créer plusieurs en-têtes de configuration et de compatibilité autonomes. Toutefois, cet exemple complexe devrait inspirer des solutions d'espaces de noms gérées, allant du plus complexe au plus simple.

Utiliser des espaces de noms gérés en tant qu'intégrateur

L'un des objectifs clés de l'intégrateur du SDK Weave est d'inclure les en-têtes d'API publiques du SDK Weave appropriés, ainsi que d'intégrer et de développer des applications en conséquence.

À titre d'exemple fonctionnel, supposons à nouveau un profil Weave, Mercury, qui comporte des espaces de noms gérés désignés comme "Next", "Current" et "Legacy", dont les en-têtes publics sont structurés comme suit:

Weave/Profiles/Mercury/Mercury.hpp
Weave/Profiles/Mercury/Bar.hpp
Weave/Profiles/Mercury/Foo.hpp
Weave/Profiles/Mercury/Foobar.hpp
Weave/Profiles/Mercury/Next/Mercury.hpp
Weave/Profiles/Mercury/Next/Bar.hpp
Weave/Profiles/Mercury/Next/Foo.hpp
Weave/Profiles/Mercury/Next/Foobar.hpp
Weave/Profiles/Mercury/Current/Mercury.hpp
Weave/Profiles/Mercury/Current/Bar.hpp
Weave/Profiles/Mercury/Current/Foo.hpp
Weave/Profiles/Mercury/Current/Foobar.hpp
Weave/Profiles/Mercury/Legacy/Mercury.hpp
Weave/Profiles/Mercury/Legacy/Bar.hpp
Weave/Profiles/Mercury/Legacy/Foo.hpp
Weave/Profiles/Mercury/Legacy/Foobar.hpp

où Mercury.hpp est le module "umbrella" en-tête.

À moins que le cas d'utilisation concerné ne justifie explicitement l'inclusion d'un module géré d'espace de noms dans Weave, par exemple:

#include

il est préférable de référencer les en-têtes publics de module Weave par leur chemin par défaut non géré (par exemple, Weave/Profiles/Mercury/Mercury.hpp). Cela permet de suivre une progression du développement des API sans modifier continuellement les instructions d'inclusion d'un projet au fur et à mesure que ces API circulent dans le cycle de vie géré.

En suivant cette stratégie, les déploiements peuvent recibler leur code sur une autre désignation d'espace de noms géré, par exemple la désignation "Current", en spécifiant la configuration souhaitée dans le préprocesseur C/C++. Cette opération peut être effectuée sur la ligne de commande, dans le code source, ou dans un en-tête de configuration ou de préfixe:

#define WEAVE_CONFIG_MERCURY_NAMESPACE kWeaveManagedNamespace_Current

et utilisez le chemin d'accès include non géré / non qualifié:

#include

Si la désignation de l'espace de noms géré change pour les API ciblées (par exemple, de Current à Legacy), il vous suffit de recibler l'espace de noms en ajustant la définition du préprocesseur:

#define WEAVE_CONFIG_MERCURY_NAMESPACE kWeaveManagedNamespace_Legacy