DATAMONGO-1805 - Update GridFsOperations documentation.

Fix return type in reference documentation and update Javadoc.

Author: christophstrobl

spring-data-mongodb/src/main/java/org/springframework/data/mongodb/gridfs/GridFsOperations.java

@@ -25,11 +25,10 @@
 import org.springframework.lang.Nullable;
 
 import com.mongodb.client.gridfs.GridFSFindIterable;
-import com.mongodb.gridfs.GridFSFile;
 
 /**
  * Collection of operations to store and read files from MongoDB GridFS.
- * 
+ *
  * @author Oliver Gierke
  * @author Philipp Schneider
  * @author Thomas Darimont
@@ -40,98 +39,102 @@ public interface GridFsOperations extends ResourcePatternResolver {
 
 	/**
 	 * Stores the given content into a file with the given name.
-	 * 
+	 *
 	 * @param content must not be {@literal null}.
 	 * @param filename must not be {@literal null} or empty.
-	 * @return the {@link GridFSFile} just created
+	 * @return the {@link ObjectId} of the {@link com.mongodb.client.gridfs.model.GridFSFile} just created.
 	 */
 	ObjectId store(InputStream content, String filename);
 
 	/**
 	 * Stores the given content into a file with the given name.
-	 * 
+	 *
 	 * @param content must not be {@literal null}.
 	 * @param metadata can be {@literal null}.
-	 * @return the {@link GridFSFile} just created
+	 * @return the {@link ObjectId} of the {@link com.mongodb.client.gridfs.model.GridFSFile} just created.
 	 */
 	ObjectId store(InputStream content, @Nullable Object metadata);
 
 	/**
 	 * Stores the given content into a file with the given name.
-	 * 
+	 *
 	 * @param content must not be {@literal null}.
 	 * @param metadata can be {@literal null}.
-	 * @return the {@link GridFSFile} just created
+	 * @return the {@link ObjectId} of the {@link com.mongodb.client.gridfs.model.GridFSFile} just created.
 	 */
 	ObjectId store(InputStream content, @Nullable Document metadata);
 
 	/**
 	 * Stores the given content into a file with the given name and content type.
-	 * 
+	 *
 	 * @param content must not be {@literal null}.
 	 * @param filename must not be {@literal null} or empty.
 	 * @param contentType can be {@literal null}.
-	 * @return the {@link GridFSFile} just created
+	 * @return the {@link ObjectId} of the {@link com.mongodb.client.gridfs.model.GridFSFile} just created.
 	 */
 	ObjectId store(InputStream content, @Nullable String filename, @Nullable String contentType);
 
 	/**
 	 * Stores the given content into a file with the given name using the given metadata. The metadata object will be
 	 * marshalled before writing.
-	 * 
+	 *
 	 * @param content must not be {@literal null}.
 	 * @param filename can be {@literal null} or empty.
 	 * @param metadata can be {@literal null}.
-	 * @return the {@link GridFSFile} just created
+	 * @return the {@link ObjectId} of the {@link com.mongodb.client.gridfs.model.GridFSFile} just created.
 	 */
 	ObjectId store(InputStream content, @Nullable String filename, @Nullable Object metadata);
 
 	/**
 	 * Stores the given content into a file with the given name and content type using the given metadata. The metadata
 	 * object will be marshalled before writing.
-	 * 
+	 *
 	 * @param content must not be {@literal null}.
 	 * @param filename must not be {@literal null} or empty.
 	 * @param contentType can be {@literal null}.
 	 * @param metadata can be {@literal null}
-	 * @return the {@link GridFSFile} just created
+	 * @return the {@link ObjectId} of the {@link com.mongodb.client.gridfs.model.GridFSFile} just created.
 	 */
-	ObjectId store(InputStream content, @Nullable String filename, @Nullable String contentType, @Nullable Object metadata);
+	ObjectId store(InputStream content, @Nullable String filename, @Nullable String contentType,
+			@Nullable Object metadata);
 
 	/**
 	 * Stores the given content into a file with the given name using the given metadata.
-	 * 
+	 *
 	 * @param content must not be {@literal null}.
 	 * @param filename must not be {@literal null} or empty.
 	 * @param metadata can be {@literal null}.
-	 * @return the {@link GridFSFile} just created
+	 * @return the {@link ObjectId} of the {@link com.mongodb.client.gridfs.model.GridFSFile} just created.
 	 */
 	ObjectId store(InputStream content, @Nullable String filename, @Nullable Document metadata);
 
 	/**
 	 * Stores the given content into a file with the given name and content type using the given metadata.
-	 * 
+	 *
 	 * @param content must not be {@literal null}.
 	 * @param filename must not be {@literal null} or empty.
 	 * @param contentType can be {@literal null}.
 	 * @param metadata can be {@literal null}.
-	 * @return the {@link GridFSFile} just created
+	 * @return the {@link ObjectId} of the {@link com.mongodb.client.gridfs.model.GridFSFile} just created.
 	 */
-	ObjectId store(InputStream content, @Nullable String filename, @Nullable String contentType, @Nullable Document metadata);
+	ObjectId store(InputStream content, @Nullable String filename, @Nullable String contentType,
+			@Nullable Document metadata);
 
 	/**
 	 * Returns all files matching the given query. Note, that currently {@link Sort} criterias defined at the
 	 * {@link Query} will not be regarded as MongoDB does not support ordering for GridFS file access.
-	 * 
+	 *
 	 * @see <a href="https://jira.mongodb.org/browse/JAVA-431">MongoDB Jira: JAVA-431</a>
 	 * @param query must not be {@literal null}.
-	 * @return
+	 * @return {@link GridFSFindIterable} to obtain results from. Eg. by calling
+	 *         {@link GridFSFindIterable#into(java.util.Collection)}.
 	 */
 	GridFSFindIterable find(Query query);
 
 	/**
-	 * Returns a single file matching the given query or {@literal null} in case no file matches.
-	 * 
+	 * Returns a single {@link com.mongodb.client.gridfs.model.GridFSFile} matching the given query or {@literal null} in
+	 * case no file matches.
+	 *
 	 * @param query must not be {@literal null}.
 	 * @return
 	 */
@@ -140,14 +143,14 @@ public interface GridFsOperations extends ResourcePatternResolver {
 
 	/**
 	 * Deletes all files matching the given {@link Query}.
-	 * 
+	 *
 	 * @param query must not be {@literal null}.
 	 */
 	void delete(Query query);
 
 	/**
-	 * Returns all {@link GridFsResource} with the given file name.
-	 * 
+	 * Returns the {@link GridFsResource} with the given file name.
+	 *
 	 * @param filename must not be {@literal null}.
 	 * @return the resource if it exists or {@literal null}.
 	 * @see ResourcePatternResolver#getResource(String)
@@ -156,7 +159,7 @@ public interface GridFsOperations extends ResourcePatternResolver {
 
 	/**
 	 * Returns all {@link GridFsResource}s matching the given file name pattern.
-	 * 
+	 *
 	 * @param filenamePattern must not be {@literal null}.
 	 * @return
 	 * @see ResourcePatternResolver#getResources(String)

src/main/asciidoc/reference/mongodb.adoc

@@ -2602,7 +2602,7 @@ class GridFsClient {
 
   @Test
   public void findFilesInGridFs() {
-    List<GridFSDBFile> result = operations.find(query(whereFilename().is("filename.txt")))
+    GridFSFindIterable result = operations.find(query(whereFilename().is("filename.txt")))
   }
 }
 ----