Overview  Package   Class  Use  Tree  Deprecated  Index  Help 
WebObjects 5.2.3
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.webobjects.eocontrol
Class EOQualifier

java.lang.Object
  extended bycom.webobjects.eocontrol.EOQualifier
All Implemented Interfaces:
EOQualifierEvaluation, Serializable
Direct Known Subclasses:
BooleanQualifier, EOKeyComparisonQualifier, EOKeyValueQualifier, EONotQualifier, EOOrQualifier, EOSQLQualifier, NonNullQualifier
public abstract class EOQualifier
extends Object
implements Serializable, EOQualifierEvaluation

EOQualifierは、条件に合うオブジェクトやデータベース行を選択するための情報を持つ抽象クラスです。 ただしEOSQLQualifier (EOAccess) は例外であり、EOModel (EOAccess) の生成するSQLに依存しません。 これにより、同じEOQualifierオブジェクトでメモリとデータベースの両方を検索することができます。

EOQualifierのインスタンスを生成することはありません。 独自のEOQualifierのサブクラスや次のクラスなどのサブクラスを使うことになります。

サブクラスの目的


サブクラス 目的
EOKeyValueQualifier オブジェクトの属性値と指定されたオブジェクトを比較します。 例: "weight > 150"
EOKeyComparisonQualifier オブジェクトの属性値同士を比較します。 例: "name = wife.name"
EOAndQualifier 複数のフェッチ条件をまとめます。 条件は結合されます。 例: "name = 'Fred' AND age < 20"
EOOrQualifier 複数のフェッチ条件をまとめます。 条件は別々に扱われます。 例: "name = 'Fred' OR name = 'Ethel'"
EONotQualifier 単体のフェッチ条件を否定します。 例: "NOT (name = 'Fred')"
EOSQLQualifier EOSQLExpressionに変換される、構造化されていないテキストを扱います。 EOSQLQualifierは任意のSQL文からEOSQLExpressionオブジェクトを生成する手段を提供します。 EOSQLQualifierはメモリ中のオブジェクトではなくデータベースをSQLで検索するクラスで、必要のない限り常にEOQualifierを使うべきです。

EOQualifierEvaluationインターフェースはEOQualifierオブジェクトがメモリ中のオブジェクトをどう評価するかを定義しています。 データベースを評価するには、EOSQLExpression (EOAccess) とEOEntity (EOAccess) のメソッドを使ってSQLを生成します。 SQLを生成する機能はすべてアクセスレイヤーに含まれています。

EOQualifierオブジェクトを生成する

上記で示したEOQualifierの様々なサブクラスはいずれも異なる目的に使います。 ただしEOQualifierオブジェクトはEOQualifierのクラスメソッド qualifierWithQualifierFormat で簡単に生成できます。 

    EOQualifier qual = EOQualifier.qualifierWithQualifierFormat
        ("lastName = 'Smith'", null);

このような式から生成されるQualifier群は、フォーマット文字列の内容を元にしたものになります。 例えば "lastName = 'Smith'" という文字列を qualifierWithQualifierFormat の引数にして実行すると、EOKeyValueQualifierオブジェクトを返します。 ただ、通常はここまでの詳細を気にする必要はありません。

Qualifierを生成するのに使うフォーマット文字列は、 "firstName = 'Fred' AND age < 20" のように論理式を組み合わせることができます。 Qualifierを生成するとき、論理式の組み合わせはEOQualifierの構文木に変換されます。 論理演算子 AND と OR は、それぞれEOAndQualifierとEOOrQualifierを生成します。 これらのQualifierは、Qualifier群を結合 (AND) したり個別に (OR) まとめます。


フォーマット文字列の構成

上記で述べたように、通所は qualifierWithQualifierFormat を使ってフォーマット文字列からQualifierを生成します。 このメソッドは標準C言語ライブラリの printf() 関数に似たフォーマット文字列を引数に取ります。 フォーマット文字列は、文字列・数値・ %@ で変換されるオブジェクトを含みます。 qualifierWithQualifierFormat の二番目の引数は、 %@ を変換する値や結果の配列です。 これによってQualifierを動的に組み立てることができます。 次の表はフォーマット文字列で使える変換記号と変換されるデータ型を示します。


