Yönetilen Ad Alanları

Özet

Giriş

Yönetilen ad alanları, hem Weave SDK geliştiricilerine hem de entegratörlerine hem Weave SDK'sı geliştiricilerine hem de entegratörlere, SDK içinde belirli API kümelerinin atanmasına ilişkin alt metinler sunmak ve böylece Weave SDK sürümlerinde taşıma yollarını planlayıp tahmin etmek ve belirli bir modül için birden fazla eşzamanlı Weave API'sini yönetmek amacıyla kullanılır.

Verilen ad

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

Geliştirme

Geliştirme atamasıyla yönetilen tüm ad alanları, geliştiricilere ve entegratörlere, içerdiği API'lerin aktif geliştirme aşamasında olduğunu, değişikliğe tabi olabileceğini ve resmi olarak desteklenmediğini gösterir. Özel olarak belirtilmediği sürece entegratörlerin bu API'leri kullanmaları genellikle önerilmez.

Sonraki

Sonraki ibaresiyle yönetilen tüm ad alanları, geliştiricilere ve entegratörlere, içinde bulunan API'lerin büyük oranda aktif geliştirmeleri tamamlamış olsalar da hâlâ değişebileceğini ve erken değerlendirme amaçları doğrultusunda desteklenebileceğini belirtir. Bu şekilde tanımlanan API'ler, Weave SDK API'sinde bir sonraki evrimsel ön cepheyi temsil eder ve yakın gelecekte önemli bir yayın döngüsünde şu anki varsayılan API'ler haline gelir.

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

Next yönetilen ad alanı tanımlaması, geliştiricilere ve entegratörlere gelecekteki bir sürümde mevcut, varsayılan API'nin hangisi olacağına dair ipucu vererek Weave SDK'sının nereye gideceğine dair etkili bir görünüm sunar.

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 şekilde 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ımlama veya yönetilmeyen herhangi bir ad alanı ile yönetilen (bir yönetilen ad alanı ataması yoksa) Weave SDK'sının ilgili bölümü ya da modülü için desteklenen mevcut, varsayılan ve resmi API'yi temsil eder. Bu tür API'lerde hâlâ geliştirmeler yapılabilir. Bununla birlikte, değişiklikler büyük ölçüde artımlı ve geriye dönük uyumluluk olacaktır. Bununla birlikte, hem API hem de kablosuz bağlantı konusunda değişiklik yapılmalıdır.

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 şekilde 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ünceldir.

Eski

Eski tanımlamasıyla yönetilen tüm ad alanları, geliştiricilere ve entegratörlere, içerdiği API'lerin kullanımdan kaldırıldığını ve bunların yerine yeni, geçerli bir API'nin değiştirildiğini gösterir. Bu API'ler, eskiden mevcut API'yi temsil eder.

Bu şekilde belirlenen API'ler, bir sonraki ana Weave SDK sürümünde tamamen kaybolacaktır. Sonuç olarak, Weave SDK sürümlerindeki ileri seviyelerde kalmak isteyen geliştiriciler ve entegratörlerin bu API'lerden başka bir sisteme geçiş planları yapması gerekir.

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

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

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

Kullanılması halinde, yönetilen ad alanı yaşam döngüsü Geliştirme atamasıyla başlar.

Geliştirme aşaması tamamlandığında ve kod, değerlendirme ve entegrasyon için hazır olduğunda atama ya Sonraki ya da Geçerli değerine taşınır. Alternatif olarak, tanımlama tamamen kaldırılabilir ve yönetilen ad alanı artık kullanılmayabilir. Bu da, tanımlamayı örtülü bir şekilde Güncel hale getirir.

Kod ile birlikte kullanılacak ancak mevcut kodun yerini henüz almadıysa bu durum Sonraki'ye taşınmalıdır. Kod, mevcut kodun yerini alacaksa bu durum Güncel'e taşınmalıdır.

Sonraki tanımlamasını kullanarak, kod istenen sayıda yayınlama ve değerlendirme döngüsünden geçtikten sonra, tanımlama Geçerli zamana taşınır veya Tanımlama tamamen kaldırılabilir.

Geçerli tanımlamayı kullanarak, kodun yerini yeni kod alacak ancak yine de birkaç sürüm döngüsü boyunca korunması gerekiyorsa tanımlama Eski'ye taşınır.

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

Yönetilen Ad Alanlarını Kullanma

Weave SDK kullanıcıları; geliştirici olarak, mevcut kodu genişletip sürdürerek veya entegre edici olarak Weave'i kendi uygulamasına, platformuna ve sistem koduna entegre ederek yönetilen ad alanlarıyla etkileşim kurabilir. Aşağıdaki iki bölümde, Weave tarafından yönetilen ad alanlarını bu iki bakış açısından ele almaya ilişkin öneriler ayrıntılı olarak açıklanmıştı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ştirirken çoğu durumda mevcut API ve işlev dağıtımlarını desteklemektir.

Yönetilen ad alanları, aynı API'de bu odak alanlarının her ikisinin de geriye dönük uyumlu olarak karşılanmasının mümkün olmadığı durumlarda, bu API'leri mevcut API ve işlev dağıtımlarını kesintiye uğratmayacak şekilde paralel olarak yönetmek için bir mekanizma sağlar.

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

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

// ...

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

ve şu genel üstbilgiler:

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

