Sons of DHTMLX and Spring #3

Episode 3: Turning and Turning

DHTMLX Spring Adapter
In the picture below you will find  the DHTMLX Spring Adapter class diagram for the dhtmlxGrid component.

click to enlarge

Each adapter implements the Adapter interface, which consists of the single method toXML. The AbstractAdapter class, is the base class of all the adapters and encapsulates  the methods common to all the subclasses. 
The DhtmlxHttpMessageConveter, is the class which integrates the adapters with the Spring framework. 


Spring Message Converters

The Spring MVC allows to handle any format of HTTP request and responses using a HttpMessageConverter implementation. Spring registers a set of default converters, but it is  also possible write your own and register it in the configuration file: 

1. <mvc:annotation-driven>
2.   <mvc:message-converters>
3.     <bean class="com.mylaensys.dhtmlx.adapter.DhtmlxHttpMessageConverter"/>
4.   </mvc:message-converters>
5. </mvc:annotation-driven>

Below the code of the message converter.

DhtmlxHttpMessageConverter.java

1. public class DhtmlxHttpMessageConverter
2.   extends AbstractHttpMessageConverter<Object> {
3.     public static final Charset DEFAULT_CHARSET = Charset.forName("UTF-8");
5.     public DhtmlxHttpMessageConverter() {
6.         super(new MediaType("text", "xml", DEFAULT_CHARSET));
7.     }
9.     @Override
10.     protected boolean supports(Class<?> clazz) {
11.         Class[] theInterfaces = clazz.getInterfaces();
12.         for (int i = 0; i < theInterfaces.length; i++) {
13.             if( theInterfaces[i].getName().equalsIgnoreCase( Adapter.class.getName() ) ) {
14.                 return true;
15.             }
16.         }
17.         return false;
18.     }
21.     @Override
22.     protected void writeInternal(Object object, HttpOutputMessage outputMessage)
23.   throws IOException, HttpMessageNotWritableException {
24.         Adapter adapter = (Adapter)object;
25.         outputMessage.getBody().write( adapter.toXML().getBytes() );
26.     }
27. }

The supports method detects whether the given class is supported by the converter. In this case the class must implement the Adapter interface. When a class is supported, the HttpMessageConverter invokes the writeInternal method to write the object to the Http response body. 
The writeInternal method of the DhtmlxHttpMessageConverter obtains the representation of the object in XML, invoking the toXML method of the Adapter interface. In the example below, the BookController class returns an instance of the DefaultGridAdapter to the DhtmlxHttpMessageConverter.
BookController.java

1. @Controller
2. public class BookController {
3.     @Autowired
4.     private BookService bookService;
5.     @RequestMapping(value = "/books", method = RequestMethod.GET)
6.     public @ResponseBody DefaultGridAdapter getBooks(@RequestParam("c") String c) {
7.         DefaultGridAdapter adapter = new DefaultGridAdapter(c,Book.class);
8.         adapter.setData( bookService.getBooks() );
9.         return adapter;
10.     }
11. }

Another important element is the @ResponseBody which indicates that the return type of a controller method should be written to the HTTP response body, and not placed in a Model, or interpreted as a view name as standard behavior of Spring MVC.


Grid Adapter
The DefaulGridAdapter is a basic adapter for the dhtmlxGrid component. The grid adapter constructor accepts as parameters a string containing the attributes to render, and  the class of the object. The setData method allows to set the collection of data. 
DefaultGridAdapter.java

1. public class DefaultGridAdapter extends AbstractAdapter implements Adapter {
2.     private List data;
3.     private List<String> columnList = new ArrayList<String>();
4.     private GridInterceptor interceptor = new GridInterceptorImpl();
6.     public DefaultGridAdapter(String columnList,Class clazz) {
7.         this.fieldList = getObjectFields(clazz);
9.         StringTokenizer st = new StringTokenizer(columnList,",");
10.         while(st.hasMoreTokens()) {
11.               this.columnList.add(st.nextToken());
12.         }
13.     }
15.     public List getData() {
16.         return data;
17.     }
19.     public void setData(List data) {
20.         this.data = data;
21.     }
23.     public void setInterceptor(GridInterceptor interceptor) {
24.         this.interceptor = interceptor;
25.     }
27.     @Override
28.     public String toXML() {
29.         StringBuffer buffer = new StringBuffer();
30.         buffer.append("<?xml version='1.0' encoding='UTF-8'?>");
31.         interceptor.onHeader(this,data,buffer);
32.         interceptor.onStartRows(this, data, buffer);
34.         for(Object object : data) {
35.             interceptor.onStartRow(this, object, buffer);
36.             for(String column : columnList ) {
37.                 if( fieldList.contains( column ) ) {
38.                     interceptor.onRenderCell(this, object, column, buffer);
39.                 }
40.             }
41.             interceptor.onEndRow(buffer);
42.         }
44.         interceptor.onEndRows(buffer);
46.         interceptor.onOutput(buffer);
47.         return buffer.toString();
48.     }
50. }