変換記号 変換される値や結果
%s 文字列、または toString メソッドの結果。
%d 整数や整数に変換された値。
%f 実数や実数に変換された値。
%@ 任意のオブジェクト。変換処理は行われません。
%K toString で文字列に変換され、 key として扱われる点を除けば %@ に似ています。 EOKeyValueQualifierとEOKeyComparisonQualiferのどちらかが生成されます。
%% % 文字に変換されます。

変換記号に定義されていない文字を使うと（%x など）例外を発生します。

例えば empID, firstName, lastName, salary, department （部署エンティティと１対１のリレーションシップ）の属性を持つ従業員エンティティと deptID, name の属性を持つ部署エンティティがあるとします。 単純なQualifierなら次のようにして生成することができます。 

    lastName = 'Smith'
    salary > 2500
    department.name = 'Personnel'

次の例は上記に似たQualifierを生成しますが、指定する値にフェッチ済みのエンタープライズオブジェクトを使用します。 

    Employee anEmployee;    // あるものと仮定
    Department aDept;       // あるものと仮定
    EOQualifier myQualifier;
    NSMutableArray args = new MutableVector();
    args.addObject("lastName");
    args.addObject(anEmployee.lastName());
    myQualifier = EOQualifier.qualifierWithQualifierFormat("%@ = %@", args);
    args.removeAllObjects();
    args.addObject("salary");
    args.addObject(anEmployee.salary());
    myQualifier = EOQualifier.qualifierWithQualifierFormat("%@ > %f", args);
    args.removeAllElements();
    args.addElement("department.name");
    args.addElement(aDept.name());
    myQualifier = EOQualifier.qualifierWithQualifierFormat("%@ = %@", args);

エンタープライズオブジェクトは属性値にアクセスできるメソッドを実装しています。 従業員オブジェクトの lastName と salary 、部署オブジェクトの name などに直接アクセスすることができます。 文字列と異なり、 %@ をシングルクォートで囲う必要はありません。 

    // 文字列リテラルではシングルクォートを使います。
    EOQualifier.qualifierWithQualifierFormat("lastName = 'Smith'", null);

    // %@ にはクォートを使う必要はありません。
    args.removeAllElements();
    args.addElement("Jones");
    EOQualifier.qualifierWithQualifierFormat("lastName = %@", args);

よくあるフォーマット文字列は、文字列と数値の２つのデータ型のみを使うものです。 シングルクォート、ダブルクォートで囲んだ文字列は文字列オブジェクトとして、クォートで囲まない数値は数値オブジェクトとして、クォートで囲まない文字列はキーとして扱われます。 明示的にキャストすることでこの制限を回避できます。

Qualifierに使用できる演算子に =, ==, !=, <, >, <=, >=, "like", "caseInsensitiveLike" があります。 演算子 like と caseInsensitiveLike では、パターンマッチを行うのにワイルドカードを使うことができます。


NULL値のチェック

NULLにマッチするデータベース行をフェッチするQualifierを生成するには、次のどちらかの方法で行います。 

    NSMutableArray args = new NSMutableArray();
    // 方法 1
    EOQualifier.qualifierWithQualifierFormat("bonus = nil", null);
    // 方法 2
    args.addElement(NullValue.nullValue());
    EOQualifier.qualifierWithQualifierFormat("bonus = %@", args);


ワイルドカードと like 演算子の使用

Qualifierの式でlike や caseInsensitiveLike 演算子を使う場合、パターンマッチにワイルドカードと ? を使うことができます。 

    "lastName like 'Jo*'"

Jones, Johnson, Jolsen, Josephs などにマッチします。

? は１文字にマッチします。

    "lastName like 'Jone?'"

Jones にマッチします。

アスタリスクは演算子 like か caseInsensitiveLike でのみワイルドカードとして使用できます。 例えば次の式では、 * はワイルドカードではなくリテラル値として処理されます。 

    quot;lastName = 'Jo*'"


