Yönetilen Ad Alanları

Özet

Giriş

Weave SDK'da yönetilen ad alanları, hem Weave SDK geliştiricileri hem de entegratörlere, SDK'daki belirli API gruplarının tanımlanmasıyla ilgili reklamı yapılan yönergeler ve alt metinler sağlamak için kullanılır. Böylece, Weave SDK sürümlerinde taşıma yollarını planlayıp tahmin edebilir ve potansiyel olarak belirli bir modül için birden fazla eş zamanlı Weave API'sini yönetebilirler.

Tanımlama

Yönetilen ad alanları, dört tanımlamadan biri olarak yönetilebilir:

Geliştirme

Geliştirme tanımlamasıyla yönetilen herhangi bir ad alanı, geliştiricilere ve entegratörlere, içerdikleri API'lerin aktif geliştirme aşamasında olduğunu, değişebileceğini ve resmi olarak desteklenmediğini belirtir. Entegratörlerin, özel olarak yönlendirilmedikleri sürece bu API'leri kullanmaları genellikle önerilmez.

Sonraki

Next tanımlamasıyla yönetilen herhangi bir ad alanı, geliştiricilere ve entegratörlere, içerdikleri API'lerin büyük ölçüde etkin geliştirmeleri olsa da hâlâ değişebileceğine ve erken değerlendirme amaçları doğrultusunda desteklenebileceğini gösterir. Bu şekilde belirlenen API'ler, bir Weave SDK API'de bir sonraki evrim önünü temsil eder ve yakın ile yakın gelecekte büyük bir yayın döngüsünde mevcut, varsayılan API'ler olacaktır.

Hem API'den hem de kablolu protokol açısından geriye dönük uyumluluk mevcut olabilir ancak bu şekilde belirtilen API'lerde garanti edilmez.

Sonraki yönetilen ad alanı tanımlaması, neyin gelecekteki bir sürümde varsayılan API olarak kullanılacağına dair ipuçları vererek geliştiricilere ve entegrasyon uzmanlarına Weave SDK'nın nereye yönlendireceğini etkili bir şekilde gösterir.

Sonraki yönetilen ad alanı tanımlaması, yönetilen bir ad alanının kullanılmadan bir yaşam döngüsü boyunca geçiş yapabileceği için isteğe bağlıdır (Yönetilen Ad Alanı Yaşam Döngüsü bölümüne bakın).

Şu anki adı

Geçerli tanımlamayla yönetilen herhangi bir ad alanı veya yönetilmeyen herhangi bir ad alanı (ör. yönetilen ad alanı ataması eksik) Weave SDK'nın söz konusu bölümü veya modülü için mevcut, varsayılan, resmi olarak desteklenen API'yi temsil eder. Bu tür API'lerde halen iyileştirmeler yapılabilir. Ancak değişiklikler büyük ölçüde artımlı ve geriye dönük uyumluluk sağlayacak olsa da hem API hem de kablosuz bağlantı sürdürülmelidir.

Mevcut yönetilen ad alanı tanımlaması, yönetilen bir ad alanının kullanılmadan bir yaşam döngüsü boyunca geçiş yapabileceği için isteğe bağlıdır (Yönetilen Ad Alanı Yaşam Döngüsü bölümüne bakın). Aslında yönetilmeyen tüm ad alanları dolaylı olarak Güncel'dir.

Eski

Eski tanımlamayla yönetilen herhangi bir ad alanı, geliştiricilere ve entegratörlere, içerdikleri API'lerin kullanımdan kaldırıldığını ve bunların yerini yeni ve güncel bir API'nin aldığını gösterir. Bu API'ler eskiden şu anki API'yi temsil eder.

Bu şekilde belirlenen API'ler, bir sonraki büyük Weave SDK sürümünde tamamen kullanımdan kaldırılacak; Sonuç olarak, geliştiriciler ve entegrasyon uzmanları Weave SDK sürümlerinin son ucunda kalmayı planlıyorsa bu API'lerden taşınmaya yönelik planlar oluşturmalıdır.

Yönetilen Ad Alanı Yaşam Döngüsü

Aşağıdaki şekilde, yönetilen ad alanının Geliştirme durumundan Eski'ye geçiş sürecindeki yaşam döngüsü gösterilmektedir:

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

Bu parametre kullanılırsa yönetilen ad alanı yaşam döngüsü, Geliştirme tanımlamasıyla başlar.

Geliştirme tamamlandığında ve kod, değerlendirme ve entegrasyon için hazır olduğunda tanımlama, Sonraki veya Geçerli'ye taşınır. Alternatif olarak, tanımlama tamamen kaldırılabilir ve yönetilen ad alanı artık kullanılmayabilir. Bu durum, atamanın dolaylı olarak Geçerli olmasını sağlar.

