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

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

マネージド名前空間

概要

はじめに

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

認定

マネージド名前空間は、次の 4 つの指定のいずれかとして管理できます。

開発

Development 認定で管理される Namespace は、その中に含まれる API が現在開発中であり、変更される可能性があります。また、正式にサポートされていないことをデベロッパーやインテグレータに示すものです。インテグレータは、特に指示がない限り、これらの API を使用することは一般的に推奨されません。

Next 認定で管理される Namespace は、その中に含まれている API がほぼ積極的な開発を完了していても、まだ変更される可能性があり、早期評価目的でサポートされる可能性があることをデベロッパーやインテグレータに示すものです。指定された API は Weave SDK API の次なる進化の最前線を意味し、近い将来、主要なリリースサイクルで現在のデフォルト API になります。

下位互換性は、API と無線プロトコルの両方の観点から存在しても構いませんが、そのように指定された API では保証されません。

Next のマネージド Namespace の指定により、デベロッパーやインテグレータは、Weave SDK の今後のリリースで現在のデフォルト API になるものをヒントとして効果的に示せます。

Next マネージド Namespace の指定はオプションです。そのため、マネージド Namespace は使用せずにライフサイクルを移行できます（マネージド Namespace のライフサイクルを参照）。

現在

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

「現在のマネージド Namespace」の指定はオプションです。そのため、マネージド Namespace は使用せずにライフサイクルを移行できます（マネージド Namespace のライフサイクルをご覧ください）。実際、非マネージド名前空間は暗黙的に Current です。

レガシー

Legacy 認定で管理されている Namespace は、その中に含まれている API が非推奨になり、新しい現在の API に置き換わっていることをデベロッパーやインテグレータに示すものです。これらの API は、旧バージョンの API を表しています。

指定された API は、Weave SDK の次回のメジャーリリースで完全になくなる予定です。そのため、デベロッパーやインテグレータは、Weave SDK リリースの最先端を維持したいのであれば、これらの API からの移行計画を確立する必要があります。

マネージド名前空間のライフサイクル

次の図は、開発環境から、場合によっては従来版に移行する際のマネージド Namespace のライフサイクルを示しています。

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

マネージド Namespace ライフサイクルを使用する場合、Development の認定から始まります。

開発が完了し、コードの評価と統合の準備が整うと、認定は「Next」または「Current」に移行します。または、指定が完全に破棄されてマネージド Namespace が使用されなくなると、指定が暗黙的に Current になります。

コードがそのまま運用されるものの、まだ現在のコードに取って代わるものではない場合は、評価を「Next」に移行する必要があります。コードが現在のコードに取って代わる場合、指定は「Current」に移行します。

「Next」を指定すると、コードが所定の回数のリリースと評価のサイクルを経た後に「Current」に移行します。または、この指定を完全に破棄することもできます。

現在の名称を使用すると、新しいコードに置き換えても多くのリリースサイクルにわたって維持する必要がある場合、認定はレガシーに移行します。

レガシーを示すコードは、最終的に Weave SDK から完全に削除されます。

マネージド名前空間の使用

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

デベロッパーとしてのマネージド名前空間の使用

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

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

実例として、Mercury という Weave プロファイルが現在次の管理対象外の名前空間階層に存在するとします。

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 と、潜在的には無線（OTA）プロトコルの開発が必要になる段階に達しています。マネージド Namespace を使用すると、こうした既存のデプロイを損なうことなくこの目的を実現できます。

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

デプロイ済みの既存の統合において、API と機能の現在のリリースを引き続きサポートすることを目標に、現在のコードを移行します。

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

なお、ファイルの移動に加えて、移動されたファイルのヘッダーインクルードガードも名前を変更する必要があります。名前が似ている新しいファイルがその下に作成されるため、「_CURRENT」で装飾される場合があります。

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

% 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

次に、このヘッダーを既存のヘッダーで、他のモジュール固有の 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 で指定されたマネージド Namespace も作成する場合は、もう少し複雑なことを行う必要があります。

前のタスクと同様に、マネージド Namespace の構成を示すヘッダー（ここでは MercuryManagedNamespace.hpp）が作成されます。繰り返しになりますが、この方法は、複数のヘッダーファイルがある場合に、各ヘッダーファイル内でこの内容を繰り返し、複製するよりも望ましい方法です。

% 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

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

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

#include 

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

名前空間管理のユースケースに適したものを指定できます。

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

この時点で、インフラストラクチャは既存の機能と並行して新しい機能と 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 

#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 など）で参照することをおすすめします。これにより、プロジェクトの include ディレクティブを継続的に変更することなく、API がマネージド lifecycleを通過する際に、API の開発を進行できます。

この戦略に沿うことで、デプロイは C/C++ プリプロセッサで目的の構成を指定することで、たとえば「Current」などの異なるマネージド名前空間の指定でコードをリターゲティングできます。これは、コマンドライン、ソースコード、構成ヘッダーまたはプレフィックスヘッダーで行うことができます。

#define WEAVE_CONFIG_MERCURY_NAMESPACE kWeaveManagedNamespace_Current

そして、管理対象外のインクルードパスを使用します。

#include

対象の API のマネージド Namespace の指定が変更された場合（たとえば Current から Legacy など）、プリプロセッサの定義を調整してリターゲティングします。

#define WEAVE_CONFIG_MERCURY_NAMESPACE kWeaveManagedNamespace_Legacy