Qualifier式でのセレクタの使用

Qualifierを初期化するフォーマット文字列にはメソッドも含めることができます。 パーザはコロンのつく文字列（myMethod: など）をメソッドとして扱います。 次はその例です。 

    point1 isInside: area
    firstName isAnagramOfString: "Computer"

例えば、セレクタ isAnagramOfString の実際のメソッドは次のように定義しなければなりません。 

    public Boolean isAnagramOfString (String aString){}

引数にはStringではなくObjectを渡すこともできます。 Objectを渡すと例外処理を考慮して実行され、Boolean値を返さない限り false を返します。

Qualifierで指定したメソッドはメモリ内でのみ実行され、データベースからのフェッチには使えません。


EOQualifierのサブクラスの使用

EOAndQualifier, EOOrQualifier, EONotQualifierのインスタンスを明示的に生成する必要はほとんどありません。 しかし、EOKeyValueQualifierとEOKeyComparisionQualifierのインスタンスを生成したいこともあるかもしれません。 主なメリットはQualifierをどう構築するかをより細かく制御できることです。

Qualifierのサブクラスのインスタンスを明示的に生成したければ、次のようなコードで実現できます。 EOKeyValueQualifierを使って "isOut" キー値が 1 （true を意味します）であるすべてのオブジェクトを選択します。 Qualifierはメモリ中の配列のフィルタとして使われます。 

    // qualifierを生成する
    EOQualifier qual = new EOKeyValueQualifier("isOut", 
                                               EOQualifier.QualifierOperatorEqual,
                                               new Integer(1));
    // 配列をフィルタリングして返す
    return Qualifier.filteredVectorWithQualifier(allRentals(), qual);

filteredArrayWithQualifier は、引数の配列からQualifierにマッチするオブジェクトを選択し、新しい配列で返すメソッドです。


サブクラスの作成

EOQualifierのサブクラスは、メモリ中のオブジェクトを評価するのではあればEOQualifierEvaluationインターフェースを実装しなければなりません。

See Also:
Serialized Form

Nested Class Summary
static interface EOQualifier.Comparison
           EOQualifierComparisonは比較用のメソッドを定義したインターフェースです。
static class EOQualifier.ComparisonSupport
           JavaクライアントのEOQualifier.ComparisonSupportクラスは、EOQualifierComparisonインターフェースのデフォルト実装です。
 class EOQualifier.QualifierVariableSubstitutionException
          
 
Field Summary
static NSSelector QualifierOperatorCaseInsensitiveLike
          セレクタの１つです。
static NSSelector QualifierOperatorContains
          セレクタの１つです。
static NSSelector QualifierOperatorEqual
          セレクタの１つです。
static NSSelector QualifierOperatorGreaterThan
          セレクタの１つです。
static NSSelector QualifierOperatorGreaterThanOrEqualTo
          セレクタの１つです。
static NSSelector QualifierOperatorLessThan
          セレクタの１つです。
static NSSelector QualifierOperatorLessThanOrEqualTo
          セレクタの１つです。
static NSSelector QualifierOperatorLike
          セレクタの１つです。
static NSSelector QualifierOperatorNotEqual
          セレクタの１つです。
 
Constructor Summary
EOQualifier()
           
 
Method Summary
abstract  void addQualifierKeysToSet(NSMutableSet qualifierKeys)
           qualifierKeys をqualifierのキーに追加します。
 NSSet allQualifierKeys()
           すべての式の左辺の文字列から構成されるNSSetを返します。
static NSArray allQualifierOperators()
           EOQualifierがサポートする演算子の配列を返します。
 NSArray bindingKeys()
           式で使われる変数名の文字列の配列を返します。
 Object clone()
           オブジェクトの複製を返します。
 boolean evaluateWithObject(Object object)
           サブクラスによって実装されます。 object が条件に一致すれば true を、そうでなければ false を返します。
static void filterArrayWithQualifier(NSMutableArray array, EOQualifier qualifier)
           qualifier に一致する array 中のオブジェクトを選別します。