The toXML method invokes the interceptor which contains the logic for the XML generation. Below the default implementation of the GridInteceptor.
GridInterceptorImpl.java

1. public class GridInterceptorImpl implements GridInterceptor {
4.     public void onHeader(AbstractAdapter adapter, List list, StringBuffer buffer) {
6.     }
8.     public void onStartRows(AbstractAdapter adapter, List list, StringBuffer buffer) {
9.         buffer.append("<rows>");
10.     }
12.     public void onEndRows(StringBuffer buffer) {
13.         buffer.append("</rows>");
14.     }
16.     public void onStartRow(AbstractAdapter adapter, Object object, StringBuffer buffer) {
17.         buffer.append("<row id='").append( adapter.getPrimaryKey(object).toString() ).append("'>");
18.     }
20.     public void onEndRow(StringBuffer buffer) {
21.         buffer.append("</row>");
22.     }
24.     public void onRenderCell(AbstractAdapter adapter, Object object, String column, StringBuffer buffer) {
25.         Object value = adapter.getObjectValue(object, column);
26.         buffer.append("<cell><![CDATA[").append( value.toString() ).append("]]></cell>");
27.     }
29.     public void onOutput(StringBuffer buffer) {
31.     }
32. }

It is possible to write a custom  GridIntercepter and set it via the setInterceptor method. For example to highlight the rows of the grid which match a condition, it is possible extending the DefaultGridInterceptor and overriding the onStartRow method. The code example below highlights in red the books with a price greater than 10. 

1.  public class GridInterceptorHighLight extends DefaultGridInterceptor {
3.     public void onStartRow(AbstractAdapter adapter, Object object, StringBuffer buffer) {
4.         if( object instanceof Book) {
5.             Book book = (Book)object;
6.             if( book.getPrice() > 10 ) {
7.                 buffer.append("<row id='")
8.       .append( adapter.getPrimaryKey(object).toString() )
9.       .append("' style='color:red;'>");
10.             } else {
11.                 buffer.append("<row id='")
12.       .append( adapter.getPrimaryKey(object).toString() )
13.       .append("'>");
14.             }
15.         }
16.     }
17. }

The same concept applies to the header (onHeader), to a single cell (onRenderCell) and to the end of the XML processing (onOutput). For more information about the grid XML format refer to  DHTMLX documentation.


Form Adapter
The DefaulFormAdapter is a basic adapter for the dhtmlxForm component. The adapter supports the basic operation: read, write and delete. 

GridInterceptorImpl.java

