EOFetcher (WOUnitTest 2 API)

org.pekeler.eof
Class EOFetcher

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

public class EOFetcher
extends Object
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

org.pekeler.eof Class EOFetcher

DB

EC