... more about SprHibRAD


The framework

The view

The 'view' part provides a contribution at the JEE/JSP level, specifically extending either the javax.servlet.jsp.tagext.TagSupport class or some important class from the org.springframework.web.servlet.tags.form package

The controller

The 'controller' part supports basic users management letting the final application implement the concrete invocation of the dbms directives.

The user's preferences management is also provided by the controller layer: each logged-in user can select either his/her own preferred locale or menu/nav-bar position.

In the controller the navigation chances become actual though the 'Navigator' object, a stack of nodes maintained in the http session. The generic navigator node holds information related to every main page encountered during the forward navigation and allows the user to backtrack to some previously explored page.

The controller is responsible also to maintain a map for the ordering of each data grid that lives in each page and the order, as such, can be altered by the user: the user can expect the status be kept by SprHibRAD along the navigation.

The model

The framework, at the model level, states only that all the usual model Pojos implement a same 'root' interface.

Furthermore the class impersonating the user preferences place holder is provided.

The final application and the framework

Every controller, service, dao class must inherit from the framework counterpart

The Spring @Configuration annotaded class must inherit from org.springframework.web.servlet.config.annotation.WebMvcConfigurationSupport class and has to add SprHibRAD formatters and converters and a crucial overriding is need, createRequestMappingHandlerAdapter, to let coming into play a SprHibRAD class capable of make Spring accepting particular behavior about formatting and warning forwarding; the @Configuration annotaded class must override a set parent methods to give Spring the perception that all of the ancient class is on the path: all the originally annotated methods (since annotations are not inherited). The com.sprhibrad.framework.configuration.UserManager implementing class must be returned in a @Bean declaration to make SprHibRad class managed by Spring and depedency injected within SprHiRAD itself.

There must be a org.springframework.web.servlet.support.AbstractAnnotationConfigDispatcherServletInitializer derived class implementing the 'onStartup' method; the latter needs to instantiate a com.sprhibrad.framework.configuration.ShrConfigurator object and to instantiate a com.sprhibrad.framework.configuration.MenuConfig object. The MenuConfig object needs to be load into the ServletContext through the ShrConfigurator.loadSHRparamsIntoContext method; the MenuConfig object must be populated with the entities that are desired to be shown in the menu. Spring Security, then, must be implemented, for the use that SprHibRAD does of it, by extending the org.springframework.security.config.annotation.web.configuration.WebSecurityConfigurerAdapter class, annotating the derived class with @EnableWebSecurity and loading from db the user and user's roles association overriding the configureGlobal method and by expressing the various role access-permissions to various paths corresponding to the SprHibRAD actions on the enitites.

There is an only configuration file where all the settings of the framework are set for the particular application. One of the most important properties is the country for the application currency that is reasonably unique at the application scope

There are one SprHibRAD dictionary file and a application specific dictionary file for each language supported (actually the framework detects their presence and offers the user the inherent selection options). The dictionary files are postfixed with the locale notation that includes the country notation: SprHibRAD interferes with Spring/Hibernate to contribute with some country-dependent formatting feature.

The default locale is the system locale.

The framework manages the language occurrences by keys: if no key is found for the selected language or if no dictionary is present for that language, the 'view' part resolves the issue displaying the key just as it should be qualified in the convenient dictionary file, to make easy fixing of the missed item.

As the application raises from the database, the model composition drives the entire structure of the application in terms of classes: there are two kinds of entities represented in a SprHibRAD application model: a 'VerboseLiteral', that hosts mainly a single textual attribute, and the actual entities made by several attributes and that are typically involved in relations. The formers require a dao class and a converter class, the latters require a controller class, a service class, a dao class, a form jsp page and a list jsp that renders the set of entity instances. The controller class (a @Controller annotated class) must extend com.sprhibrad.framework.controller.ImplShrController and must contain @RequestMapping annotated methods that come with mapped paths, built by the lowercase name of the entity followed by a SprHibRAD action(*). Each of these methods must have a well defined signatures in terms of Spring annotation close to each formal parameters. The jsp pages must include the directive that defines the SprHibRAD custom tags in order to have them usable in the page body (*)

The framework supports BIRT without incorporating its dependency: it is up to the final application to depend from the BIRT artifact.

As can be seen by a look into the code, no particular care was made in managing exceptions more than stack tracing (it was not at the top of design priorities). Any way the framework expects the final application to integrate common logging tools (like Apache Log4j), like any Java-based Dynamic Web application does.


The Application layout

