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!