DataSense Query Language の追加

DevKit は、Studio 6 および Mule 3 とのみ互換性があります。Mule 4 Connector を作成するには、「Mule SDK」ドキュメントを参照してください。

多くの SaaS アプリケーションは、SOQL や Salesforce Object Query Language などの適切なクエリ言語を実装するか、クエリに対応する方法で API を介してリソースを選択することをサポートします。DataSense Query Language (DSQL) は統一されたクエリ言語を提供しているため、互換性のある Anypoint™ Connector を使用して任意のアプリケーションでデータを照会できます。

ソースコード

前提条件

Anypoint Connector、DataSense、DataSense クエリエディタ、およびユーザレベルからの DataSense Query Language の追加の理解。
Java の「@」アノテーションの理解。 Anypoint DevKit API リファレンスを参照してください。
Anypoint DevKit を使用した基本的なコネクタの実装経験。
DSQL からネイティブクエリ言語への変換の仕組みの基礎となる visitor パターンの理解。情報:
- Java の例を使用した Visitor パターンのチュートリアル
- 「Visitor パターン」 Wikipedia 記事

コネクタでの DSQL の有効化

コネクタで DSQL を有効にする方法

DataSense (@MetaDataKeyRetriever および @MetaDataRetriever のアノテーションが追加されたメソッドを含む) を有効にする。
変換に使用する @QueryTranslator のアノテーションが付加された新しいメソッドを作成する。このメソッドは、その入力として org.mule.common.query.DsqlQuery オブジェクトを受け取る必要があります。
ユーザが DSQL ステートメントを入力できる @Query のアノテーションをパラメータに付加する。

このリストの最後の 2 つの項目については、このドキュメントの後半で説明します。

DSQL 構造の理解

標準の SQL 操作 (Select、Delete、Update、Insert) のうち、DSQL でサポートされるのは SELECT のみです。

すべての DSQL ステートメントは次の構造に従う必要があります。

SELECT [selectedFieldName, ]
FROM [Type]
WHERE ( [ fieldName OPERATION value, AND ] )
{ ORDER BY [fieldName, ] { DESC | ASC } }
{ OFFSET [offset_number] }
{ LIMIT [max_number_total_of_items_in_query] }

キー:

{} 省略可能な値
[] 動的値
[, ] 値の動的リスト

「DataSense Query Language の追加」ドキュメントの DSQL クエリの例を考えてみます。

Mule は内部クエリモデルを使用して、クエリを構成するさまざまなセマンティック要素を表します。

Object (オブジェクト) 例コメント

Object (オブジェクト)	例	コメント
選択済みの項目	`SELECT AccountID, FirstName, LastName`	項目のリスト。各項目は、メタデータ (項目名とデータ型) を表します。
型	`FROM Contact`	アプリケーションによって公開されたオブジェクト。これは常に 1 つの種別のリストです。
検索条件式	`WHERE (AccountID > '500' AND IsDeleted = false) OR Employee_Current = false`	オブジェクト種別の項目に対して定義された Boolean 条件。
並び替え順項目のリスト	`ORDER BY LastName`
Offset (オフセット)	`OFFSET 250`	結果セットの先頭からスキップする項目数。ページングに使用します。
Limit (制限)	`LIMIT 1000`	結果セットに含める項目数。ページングに使用します。

選択済みの項目

SELECT AccountID, FirstName, LastName

項目のリスト。各項目は、メタデータ (項目名とデータ型) を表します。

型

FROM Contact

アプリケーションによって公開されたオブジェクト。これは常に 1 つの種別のリストです。

検索条件式

WHERE

(AccountID > '500'

AND IsDeleted = false)

OR

Employee_Current

= false

オブジェクト種別の項目に対して定義された Boolean 条件。

並び替え順項目のリスト

ORDER BY LastName

Offset (オフセット)

OFFSET 250

結果セットの先頭からスキップする項目数。ページングに使用します。

Limit (制限)

LIMIT 1000

結果セットに含める項目数。ページングに使用します。

