Verwaltete Namespaces

Zusammenfassung

Einführung

Verwaltete Namespaces werden im Weave SDK verwendet, um sowohl Weave SDK-Entwicklern als auch Integratoren beworbene Anleitungen und Untertext zur Kennzeichnung bestimmter API-Sets im SDK zur Verfügung zu stellen. So können sie ihren Migrationspfad zwischen Weave SDK-Releases planen und vorhersagen und möglicherweise mehrere, gleichzeitige Weave APIs für ein bestimmtes Modul verwalten.

Bezeichnung

Verwaltete Namespaces können mit einer von vier Bezeichnungen verwaltet werden:

Entwicklung

Jeder Namespace, der mit der Kennzeichnung „Entwicklung“ verwaltet wird, weist Entwickler und Integratoren darauf hin, dass sich die darin enthaltenen APIs noch in der Entwicklung befinden, Änderungen unterliegen können und nicht offiziell unterstützt werden. In der Regel raten wir Integratoren davon ab, diese APIs zu verwenden, es sei denn, sie werden ausdrücklich dazu aufgefordert.

Weiter

Jeder Namespace, der mit der Kennzeichnung „Next“ verwaltet wird, weist Entwickler und Integratoren darauf hin, dass die enthaltenen APIs – auch wenn die aktive Entwicklung weitgehend abgeschlossen ist – noch Änderungen unterliegen können und für frühe Evaluierungszwecke unterstützt werden. Die so vorgesehenen APIs stellen die nächste Entwicklungsstufe in einer Weave SDK API dar und werden in naher Zukunft in absehbarer Zeit zu den aktuellen Standard-APIs in einem größeren Veröffentlichungszyklus.

Abwärtskompatibilität, sowohl aus der Perspektive von APIs als auch aus Sicht des Over-the-Wire-Protokolls, kann vorhanden sein, wird jedoch in den so festgelegten APIs nicht garantiert.

Die Kennzeichnung des verwalteten „Next“ bietet Entwicklern und Integratoren effektiv einen Überblick darüber, wohin das Weave SDK führt, indem darauf hingewiesen wird, was in einer zukünftigen Version die aktuelle Standard-API wird.

Die Kennzeichnung „Nächster verwalteter Namespace“ ist optional, sodass ein verwalteter Namespace einen Lebenszyklus durchlaufen kann, ohne ihn zu verwenden (siehe Lebenszyklus des verwalteten Namespace).

Aktuell

Jeder Namespace, der mit der Kennzeichnung „Current“ oder einem nicht verwalteten Namespace (d.h. ohne Kennzeichnung eines verwalteten Namespace) verwaltet wird, stellt die aktuelle, offiziell unterstützte API für den entsprechenden Teil oder das Modul des Weave SDK dar. Diese APIs werden zwar kontinuierlich verbessert, doch die Änderungen werden hauptsächlich die inkrementelle und Abwärtskompatibilität betreffen, sowohl API- als auch Over-the-Wire-Verbindungen.

Die Kennzeichnung des aktuellen verwalteten Namespace ist optional, sodass ein verwalteter Namespace einen Lebenszyklus durchlaufen kann, ohne ihn zu verwenden (siehe Lebenszyklus des verwalteten Namespace). Tatsächlich ist jeder nicht verwaltete Namespace implizit aktuell.

Legacy

Jeder Namespace, der mit der Bezeichnung „Legacy“ verwaltet wird, weist Entwickler und Integratoren darauf hin, dass die darin enthaltenen APIs veraltet sind und durch eine neue, aktuelle API ersetzt wurden. Diese APIs repräsentieren das, was früher die aktuelle API war.

Die so vorgesehenen APIs werden mit der nächsten großen Weave SDK-Version vollständig eingestellt. Daher sollten Entwickler und Integratoren Pläne für eine Migration weg von diesen APIs ausarbeiten, wenn sie bei den führenden Weave SDK-Releases bleiben möchten.

Lebenszyklus des verwalteten Namespace

Die folgende Abbildung zeigt den Lebenszyklus eines verwalteten Namespace beim Übergang von der Entwicklungsumgebung und gegebenenfalls zu einem Legacy-Namespace:

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

Falls er verwendet wird, beginnt der Lebenszyklus des verwalteten Namespace mit der Bezeichnung „Entwicklung“.

Wenn die Entwicklung abgeschlossen ist und der Code für die Bewertung und Integration bereit ist, wird die Kennzeichnung zu „Weiter“ oder „Aktuell“ migriert. Alternativ kann die Kennzeichnung vollständig entfernt und der verwaltete Namespace nicht mehr verwendet werden. Dadurch wird die Kennzeichnung implizit aktuell.

