Zarządzane przestrzenie nazw

Podsumowanie

Wstęp

Zarządzane przestrzenie nazw są używane w pakiecie SDK Weave. Zarówno deweloperzy, jak i integratorzy pakietu Weave SDK dostarczają reklamowanych wskazówek i tekstu na temat oznaczania określonych zbiorów interfejsów API w pakiecie SDK. Dzięki temu mogą planować i przewidywać ścieżkę migracji w różnych wersjach pakietu SDK Weave, a także zarządzać wieloma równoczesnymi interfejsami API Weave dla danego modułu.

Wyznaczenie

Zarządzanymi przestrzeniami nazw można zarządzać na 4 sposoby:

• Dla programistów
• Dalej
• Bieżący
• Starsza wersja

Programowanie

Każda przestrzeń nazw zarządzana przy użyciu oznaczenia Programowanie jest wskazówką dla programistów i integratorów, że zawarte w nich interfejsy API są w trakcie opracowywania, mogą ulec zmianie i nie są oficjalnie obsługiwane. Integratorom zwykle odradzamy korzystanie z tych interfejsów API, chyba że są do tego wyraźnie przeznaczone.

Dalej

Każda przestrzeń nazw zarządzana z oznaczeniem Next jest wskazówką dla deweloperów i integratorów, że zawarte w nich interfejsy API są w dużej mierze ukończone w fazie aktywnego rozwoju, ale mogą nadal podlegać zmianom i mogą być obsługiwane na potrzeby wczesnej oceny. Tak oznaczone interfejsy API stanowią następny etap ewolucji w interfejsie API Weave SDK i w najbliższej przyszłości staną się obecnymi domyślnymi interfejsami API w najbliższej przyszłości.

Zgodność wsteczna, zarówno z perspektywy interfejsu API, jak i protokołu Over-The-wire, może istnieć, ale nie jest gwarantowana przez tak wyznaczone interfejsy API.

Oznaczenie Next zarządzanej przestrzeni nazw w praktyce zapewnia deweloperom i integratorom podpowiedź, w jaki sposób powinien kierować pakiet SDK Weave, wskazując, jaki będzie obecny, domyślny interfejs API w kolejnej wersji.

Oznaczenie nowej zarządzanej przestrzeni nazw jest opcjonalne, dlatego zarządzana przestrzeń nazw może przechodzić przez cykl życia bez jej używania (zobacz Cykl życia zarządzanej przestrzeni nazw).

Bieżące

Przestrzeń nazw zarządzana przy użyciu bieżącego oznaczenia lub dowolnej niezarządzanej przestrzeni nazw (np. bez oznaczenia zarządzanej przestrzeni nazw) reprezentuje bieżący, domyślny, oficjalny obsługiwany interfejs API dla danej części lub modułu pakietu SDK Weave. Chociaż wciąż możemy ulepszać te interfejsy API, zmiany będą w dużej mierze obejmować przyrostową i wcześniejszą zgodność. Należy zachować zarówno interfejs API, jak i sieć przewodową.

Oznaczenie bieżącej zarządzanej przestrzeni nazw jest opcjonalne – dlatego zarządzana przestrzeń nazw może zostać przeniesiona przez cykl życia bez jej używania (zobacz Cykl życia zarządzanej przestrzeni nazw). W rzeczywistości każda niezarządzana przestrzeń nazw jest domyślnie ustawiona jako Bieżąca.

Starsza

Każda przestrzeń nazw zarządzana ze starszym oznaczeniem jest wskazówką dla deweloperów i integratorów, że zawarte w nich interfejsy API zostały wycofane i zastąpione nowym, aktualnym interfejsem API. Te interfejsy API reprezentują dawniej obecny interfejs API.

Tak oznaczone interfejsy API zostaną całkowicie wycofane w kolejnej głównej wersji pakietu SDK Weave. W związku z tym deweloperzy i integratorzy powinni opracować plany migracji z tych interfejsów, jeśli zamierzają pozostać na czele wersji pakietów SDK Weave.

Cykl życia zarządzanej przestrzeni nazw

Poniższy rysunek przedstawia cykl życia zarządzanej przestrzeni nazw podczas jej przechodzenia z wersji deweloperskiej i potencjalnie do starszej wersji:

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

Jeśli jest on używany, cykl życia zarządzanej przestrzeni nazw zaczyna się od oznaczenia Programowanie.