static NSArray filteredArrayWithQualifier(NSArray array, EOQualifier qualifier)
           qualifier に一致する array 中のオブジェクトを選別し、そのオブジェクトを含む新しい配列を生成して返します。
 String keyPathForBindingKey(String key)
           変数を含む式の左辺の文字列を返します。
protected static NSSelector operatorSelectorForSelectorNamed(String string)
           指定した名前の演算子のセレクタを返します。
static NSSelector operatorSelectorForString(String string)
           string に対応する演算子のセレクタを返します。
static EOQualifier qualifierToMatchAllValues(NSDictionary values)
           検索条件を含む辞書を受け取り、キーと値の組み合わせ１つごとにEOKeyValueQualifiersを生成します。
static EOQualifier qualifierToMatchAnyValue(NSDictionary values)
           検索条件を含む辞書を受け取り、キーと値の組み合わせ１つごとにEOKeyValueQualifiersを生成します。
abstract  EOQualifier qualifierWithBindings(NSDictionary bindings, boolean requiresAll)
           bindings に含まれるすべての変数を置き換えた新しいqualifierを返します。
static EOQualifier qualifierWithQualifierFormat(String format, NSArray arguments)
           フォーマット文字列 format と arguments を解析し、EOQualifierを生成して返します。
static NSArray relationalQualifierOperators()
           EOQualifierがサポートする関係演算子の配列を返します。
static String stringForOperatorSelector(NSSelector selector)
           セレクタ selector を表す文字列を返します。
abstract  void validateKeysWithRootClassDescription(EOClassDescription classDescription)
           指定されたキーやキーパスが classDescription において有効であることを保証します。
 
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

QualifierOperatorCaseInsensitiveLike

public static final NSSelector QualifierOperatorCaseInsensitiveLike
セレクタの１つです。

QualifierOperatorContains

public static final NSSelector QualifierOperatorContains
セレクタの１つです。

QualifierOperatorEqual

public static final NSSelector QualifierOperatorEqual
セレクタの１つです。

QualifierOperatorGreaterThan

public static final NSSelector QualifierOperatorGreaterThan
セレクタの１つです。

QualifierOperatorGreaterThanOrEqualTo

public static final NSSelector QualifierOperatorGreaterThanOrEqualTo
セレクタの１つです。

QualifierOperatorLessThan

public static final NSSelector QualifierOperatorLessThan
セレクタの１つです。

QualifierOperatorLessThanOrEqualTo

public static final NSSelector QualifierOperatorLessThanOrEqualTo
セレクタの１つです。

QualifierOperatorLike

public static final NSSelector QualifierOperatorLike
セレクタの１つです。

QualifierOperatorNotEqual

public static final NSSelector QualifierOperatorNotEqual
セレクタの１つです。

Constructor Detail

EOQualifier

public EOQualifier()
Method Detail

addQualifierKeysToSet

public abstract void addQualifierKeysToSet(NSMutableSet qualifierKeys)

qualifierKeys をqualifierのキーに追加します。 EOControlフレームワークの（EOQualifierの）サブクラスはqualifierの構文木に関わらずキーを追加します。 EOAndQualifierなどのqualifierは、末節のqualifier（EOKeyValueQualifierなど）にたどりつくまで再帰的にこのメソッドを実行し、キーをセットに追加します。

EOQualifierのサブクラスはこのメソッドを必ず実装しなければいけません。

Parameters:
qualifierKeys - qualifierのキーの変更可能なセット*1

allQualifierKeys

public NSSet allQualifierKeys()
すべての式の左辺の文字列から構成されるNSSetを返します。 例えば
salary > 10000 AND manager.lastName = 'smith'
のようなqualifierがあるとき、"salary, manager.lastName" の文字列を含む配列を返します。 サブクラスはこのメソッドをオーバーライドすべきではありません。 代わりに addQualifierKeysToSet をオーバーライドすべきです。

Returns:
文字列から構成されるNSSet
See Also:
addQualifierKeysToSet(NSMutableSet qualKeys)

allQualifierOperators

public static NSArray allQualifierOperators()
EOQualifierがサポートする演算子の配列を返します。 演算子は =, !=, <, <=, >, >=, like, caseInsensitiveLike です。