Burada Mercury.hpp, modülün "şemsiye" başlığıdır. Çoğu entegratör, aşağıda gösterildiği gibi "şemsiye" modül başlığını içerir:

#include

Ancak Mercury'nin geliştiricisi artık yeni nesil API'lerin ve belki de mevcut dağıtımlarla geriye dönük uyumlu olmayan kablosuz ağ protokolün geliştirilmesi gereken bir noktaya ulaştı. Yönetilen ad alanlarının kullanılması, mevcut dağıtımları bozmadan bu işlemin tamamlanmasına yardımcı olabilir.

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

API'nin güncel sürümünü desteklemeye ve mevcut dağıtılmış entegrasyonlarda işlevleri sunmaya devam etmek amacıyla 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, üstbilginin taşınan dosyalar için korumalar da içermesi gerektiğini unutmayın. Benzer şekilde adlandırılmış yeni dosyalar aşağıda yer alacağından, bunların yeniden adlandırılması ve "_CURRENT" ile süslenmiş olması gerekir.

Kod taşındıktan sonra, atılacak bir sonraki adım, ad alanını uygun şekilde (buradaki "Geçerli") yönetmektir. Öncelikle, yönetilen ad alanını tanımlayan bir üstbilgi oluşturun: "Current/MercuryManagedNamespace.hpp". Birden fazla başlık dosyası olduğunda, bu içeriğin her bir başlık dosyasında yinelenmesi ve yinelenmesi tercih edilir.

% 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

Ardından, mevcut üstbilgilerdeki diğer modüle özgü "include" direktiflerinden önce bu üstbilgiyi ekleyin. Örneğin:

#include 

#include

Uyumluluk Başlıkları Oluşturma

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

Bu sorunu gidermek için, yeni taşınan adlarla eşleşen adlara sahip uyumluluk sarmalayıcı başlıkları oluşturulmalıdır.

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

Kendisine eşlik edecek bir Geliştirme veya Sonraki olarak tanımlanmış ad alanı oluşturulmadan yalnızca Geçerli olarak tanımlanmış bir yönetilen ad alanı oluşturuluyorsa bu dosyaların içeriği, aynı ada sahip yeni taşınan üstbilgiyi belirten bir üstbilgiden Guard ve bir include yönergesinden oluşabilir:

#ifndef _WEAVE_MERCURY_BAR_HPP
#define _WEAVE_MERCURY_BAR_HPP

#include 

#endif // _WEAVE_MERCURY_BAR_HPP

Ancak yeni, uyumsuz geliştirmelere de uygun olması için Geliştirme veya Next olarak tanımlanmış bir yönetilen ad alanı oluşturuluyorsa biraz daha karmaşık bir işin 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. Aynı şekilde, birden fazla başlık dosyası olduğunda, bu içeriğin her bir başlık dosyasında tekrarlanması ve yinelenmesi tercih edilir.

% 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

Herhangi bir yapılandırma tanımlanmamışsa bunun, istenen şekilde yönetilen ad alanı tanımlamasını "Mevcut" olarak varsayılan olarak ayarladığını unutmayın.

Bu başlık kullanıldığında, 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ı için uygun olup olmadığını kontrol edin.

Geliştirme İçeriği Oluşturma

Bu noktada altyapı, mevcut işlevlerin ve API'lerin yanı sıra yeni işlevler geliştirmeye başlamak için de hazırdı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 

#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 sunulan örnekten çok daha basitse ve birçok sınıf, kaynak, dosya veya başlık yoksa tüm bunlar, dosyalar taşınmadan ve birden fazla 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 değişen bir yelpazede yönetilen ad alanı çözümlerine ilham vermelidir.

Yönetilen Ad Alanlarını Entegre Edici Olarak Kullanma

Weave SDK entegratörünün başlıca odak noktalarından biri, uygun Weave SDK genel API başlıklarını eklemek ve bunlara dayalı uygulamaları entegre edip geliştirmektir.

Çalışan bir örnek olarak yine, Next, Current ve Eski olarak tanımlanmış ad alanlarına sahip ve genel başlıkları aşağıdaki gibi yapılandırılmış bir Weave profilinin (Merkür) 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

Burada Mercury.hpp, modülün "şemsiye" başlığıdır.

Mevcut kullanım alanı, Weave'e açıkça yönetilen bir ad alanı modülü eklenmesini teşvik etmediği sürece, örneğin:

#include

Weave modülü genel üstbilgilerine, yönetilmeyen varsayılan yollarına (ör. Weave/Profiles/Mercury/Mercury.hpp) göre referansta bulunmak en iyisidir. Böylece, yönetilen lifecycle bir projenin dahil etme yönergelerini sürekli olarak değiştirmeden, API geliştirme sürecini takip edebilirsiniz.

Bu stratejinin ardından dağıtımlar, kodlarını farklı bir yönetilen ad alanı atamasında (örneğin, C/C++ ön işlemcisinde istenen yapılandırmayı belirterek) 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 / uygun olmayan dahil etme yolunu kullanın:

#include

Hedeflenen API'lerin yönetilen ad alanı tanımlaması değiştiğinde (ör. Geçerli'den Eski'ye), ön işlemci tanımını düzenleyerek yeniden hedefleme yapmanız yeterlidir:

#define WEAVE_CONFIG_MERCURY_NAMESPACE kWeaveManagedNamespace_Legacy