Kod birlikte yayınlanacaksa ve henüz mevcut kodu desteklemeyecekse tanımlama "Sonraki"ye taşınmalıdır. Kod, mevcut kodu geçersiz kılacaksa tanımlama Geçerli'ye taşınmalıdır.

Sonraki tanımlamayı kullanıldığında, kod istenen sayıda yayın ve değerlendirme döngüsünden geçtikten sonra tanımlama Geçerliliğe taşınır veya yine de Tanımlama tamamen kaldırılabilir.

Mevcut tanımlamayı kullandığınızda, kod yeni kodla değiştirilecek ancak bir dizi sürüm döngüsü boyunca korunması gerekiyorsa bu kod Eski'ye taşınır.

Eski tanımlamadan sonra kod, sonunda Weave SDK'sından tamamen kaldırılır.

Yönetilen Ad Alanlarını Kullanma

Weave SDK kullanıcıları, yönetilen ad alanlarıyla geliştirici olarak, mevcut kodu genişletip koruyarak veya Weave'i kendi uygulama, platformu ve sistem kodlarına entegre ederek entegratör olarak etkileşim kurabilir. Aşağıdaki iki bölümde, Weave tarafından yönetilen ad alanlarını bu iki açıdan ele almayla ilgili öneriler ayrıntılı olarak açıklanmaktadır.

Yönetilen Ad Alanlarını Geliştirici Olarak Kullanma

Weave SDK geliştiricisinin temel odak noktalarından biri, yeni Weave SDK API'lerini ve işlevlerini geliştirip geliştirmek, diğer yandan çoğu durumda mevcut API ve işlev dağıtımlarını desteklemektir.

Her iki odak alanının da aynı API içinde geriye dönük olarak uyumlu şekilde karşılanamaması durumunda, yönetilen ad alanları, bu API'leri mevcut API ve işlev dağıtımlarını kesintiye uğratmayacak şekilde paralel olarak yönetmeyi sağlayan bir mekanizma sağlar.

Çalışan bir örnek olarak şu anda aşağıdaki yönetilmeyen ad alanı hiyerarşisinde bulunan Mercury adlı Weave profilini düşünün:

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

// ...

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

ve aşağıdaki herkese açık başlıklar:

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

Mercury.hpp, "şemsiye" modülüdür. kullanabilirsiniz. Çoğu entegrasyon uzmanı "şemsiye" modülünü içerir başlık ekleyin:

#include

Ancak Mercury'nin gelişimi artık yeni nesil API'lerin ve muhtemelen mevcut dağıtımlarla geriye dönük uyumlu olmayan kablolu protokol geliştirilmesinin gerekli olduğu bir noktaya ulaştı. Yönetilen ad alanlarını kullanarak mevcut dağıtımları bozmadan bu işlemleri gerçekleştirebilirsiniz.

Mevcut Ad Alanını Geçerli Olana Taşı

API'nin mevcut sürümünü ve dağıtılan mevcut entegrasyonların işlevlerini desteklemeye devam etmek için atmanız gereken ilk görev, mevcut kodu taşımaktır:

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

Dosyaları taşımaya ek olarak, başlığın taşınan dosyalar için korumalar da içerdiğini unutmayın. Bunlar, aşağıdaki gibi yeni ve benzer adlandırılmış dosyalar oluşturulacağından dosyaların '_CURRENT' ile süslenmesi gerekir.

Kod taşındıktan sonraki adım, ad alanını uygun tanımlamayla (buradaki "Geçerli") yönetmektir. Öncelikle, yönetilen ad alanını "Current/MercuryManagedNamespace.hpp" olarak tanımlayan bir başlık oluşturun. Böyle bir başlık oluşturmak, birden fazla başlık dosyası olduğunda bu içeriğin her bir başlık dosyasında tekrarlanması ve çoğaltılması tercih edilir.

% 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

Ardından, bu üstbilgiyi, modüle özgü diğer "include" (ekleme) yönergelerinden önce mevcut başlıklara ekleyin. Örneğin:

#include 

#include

Uyumluluk Üst Bilgileri Oluşturma

Ancak mevcut başlıkları yeni bir konuma taşımak ve bunların tek başına ad alanını yönetmek, tüm dağıtımların az önce yukarıya taşınan başlıkları belirten yönergeler kullandıkları için bu dağıtımların değişmeden çalışmasını sağlamak için yeterli değildir.

Bu sorunu gidermek için, az önce taşınanlarla eşleşen adlara sahip uyumluluk sarmalayıcı başlıkları oluşturulmalıdır.

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

