ThingWorx アプリケーションをパッケージ化および展開する際の最良事例
拡張機能を開発および展開する際には、以下の最良事例を使用します。
クリーンなプラットフォームインスタンスで開発
ThingWorx はコード用のセーフガードやサンドボックスを提供していません。環境が不安定になることも考えられます。アプリケーションの不安定な状態を解消するには、以下の操作を行います。
• 開発プロセスでエラーが発生した場合、Apache Tomcat サーバーを再起動します。
• ThingworxStorage ディレクトリを完全に除去するように求められることがあります。ThingWorxStorage ディレクトリを除去した場合に作業内容が失われないようにするため、クリーンなプラットフォームインスタンスでアプリケーションを開発することをお勧めします。
拡張機能の構造
拡張機能の成果物は以下のフォルダ構造で ZIP ファイルにパッケージ化されていなければなりません。
• /metadata.xml - 拡張機能に関する情報および拡張機能内の各種成果物に関する詳細。
• /Entities/ - エンティティタイプ別にサブフォルダに整理されたゼロ個以上のエンティティ XML ファイル。
• /lib/ - 拡張機能のカスタム Java クラスが含まれている JAR ファイル、および拡張機能が必要とするサードパーティ JAR ファイル。
• /ui/ - マッシュアップの構築および実行に使用されるカスタムウィジェットを定義するファイル。
アプリケーションの 1 つの ZIP ファイルに複数の拡張機能をバンドル
複数の拡張機能が含まれている IoT ソリューションを単一の ZIP ファイルとしてバンドルできます。単一の ZIP ファイルに拡張機能ごとに別個の ZIP ファイルが含まれています。これによって、各拡張機能が独立して実装されます。以降のリリースでの更新は拡張機能ごとに行った方が簡単です。
拡張機能の名前とバージョンの変換
拡張機能および拡張機能の ZIP ファイルの命名方法に制約はありません。拡張機能に名前を指定した後で、変更することはできません。ただし、ZIP ファイルの名前は変更できます。
拡張機能とその ZIP ファイルに別の名前を指定することは可能ですが、拡張機能とその ZIP ファイルには同じ名前を指定することをお勧めします。ZIP ファイルの名前にはバージョン番号を含めることもできます。
複数の拡張機能が ZIP の ZIP としてバンドルされている IoT ソリューションを作成できます。この場合、すべての ZIP を同じリリース番号にすることをお勧めします。2 つの拡張機能が含まれている IoT ソリューションがあるとします。単一の ZIP ファイル内の拡張機能それぞれにリリース番号が付いています。2 つの拡張機能の名前で同じリリース番号を指定するようにします。さらに、ZIP の ZIP の名前で同じリリース番号を指定します。たとえば、IoT ソリューションのリリース番号が 7.9 である場合、すべての ZIP ファイルの名前でリリース番号として 7.9 を指定します。
metadata.xml ファイルでは、拡張機能のバージョンの指定に属性
packageVersion が使用されます。これは必須の属性であり、その値は
<major>.<minor>.<patch> というフォーマットに従い、ここでバージョンの各部分は数値です。拡張機能はセマンティックバージョン管理規則に従わなければなりません。詳細については、
セマンティックバージョン管理を参照してください。
拡張機能の依存性
このセクションでは、ほかの拡張機能への拡張機能の依存について説明します。
ほかの拡張機能への拡張機能の依存
拡張機能がほかの拡張機能に依存している場合、metadata.xml ファイル内の dependsOn 属性を使用して依存を指定することをお勧めします。この属性の値は <name>:<major>.<minor>.<patch> というフォーマットで拡張機能の名前およびバージョンがコンマで区切ってリストされたものであり、各バージョンは数値でのみ指定します。例: dependsOn= "ExtensionOne:2.5.1,ExtensionTwo:1.2.0"
あまり多くの依存を指定しないようにします。拡張機能がアップグレードされた場合、それに依存する拡張機能も影響を受けます。
ほかの拡張機能への緊密な関連を避ける
拡張機能とほかの拡張機能との関連を緊密にしないようにします。
• お使いの拡張機能が新規メジャーバージョンにアップグレードしなければならない別の拡張機能と緊密に関連している場合、アップグレードを実行する前にお使いの拡張機能およびその依存チェーン全体を削除するように求められます。
• 緊密な関連を避ける最も良い方法としては、必要な機能の Thing および Thing Template を作成します。これらの Thing および Thing Template は拡張機能の一部ではないので、拡張機能のアップグレードに含まれません。
• 拡張機能マッシュアップでほかの拡張機能のウィジェットを使用している場合、緊密な関連を避けることが困難なこともあります。
拡張機能のサイズ
大きくて複雑な拡張機能はメンテナンスとアップグレードが困難な場合があります。機能に基づいて拡張機能を小さなコンポーネントに分割することで、メンテナンスとアップグレードが容易になります。複数の拡張機能を単一の ZIP ファイルにバンドルできます。詳細については、
アプリケーションの 1 つの ZIP ファイルに複数の拡張機能をバンドルのセクションを参照してください。
拡張機能で外部 JAR ファイルを使用
ThingWorx ではサードパーティライブラリをコードに含めることができます。ただし、共通の JAR ファイルは使用しないようにします。代わりに、アプリケーション内に SDK とともにパッケージ化されている JAR ファイルを使用します。次の点を考慮します。
• /Thingworx/WEB-INF/lib フォルダにある既存の JAR ファイルを拡張機能で使用できます。ただし、外部 JAR ファイルを拡張機能で使用する場合は、その JAR ファイルのルート名が、/Thingworx/WEB-INF/lib フォルダにあるほかの JAR ファイルと同じであってはなりません。
JAR ファイルのルート名は、ファイル名の最初の文字から最初の数字までの名前です。このテーブルは、/Thingworx/WEB-INF/lib フォルダにある次の JAR ファイルのルート名を示しています。
|
JAR ファイル名
|
Root Name
|
|
postgresql-42.2.5.jar
|
postgresql-
|
|
log4j-1.2.17.jar
|
log
|
|
metrics-core-3.1.2.jar
|
metrics-core-
|
• ThingWorx Platform では、複数のソースが同じ JAR ファイルを使用できます。
• 複数のソースが同じ JAR ファイルを使用している場合、拡張機能をプラットフォームにアップロードする際や、拡張機能の構築中に間違ったバージョンの JAR が使用された場合、競合が発生することがあります。
• プラットフォームの将来のバージョンで作業を続行するためには拡張機能を更新する必要が生じることがあります。
• 顧客は同じ JAR ファイルを必要とする 2 つの拡張機能を同時に使用することはできません。
エンティティを編集不可能にする
マッシュアップやスタイル定義などのエンティティを作成する際には、拡張機能のエンティティを編集不可能にします。編集不可能なエンティティだけをその場でアップグレードできます。編集可能なエンティティはアップグレードできません。デフォルトでは、新規エンティティは編集不可能です。
• 一部のエンティティを編集可能にする場合、それらのエンティティを別個の拡張機能にバンドルして、拡張機能のほかのコンポーネントを簡単にアップグレードできるようにします。
• 編集可能なエンティティでは、マッシュアップ上の編集可能な場所を最小限にすることをお勧めします。編集可能な場所を最小限にするには、埋め込みマッシュアップを使用します。
カスタムロゴを追加するなど、拡張機能をカスタマイズ可能にする場合、代替アプローチが機能するかどうかについて検討します。
• Thing のコンフィギュレーションを代わりに使用できるか? 編集不可能な Thing でもコンフィギュレーションテーブルの変更は可能です。
• サービスを使用して、メディアエンティティまたは埋め込みマッシュアップを提供するコンフィギュレーションを検索できるか?
編集可能なエンティティが含まれている拡張機能をアップグレード
編集可能なエンティティが含まれている拡張機能をアップグレードする際には、マイグレーションテストを実行して、アップグレードプロセス中にタグなどの情報が失われないかチェックします。
エンティティを整理
プロジェクトおよびモデルタグを使用してエンティティをグループ化することをお勧めします。拡張機能のすべてのエンティティに 1 つのプロジェクトを使用しなければなりません。拡張機能のすべてのエンティティへのタグ付けに使用可能な 1 つ以上のモデルタグを作成します。
削除する前にストレージをバックアップ
現在の ThingworxStorage フォルダを削除する前にバックアップすることをお勧めします。
Eclipse プラグイン
Eclipse プラグインを使用することで、拡張機能を簡単に開発および構築できます。これはソースファイル、アノテーション、メソッドを自動的に生成する操作を提供します。これらの操作によってメタデータファイルも更新され、拡張機能の適切なコンフィギュレーションが維持されます。このプラグインによって、アノテーションおよびメタデータファイルの構文とフォーマットも正しく維持されます。