Returns:
EOQualifierがサポートする演算子の配列
See Also:
relationalQualifierOperators()

bindingKeys

public NSArray bindingKeys()
式で使われる変数名の文字列の配列を返します。 同じ変数が何度も使われても、このリストには一つしか含まれません。

Returns:
Qualifierで使われる変数名の文字列の配列を返します。

clone

public Object clone()
オブジェクトの複製を返します。

Returns:
オブジェクトの複製を返します。

evaluateWithObject

public boolean evaluateWithObject(Object object)
サブクラスによって実装されます。 object が条件に一致すれば true を、そうでなければ false を返します。 引数は、エンタープライズオブジェクトやスナップショットの辞書など key-value coding が実装されているオブジェクトであるべきです。

Specified by:
evaluateWithObject in interface EOQualifierEvaluation
Parameters:
object - 入力するオブジェクト
Returns:
object が条件に一致すれば true を、そうでなければ false を返します。

filterArrayWithQualifier

public static void filterArrayWithQualifier(NSMutableArray array,
                                            EOQualifier qualifier)
qualifier に一致する array 中のオブジェクトを選別します。

Parameters:
array - 入力する配列
qualifier - データベース選択条件

filteredArrayWithQualifier

public static NSArray filteredArrayWithQualifier(NSArray array,
                                                 EOQualifier qualifier)
qualifier に一致する array 中のオブジェクトを選別し、そのオブジェクトを含む新しい配列を生成して返します。

Parameters:
array - 入力する配列
qualifier - データベース選択条件
Returns:
qualifier に一致する array 中のオブジェクトを選別した新しい配列

keyPathForBindingKey

public String keyPathForBindingKey(String key)
変数を含む式の左辺の文字列を返します。 "salary > $amount and manager.lastName = $manager" というqualifierがあるとき、 bindingKeys を実行すると (amount, manager) の配列を返します。 keyPathForBindingKey を実行すると、引数が amount なら salary を、manager なら manager.lastName を返します。

Parameters:
key - 入力する文字列
Returns:
変数を含む式の左辺の文字列

operatorSelectorForSelectorNamed

protected static NSSelector operatorSelectorForSelectorNamed(String string)
指定した名前の演算子のセレクタを返します。

Parameters:
string - セレクタ名
Returns:
セレクタ

operatorSelectorForString

public static NSSelector operatorSelectorForString(String string)
string に対応する演算子のセレクタを返します。 このメソッドはqualifierを解析時に使われます。 例えば、次のコードはセレクタ QualifierOperatorNotEqual を返します。 
Selector selector = Qualifier.operatorSelectorForString(!=);
対応している文字列は =, ==, !=, <, >, <=, >=, "like", "caseInsensitiveLike" です。 おそらくこのメソッドは独自にqualifierのパーザを書くときにしか使われないでしょう。

Parameters:
string - 入力する文字列
Returns:
文字列に対応する演算子のセレクタ
See Also:
stringForOperatorSelector(NSSelector selector)

qualifierToMatchAllValues

public static EOQualifier qualifierToMatchAllValues(NSDictionary values)
検索条件を含む辞書を受け取り、キーと値の組み合わせ１つごとにEOKeyValueQualifiersを生成します。 このメソッドはqualifierをANDで結合し、EOAndQualifierを返します。

Parameters:
values - 検索条件を含む辞書
Returns:
EOAndQualifierオブジェクト

qualifierToMatchAnyValue

public static EOQualifier qualifierToMatchAnyValue(NSDictionary values)
検索条件を含む辞書を受け取り、キーと値の組み合わせ１つごとにEOKeyValueQualifiersを生成します。 このメソッドはqualifierをORで結合し、EOOrQualifierを返します。

Parameters:
values - 検索条件を含む辞書
Returns:
EOOrQualifierオブジェクト

qualifierWithBindings

public abstract EOQualifier qualifierWithBindings(NSDictionary bindings,
                                                  boolean requiresAll)