1. public class DefaultFormAdapter extends AbstractAdapter implements Adapter {
2.     public static final String Insert = "inserted";
3.     public static final String Update = "updated";
4.     public static final String Delete = "deleted";
5.     private Object data;
6.     private String operation;
8.     public DefaultFormAdapter(Object data) {
9.         initialize( data );
10.         this.operation = "";
11.     }
12.     public DefaultFormAdapter(Object data,String operation) {
13.         initialize( data );
14.         this.operation = operation;
15.     }
17.     public DefaultFormAdapter(Object data,BindingResult binding) {
18.          initialize(data);
19.          if( binding.hasErrors() ) {
20.              for( FieldError e : binding.getFieldErrors() ) {
21.                 this.errorList.add(new ErrorMessage(e.getField(), e.getDefaultMessage()));
22.             }
23.          }
24.     }
26.     private void initialize(Object data) {
27.         this.fieldList = getObjectFields(data.getClass());
28.         Object id = getPrimaryKey( data );
29.         if( id == null ) {
30.             this.operation = Insert;
31.         } else {
32.             this.operation = Update;
33.         }
34.         this.data = data;
35.     }
37.     public Object getData() {
38.         return data;
39.     }
41.     public void setData(Object data) {
42.         this.data = data;
43.     }
45.     private boolean isWriting() {
46.         return Insert.equalsIgnoreCase( this.operation ) || Update.equalsIgnoreCase( this.operation ) || Delete.equalsIgnoreCase( this.operation ) ;
47.     }
48.     public boolean hasValidData() {
49.         return errorList.size() == 0;
50.     }
52.     public String toErrorXML() {
53.         StringBuffer buffer = new StringBuffer();
54.         String id = getPrimaryKey( data ).toString();
55.         buffer.append("<data>");
56.         for( ErrorMessage e : errorList ) {
57.                 buffer.append("<action sid='").append( id == null ? "" : id.toString() ).append( "' ");
58.                 buffer.append("type='invalid' ");
59.                 buffer.append("field='" + e.getField() + "' ");
60.                 buffer.append("message='" ).append( e.getMessage() ).append("'/>");
61.         }
62.         buffer.append("</data>");
63.         return buffer.toString();
64.     }
66.     @Override
67.     public String toXML() {
68.         StringBuffer buffer = new StringBuffer();
70.         if( isWriting() ) {
71.             if( this.errorList.size() == 0 ) {
72.                 buffer.append( toStoreXML() );
73.             } else {
74.                 buffer.append( toErrorXML() );
75.             }
77.         } else {
78.             buffer.append(toDataXML());
79.         }
80.         return buffer.toString();
81.     }
83.     private String toDataXML() {
84.         StringBuffer buffer = new StringBuffer();
85.         buffer.append("<?xml version='1.0' encoding='UTF-8'?>");
86.         buffer.append("<data>");
87.         try {
88.             if( data != null ) {
89.                 for(String field : fieldList) {
90.                     Object value = getObjectValue(data, field);
91.                     buffer.append("<").append(field).append("><![CDATA[").append( value.toString() ).append(  "]]></").append(field).append(">");
92.                 }
93.             }
94.         } catch (Exception e) {
95.             log.severe(e.getMessage());
96.         }
97.         buffer.append("</data>");
98.         return buffer.toString();
100.     }
102.     public String toStoreXML() {
103.         StringBuffer buffer = new StringBuffer();
104.         buffer.append("<data>");
105.         buffer.append("<action type='").append( this.operation ).append("' ");
106.         if( data != null ) {
107.             String id = getPrimaryKey( data ).toString();
108.             buffer.append("sid='").append( id ).append("' ");
109.             buffer.append("tid='").append( id ).append("'/>");
110.         } else {
111.             buffer.append("field='id' ");
112.             buffer.append("sid='").append( "0" ).append("' ");
113.             buffer.append("tid='").append( "0" ).append("' ");
114.             buffer.append("message='" ).append( "invalid data " ).append("'/>");
115.         }
116.         buffer.append("</data>");
117.         return buffer.toString();
118.     }
119. }

The form adapter toXML method generates  the appropriate XML message depending on the operation. The toDataXML returns the XML for the load method of the dhtmlxForm, toStoreXML and toErrorXML handle the send method. Below an example of the BookController using the form adapter.     

BookController.java

1. public class BookController {
2.     @Autowired
3.     private BookService bookService;
5.     @RequestMapping(value = "/books/{id}", method = RequestMethod.GET)
6.     public @ResponseBody DefaultFormAdapter getBook(@PathVariable("id") final String id) {
7.         Book book = bookService.getBook(id);
8.         DefaultFormAdapter adapter = new DefaultFormAdapter( book );
9.         return adapter;
10.     }
12.     @RequestMapping(value = "/book", method = RequestMethod.POST)
13.     public @ResponseBody DefaultFormAdapter storeBook(@Valid @ModelAttribute Book book, BindingResult binding) {
14.         DefaultFormAdapter adapter = new DefaultFormAdapter(book,binding);
15.         if( adapter.hasValidData() ) {
16.             bookService.store(book);
17.         }
18.         return adapter;
19.     }
21.     @RequestMapping(value = "/book/{id}", method = RequestMethod.DELETE)
22.     public @ResponseBody DefaultFormAdapter deleteBook(@PathVariable("id") final String id) {
23.         Book book = bookService.getBook(id);
24.         DefaultFormAdapter adapter = new DefaultFormAdapter(book,DefaultFormAdapter.Delete);
25.         bookService.remove(id);
26.         return adapter;
27.     }
29. }