Most of the features of the layout of an application built on the top of SprHibRAD framework (or specifically generated by the SprHibRAD generator) can be seen through the screen-shots aside.

[ For an immediate dynamic perception of the layout, try online the sample application from the sample applications page. ]

The login form takes the user to the home page where the application name is at the top and the application menu is just below or on the left side of the page: there is a marginal area that contains either the application menu or a navigation bar that traces the path of the navigation made by the user along the logical model of the application: its default position is at the top of the page.

In the configuration file there are a small set of attributes that have 'sprHibRad.' as prefix:

  • appName : the application name as it appears in the home page
  • pagesize : the quantity of rows per page in the presentation of the result set of a search operation
  • userprefsmenu : if 'true' it states the presence of the 'user's preferences' menu-item in the application menu (if false, the 'change password' menu-item appears there instead)
  • dateStyle : the general format style for all dates a part when a Spring @DateTimeFormat annotation is present close to the model entity attribute (it follows the 'style' pattern syntax of the @DateTimeFormat annotation)
  • currencyCountry : the SprHibRAD application manages one only currency : here it is specified.
  • langParameterizedReports : if 'true', all the BIRT reports must be located in the top level of the WebContent/reports path, must contain loc_country' and 'loc_lang' parameters and must have inside the 'dictionary_([dictionary-key]) invocation for each language dependent label'; if false, for every report required, one instance must be developed, one for every Locale provided and the instance must be located in a folder named as the Locale
  • minPwdSize : minimum length of a password.

In the user's preferences context the user can choose either the preferred Locale and the position of the menu/navig-bar.

From every entity menu-item the user comes to a managing page from which a search or a creation of new entity instance can be done.

The search produces a listing that is possibly paginated; in each listing page a 'new search' link is added to go back to the search context where criteria can be specified for all the attributes present in the criteria area: criteria operators are ' ' (stays for 'equal' and 'like' for text attributes), '<', '>', 'N' (is null), 'NN' (is not null) - (criteria are 'AND' processed).

Every row of the listing comes with a link for deleting and another for viewing the instance.

Either the 'view' action or the 'new item' action lead to the entity form page.

The entity form page can have two states:

  • idle for
    • viewing main data and any details grid
    • management of any binary attribute present in the main data
  • editing where the editing of the main data a part from any binary attributes is possible. Binary attributes and details grid are left away.

The 'new item' link leads directly to the editing status of the entity form page.

The entity form page can have one or more entity details grids, that have row-commands similar to the entity listing page grid; every details grid has at the top an 'Add' link to make possible the addition of details instances.

Either the search/result list grid or every details list grid have a predefined ordering schema that, during the user's working session, can be modified (by the user) by clicking on the various column headings, basing of a desired sequence, and by clicking on the 'clear order' link, when a new scheme needs to be set from scratch (note: by clicking on a column already participating in the schema - that's already marked as oriented - its ordering versus is changed.

The entity form page, in the 'view' state, allows the management of each binary attribute, two kinds of it do exist: 'handout' and 'image'; the first has a small icon to state the existence of the value, the second has the preview; the latter, when present, is click-able to go to the actual image

The generator

The second part of this work, the SprHibRAD generator, is the natural consequence of all the assumptions made about limitations and constraints of the SprHibRAD framework project: in fact it automates the compliance to the grammar that the final application needs to conform to, in order to invoke the SprHibRAD framework APIs correctly, and also to conform to Spring MVC and Hibernate requirements. So that the development of this part involved purely deterministic work.

Unfortunately I had no ready know-how for properly integrating such a job in the Eclipse environment and the investment in that would have taken poor value in respect of what the availability of the Generator itself represents. So I developed it as AWT/Swing application taking care that the application itself were comfortably usable in Windows, Linux and Mac Os X as well.

A dedicated page for its description and usage is indeed provided here.

Names: plural form helper

A third artifact that is just a small fragment of code providing the plural form of the name instances used by both the framework and the generator.

The java packages of the suite

The license

SprHibRAD (1.0) is a free software and is distributed under the terms of the GNU Lesser General Public License. License terms are here illustrated.

----------------------------------------------------------

(*) - I apologize for not documenting exhaustively this work : in the case you were interested in this project, in order to get a rigorous syntax of each part of the final application, please refer to the resulting generated code, produced by the SprHibRAD generator - the generated code makes substantially use of the entirity of the SprHibRAD framework APIs. You can see also the "My_Clinic" sample on GitHub, indeed.