merge fflib-apex-common back to master of fork

.gitignore

@@ -1,3 +1,4 @@
+.vim-force.com/
 
 *.prefs
 

README.md

@@ -1,5 +1,5 @@
-FinancialForce Apex Common
-==========================
+FFLib Apex Common
+=================
 
 [![Build Status](https://travis-ci.org/financialforcedev/fflib-apex-common.svg)](https://travis-ci.org/financialforcedev/fflib-apex-common) 
 

fflib/src/classes/fflib_ApplicationTest.cls

@@ -1,5 +1,5 @@
 /**
- * Copyright (c) 2014, FinancialForce.com, inc
+ * Copyright (c) 2014-2015, FinancialForce.com, inc
  * All rights reserved.
  *
  * Redistribution and use in source and binary forms, with or without modification, 

fflib/src/classes/fflib_ISObjectDomain.cls

@@ -6,7 +6,7 @@
 * infringement of copyright and may result in criminal or other legal
 * proceedings.
 *
-* Copyright (c) 2013 FinancialForce.com, inc. All rights reserved.
+* Copyright (c) 2013-2014 FinancialForce.com, inc. All rights reserved.
 */
 
 public interface fflib_ISObjectDomain 

fflib/src/classes/fflib_ISObjectSelector.cls

@@ -6,7 +6,7 @@
 * infringement of copyright and may result in criminal or other legal
 * proceedings.
 *
-* Copyright (c) 2013 FinancialForce.com, inc. All rights reserved.
+* Copyright (c) 2013-2014 FinancialForce.com, inc. All rights reserved.
 */
 
 public interface fflib_ISObjectSelector

fflib/src/classes/fflib_ISObjectUnitOfWork.cls

@@ -6,7 +6,7 @@
 * infringement of copyright and may result in criminal or other legal
 * proceedings.
 *
-* Copyright (c) 2013 FinancialForce.com, inc. All rights reserved.
+* Copyright (c) 2013-2014 FinancialForce.com, inc. All rights reserved.
 */
 
 /**
@@ -53,6 +53,20 @@ public interface fflib_ISObjectUnitOfWork
      * @param relatedTo A SOBject instance (yet to be commited to the database)
      */
     void registerRelationship(Messaging.SingleEmailMessage email, SObject relatedTo);
+    /**
+     * Registers a relationship between a record and a lookup value using an external ID field and a provided value. This
+     * information will be used during the commitWork phase to make the lookup reference requested when inserted to the database.
+     *
+     * @param record An existing or newly created record
+     * @param relatedToField A SObjectField reference to the lookup field that relates the two records together
+     * @param externalIdField A SObjectField reference to a field on the target SObject that is marked as isExternalId
+     * @param externalId A Object representing the targetted value of the externalIdField in said lookup
+     *
+     * Usage Example: uow.registerRelationship(recordSObject, record_sobject__c.relationship_field__c, lookup_sobject__c.external_id__c, 'abc123');
+     *
+     * Wraps putSObject, creating a new instance of the lookup sobject using the external id field and value.
+     */
+     void registerRelationship(SObject record, Schema.sObjectField relatedToField, Schema.sObjectField externalIdField, Object externalId);
     /**
      * Register an existing record to be updated during the commitWork method
      *

fflib/src/classes/fflib_QueryFactory.cls

@@ -1,5 +1,5 @@
 /**
- * Copyright (c) 2014, FinancialForce.com, inc
+ * Copyright (c) 2014-2015, FinancialForce.com, inc
  * All rights reserved.
  *
  * Redistribution and use in source and binary forms, with or without modification, 

fflib/src/classes/fflib_QueryFactoryTest.cls

@@ -1,5 +1,5 @@
 /**
- * Copyright (c) 2014, FinancialForce.com, inc
+ * Copyright (c) 2014-2015, FinancialForce.com, inc
  * All rights reserved.
  *
  * Redistribution and use in source and binary forms, with or without modification, 

fflib/src/classes/fflib_SObjectMocks.cls

@@ -76,6 +76,11 @@ public class fflib_SObjectMocks
 			mocks.mockVoidMethod(this, 'registerRelationship', new List<Type> {Messaging.SingleEmailMessage.class, SObject.class}, new List<Object> {email, relatedTo});
 		}
 
+        public void registerRelationship(SObject record, Schema.sObjectField relatedToField, Schema.sObjectField externalIdField, Object externalId)
+        {
+            mocks.mockVoidMethod(this, 'registerRelationship', new List<Type> {SObject.class, Schema.sObjectField.class, Schema.sObjectField.class, Object.class}, new List<Object> {record, relatedToField, externalIdField, externalId});
+		}
+
 		public void registerDirty(SObject record)
 		{
 			mocks.mockVoidMethod(this, 'registerDirty', new List<Type> {SObject.class}, new List<Object> {record});

fflib/src/classes/fflib_SObjectUnitOfWork.cls

@@ -273,6 +273,28 @@ public virtual class fflib_SObjectUnitOfWork
         m_relationships.get( Messaging.SingleEmailMessage.class.getName() ).add(email, relatedTo);
     }
 
+    /**
+     * Registers a relationship between a record and a lookup value using an external ID field and a provided value. This
+     * information will be used during the commitWork phase to make the lookup reference requested when inserted to the database.
+     *
+     * @param record An existing or newly created record
+     * @param relatedToField A SObjectField reference to the lookup field that relates the two records together
+     * @param externalIdField A SObjectField reference to a field on the target SObject that is marked as isExternalId
+     * @param externalId A Object representing the targetted value of the externalIdField in said lookup
+     *
+     * Usage Example: uow.registerRelationship(recordSObject, record_sobject__c.relationship_field__c, lookup_sobject__c.external_id__c, 'abc123');
+     *
+     * Wraps putSObject, creating a new instance of the lookup sobject using the external id field and value.
+     */
+    public void registerRelationship(SObject record, Schema.sObjectField relatedToField, Schema.sObjectField externalIdField, Object externalId)
+    {
+        // NOTE: Due to the lack of ExternalID references on Standard Objects, this method can not be provided a standardized Unit Test. - Rick Parker
+        String sObjectType = record.getSObjectType().getDescribe().getName();
+        if(!m_newListByType.containsKey(sObjectType))
+            throw new UnitOfWorkException(String.format('SObject type {0} is not supported by this unit of work', new String[] { sObjectType }));
+        m_relationships.get(sObjectType).add(record, relatedToField, externalIdField, externalId);
+    }
+
     /**
      * Register an existing record to be updated during the commitWork method
      *
@@ -678,6 +700,42 @@ public virtual class fflib_SObjectUnitOfWork
 
         }
 
+        public void add(SObject record, Schema.sObjectField relatedToField, Schema.SObjectField externalIdField, Object externalId)
+        {
+            if (relatedToField == null) {
+                throw new UnitOfWorkException('Invalid argument: relatedToField.');
+            }
+
+            String relationshipName = relatedToField.getDescribe().getRelationshipName();
+            if (String.isBlank(relationshipName)) {
+                throw new UnitOfWorkException('Invalid argument: relatedToField. Field supplied is not a relationship field.');
+            }
+
+            List<Schema.SObjectType> relatedObjects = relatedToField.getDescribe().getReferenceTo();
+            Schema.SObjectType relatedObject = relatedObjects[0];
+
+            String externalIdFieldName = externalIdField.getDescribe().getName();
+            Boolean relatedHasExternalIdField = relatedObject.getDescribe().fields.getMap().keySet().contains(externalIdFieldName.toLowerCase());
+            Boolean externalIdFieldIsValid = externalIdField.getDescribe().isExternalId();
+
+            if (!relatedHasExternalIdField) {
+                throw new UnitOfWorkException('Invalid argument: externalIdField. Field supplied is not a known field on the target sObject.');
+            }
+
+            if (!externalIdFieldIsValid) {
+                throw new UnitOfWorkException('Invalid argument: externalIdField. Field supplied is not a marked as an External Identifier.');
+            }
+
+            RelationshipByExternalId relationship = new RelationshipByExternalId();
+            relationship.Record = record;
+            relationship.RelatedToField = relatedToField;
+            relationship.RelatedTo = relatedObject;
+            relationship.RelationshipName = relationshipName;
+            relationship.ExternalIdField = externalIdField;
+            relationship.ExternalId = externalId;
+            m_relationships.add(relationship);
+        }
+
         public void add(SObject record, Schema.sObjectField relatedToField, SObject relatedTo)
         {
             // Relationship to resolve
@@ -702,6 +760,23 @@ public virtual class fflib_SObjectUnitOfWork
         void resolve();
     }
 
+    private class RelationshipByExternalId implements IRelationship
+    {
+        public SObject Record;
+        public Schema.sObjectField RelatedToField;
+        public Schema.SObjectType RelatedTo;
+        public String RelationshipName;
+        public Schema.sObjectField ExternalIdField;
+        public Object ExternalId;
+
+        public void resolve()
+        {
+            SObject relationshipObject = this.RelatedTo.newSObject();
+            relationshipObject.put( ExternalIdField.getDescribe().getName(), this.ExternalId );
+            this.Record.putSObject( this.RelationshipName, relationshipObject );
+        }
+    }
+
     private class Relationship implements IRelationship
     {
         public SObject Record;

fflib/src/classes/fflib_StringBuilder.cls

@@ -1,5 +1,5 @@
 /**
- * Copyright (c), FinancialForce.com, inc
+ * Copyright (c) 2013-2014, FinancialForce.com, inc
  * All rights reserved.
  *
  * Redistribution and use in source and binary forms, with or without modification, 

fflib/src/classes/fflib_StringBuilderTest.cls

@@ -1,5 +1,5 @@
 /**
- * Copyright (c), FinancialForce.com, inc
+ * Copyright (c) 2013-2014, FinancialForce.com, inc
  * All rights reserved.
  *
  * Redistribution and use in source and binary forms, with or without modification,