Merge remote-tracking branch 'origin/master' into

refactor_add_support_for_other_rest_clients

Author: rmcdouga

fluentforms/core/src/main/java/com/_4point/aem/fluentforms/api/DocumentFactory.java

@@ -7,16 +7,62 @@
 
 import com._4point.aem.fluentforms.impl.AdobeDocumentFactoryImpl;
 
+/**
+ * Factory class for creating Document objects.  In AEM server-side code, this is usually an AdobeDocumentFactoryImpl class 
+ * and in client code this is usually a SimpleDocumentFactoryImpl.
+ */
 public interface DocumentFactory {
 
+	/**
+	 * Creates a Document from a byte-array.  
+	 * 
+	 * @param data - The byte-array serving as the content-source for the Document.
+	 * @return
+	 */
 	public Document create(byte[] data);
 
+	/**
+	 * Creates a Document from a file. 
+	 * 
+	 * @deprecated Use create(Path) instead.
+	 * 
+	 * @param file - The file serving as the content-source for the Document.
+	 * @param ownFile - Whether the file is henceforth to be managed by the Document.
+	 * @return
+	 */
+	@Deprecated
 	public Document create(File file, boolean ownFile);
 
+	/**
+	 * Creates a Document from a file. Equivalent to create(file, false). See create(java.io.File, boolean) for more details.
+	 * 
+	 * @deprecated Use create(Path) instead.
+	 * 
+	 * @param file - The file serving as the content-source for the Document.
+	 * @return
+	 */
+	@Deprecated
 	public Document create(File file);
 
+	/**
+	 * Creates a Document from a file path. Equivalent to create(file, false). See create(java.io.File, boolean) for more details.
+	 * 
+	 * @param file - The file path serving as the content-source for the Document.
+	 * @return
+	 */
 	public Document create(Path file);
 
+	/**
+	 * Creates a Document from an input-stream. 
+	 * 
+	 * Note that the Document at no point in its life-cycle ever closes the input-stream itself, 
+	 * in keeping with the practice of not managing resources passed in externally unless explicitly instructed to do so. 
+	 * Hence, it is the responsibility of the application creating the Document to also close the input-stream properly 
+	 * when the time comes. 
+	 * 
+	 * @param is - The input-stream serving as the content-source for the Document.
+	 * @return
+	 */
 	public Document create(InputStream is);
 
 //  Removed because this won't work with the client version of this library.  This may be re-instated later
@@ -26,12 +72,38 @@ public interface DocumentFactory {
 //
 //	public Document create(String jcrPath, ResourceResolver resolver);
 //
+	/**
+	 * For internal use only.
+	 * 
+	 * @param jcrPath
+	 * @return
+	 */
 	public Document create(String jcrPath);
 
+	/**
+	 * For internal use only.
+	 * 
+	 * @param url
+	 * @return
+	 */
 	public Document create(URL url);
 
+	/**
+	 * For internal use only.
+	 * 
+	 * @param document
+	 * @return
+	 */
 	public Document create(com.adobe.aemfd.docmanager.Document document);	
 
+	/**
+	 * Intended as a convenience method however it returns an AdobeDocumentFactoryImpl which is not useful
+	 * for client side code, so it's best to avoid using this unless you know what you are doing.
+	 * 
+	 * It may be deprecated and removed in the future version of FluentForms.
+	 * 
+	 * @return
+	 */
 	public static DocumentFactory getDefault() {
 		return AdobeDocumentFactoryImpl.getFactory();
 	}

fluentforms/core/src/main/java/com/_4point/aem/fluentforms/impl/SimpleDocumentFactoryImpl.java

@@ -3,12 +3,12 @@
 import java.io.ByteArrayInputStream;
 import java.io.ByteArrayOutputStream;
 import java.io.File;
-import java.io.FileInputStream;
-import java.io.FileNotFoundException;
 import java.io.IOException;
 import java.io.InputStream;
 import java.io.OutputStream;
+import java.io.UncheckedIOException;
 import java.net.URL;
+import java.nio.file.Files;
 import java.nio.file.Path;
 import java.util.Arrays;
 import java.util.Map;
@@ -26,12 +26,19 @@ public enum SimpleDocumentFactoryImpl implements DocumentFactory {
 
 	private static final Document EMPTY_DOCUMENT = new EmptyDocumentImpl();
 
+	/**
+	 * Returns a singleton instance of this SimpleDocumentFactoryImpl.
+	 * 
+	 * @return - singleton instance of SimpleDocumentFactoryImpl
+	 */
 	public static DocumentFactory getFactory() {
 		return INSTANCE;
 	}
 
 	/* (non-Javadoc)
 	 * @see com._4point.aem.fluentforms.api.DocumentFactory#create(byte[])
+	 * 
+	 * It holds a defensive copy of the array in memory.
 	 */
 	@Override
 	public Document create(byte[] data) {
@@ -42,6 +49,7 @@ public Document create(byte[] data) {
 	 * @see com._4point.aem.fluentforms.api.DocumentFactory#create(java.io.File, boolean)
 	 */
 	@Override
+	@Deprecated
 	public Document create(File file, boolean ownFile) {
 		return new SimpleDocumentImpl(file, ownFile);
 	}
@@ -50,6 +58,7 @@ public Document create(File file, boolean ownFile) {
 	 * @see com._4point.aem.fluentforms.api.DocumentFactory#create(java.io.File)
 	 */
 	@Override
+	@Deprecated
 	public Document create(File file) {
 		return new SimpleDocumentImpl(file);
 	}
@@ -127,20 +136,19 @@ private SimpleDocumentImpl(byte[] data) {
 
 		private SimpleDocumentImpl(File file, boolean ownFile) {
 			// We ignore the ownFile parameter because we don't care.  We are going to just read it in anyway.
-			try {
-				this.inlineData = readToByteArray(new FileInputStream(file));
-			} catch (FileNotFoundException e) {
-				// Convert to runtime exception.
-				throw new IllegalArgumentException("File not found. (" + file.toString() + ").", e);
-			}
+			this(file.toPath());
 		}
 
 		private SimpleDocumentImpl(File file) {
+			this(file.toPath());
+		}
+
+		private SimpleDocumentImpl(Path path) {
 			try {
-				this.inlineData = readToByteArray(new FileInputStream(file));
-			} catch (FileNotFoundException e) {
+				this.inlineData = Files.readAllBytes(path);
+			} catch (IOException e) {
 				// Convert to runtime exception.
-				throw new IllegalArgumentException("File not found. (" + file.toString() + ").", e);
+				throw new UncheckedIOException("Error reading file (" + path.toString() + ").", e);
 			}
 		}
 

fluentforms/pom.xml

@@ -85,7 +85,7 @@
 		<pitest.junit5.maven.plugin.version>1.2.1</pitest.junit5.maven.plugin.version>
 
 		<!-- Testing dependencies -->
-        <mockito.version>5.8.0</mockito.version>
+        <mockito.version>4.11.0</mockito.version> <!-- Last version that supports Java 8 -->
         <junit.version>5.10.1</junit.version>
         <wcm.mocks.version>5.4.0</wcm.mocks.version>
         <slf4j-test.version>1.2.0</slf4j-test.version>