Gdy programowanie zostanie ukończone, a kod będzie gotowy do oceny i integracji, oznaczenie zostanie przeniesione na wartość Dalej lub Bieżący. Oznaczenie może też zostać całkowicie usunięte, a zarządzana przestrzeń nazw nie jest już używana. W rezultacie oznaczenie to będzie domyślnie oznaczone jako Aktualne.

Jeśli kod ma działać równolegle do bieżącego kodu, ale nie ma go jeszcze zastępować, oznaczenie powinno zostać przeniesione do sekcji Next (Dalej). Jeśli kod ma zastąpić obecny kod, oznaczenie powinno zostać przeniesione do bieżącego.

W przypadku oznaczenia Next, gdy kod osiągnie pożądaną liczbę wersji i cykli oceny, oznaczenie zostanie przeniesione do kategorii „Bieżące” lub też oznaczenie może zostać całkowicie usunięte.

Jeśli używasz oznaczenia Bieżące, jeśli chcesz zastąpić kod nowym kodem, ale nadal musisz go zachować przez większą liczbę cykli wydania, oznaczenie zostanie przeniesione do starszej wersji.

Zgodnie ze starszym oznaczeniem kod jest ostatecznie usuwany z pakietu SDK Weave.

Korzystanie z zarządzanych przestrzeni nazw

Użytkownicy pakietu Weave SDK mogą wchodzić w interakcje z zarządzanymi przestrzeniami nazw jako programiści, rozszerzając i utrzymując kod lub jako integrator, integrując Weave z własną aplikacją, platformą i kodem systemu. W dwóch sekcjach znajdziesz zalecenia dotyczące postępowania z zarządzanymi przestrzeniami nazw Weave z obu tych perspektyw.

Korzystanie z zarządzanych przestrzeni nazw jako deweloper

Programista Weave SDK skupia się głównie na ulepszaniu i rozwijaniu nowych interfejsów API i funkcji pakietu Weave SDK, a jednocześnie w wielu przypadkach zapewnia obsługę istniejących wdrożeń interfejsów API i funkcji.

Gdy nie można zrealizować obu tych obszarów w ramach tego samego interfejsu API w sposób zgodny wstecznie, zarządzane przestrzenie nazw zapewniają mechanizm do równoległego zarządzania tymi interfejsami API w sposób, który nie zakłóca istniejących wdrożeń interfejsów API i funkcji.

Załóżmy na przykład, że masz profil Weave o nazwie Mercury, który obecnie istnieje w tej niezarządzanej hierarchii przestrzeni nazw:

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

// ...

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

oraz następujące publiczne nagłówki:

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

gdzie Mercury.hpp to nagłówek modułu „parasol”. Większość integratorów umieszcza po prostu nagłówek modułu „parasol”, jak w przykładzie:

#include 

Jednak technologia Mercury osiągnęła punkt, w którym konieczne jest opracowanie nowej generacji interfejsów API, a potem również protokołu Over-The-wire, który nie jest zgodny wstecznie z istniejącymi wdrożeniami. Użycie zarządzanych przestrzeni nazw może w tym pomóc bez przerywania istniejących wdrożeń.

Przenieś istniejącą przestrzeń nazw do bieżącej

Jeśli zależy Ci na zapewnieniu ciągłości obsługi bieżącej wersji interfejsu API i jego funkcji w istniejących już wdrożonych integracjach, pierwszym zadaniem jest przeniesienie obecnego kodu:

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

Pamiętaj, że oprócz przeniesienia plików należy też zmienić nazwy osłon w nagłówku, które mogłyby zostać oznaczone jako „_CURRENT”, ponieważ poniżej zostaną utworzone nowe pliki o podobnych nazwach.

Po przeniesieniu kodu następnym krokiem jest zarządzanie przestrzenią nazw za pomocą odpowiedniego oznaczenia, tutaj „Current”. Najpierw utwórz nagłówek definiujący zarządzaną przestrzeń nazw, np. „Current/MercuryManagedNamespace.hpp”. Lepiej utworzyć taki nagłówek niż powtarzanie i powielanie tej treści w każdym pliku nagłówkowym w przypadku wielu plików.

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

#include 

#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

Następnie umieść ten nagłówek przed innymi dyrektywami „include” w istniejących nagłówkach. Na przykład:

#include 

#include 

Utwórz nagłówki zgodności

Samo przeniesienie istniejących nagłówków do nowej lokalizacji i sama przestrzeń nazw nie wystarczy, aby zapewnić, że istniejące wdrożenia będą działać bez zmian, ponieważ we wszystkich będą używane dyrektywy „include”, które zawierają już przeniesione nagłówki.

