エンティティーおよびオブジェクトの取得 (Query API)

WebSphere® eXtreme Scale は、EntityManager API を使用したエンティティーの検索、および ObjectQuery API を使用した Java オブジェクトの検索用の柔軟な照会エンジンを提供します。

WebSphere eXtreme Scale の照会機能

eXtreme Scale 照会エンジンを使用すると、eXtreme Scale 照会言語を使用して、エンティティーまたはオブジェクト・ベースのスキーマで SELECT タイプの照会ができます。

この照会言語では、以下の機能が提供されます。

Query インターフェース

エンティティー照会の実行を制御する場合に、照会インターフェースを使用します。

EntityManager.createQuery(String) メソッドを使用して、Query を作成します。各照会インスタンスを、それが取り出された EntityManager インスタンスと共に複数回使用できます。

各照会の結果、1 つのエンティティーが生成されます。この場合、エンティティー・キーは、行 ID (型 long の) であり、エンティティー値には、SELECT 文節のフィールド結果が含まれています。各照会結果を、それ以降の照会で使用できます。

以下のメソッドは、com.ibm.websphere.objectgrid.em.Query インターフェースで使用できます。

public ObjectMap getResultMap()

getResultMap メソッドは SELECT 照会を実行し、結果を照会で指定した順序で ObjectMap オブジェクトに戻します。結果の ObjectMap は、現行のトランザクションに対してのみ有効です。

マップ・キーは、結果の数値であり、型 long で 1 から始まります。マップ値は、タイプ com.ibm.websphere.projector.Tuple であり、この場合、各属性および関連は、照会の select 文節内の順序位置に基づいて指定されます。このメソッドを使用して、マップ内に保管されている Tuple オブジェクトに対する EntityMetadata を取り出してください。

getResultMap メソッドは、複数の結果が存在する可能性がある場合に、照会結果のデータを取り出す、最も高速なメソッドです。結果のエンティティーの名前は、ObjectMap.getEntityMetadata() および EntityMetadata.getName() メソッドを使用して取り出すことができます。

例: 以下の照会では、2 つの行を返します。

String ql = SELECT e.name, e.id, d from Employee e join e.dept d WHERE d.number=5
 Query q = em.createQuery(ql);
 ObjectMap resultMap = q.getResultMap();
 long rowID = 1; // starts with index 1
 Tuple tResult = (Tuple) resultMap.get(new Long(rowID));
 while(tResult != null) {
     // The first attribute is name and has an attribute name of 1
     // But has an ordinal position of 0.
     String name = (String)tResult.getAttribute(0);
     Integer id = (String)tResult.getAttribute(1);

     // Dept is an association with a name of 3, but
     // an ordinal position of 0 since it's the first association.
     // The association is always a OneToOne relationship,
     // so there is only one key.
     Tuple deptKey = tResult.getAssociation(0,0);
     ...
     ++rowID;
     tResult = (Tuple) resultMap.get(new Long(rowID));

 }

public Iterator getResultIterator

getResultIterator メソッドは SELECT 照会を実行し、照会の結果を Iterator を使用して戻します。この場合、各結果は、Object (単一値照会の場合) または Object[] (複数値照会の場合) のいずれかです。Object[] 結果内の値は、照会順序で保管されます。結果の Iterator は、現行のトランザクションに対してのみ有効です。

このメソッドは、EntityManager コンテキスト内の照会結果を取り出す場合に推奨されます。オプションの setResultEntityName(String) メソッドを使用して、結果のエンティティーを指定し、以降の照会で使用できるようにすることができます。

例: 以下の照会では、2 つの行を返します。

String ql = SELECT e.name, e.id, e.dept from Employee e WHERE e.dept.number=5
 Query q = em.createQuery(ql);
 Iterator results = q.getResultIterator();
 while(results.hasNext()) {
     Object[] curEmp = (Object[]) results.next();
     String name = (String) curEmp[0];
     Integer id = (Integer) curEmp[1];
     Dept d = (Dept) curEmp[2];
     ...
 }

public Iterator getResultIterator(Class resultType)

getResultIterator(Class resultType) メソッドは、SELECT 照会を 実行し、エンティティー Iterator を使用して照会結果を戻します。エンティティーの型は、resultType パラメーターによって決定されます。結果の Iterator は、現行のトランザクションに対してのみ有効です。

EntityManager API を使用して結果のエンティティーにアクセスする場合は、このメソッドを使用してください。

例: 以下の照会では、1 つの事業部について、全従業員と、従業員が所属する部門を給与順に返します。給与の高い順に 5 人の従業員を印刷してから、同じ作業セット内の 1 つの部門のみから、従業員の作業を選択する場合は、以下のコードを使用します。