Wenn der Code neben dem aktuellen Code enthalten sein soll, aber noch nicht ersetzt werden soll, sollte die Kennzeichnung zu „Weiter“ migriert werden. Wenn der Code aktuellen Code ersetzen soll, sollte die Bezeichnung zu „Current“ migriert werden.

Wenn der Code die gewünschte Anzahl von Release- und Bewertungszyklen durchlaufen hat, wird die Kennzeichnung mit der Kennzeichnung „Next“ in die Rolle „Current“ (Aktuell) migriert oder die Bezeichnung kann vollständig entfernt werden.

Wenn der Code mit der Kennzeichnung „Aktuell“ durch neuen Code ersetzt werden soll, aber noch über mehrere Releasezyklen beibehalten werden muss, wird die Kennzeichnung zu „Legacy“ migriert.

Der Code wird schließlich vollständig aus dem Weave SDK entfernt.

Verwaltete Namespaces verwenden

Weave SDK-Nutzer können mit verwalteten Namespaces interagieren, entweder als Entwickler, um vorhandenen Code zu erweitern und zu pflegen, oder als Integrator, der Weave in ihren eigenen Anwendungs-, Plattform- und Systemcode integriert. In den folgenden zwei Abschnitten finden Sie Empfehlungen für den Umgang mit von Weave verwalteten Namespaces aus diesen beiden Perspektiven.

Verwaltete Namespaces als Entwickler verwenden

Ein Hauptschwerpunkt des Weave SDK-Entwicklers ist die Verbesserung und Entwicklung neuer Weave SDK-APIs und -Funktionen, während in vielen Fällen gleichzeitig vorhandene API- und Funktionsbereitstellungen unterstützt werden.

Wenn es nicht möglich ist, beide Schwerpunkte in rückwärtskompatibler Weise innerhalb derselben API zu erfüllen, bieten verwaltete Namespaces einen Mechanismus zur parallelen Verwaltung dieser APIs, ohne dass bestehende API- und Funktionsbereitstellungen beeinträchtigt werden.

Nehmen wir als Beispiel das Weave-Profil Mercury an, das sich derzeit in der folgenden nicht verwalteten Namespace-Hierarchie befindet:

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

// ...

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

und die folgenden öffentlichen Header:

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

Dabei ist Mercury.hpp das Modul „Regenschirm“. Header. Die meisten Integratoren fügen einfach das Dachmodul Kopfzeile wie hier gezeigt:

#include

Die Entwickler von Mercury haben jedoch einen Punkt erreicht, an dem eine nächste Generation der APIs und möglicherweise auch das Over-the-Wire-Protokoll entwickelt werden muss, das für bestehende Bereitstellungen nicht abwärtskompatibel ist. Mit verwalteten Namespaces können Sie dies erreichen, ohne diese vorhandenen Bereitstellungen zu unterbrechen.

Vorhandenen Namespace in „Aktuell“ verschieben

Damit der aktuelle API-Release und die Funktionalität für vorhandene bereitgestellte Integrationen weiterhin unterstützt werden, besteht die erste Aufgabe darin, den aktuellen Code zu verschieben:

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

Hinweis: Neben dem Verschieben der Dateien sollte der Header auch Guards für die verschobenen Dateien umbenennen und möglicherweise mit '_CURRENT' versehen, da neue Dateien mit ähnlichen Namen an ihrer Position darunter erstellt werden.

Nachdem der Code verschoben wurde, besteht der nächste Schritt darin, den Namespace mit der entsprechenden Bezeichnung, hier „Aktuell“, zu verwalten. Erstellen Sie zuerst einen Header, der den verwalteten Namespace als „Current/MercuryManagedNamespace.hpp“ definiert. Das Erstellen eines solchen Headers ist der Wiederholung und Duplizierung dieses Inhalts in jeder Headerdatei vorzuziehen, wenn mehrere Headerdateien vorhanden sind.

% 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

Fügen Sie diesen Header als Nächstes vor anderen modulspezifischen Einschluss-Anweisungen in die vorhandenen Header ein. Beispiel:

#include 

#include

Kompatibilitätsheader erstellen

Das Verschieben der vorhandenen Header an einen neuen Speicherort und die Verwaltung ihres Namespace allein reicht jedoch nicht aus, um sicherzustellen, dass vorhandene Bereitstellungen ohne Änderungen funktionieren, da sie alle Einschlussanweisungen verwenden, in denen die soeben weiter oben verschobenen Header angegeben sind.

