1. Homepage
  2. Mule SDK (1.1)
  3. Java SDK
  4. 高度なパラメーター処理

  5. 値プロバイダー

値プロバイダー

コネクタを開発する場合、エンドユーザーが値セットからパラメーターを選択できるようにすることができます。これにより、ユーザーは何を設定するかを容易に知ることができ、開発者は設定される値が正しいことに確信が持てます。

Java 列挙​をパラメーターとして使用して、この機能を既知の値に対して提供できます。SDK が列挙からすべての値を自動的に取得するため、値を UI のコンボセレクターとして提供できます。

カスタム値など、既知ではない値を含めるには、代わりに​値プロバイダー​を使用する必要があります。

パラメーターの動的データ型を検出する​メタデータ​とは異なり、この機能はパラメーターで指定できる値を提供するように設計されています。

Java 列挙

次のロールを使用してコンテンツをパブリッシュできるコンテンツパブリッシュサービス用のコネクタを開発しているとします。

  • ADMIN​

  • READER​

  • WRITER

これらのロールを提供するには、次のように、​UserRole​ 列挙を作成して ​publishAs​ 操作のパラメーターとして公開します。

例: 既知のロールを定義する Java 列挙
public enum UserRole {
    ADMIN, READER, WRITER
}

次の例の操作メソッドでは、ユーザーは特定の ​UserRole​ を使用してコンテンツをパブリッシュできます。

public void publishAs(@Content Object content, UserRole roleEnum){
    System.out.println("Publishing " + content + " with Role: " + roleEnum);
}

このソリューションは容易であり効果的ですが、いくつかの制限事項と問題があります。

  • カスタム値をサポートしない。パラメーターが列挙に基づくため、カスタム値を定義できません。たとえば、カスタムロールを使用して接続先のサービスを設定できる場合、コネクタの機能が制限されるため、​UserRole​ 列挙を引き続き使用することはできません。

  • 値が静的に定義される。接続や設定に応じて値を変更することはできません。

  • Java 列挙の命名に制限がある。列挙値を数字または特殊文字で始めることはできません。

カスタムロールが必要で、既知のユーザーロールのドロップダウンリストも使用する必要がある場合は、​値プロバイダー​を使用して、動的値と既知の値に対応できます。

値プロバイダー

値プロバイダーは、コネクタのあらゆるコンポーネント (​操作​、​ソース​、​設定​、​接続プロバイダー​、スコープなど) 内のあらゆるパラメーターに値を動的かつスマートな方法で提供するためのメカニズムです。

値プロバイダーを実装する方法

次の例では、上記の列挙ソリューションと同じ動作が生成されますが、値の開集合のメリットがあります。これはカスタム値をサポートします。

  1. ​​ValueProvider​ を実装する Java クラスを作成します。

    このインターフェースを実装する場合、​値​のセットを返す ​resolve()​ メソッドを実装する必要があります。

    public class StaticUserRoleValueProvider implements ValueProvider {

    @Override
    public Set<Value> resolve() {
        return ValueBuilder.getValuesFor("ADMIN", "READER", "WRITER");
    }
}

  2. 動的値を必要とするパラメーターを ​@OfValues()​ アノテーションでマークします。

    @OfValues​ には、パラメーターにバインドされる ​ValueProvider​ 実装が必要です。 たとえば、次の操作メソッド ​publishAs​ にはこのようなバインディングが含まれています。

    public void publishAs(@Content Object content,
@OfValues(StaticUserRoleValueProvider.class) String userRole){ (1)
    System.out.println("Publishing " + content + " with Role: " + userRole);
}

  3. これを Studio または Design Center で使用して、値の取得を開始できるようになりました。

    value provider static

接続または設定を使用した値プロバイダー

値プロバイダーは接続および設定を受け取ることができます。これにより、現在の接続および設定に基づいて値を解決できます。