String string_ql = "SELECT e.name, e.id, e.dept from Employee e WHERE
		e.dept.division='Manufacturing' ORDER BY e.salary DESC";
Query query1 = em.createQuery(string_ql);
query1.setResultEntityName("AllEmployees");
Iterator results1 = query1.getResultIterator(EmployeeResult.class);
int curEmployee = 0;
System.out.println("Highest paid employees");
while (results1.hasNext() && curEmployee++ < 5) {
	EmployeeResult curEmp = (EmployeeResult) results1.next();			
	System.out.println(curEmp);
	// Remove the employee from the resultset.
	em.remove(curEmp);
}

// Flush the changes to the result map.
em.flush();

// Run a query against the local working set without the employees we
// removed
String string_q2 = "SELECT e.name, e.id, e.dept from AllEmployees e
		WHERE e.dept.name='Hardware'";
Query query2 = em.createQuery(string_q2);
Iterator results2 = query2.getResultIterator(EmployeeResult.class);
System.out.println("Subset list of Employees");
while (results2.hasNext()) {
	EmployeeResult curEmp = (EmployeeResult) results2.next();			
	System.out.println(curEmp);
}

public Object getSingleResult

getSingleResult メソッドは単一の結果を戻す SELECT 照会を実行します。

SELECT 文節に複数のフィールドが定義されている場合には、結果はオブジェクト配列となります。この場合、配列内の各エレメントは、照会の SELECT 文節内の順序位置に基づきます。

String ql = SELECT e from Employee e WHERE e.id=100"
 Employee e = em.createQuery(ql).getSingleResult();

 String ql = SELECT e.name, e.dept from Employee e WHERE e.id=100"
 Object[] empData = em.createQuery(ql).getSingleResult();
 String empName= (String) empData[0];
 Department empDept = (Department) empData[1];

public Query setResultEntityName(String entityName)

setResultEntityName(String entityName) メソッドは照会結果エンティティーの名前を指定します。

getResultIterator または getResultMap メソッドが呼び出されるたびに、ObjectMap を備えたエンティティーが動的に作成されて照会の結果を保持します。エンティティーが指定されていないか、またはヌルである場合、エンティティーおよび ObjectMap 名は自動的に生成されます。

すべての照会結果が、トランザクションの存続期間中に使用可能であるため、照会名は、単一トランザクション内で再使用することはできません。

public Query setPartition(int partitionId)

照会の経路指定先に区画を設定します。

このメソッドは、照会内のマップが区画化されており、エンティティー・マネージャーに、単一スキーマのルート・エンティティー区画に対するアフィニティーがない場合に、必要になります。

PartitionManager インターフェースを使用して、指定されたエンティティーのバックアップ・マップに対する区画の数を決定してください。

以下の表に、照会インターフェースを通して使用可能なその他のメソッドの概要を示します。

表 1. その他のメソッド
メソッド 結果
public Query setMaxResults(int maxResult) 取り出す結果の最大数を設定します。
public Query setFirstResult(int startPosition) 取り出す最初の結果の位置を設定します。
public Query setParameter(String name, Object value) 引数を、名前付きパラメーターにバインドします。
public Query setParameter(int position, Object value) 引数を、定位置パラメーターにバインドします。
public Query setFlushMode(FlushModeType flushMode) 照会が実行されるときに使用されるフラッシュ・モード・タイプを設定し、EntityManager に対して設定されたフラッシュ・モード・タイプをオーバーライドします。

eXtreme Scale 照会のエレメント

eXtreme Scale 照会エンジンを使用すると、eXtreme Scale キャッシュの検索について単一の照会言語を使用することができます。この照会言語は、ObjectMap オブジェクトや Entity オブジェクトに保管されている Java オブジェクトの照会が可能です。以下の構文を使用して照会ストリングを作成します。

eXtreme Scale 照会は、以下のエレメントを含むストリングです。
  • 返すオブジェクトまたは値を指定する SELECT 文節。
  • オブジェクト集合に名前を付ける FROM 文節。
  • 集合に対する検索述部を含むオプションの WHERE 文節。
  • オプションの GROUP BY および HAVING 文節 (eXtreme Scale 照会の集約関数を参照)。
  • 結果の集合の順序付けを指定するオプションの ORDER BY 文節。

Java オブジェクト集合は、照会の FROM 文節で名前が使用されることで識別されます。

照会言語の各エレメントについては、以下の関連トピックでより詳しく説明します。
以下のトピックでは、Query API の使用方法について説明しています。