org.pekeler.eof
Class EOFetcher

java.lang.Object
  extended by org.pekeler.eof.EOFetcher

public class EOFetcher
extends Object

EOFetcher is a utility class for fetching EOs. It can be used instead of EOEditingContext.objectsWithFetchSpecification() and various methods in EOUtilities (in fact, EOFetcher's api has been modeled after EOUtilities). EOFetchSpecification's main purpose is to help retrieving EOs from the DB. EOFetcher enables in-memory fetches. There are several practical applications:

Unit Testing. In order for unit tests to run fast, they should not access the DB. However, if the production code under test is using EOFetchSpecifications, this is hard to accomplish. That's why it has been very common to write unit tests for WO projects which set up test objects in a database and then test the production code against the DB. For example:

 public static NSArray someObjects(EOEditingContext editingContext) {
     return EOUtilities.objectsWithFetchSpecification(editingContext, "SomeEntity",
                                                      "someObjects");
 }
 ...
 @Test
 public void someObjects() {
     SomeEntity someEntity = new SomeEntity();
     editingContext().insertObject(someEntity);
     // make someEntity disqualify
     editingContext().saveChanges();
     assertFalse(SomeEntity.someObjects(editingContext()).containsObject(someEntity));
     // make someEntity qualify
     editingContext().saveChanges();
     assertTrue(SomeEntity.someObjects(editingContext()).containsObject(someEntity));
 }
 @After
 public void cleanupDB() {
     // delete someEntity from DB
 }
 
Using EOFetcher, the test becomes simpler and faster, because it doesn't access the DB anymore:
 public static NSArray someObjects(EOEditingContext editingContext) {
     return EOFetcher.objectsWithFetchSpecificationName(editingContext, "SomeEntity",
                                                        "someObjects", EOFetcher.DBEC);
 }
 ...
 @Test
 public void someObjects() {
     SomeEntity someEntity = (SomeEntity)mockEditingContext().createSavedObject("SomeEntity");
     // make someEntity disqualify
     assertFalse(SomeEntity.someObjects(mockEditingContext()).containsObject(someEntity));
     // make someEntity qualify
     assertTrue(SomeEntity.someObjects(mockEditingContext()).containsObject(someEntity));
 }
 

Validation. Let's say the entity Person has an attribute firstName and lastName, and each person needs to have a unique full name. A common implementation looks as follows:

 public void validateForSave() throws NSValidation.ValidationException {
     super.validateForSave();
     NSDictionary keyValueDictionary = new NSDictionary(new Object[] { firstName(), lastName() },
                                                        new String[] { "firstName", "lastName" });
     NSMutableArray objects = EOUtilities.objectsMatchingValues(editingContext(), "Person",
                                                                keyValueDictionary).mutableClone();
     objects.removeObject(this);
     if (objects.count() > 0)
         throw new NSValidation.ValidationException("name is not unique");
 }
 
There are two problems with this implementation. First, it's not easily unit-testable because it is working against the database. Second, it won't validate against other unsaved persons. This is a problem when more than one person is being edited or created at the same time. The alternative implementation using EOFetcher solves these two issues and looks as follows:
 public void validateForSave() throws NSValidation.ValidationException {
     super.validateForSave();
     NSDictionary keyValueDictionary = new NSDictionary(new Object[] { firstName(), lastName() },
                                                        new String[] { "firstName", "lastName" });
     if (EOFetcher.objectNotUniqueForMatchingValues(this, keyValueDictionary))
         throw new NSValidation.ValidationException("name is not unique");
 }
 

If an EO exists in the editing context but not yet in the DB, EOFetcher will find that object when used with the DBEC or EC store. For the DB store, the object will be ignored just like EOUtilities would ignored it.

If an EO exists in the DB, and has been deleted by an editing context but not yet saved, EOFetcher will ignore that object when used with the DBEC or EC store. For the DB store, the object will be returned just like EOUtilities would return it.


Nested Class Summary
protected static class EOFetcher.DatabaseAndEditingContextStore
           
protected static class EOFetcher.DatabaseStore
           
protected static class EOFetcher.EditingContextStore
           
static class EOFetcher.Store
           
 
Field Summary
static EOFetcher.Store DB
          Store for fetching from the database.
static EOFetcher.Store DBEC
          Store for fetching from the database and editing context.
static EOFetcher.Store EC
          Store for fetching from the editing context.
 
Constructor Summary
EOFetcher()
           
 
Method Summary
static boolean objectNotUniqueForFetchSpecificationNameAndBindings(EOEnterpriseObject anObject, String aFetchSpecificationName, NSDictionary aBindingsDictionary)
          Returns true if other objects of the same entity are found in the DBEC Store with a fetch specification and bindings.
static boolean objectNotUniqueForMatchingKeyAndValue(EOEnterpriseObject anObject, String aKey, Object aValue)
          Returns true if other objects of the same entity are found in the DBEC Store having the same value for a key.
static boolean objectNotUniqueForMatchingValues(EOEnterpriseObject anObject, NSDictionary aValueDictionary)
          Returns true if other objects of the same entity are found in the DBEC Store having the same values for the keys from a key-value dictionary.
static NSArray objectsForEntityNamed(EOEditingContext anEditingContext, String anEntityName, EOFetcher.Store aStore)
          Fetches the Enterprise Objects associated with the specified entity.
static NSArray objectsMatchingKeyAndValue(EOEditingContext anEditingContext, String anEntityName, String aKey, Object aValue, EOFetcher.Store aStore)
          Creates an EOKeyValueQualifier with the specified key and value and returns matching Enterprise Objects.
static NSArray objectsMatchingValues(EOEditingContext anEditingContext, String anEntityName, NSDictionary aValueDictionary, EOFetcher.Store aStore)
          Creates EOKeyValueQualifiers for each key-value pair in the specified dictionary, ANDs these qualifiers together into an EOAndQualifier, and returns matching Enterprise Objects.
static NSArray objectsWithFetchSpecification(EOEditingContext anEditingContext, EOFetchSpecification aFetchSpecification, EOFetcher.Store aStore)
          Fetches the Enterprise Objects retrieved with the specified fetch specification.
static NSArray objectsWithFetchSpecificationName(EOEditingContext anEditingContext, String anEntityName, String aFetchSpecificationName, EOFetcher.Store aStore)
          Fetches the Enterprise Objects retrieved with the specified fetch specification.
static NSArray objectsWithFetchSpecificationNameAndBindings(EOEditingContext anEditingContext, String anEntityName, String aFetchSpecificationName, NSDictionary aBindingsDictionary, EOFetcher.Store aStore)
          Fetches the Enterprise Objects retrieved with the specified fetch specification and bindings.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

DB

public static EOFetcher.Store DB
Store for fetching from the database.


EC

public static EOFetcher.Store EC
Store for fetching from the editing context.


DBEC

public static EOFetcher.Store DBEC
Store for fetching from the database and editing context.

Constructor Detail

EOFetcher

public EOFetcher()
Method Detail

objectsWithFetchSpecification

public static NSArray objectsWithFetchSpecification(EOEditingContext anEditingContext,
                                                    EOFetchSpecification aFetchSpecification,
                                                    EOFetcher.Store aStore)
Fetches the Enterprise Objects retrieved with the specified fetch specification.

Parameters:
anEditingContext - an EOEditingContext
aFetchSpecification - the criteria specified for fetch
aStore - the Store to fetch from

objectsWithFetchSpecificationName

public static NSArray objectsWithFetchSpecificationName(EOEditingContext anEditingContext,
                                                        String anEntityName,
                                                        String aFetchSpecificationName,
                                                        EOFetcher.Store aStore)
Fetches the Enterprise Objects retrieved with the specified fetch specification.

Parameters:
anEditingContext - an EOEditingContext
anEntityName - the name of the EOEntity
aFetchSpecificationName - the name of the EOFetchSpecification for the entity
aStore - the Store to fetch from

objectsMatchingValues

public static NSArray objectsMatchingValues(EOEditingContext anEditingContext,
                                            String anEntityName,
                                            NSDictionary aValueDictionary,
                                            EOFetcher.Store aStore)
Creates EOKeyValueQualifiers for each key-value pair in the specified dictionary, ANDs these qualifiers together into an EOAndQualifier, and returns matching Enterprise Objects.

Parameters:
anEditingContext - an EOEditingContext
anEntityName - the name of the EOEntity
aValueDictionary - an NSDictionary of key-value pairs
aStore - the Store to fetch from

objectsMatchingKeyAndValue

public static NSArray objectsMatchingKeyAndValue(EOEditingContext anEditingContext,
                                                 String anEntityName,
                                                 String aKey,
                                                 Object aValue,
                                                 EOFetcher.Store aStore)
Creates an EOKeyValueQualifier with the specified key and value and returns matching Enterprise Objects.

Parameters:
anEditingContext - an EOEditingContext
anEntityName - the name of the EOEntity
aKey - key for query
aValue - value for property
aStore - the Store to fetch from

objectsWithFetchSpecificationNameAndBindings

public static NSArray objectsWithFetchSpecificationNameAndBindings(EOEditingContext anEditingContext,
                                                                   String anEntityName,
                                                                   String aFetchSpecificationName,
                                                                   NSDictionary aBindingsDictionary,
                                                                   EOFetcher.Store aStore)
Fetches the Enterprise Objects retrieved with the specified fetch specification and bindings.

Parameters:
anEditingContext - an EOEditingContext
anEntityName - the name of the EOEntity
aFetchSpecificationName - the name of the EOFetchSpecification for the entity
aBindingsDictionary - an NSDictionary of bindings for EOQualifierVariables in the EOFetchSpecification
aStore - the Store to fetch from

objectsForEntityNamed

public static NSArray objectsForEntityNamed(EOEditingContext anEditingContext,
                                            String anEntityName,
                                            EOFetcher.Store aStore)
Fetches the Enterprise Objects associated with the specified entity.

Parameters:
anEditingContext - an EOEditingContext
anEntityName - the name of the EOEntity
aStore - the Store to fetch from

objectNotUniqueForMatchingValues

public static boolean objectNotUniqueForMatchingValues(EOEnterpriseObject anObject,
                                                       NSDictionary aValueDictionary)
Returns true if other objects of the same entity are found in the DBEC Store having the same values for the keys from a key-value dictionary. The object's editing context is used for the fetch. Keys should be properties of the passed in object and the values should be the values of that object.

Parameters:
anObject - the object to be checked for uniqueness
aValueDictionary - an NSDictionary of key-value pairs

objectNotUniqueForMatchingKeyAndValue

public static boolean objectNotUniqueForMatchingKeyAndValue(EOEnterpriseObject anObject,
                                                            String aKey,
                                                            Object aValue)
Returns true if other objects of the same entity are found in the DBEC Store having the same value for a key. The object's editing context is used for the fetch. The key should be a property of the passed in object and the value should be the value of that object.

Parameters:
anObject - the object to be checked for uniqueness
aKey - the property of anObject
aValue - the property's value of anObject

objectNotUniqueForFetchSpecificationNameAndBindings

public static boolean objectNotUniqueForFetchSpecificationNameAndBindings(EOEnterpriseObject anObject,
                                                                          String aFetchSpecificationName,
                                                                          NSDictionary aBindingsDictionary)
Returns true if other objects of the same entity are found in the DBEC Store with a fetch specification and bindings. The object's editing context is used for the fetch.

Parameters:
anObject - the object to be checked for uniqueness
aFetchSpecificationName - the name of the EOFetchSpecification for the entity
aBindingsDictionary - an NSDictionary of bindings for EOQualifierVariables in the EOFetchSpecification