Added test and documentation for the cache entry

Added categories to the docs for the caching classes

framework/default/ortoo-core/default/classes/fflib-extension/caching/CacheEntry.cls

@@ -1,5 +1,10 @@
-// TODO: document
-// TODO: test
+/**
+ * Represents an entry that exists in the cache.
+ *
+ * Is dated based on the creation time so that entries can later be checked for their staleness
+ *
+ * @group Cache
+ */
 public inherited sharing class CacheEntry
 {
 	Long   createdOnEpoch;
@@ -19,13 +24,24 @@ public inherited sharing class CacheEntry
 		this.createdOnEpoch = ortoo_DateLiterals.epochTime;
 	}
 
+	/**
+	 * States if the current entry is younger than or equal to the the stated age in seconds
+	 *
+	 * @param	Long	The age to compare against, in seconds
+	 * @return	Boolean	Is the current entry younger or equal to the given age
+	 */
 	public Boolean isYoungerThanOrEqualTo( Long compareAgeInSeconds )
 	{
 		Contract.requires( compareAgeInSeconds != null, 'isYoungerThanOrEqualTo called with a null compareAgeInSeconds' );
 
 		return ageInSeconds <= compareAgeInSeconds;
 	}
 
+	/**
+	 * Returns the current value of the entry
+	 *
+	 * @return	Object	The value of the entry
+	 */
 	public Object getValue()
 	{
 		return this.value;

framework/default/ortoo-core/default/classes/fflib-extension/caching/CachedSoqlExecutor.cls

@@ -5,6 +5,8 @@
  *
  * If used, it is recommended that triggers are added to those objects, or code added to the UI that updates the objects
  * referenced in the SOQL that invalidate the cache.
+ *
+ * @group Cache
  */
 public inherited sharing class CachedSoqlExecutor //NOPMD: incorrect report of too many public methods caused by inner classes
 {

framework/default/ortoo-core/default/classes/fflib-extension/caching/ICacheAdaptor.cls

@@ -6,6 +6,8 @@
  *      * Cache.Session / Cache.SessionPartition
  *
  * This allows for the types of cache to be used interchangably / and dynamically
+ *
+ * @group Cache
  */
 public interface ICacheAdaptor
 {

framework/default/ortoo-core/default/classes/fflib-extension/caching/NullCache.cls

@@ -4,6 +4,8 @@
  * Allows for the use of code that will automatically interact with a cache and be able to switch that off dynamically and simply.
  *
  * All users are assumed to be allowed to use the cache, but it describes itself as 'not a cache' and effectively does nothing.
+ *
+ * @group Cache
  */
 public inherited sharing class NullCache implements ICacheAdaptor
 {

framework/default/ortoo-core/default/classes/fflib-extension/caching/ObjectCache.cls

@@ -7,6 +7,11 @@
  *
  * Note: The lifespan of a given object is reset whenever any object in that object's list is written.
  *       That is, either the whole of the list is aged out, or none of it is.
+ *
+ * Note: This implementation does not include age based stalesness on retrieval, but could be enhanced to, if required.
+ * 		 See the alternative 'get' options that are available on ICacheAdaptor
+ *
+ * @group Cache
  */
 public inherited sharing class ObjectCache
 {

framework/default/ortoo-core/default/classes/fflib-extension/caching/OrgCache.cls

@@ -5,6 +5,8 @@
  * custom permission as defined in 'CAN_ACCESS_CACHE_PERMISSION'.
  *
  * Attempting to access the cache without this permission will result in an OrgCache.AccessViolationException
+ *
+ * @group Cache
  */
 public inherited sharing class OrgCache implements ICacheAdaptor
 {

framework/default/ortoo-core/default/classes/fflib-extension/caching/SessionCache.cls

@@ -2,6 +2,8 @@
  * An implementation of the ICacheAdaptor that utilises the Session Level Platform Cache.
  *
  * All users are assumed to have access to the cache.
+ *
+ * @group Cache
  */
 public inherited sharing class SessionCache implements ICacheAdaptor
 {

framework/default/ortoo-core/default/classes/fflib-extension/caching/tests/CacheEntryTest.cls

@@ -0,0 +1,78 @@
+@isTest
+private without sharing class CacheEntryTest
+{
+	@isTest
+	private static void getValue_whenCalled_returnsTheValue() // NOPMD: Test method name format
+	{
+		Object expected = 'thevalue';
+		CacheEntry entry = new CacheEntry( expected );
+
+		Test.startTest();
+			Object got = entry.getValue();
+		Test.stopTest();
+
+		System.assertEquals( expected, got, 'getValue, when called, will return the value' );
+	}
+
+	@isTest
+	private static void isYoungerThanOrEqualTo_whenTheCacheIsYounger_returnsTrue() // NOPMD: Test method name format
+	{
+		TestDateTimeUtils.setCurrentDateTime( 0 );
+		CacheEntry entry = new CacheEntry( 'TheCachedEntry' );
+
+		Test.startTest();
+			TestDateTimeUtils.addToCurrentTime( 100 ); // this means the cache entry is 100 seconds old
+			Boolean got = entry.isYoungerThanOrEqualTo( 150 );
+		Test.stopTest();
+
+		System.assert( got, 'isYoungerThanOrEqualTo, when the cache entry is younger, will return true' );
+	}
+
+	@isTest
+	private static void isYoungerThanOrEqualTo_whenTheCacheIsExactlyTheGivenAge_returnsTrue() // NOPMD: Test method name format
+	{
+		TestDateTimeUtils.setCurrentDateTime( 0 );
+		CacheEntry entry = new CacheEntry( 'TheCachedEntry' );
+
+		Test.startTest();
+			TestDateTimeUtils.addToCurrentTime( 100 ); // this means the cache entry is 100 seconds old
+			Boolean got = entry.isYoungerThanOrEqualTo( 100 );
+		Test.stopTest();
+
+		System.assert( got, 'isYoungerThanOrEqualTo, when the cache entry is exactly the stated age, will return true' );
+	}
+
+	@isTest
+	private static void isYoungerThanOrEqualTo_whenTheCacheIsOlder_returnsFalse() // NOPMD: Test method name format
+	{
+		TestDateTimeUtils.setCurrentDateTime( 0 );
+		CacheEntry entry = new CacheEntry( 'TheCachedEntry' );
+
+		Test.startTest();
+			TestDateTimeUtils.addToCurrentTime( 100 ); // this means the cache entry is 100 seconds old
+			Boolean got = entry.isYoungerThanOrEqualTo( 50 );
+		Test.stopTest();
+
+		System.assert( ! got, 'isYoungerThanOrEqualTo, when the cache entry is older, will return false' );
+	}
+
+	@isTest
+	private static void isYoungerThanOrEqualTo_whenPassedANullAge_throwsAnException() // NOPMD: Test method name format
+	{
+		CacheEntry entry = new CacheEntry( 'TheCachedEntry' );
+
+		Test.startTest();
+			String exceptionMessage;
+			try
+			{
+				entry.isYoungerThanOrEqualTo( null );
+			}
+			catch ( Contract.RequiresException e )
+			{
+				exceptionMessage = e.getMessage();
+			}
+		Test.stopTest();
+
+		ortoo_Asserts.assertContains( 'isYoungerThanOrEqualTo called with a null compareAgeInSeconds', exceptionMessage, 'isYoungerThanOrEqualTo, when passed a null age, will throw an exception' );
+	}
+}

framework/default/ortoo-core/default/classes/fflib-extension/caching/tests/CacheEntryTest.cls-meta.xml

@@ -0,0 +1,5 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<ApexClass xmlns="http://soap.sforce.com/2006/04/metadata">
+    <apiVersion>52.0</apiVersion>
+    <status>Active</status>
+</ApexClass>