同様に、検索条件式は、一連の項目名、データリテラル、区切り文字、比較とグループ化の演算子などによって内部的に表されます。

クエリモデルおよびそれに対するコードからのアクセスについての詳細は、クエリモデルをクエリ言語に変換する新しいネイティブクエリ言語トランスレータをビルドするときに表示されます。

DSQL 構造からの変換

最初のステップは、@QueryTranslator のアノテーションが付加された新しいメソッドを @Connector で作成することです。このメソッドは、その入力として DSQL クエリ (org.mule.common.query.DsqlQuery オブジェクト) を受け取ります。

この変換を簡単にするために利用できる、一連の visitor クラスがあります。

visitor クラスとクエリ言語

一連の visitor クラスは、クエリモデル要素と特定のクエリ言語構文 ( Visitor パターンを実装するクラス) の間のマッピングを実装し、クエリモデルをトラバースし、必要なネイティブクエリ言語で対応するステートメントを生成します。

パッケージ org.mule.common.query は、DSQL クエリ言語のさまざまな部分を表す Visitor インターフェースを定義し、DSQL 構文を実装する Visitor のデフォルト実装を提供します。

Visitor インターフェース実装クラス実装される構文

Visitor インターフェース	実装クラス	実装される構文
`QueryVisitor`	DefaultQueryVisitor DSQLQueryVisitor	「式の先頭」 (検索条件式の前の単語「WHERE」など) 項目リスト型 Limit 句と Offset 句優先順位演算子並び替え項目比較 Boolean 演算子
`OperatorVisitor`	DefaultOperatorVisitor	特定の比較演算子 (equals、not-equals、greater/less than、LIKE など)

QueryVisitor

DefaultQueryVisitor

DSQLQueryVisitor

「式の先頭」 (検索条件式の前の単語「WHERE」など)
項目リスト
型
Limit 句と Offset 句
優先順位演算子
並び替え項目
比較
Boolean 演算子

OperatorVisitor

DefaultOperatorVisitor

特定の比較演算子
(equals、not-equals、greater/less than、LIKE など)

新しいクエリ言語のサポートを実装するには、DefaultQueryVisitor および DefaultOperatorVisitor を拡張するクラスを定義し、それらを使用してクエリモデルからネイティブクエリ言語ステートメントを作成します。新しいクラス MyAppQueryVisitor および MyAppOperatorVisitor に名前を付けることができます。次のセクションでは、それらの作成方法について説明します。

演算子 visitor クラスの実装

新しい演算子 visitor クラスを作成すると、ネイティブクエリ言語の比較演算子構文 (LIKE を含む) を定義できます。

すべての DSQL 比較演算子を実装する DefaultOperatorVisitor を拡張する新しいクラスをコネクタで定義します。

DefaultOperatorVisitor クラスの例:

public class DefaultOperatorVisitor implements OperatorVisitor {
    public static final String LIKE = " like ";
    public static final String GREATER_OR_EQUALS = " >= ";
    public static final String NOT_EQUALS = " <> ";
    public static final String EQUALS = " = ";
    public static final String LESS_OR_EQUALS = " <= ";
    public static final String GREATER = " > ";
    public static final String LESS = " < ";
    @Override public String lessOperator() {
        return LESS;
    }
    @Override public String greaterOperator() {
        return GREATER;
    }
    @Override public String lessOrEqualsOperator() {
        return LESS_OR_EQUALS;
    }
    @Override public String equalsOperator() {
        return EQUALS;
    }
    @Override public String notEqualsOperator() {
        return NOT_EQUALS;
    }
    @Override public String greaterOrEqualsOperator() {
        return GREATER_OR_EQUALS;
    }
    @Override public String likeOperator() {
        return LIKE;
    }
}

ほとんどの言語は、主に同じ演算子を使用します。独自の言語で操作を実装するための最短の方法は、DefaultOperatorVisitor を拡張する新しいクラスを作成し、使用言語が DSQL と異なる場合にそれらの演算子を返すメソッドを上書きすることです。

