Be it X-Form-Urlencoded or JSON HTTP post to a REST resource end-point, there is no specific “data type” for date or time related data. Most developers will have these data posted as “String” or just simply convert them to Unix timestamp value (e.g. 1435061152). But, as developers implement more and more end-point methods, codes to parse of date, time and timestamp string representation values to actual java.sql.Date or java.util.Date will be repetitive (and boring). So, the intention of this article is to show how to implement a custom data type for handling date and time related string values in JAX-RS 2.0 REST end-point method parameters.




Compatibility

The codes were tested with Payara 4.1 and Wildfly 8.2. For the other rest of the application servers and servlet containers, JAX-RS 2.0 libraries / Java EE 7 compatibility is required to run this.

Sample Application

To demonstrate this, let’s build a sample application that has a JAX-RS REST resource end-point which takes custom data type object classes through @FormParam parameter values and converting them to java.sql.Date, java.sql.Time, java.sql.Timestamp and java.util.Date for convenience.

Example HTTP POST Request

Let’s say a HTTP POST of the below URL is made (with “SampleApplication” as the application name and therefore, the context):

http://<hostname>:<port>/SampleApplication/rest-api/request-handler/post-request-with-dates-and-time/

As for the HTTP parameters to be posted along with this URL, they are:

Post ParametersValue (String)SimpleDateFormat patternCustom Data Type Class Name
date_field1948-05-15yyyy-MM-ddRESTDateParam
time_field3:23PMh:mmaRESTTimeParam
timestamp_field1979-10-11T14:45:00yyyy-MM-dd’T’HH:mm:ssRESTTimestampParam
timestamp_with_tzd_field1979-10-11T14:45:00+0800yyyy-MM-dd’T’HH:mm:ssZRESTTimestampWithTZDParam

Implementing The Custom Data Type Classes

Parsing the date string value and converting it to java.sql.Date

First, let’s write a custom data type class that handles the parameter “date_field“, which parses the string representation of date in the format ‘yyyy-MM-dd‘ and turning it to java.sql.Date.

Codes for RESTDateParam.java

Code Explanation
Here, we first define the appropriate date format e.g. “yyyy-MM-dd” for SimpleDateFormat to parse the date string. Once the constructor had been invoked and after the conversion, we can then grab the java.sql.Date object through the getDate() method. Besides java.sql.Date, you may want the resulting object to be either java.util.Date or java.util.Calendar and that’s fine, which largely depends on the application specifics. Here, since we don’t keep extra information of time and time zone, just a plain java.sql.Date is good enough.

Like so for the rest of the custom data type classes below.

Parsing the time string value (with AM/PM indicator) and converting it to java.sql.Time

Codes for RESTTimeParam.java

Parsing the date and time string value and converting it to java.sql.Timestamp

Codes for RESTTimestampParam.java

Parsing the time string value (with time zone data) and converting it to java.util.Date (with time zone information)

Codes for RESTTimestampWithTZDParam.java

Implementing the REST Resource End-Point

So after the necessary custom data type classes to handle various formats of date and time were defined. The REST resource end-point method will now be able to use these classes to encapsulate various data format given. All that is to do is to use it directly as the data type of the end-point method arguments. For example:

// ...
@POST
@Path( "/path-root/path-value" )
public Response methodThatHandlesPostRequest(
    @FormParam( "date_field" ) RESTDateParam dateField
) {
    // The rest of the implementation...
}
// ...

Let’s take a look at a complete JAX-RS 2.0 REST Resource End-Point implementation example.

Codes for RESTResource.java

Not forgetting the initiating REST Application class that extends javax.ws.rs.core.Application…

Codes for RESTApplication

Testing through a HTML Client with jQuery Ajax POST

To test the custom data type classes, a simple HTML page was written with the use of jQuery, which performs an ajax HTTP POST to the end-point URL. Just package the below HTML file as part of the web app to be deployed together for testing. Please deployed this to the appropriate application server or servlet container.

Codes for post-with-custom-param-data-type.html

The Result

Once the ‘Submit‘ button is clicked, the HTML client should receive the rightful JSON response from the REST Resource End-Point method (path: post-request-with-custom-param-data-type) and be displayed at the bottom of the screen.


Post Result

Post Result


That’s all. Thank you for reading and hope it helps.

Max Lam
About the Author

Born and currently resides in Malaysia, a seasoned Java developer whom had held positions as Senior Developer, Consultant and Technical Architect in various enterprise software development companies.

Related Posts

(adsbygoogle = window.adsbygoogle || []).push({}); I was performing evaluation on various SaaS...

There are times that retrieving a large data set through JPA is necessary (e.g. more than 1,000,000...

By default, JAX-RS Response is cached (at least on Glassfish Application Server). If you are...