Google は、黒人コミュニティのための人種的公平の促進に取り組んでいます。詳細をご覧ください。

このページは Cloud Translation API によって翻訳されました。

マネージド Namespace

概要

はじめに

マネージド名前空間は Weave SDK で使用され、Weave SDK のデベロッパーとインテグレータの両方に、SDK 内の特定の API セットの指定に関するアドバタイズされたガイダンスとサブテキストが提供されます。これにより、Weave SDK リリース間での移行パスの計画と予測が可能になります。場合によっては、特定のモジュールに対して複数の同時実行 Weave API を管理できます。

認定

マネージド Namespace は、次の 4 つの指定のいずれかとして管理されます。

開発

「開発」の名称で管理される名前空間は、そこに含まれる API が開発中で、変更される可能性があり、正式にはサポートされていないことをデベロッパーやインテグレータに示すものとなります。一般に、インテグレータは特に指示がない限り、これらの API を使用することはおすすめしません。

Next の認定で管理される名前空間は、デベロッパーやインテグレータに対して、そこに含まれる API は概ねアクティブな開発が完了していますが、まだ変更される可能性があり、早期評価目的でサポートされていることを示しています。そのように指定された API は、Weave SDK API における次なる進化の最前線であり、直近から近い将来にかけての主要なリリースサイクルにおける現在のデフォルト API となります。

API と無線プロトコルの両方の観点からの下位互換性はある場合がありますが、そのように指定された API では保証されません。

Next のマネージド名前空間の指定により、デベロッパーやインテグレータは、今後のリリースで現在のデフォルト API が何になるのかを示唆することで、Weave SDK の今後の方向性を効果的に把握できるようになります。

Next マネージド名前空間の指定は任意です。指定されていなくても、マネージド名前空間はライフサイクルを通じて移行できます（マネージド名前空間のライフサイクルをご覧ください）。

現在

Current の指定または管理されていない名前空間（マネージド名前空間の指定がないなど）で管理される名前空間は、Weave SDK の該当部分またはモジュールに対して現在サポートされている、デフォルトで公式にサポートされている API を表します。このような API の機能強化が現在も継続されている可能性がありますが、変更点は主に増分となり、API と無線（OTA）の両方で下位互換性を維持する必要があります。

現在のマネージド名前空間の指定は任意です。指定されていなくても、マネージド名前空間はそのライフサイクルを通じて移行できます（マネージド名前空間のライフサイクルをご覧ください）。実際、管理対象外の名前空間は暗黙的に Current です。

レガシー

「Legacy」の名称で管理される名前空間は、そこに含まれる API が非推奨となり、新しい現行 API に置き換わることをデベロッパーやインテグレータに通知しています。これらの API は、現在の API の名称です。

指定された API は、次回の Weave SDK リリースで完全に消滅します。そのため、デベロッパーやインテグレータは、Weave SDK リリースの最先端のリリースを使い続けるつもりであれば、これらの API からの移行計画を策定する必要があります。

マネージド Namespace のライフサイクル

次の図は、Development から Legacy に移行する際のマネージド Namespace のライフサイクルを示しています。

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

マネージド Namespace が使用されている場合、マネージド Namespace のライフサイクルは「Development」指定から始まります。

開発が完了し、コードの評価と統合の準備が整ったら、指定を Next または Current に移行します。または、指定を完全に削除して、マネージド名前空間が使用されなくなり、事実上、指定が暗黙的に Current になります。

そのコードが現行のコードに置き換わるのにまだ置き換わらない場合は、認定を Next に移行します。コードが現在のコードに置き換わる場合は、現在のコードの指定が Current に移行します。

「Next」を使用して、コードのリリースと評価サイクルを必要な回数だけ実行した後、この認定を Current に移行します。また、この認定を完全に取り消すこともできます。

コードを新しいコードで置き換える必要があるものの、何度かリリースサイクルにわたって維持する必要がある場合は、現行の名称を使用して、以前の名称に移行します。

以前の名称のコードは、最終的に Weave SDK から完全に削除されます。

マネージド Namespace の使用

Weave SDK のユーザーは、マネージド名前空間をデベロッパーとして操作して既存のコードを拡張および保守することも、インテグレータとして Weave を独自のアプリケーション、プラットフォーム、システムコードに統合することもできます。以下の 2 つのセクションでは、Weave が管理する名前空間を扱う際の推奨事項をそれぞれの観点から詳しく説明します。

デベロッパーとしてのマネージド Namespace の使用

Weave SDK の開発者は、新しい Weave SDK API や機能の強化と開発を行いながら、多くの場合、既存の API や機能のデプロイをサポートすることに注力しています。

同じ API 内で両方の重点分野を下位互換性のある方法で満たすことができない場合は、マネージド名前空間が、既存の API および機能のデプロイを中断することなく、これらの API を並行して管理するメカニズムを提供します。

動作例として、Weave プロファイル Mercury が現在、以下の非マネージド Namespace 階層に存在するとします。

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

// ...

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

および次の公開ヘッダー:

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

Mercury.hpp は「umbrella」モジュールですできます。ほとんどのインテグレータは単にモジュール「umbrella」をヘッダーを示しています。