たとえば、Salesforce.com コネクタでは、クラス SfdcOperatorVisitor は notEqualsOperator(): を上書きします。

import org.mule.common.query.DefaultOperatorVisitor;


public class SfdcOperatorVisitor extends DefaultOperatorVisitor {
 @Override public java.lang.String notEqualsOperator() {
        return " != ";
    }
}

残りの演算子は SOQL と DSQL で同一であるため、その他の変更は必要ありません。

クエリ visitor クラスの実装

新しいクエリ visitor クラスを作成すると、コアのクエリモデル構成をネイティブクエリ言語で表すためのクエリ構文を定義できます。

DefaultQueryVisitor クラスを拡張する新しいクラスをコネクタプロジェクトで作成します。

サービスで次の構文を使用しているとします。

S [selectedFieldName, ]
F [Type]
W ( [ fieldName OPERATION value, & ] )

次の例は、DSQL を構文に変換する visitor を示しています。

public class SimpleSyntaxVisitor extends DefaultQueryVisitor {

    private StringBuilder stringBuilder;

    public SimpleSyntaxVisitor()
    {
        stringBuilder = new StringBuilder();
    }

    @Override
    public void visitFields(java.util.List<org.mule.common.query.Field> fields) {
        StringBuilder select = new StringBuilder();
        select.append("S ");
        Iterator<Field> fieldIterable = fields.iterator();
        while (fieldIterable.hasNext())
        {
            String fieldName = addQuotesIfNeeded(fieldIterable.next().getName());
            select.append(fieldName);
            if (fieldIterable.hasNext())
            {
                select.append(",");
            }
        }

        stringBuilder.insert(0, select);
    }

    @Override
    public void visitTypes(List<Type> types)
    {
        stringBuilder.append(" F ");
        Iterator<Type> typeIterator = types.iterator();
        while (typeIterator.hasNext())
        {
            String typeName = addQuotesIfNeeded(typeIterator.next().getName());
            stringBuilder.append(typeName);
            if (typeIterator.hasNext())
            {
                stringBuilder.append(",");
            }
        }
    }

    //(...)

    @Override
    public void visitBeginExpression()
    {
        stringBuilder.append(" W ");
    }

    public String toSimpleQuery()
    {
        return stringBuilder.toString();
    }
}

この機能を含む完全なコネクタについては、 GitHub リポジトリを参照してください。

@QueryTranslator へのクエリ visitor の追加

@Connector クラスで、visitor クラスのインスタンスを提供し、クエリを返すメソッドをコールする、@QueryTranslator のアノテーションが付加されたメソッドを実装します。

@QueryTranslator
public String toNativeQuery(DsqlQuery query){
    SimpleSyntaxVisitor visitor = new SimpleSyntaxVisitor();
    query.accept(visitor);
    return visitor.dsqlQuery();
}

コネクタユーザへの DSQL の表示方法

コネクタをビルドして Anypoint Studio にインストールすると、そのコネクタは Mule プロジェクトで使用できるようになります。それをフローに追加し、そのプロパティエディタを開きます。

クエリの言語を選択できます。この場合、サービスのネイティブクエリ言語または DSQL を選択できます。DSQL を選択している場合、既存の項目の中から選択するだけで、クエリビルダーツールを使用して自動的にクエリを生成できます。

ビルドしたクエリによって、コネクタの [Query Text (クエリテキスト)] 項目が入力されます。この項目のテキストを編集することもできます。

DSQL でクエリを作成したら、クエリ言語をサービスのネイティブクエリ言語に変更し、変換が正常に実行されていることを確認できます。

DataSense のおかげで、コネクタの後に DataMapper 要素を含めた場合、DataMapper はクエリを解釈し、それによって返される項目のみを表示します。

この場合、DataMapper は firstName 項目のみがある Authors のリストを処理します。

ガートナーが MuleSoft をリーダーとして評価

Salesforce のフルパワーを解放する API 活用術

Anypoint Platform：開発基礎 (無料)

MuleSoft Forum Japan