項目レベルの機能

Java SDK には、値プロバイダーとサンプルデータでの項目レベルの機能をサポートするいくつかの機能が含まれています。これらの機能を使用すると、パラメーター項目の値プロバイダーを定義したり、パラメーター項目を値プロバイダーまたはサンプルデータの代理パラメーターとして使用したりできます。

これらの機能は Mule 4.4.0 と互換性がありますが、Mule バージョンに関係なく、すべての Anypoint Connector で使用できます。

パラメーターの一部に対する値プロバイダーの定義

アノテーション @FieldValues を使用して、パラメーター項目の値プロバイダーを定義します。

@FieldValues アノテーションには次の情報が必要です。

value

項目の値を提供します。
targetSelectors

値プロバイダーによって提供された値がパラメーターのどの部分に含まれるかを説明します。 DataWeave 構文では、アノテーションのこの部分を定義し、ネストされた項目、XML 属性、または名前にスペースを含む項目を介してセレクターを説明します。

次の例は、JSON 入力ストリームである body というパラメーターに指定された値を含む操作を示しています。

public class ChatOperations {
 public void sendChatMessage(@Connection ChatConnection chatConnection,
       @FieldValues(value = WorkspacesValueProvider.class, targetSelectors = "routingInfo.workspace")
       @TypeResolver(ChatMessageResolver.class) @Content InputStream body) {
    // Do message sending
  }
}

body パラメーターには、routingInfo という項目があり、この項目には workspace という項目があります。WorkspacesValueProvider は、接続を使用して可能なワークスペースを取得する値プロバイダーです。

パラメーターのいくつかの部分に対する値プロバイダーの定義

パラメーターには、値が提供される部分を複数使用できます。 @FieldValues アノテーションは繰り返し可能なアノテーションであるため、パラメーターに複数回アノテーションを付けることができます。

次の例は、body というパラメーターを使用した操作を示しています。このパラメーターは、値プロバイダーで 2 つの部分を使用する JSON 入力ストリームです。

public class ChatOperations {
 public void sendChatMessage(@Connection ChatConnection chatConnection,
       @FieldValues(value = WorkspacesValueProvider.class, targetSelectors = "routingInfo.workspace")
       @FieldValues(value = ChannelIdValueProvider.class, targetSelectors = "channelId")
       @TypeResolver(ChatMessageResolver.class) @Content InputStream body) {
    // Do message sending
  }
}

パラメーター body は、相互に独立した値を持つ 2 つの項目 (routingInfo.workspace と channelId) の値を定義します。

パラメーターのいくつかの部分に対するマルチレベル値プロバイダーの定義

パラメーターのいくつかの部分に対してマルチレベル値プロバイダーを使用します。

たとえば、channelId 項目の値を routingInfo.workspace 項目の値に連動させるとします。

これを定義するため、@FieldValues アノテーションの targetSelectors 属性は常に文字列の配列を受け取ります。複数の文字列が指定されている場合は、マルチレベル値プロバイダーが定義されます。指定された各項目では、値プロバイダーの値部分、配列内の順序、および値部分の順序を定義します。

次の例は、パラメーター部分のマルチレベル値プロバイダーを定義する方法を示しています。

public class ChatOperations {
 public void sendChatMessage(@Connection ChatConnection chatConnection,
      @FieldValues(value = ChatMultiLevelValueProvider.class,  targetSelectors = {"workspace", "channelId"})
      @TypeResolver(ChatMessageResolver.class) @Content InputStream body) {}
}

マルチレベル値プロバイダーは、他の値プロバイダーと同様に含まれています。

次の例は、マルチレベル値プロバイダーがどのように表示されるかを示しています。

public class ChatMultiLevelValueProvider implements ValueProvider {

 @Connection
 private ChatConnection chatConnection;

 @Override
 public Set<Value> resolve() {
   Set<Value> values = new HashSet<>();
   List<String> workspaces = chatConnection.getWorkspaces();
   workspaces.stream().forEach(workspace -> {
     ValueBuilder valueBuilder = newValue(workspace);
     chatConnection.getChannels(workspace).stream().forEach(channel -> valueBuilder.withChild(newValue(channel)));
     values.add(valueBuilder.build());
   });
   return values;
 }

 @Override
 public String getId() {
   return "Chat multilevel value provider";
 }
}

XML 属性に対する値プロバイダーの定義

対象セレクターは DataWeave 構文を使用します。操作のパラメーターが XML 要素である場合、この構文を使用して、そのパラメーターの一部である属性の値プロバイダーを定義します。

次の例は、DataWeave 構文で属性の値プロバイダーを定義する方法を示しています。