#include

しかし、Mercury の開発会社は、次世代の API、そして潜在的には既存のデプロイメントとの下位互換性がない無線プロトコル（over-the-wire）プロトコルを開発する必要性が生じています。マネージド Namespace を使用すると、こうした既存のデプロイを中断することなく、これを実現できます。

既存の名前空間を現在の名前空間に移動

現在のリリースの API と既存のデプロイ済み統合の機能を引き続きサポートすることを目標に、最初のタスクは現在のコードを移行することです。

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

ファイルの移動に加えて、移動したファイルのヘッダインクルードガードも変更する必要があります。その際、ファイル名を「_CURRENT」で修飾する必要があります。これは、同じ名前のファイルがその下に作成されるためです。

コードを移動したら、次に、適切な指定（ここでは「Current」）を使用して名前空間を管理します。まず、マネージド名前空間を「Current/MercuryManagedNamespace.hpp」として定義するヘッダーを作成します。複数のヘッダーファイルがある場合は、各ヘッダーファイルでこのコンテンツを繰り返し、複製するよりも、このようなヘッダーを作成するほうが適切です。

% 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

次に、既存のヘッダー内の他のモジュール固有の include ディレクティブの前に、このヘッダーをインクルードします。例:

#include 

#include

互換性ヘッダーを作成する

ただし、既存のヘッダーを新しい場所に移動し、Namespace だけを管理するだけでは、既存のデプロイメントが変更なしで動作するようにするには、先ほど移動したヘッダーを指定する include ディレクティブを使用しているため、不十分です。

これに対処するには、移動した名前と一致する名前の互換性ラッパーヘッダーを作成する必要があります。

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

Development または Next で指定されたマネージド名前空間を作成せずに、Current 指定のマネージド名前空間のみを作成する場合、このファイルの内容は、ヘッダーインクルードガードと、新しく移動した同じ名前のヘッダーを指定する include ディレクティブだけで構成できます。

#ifndef _WEAVE_MERCURY_BAR_HPP
#define _WEAVE_MERCURY_BAR_HPP

#include 

#endif // _WEAVE_MERCURY_BAR_HPP

ただし、Development または Next で指定されたマネージド名前空間を作成する場合、互換性のない新しい開発に対応するために、少し複雑な作業が必要になります。

前と同様に、マネージド名前空間構成のヘッダーが作成されます（ここでは MercuryManagedNamespace.hpp）。繰り返しになりますが、ヘッダーファイルが複数ある場合は、各ヘッダーファイルでこのコンテンツを繰り返し、複製するよりも、この方法のほうが適しています。

% 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

デフォルトでは、マネージド名前空間の指定は「Current」になります。構成が定義されていない場合です。

このヘッダーを設定すると、互換性ラッパーのヘッダーを編集して以下を含めることができます。

#include 

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

名前空間管理のユースケースに適したものであれば、どのようなものでもかまいません。

開発コンテンツを作成する

この時点でインフラストラクチャは準備が整い、既存の機能と API に加えて新しい機能や API の構築を開始しています。

% 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

もちろん、モジュールがここで紹介した例よりはるかにシンプルであり、クラス、ソース、ファイル、ヘッダーが多くない場合、ファイルを移動したり、複数のスタンドアロンの構成と互換性ヘッダーを作成したりすることなく、同じヘッダーファイルですべてを実現できます。ただし、この複雑な例では、複雑なものからシンプルなものまで、幅広い範囲でマネージド名前空間ソリューションに影響を与えるはずです。

インテグレータとしてのマネージド Namespace の使用

Weave SDK インテグレータは、適切な Weave SDK 公開 API ヘッダーのインクルードと、それに対するアプリケーションの統合と開発に重点を置きます。

再び動作例として、Weave プロファイル Mercury に、Next、Current、Legacy で指定されたマネージド名前空間があり、公開ヘッダーが次のように構成されているとします。

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 は「umbrella」モジュールですできます。

現在のユースケースで、Weave 内に名前空間で管理されるモジュールを明示的に含める必要がある場合を除きます。次に例を示します。

#include

Weave モジュールの公開ヘッダーは、管理対象外のデフォルトパス（例: Weave/Profiles/Mercury/Mercury.hpp）で参照することをおすすめします。これにより、API がマネージドライフサイクルを通過する際に、プロジェクトの include ディレクティブを継続的に変更することなく、API 開発の進行に沿うことができます。

この戦略に従えば、デプロイは、C/C++ プリプロセッサで必要な構成を指定することにより、別のマネージド名前空間の指定（Current の指定など）でコードを再ターゲットできます。これは、コマンドライン、ソースコード、構成ヘッダー、接頭辞ヘッダーで行うことができます。

#define WEAVE_CONFIG_MERCURY_NAMESPACE kWeaveManagedNamespace_Current

管理対象外のインクルードパスまたは修飾されていないインクルードパスを使用します。

#include

ターゲット API のマネージド Namespace の指定が変更された場合（Current から Legacy に変更するなど）は、プリプロセッサの定義を調整してターゲットを変更するだけで済みます。

#define WEAVE_CONFIG_MERCURY_NAMESPACE kWeaveManagedNamespace_Legacy