The getBook method implements the read operation, while storeBook creates or updates  the object. The DefaultFormAdapter constructor used in the storeBook method takes two parameters: the first one is the model object, the second (BindingResult) holds the result of the validation. When the object contains valid data (hasValidData) the controller can perform write operation to the datastore.    


While waiting for the next episode, don't forget to join the virtual strike against Internet censorship.

Stay Tuned!

Sons of DHTMLX and Spring #2

Episode 2: Caregiver

In the previous episode the DHTMLX Spring Adatper was introduced, now it is time to take care of the object through validation. 



Forms
Since version 2.0 the Spring framework includes a JSP  tag library,  to make writing HTML forms much easier. A typical HTML form written using Spring JSP form tags  looks like the code below: 

Spring Form

1. <%@ taglib uri="http://www.springframework.org/tags/form" prefix="form" %>
2. <form:form id="book" method="post">
3.   <form:label path="author">Author:</form:label>
4.   <form:input path="author"/> <br/>
5.   <form:label path="title">Title:</form:label>
6.   <form:input path="title"/> <br/>
7.   <form:label path="price">Price:</form:label>
8.   <form:input path="price"/> <br/>
9.   <form:label path="sales">Sales:</form:label>
10.   <form:input path="sales"/> <br/>
11.   <input type="submit" value="Save">
12. </form:form>

DHTMLX version 2.6 introduced the dhtmlxForm component in 2010, providing a flexible Javascript API to create rich form, process events and validate data. The version 3.0 released in July 2011 includes a new version of dhtmlxForm, supporting integration with dhtmlxCalendar and dhtmlxCombo, and new ways to position form controls to build sophisticated web forms. Below the  Javascript code to create a DHTMLX form:

DHTMLX Form

1. <div id="form" style="width:280px;height:250px;"/>
2. var form_struct = [
3.   { type: 'input', name: 'author' , value: '', label:'Author:'},
4.   { type: 'input', name: 'title' , value: '', label:'Title:'},
5.   { type: 'input', name: 'price' , value: '', label:'Price:'},
6.   { type: 'input', name: 'sales' , value: '', label:'Sales:'},
7.   { type: 'button', name: 'button_save', value:'Save'  },
8.   ];
9. var formObject = new dhtmlXForm("form",form_struct);

The DHTMLX Tag Library, a JSP Tag library created on top of the DHTMLX component framework, allows to create DHTMLX forms with a very similar syntax to Spring JSP form tags.

DHTMLX Tags Form

1. <%@ taglib prefix="dhtmlx" uri="http://www.mylaensys.com/dhtmlx" %>
2. <dhtmlx:form name='book'>
3.  <dhtmlx:formInput name='author' label='Author:'/>
4.  <dhtmlx:formInput name='title' label='Title:'/>
5.  <dhtmlx:formInput name='price' label='Price:'/>
6.  <dhtmlx:formInput name='sales' label='Sales:'/>
7.  <dhtmlx:formButton name='button_save' value='Save'/>
8. </dhtmlx:form>

The code example in this series uses the DHTMLX Tag Library version 1.6, a recent release which include some of the new features of DHTMLX 3.0. Of course it also works without the tags using the Javascript DHTMLX API.

Client Side Validation
The dhtmlxForm let you specify client validation rules at field level using the validate  property. The DHTMLX Tag Library supports the validate property as attribute of the tag. Below the source code of the of the example form:

1. <%@ taglib prefix="dhtmlx" uri="http://www.mylaensys.com/dhtmlx" %>
2. <dhtmlx:form name='form'>
3.   <dhtmlx:formHidden name='id'/>
4.   <dhtmlx:formLabel name="message" label="" labelWidth="470"/>
5.   <dhtmlx:formInput name='author' validate="NotEmpty"/>
6.   <dhtmlx:formLabel name="authorError" label=""/>
7.   <dhtmlx:formInput name='title' validate="NotEmpty"/>
8.   <dhtmlx:formLabel name="titleError" label=""/>
9.   <dhtmlx:formInput name='price' validate="ValidInteger"/>
10.   <dhtmlx:formInput name='sales' validate="ValidInteger"/>
11.   <dhtmlx:formLabel name="message" label="">
12.   <dhtmlx:formLabel name="dummy" label="" labelWidth="120"/>
13.     <dhtmlx:formNewColumn/>
14.     <dhtmlx:formButton name='button_upd' value='Update'/>
15.     <dhtmlx:formNewColumn/>
16.     <dhtmlx:formButton name='button_close' value='Close'/>
17.   </dhtmlx:formLabel>
18. </dhtmlx:form>

