Introduction
Source code for the application is available on GitHub.
An application using OpenUI5 at the front-end will sooner or later need to connect to the back-end services for some business logic processing. In this blog entry we'll show how we can use the popular Spring MVC framework to expose REST-like endpoints for such server-side processing. Spring MVC makes it very simple to setup and configure an interface which will handle requests with Json payload, converting all domain model objects from Json to Java and back for us.
- Simple Maven project with embedded Tomcat for testing locally
- Servlet 3.0, no-XML, set-up for the web application using Spring's annotation based configuration
- JSR-303, Bean Validation through annotations, used on the model POJOs
- Spring MVC set up with a web jar for OpenUI5 runtime and automatic serialization of the model to Json
Useful links
Here are some useful links.
Application
This is a very simple single-page application which has a table of fruit, each having a name (String) and a quantity (integer). One can add a new fruit, delete an existing entry from the table or update an existing fruit using an inline-edit.
Taking just the "add" operation as an example, we can see that the home view, home.view.js, calls the controller with a JavaScript object constructed as to represent a Fruit when it is serialized as the part of the Ajax request by the controller.
// add button
var oButton = new sap.ui.commons.Button({
text: "Add",
press: function () {
// check if quantity is a number
if (oInput2.getValueState() !== sap.ui.core.ValueState.Error) {
oController.add({
// id attribute can be ignored
name: oInput1.getValue(),
quantity: oInput2.getValue()
}
);
}
}
});The controller, home.controller.js, then is simply sending the serialized Fruit object as the content of a POST request to the appropriate endpoint (/home/add) made available by the Spring MVC controller. Once the Ajax call returns the updated model data, it is simply rebound to the JSONModel associated with the view.
add: function (fruit) {
this.doAjax("/home/add", fruit).done(this.updateModelData)
.fail(this.handleAjaxError);
},
updateModelData: function (modelData) {
console.debug("Ajax response: ", modelData);
var model = this.getView().getModel();
if (model == null) {
// create new JSON model
this.getView().setModel(new sap.ui.model.json.JSONModel(modelData));
}
else {
// update existing view model
model.setData(modelData);
model.refresh();
}
}In what follows we'll look in detail how to implement a REST-like endpoint handling Json payloads using Spring MVC framework.
Spring MVC set-up
We are using Servlet 3.0, no web.xml, approach based on Java annotations to set up a simple Spring MVC web application. For this we need an implementation of org.springframework.web.WebApplicationInitializer where we specify the class which will be used when constructing an instance of org.springframework.web.context.support.AnnotationConfigWebApplicationContext and where we declare a dispatcher servlet. Here is our implementation, com.github.springui5.conf.WebAppInitializer.
public class WebAppInitializer implements WebApplicationInitializer {
private static final Logger logger = LoggerFactory.getLogger(WebAppInitializer.class);
@Override
public void onStartup(ServletContext servletContext) throws ServletException {
logger.info("Initializing web application with context configuration class {}", WebAppConfigurer.class.getCanonicalName());
// create annotation based web application context
AnnotationConfigWebApplicationContext webAppContext = new AnnotationConfigWebApplicationContext();
webAppContext.register(WebAppConfigurer.class);
// create and register Spring MVC dispatcher servlet
ServletRegistration.Dynamic dispatcher = servletContext.addServlet("dispatcher",
new DispatcherServlet(webAppContext));
dispatcher.setLoadOnStartup(1);
dispatcher.addMapping("/");
}
}The actual configuration is given then by com.github.springui5.conf.WebAppConfigurer class.
@Configuration
@EnableWebMvc
@ComponentScan(basePackages = {"com.github.springui5.web"})
public class WebAppConfigurer extends WebMvcConfigurerAdapter {
/**
* Enable default view ("index.html") mapped under "/".
*/
@Override
public void configureDefaultServletHandling(DefaultServletHandlerConfigurer configurer) {
configurer.enable();
}
/**
* Set up the cached resource handling for OpenUI5 runtime served from the webjar in {@code /WEB-INF/lib} directory
* and local JavaScript files in {@code /resources} directory.
*/
@Override
public void addResourceHandlers(ResourceHandlerRegistry registry) {
registry.addResourceHandler("/resources/**").addResourceLocations("classpath:/resources/", "/resources/**")
.setCachePeriod(31556926);
}
/**
* Session-scoped view-model bean for {@code home.view.js} view persisting in between successive Ajax requests.
*/
@Bean
@Scope(value = "session", proxyMode = ScopedProxyMode.TARGET_CLASS)
public HomeViewModel homeModel() {
return new HomeViewModel();
}
}We use a helpful EnableWebMvc annotation, which configures our application with some useful defaults. For example, Spring will automatically configure an instance of org.springframework.http.converter.json.MappingJackson2HttpMessageConverter message converter which will use a Jackson to Java converter to serialize the model returned by the Ajax handling methods of the controller.
Another interesting thing to notice is that we are using Spring's resource servlet to serve the static JavaScript (OpenUI5 runtime) from the web JAR available on the classpath of the application. To create the web JAR, we can simply package the OpenUI5 runtime JavaScript, available for download, into a JAR and add it to the WEB-INF/lib directory of our project.
The session-scoped bean, com.github.springui5.model.HomeViewModel, is responsible for maintaining the reference to the model object corresponding to the client's view.
public class HomeViewModel {
private HomeModel homeModel;
/**
* Initializes and returns a new model.
*/
public HomeModel getNewHomeModel() {
homeModel = new HomeModel();
return homeModel;
}
/**
* Returns the model for this view-model.
*/
public HomeModel getHomeModel() {
if (homeModel == null) {
throw new RuntimeException("HomeModel has not been initialized yet.");
}
return homeModel;
}
}ComponentScan annotation specifies where to look for the controllers of the application. The single controller for the home view is com.github.springui5.web.HomeController.
@Controller
@RequestMapping(value = "/home", method = RequestMethod.POST, consumes = "application/json", produces = "application/json")
public class HomeController {
private static final Logger logger = LoggerFactory.getLogger(HomeController.class);
/**
* Session-scoped view-model bean.
*/
@Autowired
private HomeViewModel vm;
/**
* Initializes the model for the view.
*/
@RequestMapping
public
@ResponseBody
HomeModel handleInit() {
return vm.getNewHomeModel().show();
}
/**
* Adds the {@linkplain com.github.springui5.domain.Fruit} parsed from the request body to the list of fruit in the
* model.
*/
@RequestMapping("/add")
public
@ResponseBody
HomeModel handleAdd(@Valid @RequestBody Fruit fruit, BindingResult errors) {
if (errors.hasErrors()) {
throw new FruitValidationException(errors);
}
return vm.getHomeModel().add(fruit).clearError().show();
}
/**
* Deletes the the {@linkplain com.github.springui5.domain.Fruit} with matching {@code id} from the list of fruit in
* the model.
*/
@RequestMapping("/delete/{id}")
public
@ResponseBody
HomeModel handleDelete(@PathVariable long id) {
return vm.getHomeModel().delete(id).clearError().show();
}
/**
* Updates the the {@linkplain com.github.springui5.domain.Fruit} with matching {@code id} from the list of fruit in
* the model.
*/
@RequestMapping("/update")
public
@ResponseBody
HomeModel handleUpdate(@Valid @RequestBody Fruit fruit, BindingResult errors) {
if (errors.hasErrors()) {
throw new FruitValidationException(errors);
}
return vm.getHomeModel().update(fruit).clearError().show();
}
/**
* Custom exception handler for {@linkplain FruitValidationException} exceptions which produces a response with the
* status {@linkplain HttpStatus#BAD_REQUEST} and the body string which contains the reason for the first field
* error.
*/
@ExceptionHandler
@ResponseStatus(HttpStatus.BAD_REQUEST)
public
@ResponseBody
HomeModel handleException(FruitValidationException ex) {
String error = String.format("%s %s", ex.getRejectedField(), ex.getRejectedMessage());
logger.debug("Validation error: {}", error);
return vm.getHomeModel().storeError(error);
}
}We are autowiring the view-model bean into the controller. It will be reinitialized by Spring automatically for each new client of the application (new browser, for example). Ajax request handling is configured on the class and method levels via RequestMapping annotations specifying the URL paths available in the form /home or /home/add. Some methods accept a model object (Fruit) deserialized or unmarshalled from the Json in the body of the POST request via RequestBody annotations.
Each conroller method returns the instance of HomeModel which will be automatically serialized or marshalled to Json and later bound to the JSONModel on the client side.
Model and validation
The domain model used on the server is a couple of simple POJOs annotated with JSR-303 annotations (using Hibernate Validator implementation). Here is the class for com.github.springui5.model.HomeModel.
public class HomeModel implements Serializable {
private static final Logger logger = LoggerFactory.getLogger(HomeModel.class);
private List<Fruit> listOfFruit;
private String error;
public List<Fruit> getListOfFruit() {
return listOfFruit;
}
public void setListOfFruit(List<Fruit> listOfFruit) {
this.listOfFruit = listOfFruit;
}
public String getError() {
return error;
}
public void setError(String error) {
this.error = error;
}
public HomeModel() {
listOfFruit = new ArrayList<>(Arrays.asList(new Fruit("apple", 1), new Fruit("orange", 2)));
}
public HomeModel add(Fruit fruit) {
// set id, it is 0 after deserializing from Json
fruit.setId(Fruit.newId());
listOfFruit.add(fruit);
return this;
}
public HomeModel delete(final long id) {
CollectionUtils.filter(listOfFruit, new Predicate() {
@Override
public boolean evaluate(Object object) {
return ((Fruit) object).getId() != id;
}
});
return this;
}
public HomeModel update(final Fruit fruit) {
// find the fruit with the same id
Fruit oldFruit = (Fruit) CollectionUtils.find(listOfFruit, new Predicate() {
@Override
public boolean evaluate(Object object) {
return ((Fruit) object).getId() == fruit.getId();
}
});
// update the fruit
oldFruit.setName(fruit.getName());
oldFruit.setQuantity(fruit.getQuantity());
return this;
}
public HomeModel storeError(String error) {
this.error = error;
return this;
}
public HomeModel clearError() {
this.error = null;
return this;
}
public HomeModel show() {
logger.debug(Arrays.toString(listOfFruit.toArray()));
return this;
}
}And here is the com.github.springui5.domain.Fruit class.
public class Fruit implements Serializable {
private static long offset = 0L;
private long id;
@NotNull
@NotBlank
private String name;
@NotNull
@Min(1)
private int quantity;
/**
* Returns a new value for {@code id} attribute. Uses timestamp adjusted with the static offset. Used only for
* illustration.
*/
public static long newId() {
return System.currentTimeMillis() + offset++;
}
public Fruit() {
// default constructor
}
public Fruit(String name, int quantity) {
this.id = Fruit.newId();
this.name = name;
this.quantity = quantity;
}
public long getId() {
return id;
}
public void setId(long id) {
this.id = id;
}
public String getName() {
return name;
}
public void setName(String name) {
this.name = name;
}
public int getQuantity() {
return quantity;
}
public void setQuantity(int quantity) {
this.quantity = quantity;
}
@Override
public boolean equals(Object obj) {
return obj instanceof Fruit && ((Fruit) obj).getId() == id;
}
@Override
public String toString() {
return "Fruit [id: " +
id +
", name: " +
name +
", quantity: " +
quantity +
"]";
}
}Upon the initial request for the model data (/home) this is what the controller returns. Notice how the list of Fruit domain objects was automatically serialized to Json for us.
If an invalid value is submitted as the part of the request body (for example the quantity of 0 when adding a new fruit) it is automatically picked up by Spring and assigned to the org.springframework.validation.BindingResult parameter of the corresponding request handling method. The application then exposes the validation error message as the value of the models "error" attribute.
Testing the application
This is a standard Maven application which needs some mandatory dependencies to compile and run.
<!-- all of the necessary Spring MVC libraries will be automatically included -->
<dependency>
<groupId>org.springframework</groupId>
<artifactId>spring-webmvc</artifactId>
<version>4.0.0.RELEASE</version>
</dependency>
<!-- need this for Jackson Json to Java conversion -->
<dependency>
<groupId>com.fasterxml.jackson.core</groupId>
<artifactId>jackson-databind</artifactId>
<version>2.3.0</version>
</dependency>
<!-- need this to use JSR 303 Bean validation -->
<dependency>
<groupId>org.hibernate</groupId>
<artifactId>hibernate-validator</artifactId>
<version>5.0.2.Final</version>
</dependency>It also uses a Tomcat Maven plugin for running the project in an embedded Tomcat 7 using: mvn tomcat7:run from the command line.
Conclusion
Using Spring MVC with OpenUI5, the way we have described here, has some advantages. We can easily setup a REST-like endpoint which will automatically convert Json payloads to Java domain objects allowing us to concentrate on manipulating the model in Java without worrying on how the changes will be reflected in the JavaScript on the client-side. We can also plug in domain objects validation based on annotations (JSR 303), using Spring's validation mechanism. This allows us to process all business logic validation on the server-side in a declarative and transparent manner, leaving only checks for formatting errors on the client-side.
There are some disadvantages to this approach, however, the main of which, of course, is that we are returning an entire model for each request, which results in an unnecessary large data transfer. This should not be a limitation for a relatively simple views, but can represent a problem for the complicated views with a lot of data.
1 Comment