Um dieses Problem zu beheben, müssen Kompatibilitäts-Wrapper-Header mit Namen erstellt werden, die mit denen übereinstimmen, die gerade verschoben wurden.

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

Wenn nur ein aktuell als „Current“ festgelegter verwalteter Namespace erstellt wird, ohne dafür einen „Develop“- oder „Next“-bezogenen verwalteten Namespace zu erstellen, kann der Inhalt dieser Dateien einfach aus einem Header-Include-Guard und einer include-Anweisung bestehen, die den neu verschobenen Header desselben Namens angibt:

#ifndef _WEAVE_MERCURY_BAR_HPP
#define _WEAVE_MERCURY_BAR_HPP

#include 

#endif // _WEAVE_MERCURY_BAR_HPP

Wenn jedoch auch ein von "Development" oder "Next" gekennzeichneter verwalteter Namespace erstellt wird, um neue, inkompatible Entwicklungen zu ermöglichen, muss etwas komplexer erstellt werden.

Wie zuvor wird ein Header für die Konfiguration des verwalteten Namespace erstellt, hier als MercuryManagedNamespace.hpp. Diese Methode ist der Wiederholung und Duplizierung dieses Inhalts in jeder Headerdatei vorzuziehen, wenn mehrere Headerdateien vorhanden sind.

% 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

Beachten Sie, dass die Kennzeichnung des verwalteten Namespace wie gewünscht standardmäßig auf „Aktuell“ gesetzt ist. wenn keine Konfiguration definiert wurde.

Mit diesem Header können die Header der Kompatibilitäts-Wrapper so bearbeitet werden, dass sie Folgendes enthalten:

#include 

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

oder was für den jeweiligen Anwendungsfall der Namespace-Verwaltung geeignet ist.

Entwicklungsinhalte erstellen

Jetzt ist die Infrastruktur eingerichtet, um neben den vorhandenen Funktionen und APIs neue Funktionen und APIs zu entwickeln.

% 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

Wenn ein Modul deutlich einfacher ist als das hier vorgestellte Beispiel und nicht viele Klassen, Quellen, Dateien oder Header enthält, kann dies in derselben Header-Datei erreicht werden, ohne dass Dateien verschoben und mehrere eigenständige Konfigurations- und Kompatibilitäts-Header erstellt werden müssen. Bei diesem komplexen Beispiel sollte es jedoch zu verwalteten Namespace-Lösungen entlang eines Spektrums von komplex bis einfach inspirieren.

Verwaltete Namespaces als Integrator verwenden

Ein Hauptschwerpunkt des Weave SDK-Integrators ist die Einbindung der entsprechenden öffentlichen API-Header des Weave SDK sowie die Integration und Entwicklung von Anwendungen auf Basis dieser Header.

Nehmen wir wieder als Beispiel das Weave-Profil Mercury an, das über als Nächstes, Aktuell und Legacy gekennzeichnete verwaltete Namespaces verfügt, deren öffentliche Header wie folgt strukturiert sind:

  • 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

Dabei ist Mercury.hpp das Modul „Regenschirm“. Header.

Es sei denn, der vorliegende Anwendungsfall motiviert dazu, ein Namespace-verwaltetes Modul in Weave explizit aufzunehmen. Zum Beispiel:

#include

Am besten referenzieren Sie die öffentlichen Header von Weave-Modulen über ihre nicht verwalteten Standardpfade (z.B. Weave/Profiles/Mercury/Mercury.hpp). Auf diese Weise können Sie den Fortschritt der API-Entwicklung verfolgen, ohne die Einschlussanweisungen eines Projekts kontinuierlich zu ändern, während diese APIs den verwalteten Lebenszyklus durchlaufen.

Bei dieser Strategie können Bereitstellungen ihren Code dann mit einer anderen Bezeichnung für einen verwalteten Namespace, z. B. mit der Bezeichnung „Current“, neu ausrichten. Dazu wird die gewünschte Konfiguration im C/C++-Präprozessor angegeben. Dies kann in der Befehlszeile, im Quellcode, in einem Konfigurations- oder Präfixheader erfolgen:

#define WEAVE_CONFIG_MERCURY_NAMESPACE kWeaveManagedNamespace_Current

und verwenden Sie den „Nicht verwaltet“-/„Unqualifiziert“-Include-Pfad:

#include

Wenn und wenn sich die Kennzeichnung des verwalteten Namespace für die Ziel-APIs ändert, z. B. von „Aktuell“ zu „Legacy“, führen Sie einfach ein Retargeting durch, indem Sie die Präprozessordefinition anpassen:

#define WEAVE_CONFIG_MERCURY_NAMESPACE kWeaveManagedNamespace_Legacy