In order to minimize the client to server data exchange, it is a 'user friendly' practice to perform client side validation before sending data to the server. I used the expression 'user friendly' because the client side validation can be easily bypassed.


Server Side Validation 
Staring from release 3, Spring has introduced several enhancements to the validation framework, including Bean Validation API (JSR-303). It is possible to declare validation constraints using annotations. This example has been written to run on the Google App Engine (using JDO). In the Book class below, in addition to the validation, you will find the persistence annotations.
Book.java

1. public class Book {
2.   @PrimaryKey
3.   @Persistent(valueStrategy = IdGeneratorStrategy.IDENTITY)
4.   private Long id;
5.   @Persistent
6.   @NotEmpty
7.   @Size(min = 5, max = 20)
8.   private String author;
9.   @Persistent
10.   @NotEmpty
11.   @Size(min = 5, max = 20)
12.   @BookConstraint( message = "title already exists")
13.   private String title;
14.   @Persistent
15.   private Integer sales;
16.   @Persistent
17.   private Integer price;
18. }

A custom constraint annotation BookConstraint has been added to the title attribute, in order to evaluate if the book already exists in the datastore. You can find additional information about writing custom constraint in Spring documentation.

BookConstraint.java

1. @Documented
2. @Retention(RetentionPolicy.RUNTIME)
3. @Target({ElementType.METHOD,ElementType.FIELD,ElementType.ANNOTATION_TYPE })
4. @Constraint(validatedBy = BookValidator.class)
5. public @interface BookConstraint {
6.     String message() default "{some.error.code}";
7.     Class<?>[] groups() default {};
8.     Class<? extends Payload>[] payload() default {};
9. }

BookValidatior.java

1. public class BookValidator implements ConstraintValidator<BookConstraint,String> {
2.   @Autowired
3.   private BookDao bookDao;
5.   @Override
6.   public void initialize(BookConstraint bookConstraint) {
8.   }
10.   @Override
11.   public boolean isValid(String title, ConstraintValidatorContext context) {
12.     return bookDao.findByTitle( title ).size() < 2;
13.   }
14. }

After validation the BookController receives an instance of the Book class initialized with the form data and a BindingResult object containing the errors detected.
BookController.java

1. @Controller
2. public class BookController {
3.     @Autowired
4.     private BookService bookService;
5.     @RequestMapping(value = "/book", method = RequestMethod.POST)
6.     public @ResponseBody DefaultFormAdapter
7.   storeBook(@Valid @ModelAttribute Book book, BindingResult binding) {
8.         DefaultFormAdapter adapter = new DefaultFormAdapter(book,binding);
9.         if( adapter.hasValidData() ) {
10.             bookService.store(book);
11.         }
12.         return adapter;
13.     }
14. }

The dhtmlxForm posts the data performing an Ajax request. To return the errors triggered by the validation, the DHTMLX Spring Adapter creates an XML message. Below a XML response  example including one error message:

1. <data>
2.   <action
3.    sid="42"
4.    type="invalid"
5.    field="title"
6.    message="error !">
7.   </action>
8. </data>

On client side, the Javascript function getErrors parses the response message and sets the text on the error labels.

1. function getErrors(form,response) {
2.   var errorList = new Array();
3.   $('action', response).each(function(i) {
4.         field = $(this).attr("field");
5.         if( field != undefined ) {
6.             message = $(this).attr("message");
7.             form.setValidateCss(field, false);
8.             form.setItemLabel(field + "Error" , message );
9.             errorList.push( field );
10.         }
11.   });
12.   return errorList;
13. }
14. form.attachEvent("onButtonClick", function(id) {
15.   if (id == "button_upd") {
16.     clearMessages();
17.     form.send('/app/book', function(loader, response) {
18.           errorList = getErrors( form , response );
19.     });
20.   }
21. });

For those who like sequence diagrams see below.

In the next episode, the design of the DHTMLX Spring adapter will be presented in detail. For those who can't wait the application, running on the Google App Engine, is available  here.

Stay Tuned!