Skip to content

Services Developer Guide

Jump to bottom
rs146 edited this page Nov 1, 2014 · 9 revisions

Services Developer Guide

Please take note of the:

  • coding and naming conventions for classes and packages.
  • existing code for exact details of class implementations. This will always be a moving target, so try to be aware of the code others are checking in.

Steps to creating a new set of pages

  1. Create the controller class in the package based on the naming convention, implement the outline showWidgetList method to show a list of objects. Do not populate model attributes yet. Return the expected view path, e.g "widgets/list".
  2. Create the views directory and the list jsp file with dummy data. Boring recommendation: <h1>Hello widgets world</h1>
  3. Run the application and make sure the uri is picking up the controller and showing the text you entered in the jsp.
  4. Create any hibernate objects and mapping files if they are not already there.
  5. Create the dao interface class with the findWidgets() method. Create the hibernate implementation.
  6. Add the DAO to the controller class, using the @Autowire annotation.
  7. Add the attribute to the model, e.g. model.addAttribute("widgets", widgetDao.findWidgets());.
  8. Edit the jsp file to include the toString representation of the list, e.g ${widgets}.
  9. Run the application and make sure widgets objects are picked up.
  10. Fill in the remaining routing methods, testing each step of the way.

Gotchas

Checkstyle

Checkstyle enforces coding standards, and can cause the build to break if ignored. If you install the NetBeans plugin, checkstyle violations show up as yellow underlines. If you can't find where in the code you have the violations, look inside the target/checkstyle-result.xml file for the complete list.

Controller Classes

The controller class controls the methods of interacting with a specific resource like the widget.

Points to note:

  • @Controller annotation - required for the spring framework to create an instance of the object when the servlet container (glassfish) starts up.
  • @RequestMapping annotation - required to set up the URI mapping. It is expected that every class will have a class level annotation, e.g. @RequestMapping("/widgets"), then method level ones for list display, specific instance display, etc. The @PathVariable annotation is used to match variables defined in the request path to method arguments.
  • @Autowired annotations, used on any injected dependencies, like the DAO.
  • @PreAuthorize annotations, used on each routing method. This is picked up the by the spring security implementation to block users whose ACL does not permit them to see/edit the resource
  • @Transactional annotations, used on each routing method. This is picked up by the spring transactional implementation to determine if the change requires data to be read or changed.
  • The ModelMap object passed in as a method parameter on the routing methods is the data that the spring mvc framework passes to the view, so should be populated with the data that needs to be displayed. The view (jsp) is responsible for formatting the model data; the control should not be generating any html formatted strings.
  • The string returned by the routing methods is the path to the view (jsp) file, e.g. "/widgets/list". It call also return a redirect to go to a different uri, e.g. "redirect:widgets" to go back to the widgets list.

Naming Conventions

Uris

ROMS is primarily a CRUD (Create-Read-Update-Delete) web application. The uris used reflect the same naming convention used by Ruby-on-Rails and other CRUD application frameworks. See the ruby guidelines for reference.

To interact with widgets:

Action Uri Description
GET /widgets Display the list of widgets
GET /widgets/:id Display a specific widget
GET /widgets/new Display the form for creating a new widget
POST /widgets/ Create a new widget
GET /widgets/:id/edit Display the form for editing an existing widget
PUT /widgets/:id Update a specific widget
DELETE /widgets/:id Delete a specific widget

Urls should use dash separated names, e.g. /green-widgets/.

By following this pattern, we create an API that could be deemed as "REST-like".

Packages and classes

The controller names, daos and jsp files should reflect the uri naming.

  • Package: uk.org.rbc1b.roms.controller.widget (note: singular widget)
  • Controller: WidgetsController - the controller class (plural name)
  • DAO: WidgetDao, HibernateWidgetDao - the DAO interface and implementation (singular name, reflecting database tables and mapped objects)

Views

Path Description
/WEB-INF/views/widgets/list.jsp display list of widgets
/WEB-INF/views/widgets/show.jsp display a specific widget
/WEB-INF/views/widgets/edit.jsp edit a specific widget. This may be shared with the create if possible
/WEB-INF/views/widgets/create.jsp create a new widget. This is required if the view cannot be combined with the edit form

Main technologies Used

Maven is a build automation tool. We use it to define how the software gets build, and what dependencies need to be pulled in.

Hibernate is an object-relational mapping (ORM) library. It maps between the database tables and the application classes.

Spring is an application framework and collection of libararies. These include:

Using JEE properties in GlassFish and Spring

Create a JNDI custom property/resource in GlassFish, e.g. jndi/_edifice_property. Then, make sure that we can access that property in our Spring applicationContext.xml:

<jee:jndi-lookup id="edificeProperty" jndi-name="jndi/_edifice_property" resource-ref="true" /> To access these properties, simply use the following code:

In your code's properties/attributes:
@Resource(name = "edificeProperty")
private Properties edificeProperty;

Then, in your code:

String prop = edificeProperty.getProperty("Name of property");

Obviously, you should include checks to see if it is set or not.

Further background reading

  • HTTP. Specifically, understanding the request methods and the response codes.
  • Post/Redirect/Get used to prevent multiple form submissions.
Clone this wiki locally