title: In Jersey, how do you deal with @POST parameters of a deeply nested, complex object?
body: <p>I'm using Jersey 1.x here and I have a <code>@POST</code> method that requires sending over a deeply nested, complex object.  I'm not sure of all my options, but it seems like a lot are <a href="http://jersey.java.net/nonav/documentation/1.8/user-guide.html#d4e253" rel="nofollow">described in this documentation</a>: </p>
  
  <blockquote>
    <p>In general the Java type of the method parameter may:</p>
    
    <ol>
    <li><p>Be a primitive type;</p></li>
    <li><p>Have a constructor that accepts a single String argument;</p></li>
    <li><p>Have a static method named valueOf or fromString that accepts a single String argument (see, for example, Integer.valueOf(String) and
    java.util.UUID.fromString(String)); or</p></li>
    <li><p>Be List, Set or SortedSet, where T satisfies 2 or 3 above. The resulting collection is read-only.</p></li>
    </ol>
  </blockquote>
  
  <p>Ideally, I wish that I could define a method like this:</p>
  
  <pre><code>@POST
  @Consumes(MediaType.APPLICATION_FORM_URLENCODED)
  @Path("complexObject")
  public void complexObject(@FormParam("complexObject") ComplexObject complexObject) throws Exception {
  </code></pre>
  
  <p>But I guess I can only do that if my object satisfies the requirements above (which in my case, it does not).  To me it seems that I have a choice.  </p>
  
  <h3>Option 1: Implement <code>fromString</code></h3>
  
  <p>Implement item #3 above.  </p>
  
  <h3>Option 2: Pass in the <code>complexObject</code> in pieces</h3>
  
  <p>Break up the <code>complexObject</code> into pieces so the parameters become this:</p>
  
  <pre><code>@POST
  @Consumes(MediaType.APPLICATION_FORM_URLENCODED)
  @Path("complexObject")
  public void complexObject(@FormParam("piece1") LessComplexPiece lessComplexPiece1, 
  @FormParam("piece2") LessComplexPiece lessComplexPiece2, 
  @FormParam("piece3") LessComplexPiece lessComplexPiece3) throws Exception {
  </code></pre>
  
  <p>This may not be enough if <code>LessComplexPiece</code> does not satisfy the requirements above.  I'm wondering what the best option is here.  What do people usually do in this situation?  Here are the pros and cons I can think of:</p>
  
  <h1>Cons of Implement <code>fromString</code></h1>
  
  <ul>
  <li>Have to maintain a custom deserializer.  Every time the class is modified, this deserializer may break.  There's more risk for bugs in general.</li>
  <li>It will probably be impossible to generate documentation that describes the pieces of the complex object.  I'll have to write that by hand.</li>
  <li>For each piece of the complex object, I'll have to write my own casting and validation logic.</li>
  <li>I'm not sure what the post data would look like.  But, this may make it very difficult for someone to call the API from a web page form.  If the resource accepted primitives, it would be easy. EG: <code>complexObject=seralizedString</code> vs <code>firstName=John</code> and <code>lastName=Smith</code></li>
  <li>You may not be able to modify the class for various reasons (thankfully, this is not a limitation for me)</li>
  </ul>
  
  <h1>Pros of Implementing <code>fromString</code></h1>
  
  <ul>
  <li>This could avoid a method with a ton of parameters.  This will make the API less intimidating to use.</li>
  <li>This argument is at the level of abstraction I want to work at in the body of my method:</li>
  <li>I won't have to combine the pieces together by hand (well technically I will, it'll just have to be in the deserializer method)</li>
  <li>The deserializer can be a library that automates the process (XStream, gensen, etc.) and save me a lot of time.  This can mitigate the bug risk.  </li>
  <li>You may run into "namespace" clashes if you flatten the object to send over pieces.  For example, imagine sending over an <code>Employee</code>.  If he has a <code>Boss</code>, you now have to provide a <code>EmployeeFirstName</code> and a <code>BossFirstName</code>.  If you were just deserializing an object, you could nest the data appropriately and not have to include context in your parameter names.  </li>
  </ul>
  
  <p>So which option should I choose?  Is there a 3rd option I'm not aware of?</p>