org.zdevra.guice.mvc.converters.package-info Maven / Gradle / Ivy
The newest version!
/*****************************************************************************
* Copyright 2011 Zdenko Vrabel
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*
*****************************************************************************/
/**
* This package contains all classes and related annotations, which provide conversions
* from strings to concrete data types.
*
* Numbers are converted automatically. Special cases are Boolean and Date types. For
* parameters of these types are used special annotations:
*
*
* - {@link org.zdevra.guice.mvc.converters.BooleanConv}
*
- The annotation define how the string will convert to boolean.
*
*
- {@link org.zdevra.guice.mvc.converters.DateConv}
*
- The annotation define how the string will convert to Date.
*
*
*
*
* Custom converters
*
* Normally, the controler's method attributes can be filled in from the HTTP request and they are
* automatically converted to few basic types like a String, Integer, Double, Date etc. Sometime we are
* in situations, when we want to have some custom type as a method's argument. Let's assume the
* controller's method addPerson:
*
*
* {@literal @}Path("/person/add")
* public void savePerson( {@literal @}RequestParameter("prs") Person personToSave) {
* ...
* }
*
*
* Also assume HTML form which invokes the controller's method:
*
* <FORM action="person/add" method="post">
* Name: <INPUT type="text" name="prs-name" />
* Surname: <INPUT type="text" name="prs-surname" />
* Age: <INPUT type="text" name="prs-age" />
* <INPUT type="submit" value="Submit" />
* </FORM>
*
*
* Lime MVC has a conversion mechanism which can be easyly extended. You need to implement your custom converter itself and
* converter's factory. Converter implementation takes a values from request and construct concrete instance which will be filled in
* into method's argument.
*
*
* private static class PersonConverter implements ConversionService.Converter {
*
* public Person convert(String nameInForm, Map data)
* {
* String personName = data.get(nameInForm + "-name")[0];
* String personSurname = data.get(nameInForm + "-surname")[0];
* int personAge = Integer.parse(data.get(nameInForm + "-age")[0]);
* return new Person(personName, personSurname, personAge);
* }
* }
*
*
* The convert() method's 'nameInForm' is filled in with value from the RequestParameter annotation and 'data' map contains the post data
* from the HTTP request. The Converter's factory makes the instance of converter for concrete argument in the beginning when the
* Lime MVC module is initialized. Usually the factory constructs the singletoned instance. Example of the exception is Date conversion,
* when is created instance of converter for each argument because the DateConv annotation or Boolean conversion when we can use the
* BooleanConv annotation.
*
*
* public class PersonConverterFactory implements ConversionService.ConverterFactory {
*
* private final ConversionService.Converter converter = new PersonConverter();
*
* public ConversionService.Converter createConverter(Class argumentType, Annotation[] annotations) {
* if (type == Person.class) {
* return converter;
* }
* return null;
* }
* }
*
*
* Factory's createConverter method is called for each argument in each controller's method. When the type of argument is matching with the
* factory's supported type, the instance of converted is returned. When the argument type is different, then createConverter returns null.
* The annotations contains all argument's annotations. You might define your custom annotations for argument and you can parametrize the
* convertor via these annotations. As a example you can look into DateConverterFactory.
*
*
* The last step is a registration of the converter. This happens when you call the registerConverter() method in your MvcModule's implementation.
*
*
* public class MyModule extends new MvcModule() {
* protected void configureControllers() {
* registerConverter(new PersonConverterFactory());
* ...
* }
* }
*
*
*/
package org.zdevra.guice.mvc.converters;