[418] @FormParam spec and example changes

Signed-off-by: Andy McCright <j.andrew.mccright@gmail.com>
jakartaee · May 5, 2021 · b5319b0 · b5319b0
1 parent 88e9517
commit b5319b0
Show file tree

Hide file tree

Showing 2 changed files with 37 additions and 11 deletions.
diff --git a/examples/src/main/java/jaxrs/examples/multipart/MultipartResource.java b/examples/src/main/java/jaxrs/examples/multipart/MultipartResource.java
@@ -16,13 +16,18 @@
 import java.util.List;
 
 import jakarta.ws.rs.BadRequestException;
+import jakarta.ws.rs.Consumes;
+import jakarta.ws.rs.FormParam;
 import jakarta.ws.rs.GET;
 import jakarta.ws.rs.NotFoundException;
+import jakarta.ws.rs.NotSupportedException;
 import jakarta.ws.rs.POST;
 import jakarta.ws.rs.Path;
+import jakarta.ws.rs.Produces;
 import jakarta.ws.rs.QueryParam;
 import jakarta.ws.rs.WebApplicationException;
 import jakarta.ws.rs.core.EntityPart;
+import jakarta.ws.rs.core.MediaType;
 import jakarta.ws.rs.core.Response;
 
 @Path("/multipart")
@@ -31,6 +36,7 @@ public class MultipartResource {
     private static final String PDF_ROOT_DIR = System.getProperty("pdf.root.dir", "/myPDFs");
 
     @GET
+    @Produces(MediaType.MULTIPART_FORM_DATA)
     public List<EntityPart> getAllPdfFilesInDirectory(@QueryParam("dirName") String dirName) throws IOException {
         File dir = getDirectoryIfExists(dirName);
         List<EntityPart> parts = new ArrayList<>();
@@ -43,6 +49,7 @@ public List<EntityPart> getAllPdfFilesInDirectory(@QueryParam("dirName") String
     }
 
     @POST
+    @Consumes(MediaType.MULTIPART_FORM_DATA)
     public Response postNewPdfFiles(@QueryParam("dirName") String dirName, List<EntityPart> parts) throws IOException {
         File dir = getDirectoryIfExists(dirName);
         for (EntityPart p : parts) {
@@ -57,11 +64,34 @@ public Response postNewPdfFiles(@QueryParam("dirName") String dirName, List<Enti
         return Response.ok().build();
     }
 
+    @Path("/apply")
+    @POST
+    @Consumes(MediaType.MULTIPART_FORM_DATA)
+    public Response applyForJob(@FormParam("name") String name,
+                                @FormParam("recentPhoto") InputStream photoStream,
+                                @FormParam("resume") EntityPart resume) {
+
+        String resumeFileName = resume.getFileName().orElseThrow(NotSupportedException::new);
+
+        if (resumeFileName.toLowerCase().endsWith(".pdf")) {
+            processPdfResume(resume.getContent());
+        } else {
+            // handle other file types, like Word docs, etc.
+        }
+
+        // process new application...
+        return Response.ok("Application received").build();
+    }
+
     private File getDirectoryIfExists(String dirName) {
         File dir = new File(PDF_ROOT_DIR, dirName);
         if (!dir.exists()) {
             throw new NotFoundException("dirName, " + dirName + ", does not exist");
         }
         return dir;
     }
+
+    private void processPdfResume(InputStream is) {
+        // ...
+    }
 }
diff --git a/...s-spec/src/main/asciidoc/chapters/resources/_declaring_method_capabilities.adoc b/...s-spec/src/main/asciidoc/chapters/resources/_declaring_method_capabilities.adoc
@@ -163,10 +163,8 @@ public class WidgetsResource3 {
 
 Another approach is to use `@FormParam` parameters where the value in the
 annotation corresponds to the name of the part. The parameter type may be
-a `jakarta.ws.rs.core.EntityPart`, a `java.io.InputStream`, a `String`, or
-any type that can be converted to using a registered `MessageBodyReader` or
-`ParamConverter`. Here is
-an example:
+a `jakarta.ws.rs.core.EntityPart`, a `java.io.InputStream`, or a `String`.
+Here is an example:
 
 [source,java]
 ----
@@ -177,17 +175,15 @@ public class WidgetsResource4 {
     @Consumes(MediaType.MULTIPART_FORM_DATA)
     public Response postWidget(@FormParam("part1Name") String part1, 
                                @FormParam("part2Name") InputStream part2,
-                               @FormParam("part3Name") EntityPart part3,
-                               @FormParam("part4Name") Widget part4) {...}
+                               @FormParam("part3Name") EntityPart part3) {...}
 }
 ----
 
 The only way to access the headers for a particular part is to use the
-`EntityPart` type. The `InputStream`, `String`, and additional parameter
-types will only provide the content of the part. Note that parts of a
-multipart entity can be quite large, so care should be taken when using
-`String` parameter types as that will load the entire content of the part
-into the Java heap.
+`EntityPart` type. The `InputStream` and `String` types will only provide
+the content of the part. Note that parts of a multipart entity can be quite
+large, so care should be taken when using `String` parameter types as that
+will load the entire content of the part into the Java heap.
 
 When converting the part's content, the implementation MUST use the encoding
 charset specified in the part's `Content-Type` header, or `UTF-8` if the