接続および設定パラメーターに配置されている値プロバイダーに接続および設定を挿入することはできません。

接続または設定の受け取り

@Connection​ および ​@Config​ アノテーションを使用して、値プロバイダー内での接続および設定の使用を宣言します。これらのアノテーションを使用する値プロバイダーが正常に機能するには、設定または接続が​有効である​ことが必要です。SDK では、接続と設定が有効でない限り、解決ロジックは実行されません。

public class ConnectedValueProvider implements ValueProvider {

  @Connection
  ServiceConnection connection;

  @Config
  ServiceConfig config;

  @Override
  public Set<Value> resolve() throws ValueResolvingException {
    //Do whatever is required with the connection or config
    List<String> result = connection.retrieveInfo();
    return ValueBuilder.getValuesFor(result);
  }
}
挿入する接続と設定の型は、値プロバイダーを参照する操作またはソースで定義された型と互換性がある必要があります。

例 2: 接続された値プロバイダーのユースケース

上記のロールの例では、サービスでカスタムロールを定義できましたが、コネクタがそれらのロールを伝達することはできませんでした。

稼働中の接続を介して値を解決するように値プロバイダーを実装すると、使用可能なロールをフェッチし、値プロバイダーを介してロールを伝達できるようになります。

public class UserRoleValueProvider implements ValueProvider {

  @Connection
  ServiceConnection connection;

  @Override
  public Set<Value> resolve() throws ValueResolvingException {
    return ValueBuilder.getValuesFor(connection.getAvailableRoles());
  }
}

他のパラメーターに依存する値プロバイダー

接続と設定を挿入することに加えて、値プロバイダーは、​​同じコンテキスト​​の他のパラメーターに依存することができます。SDK では、必須パラメーターが設定されるまで、値プロバイダーの解決ロジックは実行されません。

「​同じコンテキスト​」とは、値プロバイダーをコンポーネントで使用する場合、そのコンポーネントに必須パラメーターが存在する必要があることを意味します。たとえば、パラメーター ​dynamicParam​ 内で値プロバイダーを使用する設定 ​FancyConfig​ でパラメーター ​aConfigParam​ の値を必要とする場合、​aConfigParam​ が ​FancyConfig​ 設定に存在する必要があります。

必須パラメーターで式を使用すると、アクティブなイベントなしでは式を解決できないために値プロバイダーの実行が無効になる場合があります。

必須パラメーターの宣言

コネクタや設定の場合と同様に、​@Parameter​ アノテーションを使用して、解決ロジックの実行に必要なパラメーターを宣言します。次の例の ​String requiredParam​ など、必須パラメーターと​​同じ型と名前​​の値プロバイダーの項目でアノテーションを使用します。

外部パラメーターの例: 2 つのパラメーターを宣言する操作 (1 つは値プロバイダーを使用)
public void operationWithValueProvider(String requiredParam, @OfValues(ValueProviderWithRequiredParams.class) String dynamicParam){

}
外部パラメーターの例: requiredParam​ パラメーターを必要とする値プロバイダー
public class ValueProviderWithRequiredParams implements ValueProvider {

    @Parameter
    String requiredParam;

    @Override
    public Set<Value> resolve() {
      return ValuesBuilder.getValuesFor(param);
    }
}
必須パラメーターが設定されていない場合

コンポーネントで必須として定義されたパラメーターをエンドユーザーが設定しない場合、値プロバイダーは実行されません。ただし、パラメーターが省略可能として定義されている場合、値プロバイダーは ​Null​ 値を使用して実行されるため、null に対応する処理が必要です。

例 3: コンテキストパラメーターを使用する値プロバイダー

日と月の日付ピッカーが必要なケースを考えてみます。 2 つの列挙を使用すればこれを容易に表すことができますが、すべての月の日数が同じであるわけではありません。そのため、この表現で、ユーザーが無効な日付を設定できるようにします。