bindings に含まれるすべての変数を置き換えた新しいqualifierを返します。 requiresAll が true なら、 bindings に変数が含まれなければ例外を発生します。 requiresAll が false なら、見つからない変数の分だけ構文木が切り詰められます。

Parameters:
bindings - バインディングの辞書
requiresAll - すべての条件（変数が存在するかどうか）を必須にするかどうか
Returns:
bindings に含まれるすべての変数を置き換えた新しいqualifier

qualifierWithQualifierFormat

public static EOQualifier qualifierWithQualifierFormat(String format,
                                                       NSArray arguments)

フォーマット文字列 format と arguments を解析し、EOQualifierを生成して返します。 変換記号 (%@) が含まれていれば arguments の値で置き換えます。

このメソッドは format を元に、基本的なqualifierを木構造になるように生成します。 例えば "firstName = 'Joe' AND department = 'Facilities'" のフォーマット文字列からは、２つのEOKeyValueQualifierを含むEOAndQualifierが生成されます。 次のコードは qualifierWithQualifierFormat メソッドの一般的な使い方です。 エンティティ名とqualifierを含むEOFetchSpecificationを生成しています。 続いてEOFetchSpecificationをEODisplayGroupのデータソースに設定し、EODisplayGroupにフェッチするよう要求します。 

    EODisplayGroup displayGroup;   // あるものと仮定
    EOQualifier qualifier;
    EOFetchSpecification fetchSpec;
    EODatabaseDataSource dataSource;
    dataSource = (EODatabaseDataSource)displayGroup.dataSource();
    qualifier = EOQualifier.qualifierWithQualifierFormat(cardType = 'Visa', null);
    fetchSpec = new EOFetchSpecification(Member, qualifier, null), null);

    dataSource.setFetchSpecification(fetchSpec);
    displayGroup.fetch();

qualifierWithQualifierFormat は、フォーマット文字列 format に含まれるキーが存在するかどうかを検証しません。 もし format に文法エラーがあれば例外を発生します。

Parameters:
format - フォーマット文字列
arguments - 引数の配列
Returns:
EOQualifierオブジェクト

relationalQualifierOperators

public static NSArray relationalQualifierOperators()
EOQualifierがサポートする関係演算子の配列を返します。 演算子には =, !=, <, <=, >, >= があります。 文字列の演算子 "like" と "caseInsensitiveLike" 以外のすべての演算子を返す、と言い換えることもできます。

Returns:
EOQualifierがサポートする演算子（文字列のもの以外）の配列
See Also:
allQualifierOperators()

stringForOperatorSelector

public static String stringForOperatorSelector(NSSelector selector)

セレクタ selector を表す文字列を返します。 例えば次のコードでは != を返します。 

    String operator =
        EOQualifier.stringForOperatorSelector(EOQualifier.QualifierOperatorNotEqual);

次のリストは対応している selector です。

おそらくこのメソッドは独自にqualifierのパーザを書くときにしか使われないでしょう。

Parameters:
selector - 入力するセレクタ
Returns:
セレクタを表す文字列
See Also:
operatorSelectorForString(String string), QualifierOperatorEqual, QualifierOperatorNotEqual, QualifierOperatorLessThan, QualifierOperatorGreaterThan, QualifierOperatorLessThanOrEqualTo, QualifierOperatorGreaterThanOrEqualTo, QualifierOperatorContains, QualifierOperatorLike, QualifierOperatorCaseInsensitiveLike

validateKeysWithRootClassDescription

public abstract void validateKeysWithRootClassDescription(EOClassDescription classDescription)
指定されたキーやキーパスが classDescription において有効であることを保証します。 このメソッドは未知のキーがあれば例外を発生します。*2

Parameters:
classDescription - 検証するために使うEOClassDescriptionオブジェクト
Overview  Package   Class  Use  Tree  Deprecated  Index  Help 
Last updated Thu Oct 21 15:04:16 PDT 2004.
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD
Copyright © 2004 Apple Computer, Inc.

*1 原文は "The mutable array of qualifier keys" だが、配列ではないので修正した。

*2 原文ではキーが有効なときは null を返すことになっているが、戻り値は void なので何も返さない。