Yalnızca Geçerli olarak atanmış bir yönetilen ad alanı, ona eşlik edecek bir Geliştirme veya Next tarafından atanmış yönetilen ad alanı oluşturulmadan oluşturuluyorsa bu dosyaların içeriği, aynı ada sahip yeni taşınan üst bilgiyi belirten bir "Guard" ve "include" yönergesi içeren bir başlıktan oluşabilir:

#ifndef _WEAVE_MERCURY_BAR_HPP
#define _WEAVE_MERCURY_BAR_HPP

#include 

#endif // _WEAVE_MERCURY_BAR_HPP

Bununla birlikte, yeni ve uyumsuz geliştirmeyi desteklemek için Geliştirme veya Sonraki tarafından atanmış bir yönetilen ad alanı da oluşturuluyorsa biraz daha karmaşık bir işlem yapılması gerekir.

Daha önce olduğu gibi, burada MercuryManagedNamespace.hpp olarak yönetilen ad alanı yapılandırması için bir başlık oluşturulur. Yine bu yöntem, birden fazla başlık dosyası olduğunda bu içeriğin her bir başlık dosyasında tekrarlanması ve çoğaltılması tercih edilir.

% 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

Bu işlemin istenen şekilde, yönetilen ad alanı atamasını varsayılan olarak "Current" olarak ayarladığını unutmayın herhangi bir yapılandırma tanımlanmamışsa.

Bu başlık yerleştirildiğinde, uyumluluk sarmalayıcı başlıkları artık şunları içerecek şekilde düzenlenebilir:

#include 

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

kullanım alanına uygun bir şekilde düzenleyebiliriz.

Geliştirme İçeriği Oluşturma

Bu noktada, mevcut işlevselliklerin ve API'lerin yanı sıra yeni işlevler ve API'ler oluşturmaya başlamak için altyapı artık hazır.

% 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

Elbette bir modül burada verilen örnekten çok daha basitse ve çok sayıda sınıf, kaynak, dosya ya da başlık içermiyorsa, tüm bu işlemler, dosyalar taşınmadan ve birden çok bağımsız yapılandırma ve uyumluluk başlığı oluşturulmadan aynı başlık dosyasında gerçekleştirilebilir. Ancak bu karmaşık örnek, karmaşıktan basite doğru yelpazedeki yönetilen ad alanı çözümlerine ilham vermelidir.

Yönetilen Ad Alanlarını Entegratör Olarak Kullanma

Weave SDK entegratörünün en önemli odak noktalarından biri, uygun Weave SDK herkese açık API başlıklarını dahil etmek ve bunlarla uygulama entegre edip geliştirmektir.

Başarılı bir örnek olarak yine Mercury'nin Sonraki, Geçerli ve Eski şeklinde tanımlanmış yönetilen ad alanlarına sahip olduğunu ve herkese açık başlıkları aşağıdaki gibi yapılandırılmış bir Weave profilinin olduğunu varsayalım:

  • 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

Mercury.hpp, "şemsiye" modülüdür. kullanabilirsiniz.

Mevcut kullanım alanı, Weave'de açık bir şekilde ad alanı tarafından yönetilen bir modül dahil edilmesini gerektirmiyorsa, örneğin:

#include

Weave modülü herkese açık başlıklarına, yönetilmeyen, varsayılan yollarıyla (ör. Weave/Profiles/Mercury/Mercury.hpp) başvuruda bulunmanız önerilir. Böylece, API'ler yönetilen yaşam döngüsünde ilerlerken bir projenin dahil etme yönergelerinde sürekli değişiklik yapmadan, API geliştirme sürecinin ilerlemesini takip edebilirsiniz.

Bu stratejinin ardından dağıtımlar, C/C++ ön işlemcisinde istenen yapılandırmayı belirterek kodlarını farklı bir yönetilen ad alanı tanımlamasında (ör. Mevcut tanımlama) yeniden hedefleyebilir. Bu işlem komut satırında, kaynak kodunda veya bir yapılandırma ya da önek başlığında yapılabilir:

#define WEAVE_CONFIG_MERCURY_NAMESPACE kWeaveManagedNamespace_Current

ve yönetilmeyen / nitelikli olmayan dahil etme yolunu kullanın:

#include

Hedeflenen API'lerin yönetilen ad alanı tanımlaması değişirse (ör. Geçerli olandan Eski'ye) söz konusu olduğunda, ön işlemci tanımını düzenleyerek yeniden hedeflemeniz yeterlidir:

#define WEAVE_CONFIG_MERCURY_NAMESPACE kWeaveManagedNamespace_Legacy