この問題を修正する手順は、次のとおりです。

  1. 日付ピッカーを公開する操作を定義します。

    この操作は 2 つのパラメーターを受け取ります。使用可能なすべての月を静的に伝達する ​monthEnum​ と、月の日付を伝達するために使用する ​day​ です。

    Publish On Date (パブリッシュ日) 操作
    public void publishOnDate(Month monthEnum, @OfValues(DayValueProvider.class) String day) {
}

  2. ​​Month​ 列挙を定義します。

    ​​Month​ は、使用可能なすべての月を含み、各月の日数を特定します。

    MonthEnum 列挙
    public enum Month {

    JANUARY(31), FEBRUARY(28), MARCH(31), APRIL(30), MAY(31), JUNE(30),
    JULY(31), AUGUST(31), SEPTEMBER(30), OCTOBER(31), NOVEMBER(30), DECEMBER(31);

    private int dayCount;

    MonthEnum(int i) {
        dayCount = i;
    }

    public int getDayCount() {
        return dayCount;
    }
}

  3. 選択された月をコンシュームする値プロバイダーを作成します。

    選択された月に応じて、値プロバイダーは、その月で使用可能なすべての日を動的に提供します。​DayValueProvider​ は、動作するには ​monthEnum​ が必要であることを示します。

    public class DayValueProvider implements ValueProvider {

    @Parameter
    Month monthEnum; (1)

    @Override
    public Set<Value> resolve() {
      return ValueBuilder.getValuesFor(getNumbersFrom(1, monthEnum.getDayCount())
              .stream()
              .map(num -> String.format("%02d", num)));
    }

    List<Integer> getNumbersFrom(int init, int end){
        List<Integer> numbers = new ArrayList<>(end - init);
        for (int i = init; i <= end; i++) {
            numbers.add(i);
        }
        return numbers;
    }
}

  4. 結果は次のようになります。

    次のアニメーションで示されているように、​Day​ セレクターは、​Month enum​ パラメーターの値に基づいて動的に入力されます。

    value provider months

値構造

値プロバイダーは値のセットを返します。​Value​ は、次のプロパティで構成される単純な構造です。

  • id​ : この値の一意の識別子。これは必須です。

  • displayName​: UI に表示される名前。これは省略可能です。デフォルトでは、ID が表示名として使用されます。

値の作成方法

ValueBuilder​ を使用して値を作成するための独自の方法があります。

ValueBuilder adminValueBuilder = ValueBuilder.newValue("ADMIN_USR_ROLE"); (1)
adminValueBuilder.withDisplayName("Admin"); (2)
Value adminValue = newValue.build(); (3)
1 Value​ の ID を使用して ​ValueBuilder​ を作成する必要があります。
2 必要に応じて、表示名を使用して値を強化することができます。
3 Value​ インスタンスを返すためのビルダーを作成します。

ValueBuilder ユーティリティ

ValueBuilder​ は、特定のケースで値の作成を容易にするユーティリティを提供します。

Values に変換する必要がある値を含む ​List<String>​、​String[]​、​Stream<String>​、または ​Map<String, String>​ がある場合、この変換を行う最も簡単な方法は、​getValuesFor()​ を使用することです。

// Array Case
Set<Value> arrayCase = ValueBuilder.getValuesFor("Admin", "Writer");

// List Case
List<String> valueList = new ArrayList<>();
valueList.add("Admin");
valueList.add("Writer");
Set<Value> listCase = ValueBuilder.getValuesFor(valueList);

// Stream Case
Set<Value> streamCase = ValueBuilder.getValuesFor(valueList.stream());

// Map Case
// The Key will be considered as ID and the Value as Display Name
Map<String, String> valueMap = new HashMap<>();
valueMap.put("ADMIN_USR_ROLE", "Admin");
valueMap.put("WRITER_USR_ROLE") "Writer");
Set<Value> mapCase = ValueBuilder.getValuesFor(valueMap);