メタデータキーパラメーター

動的メタデータ構造を記述するには、どの型を表現するのかを知る必要があります。この型の参照を定義するには、記述する型 (Account など) の ID を含む @MetadataKeyId パラメーターを操作で指定します。この ID は、そのパラメーターで定義されているメタデータリゾルバーに渡されます。

たとえば、汎用レコードをリモートシステムに保存する操作があるとして、サポートされる型として Account や Organization を記述しておけば、デザインしやすくなります。この場合は、操作のパラメーターの 1 つに ID として Account または Organization を含む型の参照を定義します。このパラメーターは、バケットに保存するレコードの Account 構造または Organization 構造 (エンドユーザーが使うと決めた方) を記述します。

メタデータキーのリストの提供

動的メタデータを解決する最も一般的なケースでは、解決される可能性のある各型を特定するキーの動的セットを用意します。エンドユーザーが設計時にコネクタを設定する際には、操作を選択してから、動的に入力されるキーをセットから選択すると、そのキーがメタデータ解決の MetadataKeyId になります。

動的キーの解決を実装するには、まず TypeKeysResolver を宣言します。

public class RecordKeysResolver implements TypeKeysResolver {

  @Override
  public String getCategoryName() {
    return "Records";
  }

  @Override
  public Set<MetadataKey> getKeys(MetadataContext context) throws MetadataResolvingException, ConnectionException {
     // First we need to obtain the key IDs that will be used.
     // This is where you'd normally use `context.getConfig()`
     // or `context.getConnection()` to obtain the entity id's
     // from a remote service, for this demo the keys will be fixed
     List<String> keyIds = Arrays.asList("Author_id", "BookList_id", "Book_id");

     HashSet<MetadataKey> keys = new HashSet<>();
     for (String id: keyIds){
       // For each possible if, we create a new MetadataKey with that ID
       MetadataKeyBuilder builder = MetadataKeyBuilder.newKey(id);

       // Then, we add a DisplayName to that MetadataKey,
       // this will be the name shown in the UI
       builder.withDisplayName(StringUtils.removeEnd(id, "_id"));

       //finally, add the key to the Set of known MetadataKeys
       keys.add(builder.build());
     }

     return keys;
  }

}

上の例では、MetadataKey の動的セットを作成するのに必要なすべての要素が定義されています。実装するメソッドは getKeys で、利用可能なすべてのキーをユーザーに出力します。

Author_id などの id 要素は内部で使用され、表現したい構造に対してすべてのリゾルバーにおいて一意である必要があります。displayName は、ユーザーに表示するキーの名前であるため、わかりやすく読みやすい名前にしてください。

リゾルバーを定義したら、クラス定義レベルでその keysResolver 値を使用して @MetadataScope アノテーションを追加し、キーであるパラメーターに @MetadataKeyId アノテーションを付けることで、リゾルバーを操作またはソースとして使用できます。すべてのメタデータリゾルバーは、操作またはソースの同じカテゴリに属している必要があります。

@MetadataScope(keysResolver = RecordKeysResolver.class)
public class OperationWithMetadataKey {

    public void create(@MetadataKeyId String type,
                       @Config MyConfig config){
        //...
    }
}

@MetadataScope(keysResolver = RecordKeysResolver.class)
public class DocsMetadataSource extends Source<Map<String, Object>, Void> {

    @MetadataKeyId
    @Parameter
    public String type;

    //...
  }

前の例は、ソースのメタデータキーをサポートする唯一の方法です。ソースを定義するときに、@MetadataKeyId アノテーションでリゾルバーを設定しないでください。

操作クラス定義レベルで @MetadataScope アノテーションを設定すると、そのすべての操作でメタデータが提供され、スコープからリゾルバーを継承するため、すべての操作に @MetadataKeyId アノテーションが付いたパラメーターが必要であることを示します。

1 つの操作に対してキーリゾルバーを設定することもできます。

public class MyOperations {

    public void operationWithMetadataKey(@MetadataKeyId(RecordKeysResolver.class) String type,
                       @Config MyConfig config){
        //...
    }

    public void plainOperation(@Config MyConfig config){
        //...
    }
}

さらに、操作クラス定義レベルで @MetadataScope アノテーションがある場合は、パラメーターに @MetadataKeyId アノテーションの値を設定し、1 つの操作に対してスコープレベルで定義されたリゾルバーを上書きできます。

@MetadataScope(keysResolver = ClassLevelResolver.class)
public class MyOperations {

    public void operation(@MetadataKeyId String type, @Config MyConfig config){
        // This operation will use the ClassLevelResolver
    }

    public void operationWithAnotherResolver(@MetadataKeyId(OverridingResolver.class) String type,
                       @Config MyConfig config){
        // This operation will use the OverridingResolver
    }
}

前の 2 つの例 (パラメーターレベルでのリゾルバーの設定、およびスコープから継承されたリゾルバーの上書き) は、操作を定義するときにのみ動作します。これらの機能はソースでは使用できません。

ユーザー定義の MetadataKey

ユーザー定義の MetadataKey は、エンドユーザーが自由に提供できるキーであり、潜在的な要素のリストでは定義されません。

たとえば、クエリでは非常によくあるケースですが、エンドユーザーが実行したいクエリ全体を MetadataKey として使用します。

ユーザー定義の MetadataKey を宣言するには、パラメーターアノテーション、またはクラス定義で存在する場合は @MetadataScope アノテーションに対して TypesKeyResolver を指定せずに、パラメーターに @MetadataKeyId アノテーションを付けます。

public class MyOperations {

  public void query(@MetadataKeyId String query){
      //...
  }
}

省略可能な MetadataKey パラメーター

バージョン 1.3 以降で使用できます。

MetadataKey パラメーターは、他のパラメーターと同じように @Optional アノテーションを付けて省略可能にすることができます。

public void query(@MetadataKeyId @Optional String query){
 //...
}

省略可能な MetadataKey パラメーターに値が割り当てられていない場合は、null を MetadataKey 値としてメタデータコールが行われます。そのため、この MetadataKey パラメーターに関連付けられているすべての MetadataResolver パラメーターは、Null 値を受け取ることができるようにしておく必要があります。