public class ChatOperations {
 public void sendChatMessage(@Connection ChatConnection chatConnection,
      @FieldValues(value = ChannelIdValueProvider.class,  targetSelectors = "message.target.@channelId")
      @TypeResolver(XmlChatMessageResolver.class) @Content InputStream body) {}
}

この例では、body パラメーターは message というルートタグを含む XML 要素です。これには、channelId 属性を使用する target、および関連付けられた値プロバイダーが含まれます。

パラメーター静的メタデータ

代理パラメーター値を解決するときは、抽出式を実行し、代理パラメーターにその値を提供するコンポーネントからのパラメーターのメディアタイプを常に把握します。

パラメーターの静的メタデータを使用して、パラメーターのメディアタイプを取得します。たとえば、パラメーターが JSON 入力ストリームで、静的メタデータがこれを反映していない場合、パラメーターの一部を代理パラメーターとして使用することはできません。

パラメーターの一部としての代理パラメーターの定義

代理パラメーターをパラメーターの一部として定義するには、コンポーネントで値プロバイダーおよびサンプルデータプロバイダーに対する参照のバインドを定義する必要があります。これらのバインドにより、プロバイダーの代理パラメーターが評価済みの DataWeave 式の値を取得できるようになります。

代理パラメーターに対するバインドが定義されていない場合、同じ暗黙的なバインドが適用されます。代理パラメーターの名前は、そのパラメーターの値を取得するためにコンポーネント内のパラメーターの名前と同じである必要があります。

@Binding アノテーションを使用して、代理パラメーターを定義します。@FieldValues アノテーションと @SampleData アノテーションは、代理パラメーターが取得する値を定義するためにバインドの配列を取得します。

定義されたバインドは、抽出式を提供することで代理パラメーターが取得する値を宣言します。この抽出式は、セレクターのみを使用して代理パラメーターの値を取得する DataWeave 式です。

代理パラメーターの値の抽出に使用される抽出式には、いくつかの制限があります。

コンテキストからのデータは集約されません。パラメーター内の項目の値のみにアクセスするように制限されています。
抽出式の最初の部分は、コンポーネントのパラメーターの名前にのみ対応します。
抽出式を実行して値プロバイダーまたはサンプルデータプロバイダーの代理パラメーターに値を提供する場合、出力メディアタイプは常に application/java です。これは、プロバイダーが application/json または application/xml などの他のメディアタイプを想定していないことを意味します。

式で使用可能なコンテキストには、すべてのコンポーネントのパラメーターの値があります。式は、コンポーネントのパラメーターの名前で始まる必要があります。値がパラメーターの一部から取得されている場合、式はセレクターに従って目的の項目に移動します。

次の例は、代理パラメーター workspace に連動する値を持つ項目を含む body というパラメーターを示しています。

public class ChatOperations {
 public void sendChatMessage(@Connection ChatConnection chatConnection,
       @FieldValues(value = ChannelsValueProvider.class, targetSelectors = "channelId",
     bindings = {@Binding(actingParameter = "workspace",  extractionExpression = "body.routingInfo.workspace")}))
       @TypeResolver(ChatMessageResolver.class) @Content InputStream body) {
    // Do message sending
  }
}

この代理パラメーターは、同じ body パラメーターから取得されます。

次の構文は、この例で使用される値プロバイダーを示しています。

public class ChannelsValueProvider implements ValueProvider {

 @Connection
 private ChatConnection chatConnection;

 @Parameter
 private String workspace;

 @Override
 public Set<Value> resolve() {
   return ValueBuilder.getValuesFor(chatConnection.getChannels(workspace));
 }

 @Override
 public String getId() {
   return "Channels value provider";
 }
}

値プロバイダーで定義された workspace 代理パラメーターは、コンポーネントのコンテキストから項目の値を取得する抽出式にバインドされます。

サンプルデータの例

次の例は、代理パラメーターをコンポーネント内のパラメーターの項目の値にバインドする @SampleData アノテーションを示しています。

public class ChatOperations {
@SampleData(value = ChatMessageSampleDatatProvider.class, bindings = {@Binding(actingParameter = "workspace",  extractionExpression = "body.routingInfo.workspace")}))
 public Result<InputStream, ChatAttributes> retrieveChatMessage(@Connection ChatConnection chatConnection,
         @TypeResolver(ChatMessageResolver.class) @Content InputStream body) {
    // Do chat message retrieval
  }
}

ChatMessageSampleDatatProvider には、サンプルデータを提供する workspace というパラメーターが含まれています。この代理パラメーターの値は、バインドで定義された抽出式から取得されます。