Aby rozwiązać ten problem, należy utworzyć nagłówki kodu zgodności z nazwami pasującymi do przeniesionych przed chwilą.

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

Jeśli tworzona jest tylko zarządzana przestrzeń nazw aktualnie oznaczona bez tworzenia zarządzanej przestrzeni nazw dla programistów lub następnej, zawartość takich plików może się po prostu składać z nagłówka „zawierającego zabezpieczenia” i dyrektywy „include”, która określa nowo przeniesiony nagłówek o tej samej nazwie:

#ifndef _WEAVE_MERCURY_BAR_HPP
#define _WEAVE_MERCURY_BAR_HPP

#include 

#endif // _WEAVE_MERCURY_BAR_HPP

Jeśli jednak w ramach nowej, niezgodnej z założeniami przestrzeni nazw tworzona jest również zarządzana przestrzeń nazw wyznaczona przez programistyczny lub Next, należy wykonać coś bardziej złożonego.

Tak jak wcześniej, tworzony jest nagłówek konfiguracji zarządzanej przestrzeni nazw w tym miejscu jako MercuryManagedNamespace.hpp. Również w tym przypadku lepiej jest powtarzać i zduplikować tę treść w każdym pliku nagłówkowym, jeśli istnieje wiele plików nagłówkowych.

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

#include 

#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

Jeśli nie zdefiniowano żadnej konfiguracji, może to być ustawienie domyślne „Current” (Bieżąca).

Po wprowadzeniu tego nagłówka nagłówki kodu zgodności można edytować tak, aby zawierały:

#include 

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

lub dowolnych innych odpowiednich funkcji do zarządzania przestrzenią nazw.

Tworzenie treści dla programistów

Masz już teraz gotową infrastrukturę pozwalającą na opracowywanie nowych funkcji i interfejsów API oprócz istniejących.

% 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 

#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

Oczywiście, jeśli moduł jest znacznie prostszy niż ten przykład i nie ma wielu klas, źródeł, plików czy nagłówków, można to zrobić w tym samym pliku nagłówka bez konieczności przenoszenia plików oraz tworzenia wielu samodzielnych nagłówków konfiguracji i zgodności. Ten skomplikowany przykład powinien być inspiracją do tworzenia rozwiązań do zarządzania przestrzenią nazw na różnych poziomach – od złożonego do prostego.

Używanie zarządzanych przestrzeni nazw jako integratora

Głównym obszarem integratora pakietu Weave SDK jest umieszczanie odpowiednich nagłówków publicznych interfejsów API Weave SDK oraz integrowanie i tworzenie z nimi aplikacji.

Jako przykład działającego przykładu przyjmijmy ponownie profil Weave, Mercury, który ma zarządzane przestrzenie nazw Next-, Current- i Legacy, a ich nagłówki publiczne mają taką strukturę:

• 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

gdzie Mercury.hpp to nagłówek modułu „parasol”.

O ile dany przypadek użycia nie zachęca do dodania modułu zarządzanego przez przestrzeń nazw w Weave, na przykład:

#include 

najlepiej jest odwoływać się do publicznych nagłówków modułu Weave za pomocą ich niezarządzanych, domyślnych ścieżek (np. Weave/Profiles/Mercury/Mercury.hpp). Pozwala to na śledzenie postępów w opracowywaniu interfejsów API bez ciągłego zmieniania dyrektyw „uwzględniaj” w projekcie w miarę przebiegu tych interfejsów API przez zarządzany lifecycle.

Zgodnie z tą strategią wdrożenia mogą być następnie kierowane ponownie do innego oznaczenia zarządzanej przestrzeni nazw (na przykład oznaczenia bieżącego) przez określenie żądanej konfiguracji we wstępnym procesorze C/C++. Można to zrobić w wierszu poleceń, w kodzie źródłowym, w nagłówku konfiguracji lub prefiksu:

#define WEAVE_CONFIG_MERCURY_NAMESPACE kWeaveManagedNamespace_Current

i użyj ścieżki niezarządzanej / niezakwalifikowanej:

#include 

Gdy i jeśli oznaczenie zarządzanej przestrzeni nazw zmieni się dla docelowych interfejsów API, na przykład z bieżącej na starszą, po prostu zmień kierowanie, dostosowując definicję podmiotu przetwarzającego dane:

#define WEAVE_CONFIG_MERCURY_NAMESPACE kWeaveManagedNamespace_Legacy