2. Spring Mobile Device Module

Web applications should perform device resolution at the beginning of request processing, before any request handler is invoked. This ensures the Device model can be made available in request scope before any processing occurs. Request handlers can then obtain the Device instance and use it to respond differently based on its state.

By default, a LiteDeviceResolver is used for device resolution. You may plug-in another DeviceResolver implementation by injecting a constructor argument.

<interceptors>
  <!-- On pre-handle, resolve the device that originated the web request -->
  <bean class="org.springframework.mobile.device.DeviceResolverHandlerInterceptor" />
</interceptors>
                    

@Bean
public DeviceResolverHandlerInterceptor deviceResolverHandlerInterceptor() {
    return new DeviceResolverHandlerInterceptor();
}

@Override
public void addInterceptors(InterceptorRegistry registry) {
    registry.addInterceptor(deviceResolverHandlerInterceptor());
}
                    

<filter>
  <filter-name>deviceResolverRequestFilter</filter-name>
  <filter-class>org.springframework.mobile.device.DeviceResolverRequestFilter</filter-class>
</filter>
                    

When you need to lookup the current Device in your code, you can do so in several ways. If you already have a reference to a ServletRequest or Spring WebRequest, simply use DeviceUtils:

Device currentDevice = DeviceUtils.getCurrentDevice(servletRequest);
                

If you'd like to pass the current Device as an argument to one of your @Controller methods, configure a DeviceWebArgumentResolver:

<annotation-driven>
  <argument-resolvers>
    <bean class="org.springframework.mobile.device.DeviceWebArgumentResolver" />
  </argument-resolvers>
</annotation-driven>
                

You can alternatively configure a DeviceHandlerMethodArgumentResolver using Java-based configuration:

@Bean
public DeviceHandlerMethodArgumentResolver deviceHandlerMethodArgumentResolver() {
    return new DeviceHandlerMethodArgumentResolver();
}

@Override
public void addArgumentResolvers(List<HandlerMethodArgumentResolver> argumentResolvers) {
    argumentResolvers.add(deviceHandlerMethodArgumentResolver());
}
                

You can then inject the Device into your @Controllers as shown below:

@Controller
public class HomeController {

    private static final Logger logger = LoggerFactory.getLogger(HomeController.class);

    @RequestMapping("/")
    public void home(Device device) {
        if (device.isMobile()) {
            logger.info("Hello mobile user!");
        } else if (device.isTablet()) {
            logger.info("Hello tablet user!");
        } else {
            logger.info("Hello desktop user!");         
        }
    }

}
                

Spring Mobile allows for the development of different DeviceResolver implementations that offer varying levels of resolution capability. The first, and the default, is a LiteDeviceResolver that detects the presence of a mobile device but does not detect specific capabilities.

<interceptors>
  <!-- Detects the client's Device -->
  <bean class="org.springframework.mobile.device.DeviceResolverHandlerInterceptor">
    <constructor-arg>
      <bean class="org.springframework.mobile.device.LiteDeviceResolver">
        <constructor-arg>
          <list>
            <value>iphone</value>
            <value>android</value>
          </list>
        </constructor-arg>
      </bean>
    </constructor-arg>
  </bean>
</interceptors>
                    

@Bean
public LiteDeviceResolver liteDeviceResolver() {
    List<String> keywords = new ArrayList<String>();
    keywords.add("iphone");
    keywords.add("android");
    return new LiteDeviceResolver(keywords);
}

@Bean
public DeviceResolverHandlerInterceptor deviceResolverHandlerInterceptor() {
    return new DeviceResolverHandlerInterceptor(liteDeviceResolver());
}

@Override
public void addInterceptors(InterceptorRegistry registry) {
    registry.addInterceptor(deviceResolverHandlerInterceptor());
}
                    

public class CustomLiteDeviceResolver extends LiteDeviceResolver {

    @Override
    protected void init() {
        super.init();
        getNormalUserAgentKeywords().addAll(Arrays.asList(NORMAL_KEYWORDS));
    };

    private static final String[] NORMAL_KEYWORDS = new String[] { "iphone", "android" };

}
                    

The user may indicate a site preference by activating a link that submits the site_preference query parameter:

Site: <a href="${currentUrl}?site_preference=normal">Normal</a> | 
<a href="${currentUrl}?site_preference=mobile">Mobile</a>
                

The indicated site preference is saved for the user in a SitePreferenceRepository, and made available as a request attribute named 'currentSitePreference'.

Indicated site preferences are stored in a SitePreferenceRepository so they are remembered in future requests made by the user. CookieSitePreferenceRepository is the default implementation and stores the user's' preference in a client-side cookie.

public interface SitePreferenceRepository {

    /**
     * Load the user's site preference.
     * Returns null if the user has not specified a preference.
     */
    SitePreference loadSitePreference(HttpServletRequest request);
    
    /**
     * Save the user's site preference.
     */
    void saveSitePreference(SitePreference preference, HttpServletRequest request, HttpServletResponse response);

}
                

To enable SitePreference management before requests are processed, add the SitePreferenceHandlerInterceptor to your DispatcherServlet configuration:

<interceptors>
  <!-- On pre-handle, manage the user's site preference (declare after DeviceResolverHandlerInterceptor) -->
  <bean class="org.springframework.mobile.device.site.SitePreferenceHandlerInterceptor" />
</interceptors>
            

Java-based configuration is also available:

@Bean
public SitePreferenceHandlerInterceptor sitePreferenceHandlerInterceptor() {
    return new SitePreferenceHandlerInterceptor();
}

@Override
public void addInterceptors(InterceptorRegistry registry) {
    registry.addInterceptor(sitePreferenceHandlerInterceptor());
}
            

By default, the interceptor will delegate to a StandardSitePreferenceHandler configured with a CookieSitePreferenceRepository. You may plug-in another SitePreferenceHandler by injecting a constructor argument. After the interceptor is invoked, the SitePreference will be available as a request attribute named 'currentSitePreference'.

When you need to lookup the current SitePreference in your code, you can do so in several ways. If you already have a reference to a ServletRequest or Spring WebRequest, simply use SitePreferenceUtils:

SitePreference sitePreference = SitePreferenceUtils.getCurrentSitePreference(servletRequest);
            

If you'd like to pass the current SitePreference as an argument to one of your @Controller methods, configure a SitePreferenceWebArgumentResolver:

<annotation-driven>
  <argument-resolvers>
    <bean class="org.springframework.mobile.device.site.SitePreferenceWebArgumentResolver" />
  </argument-resolvers>
</annotation-driven>
                

Java-based configuration is also available:

@Bean
public SitePreferenceHandlerMethodArgumentResolver sitePreferenceHandlerMethodArgumentResolver() {
    return new SitePreferenceHandlerMethodArgumentResolver();
}

@Override
public void addArgumentResolvers(List<HandlerMethodArgumentResolver> argumentResolvers) { 
    argumentResolvers.add(sitePreferenceHandlerMethodArgumentResolver());
}
                

You can then inject the indicated SitePreference into your @Controller as shown below:

@Controller
public class HomeController {

    @RequestMapping("/")
    public String home(SitePreference sitePreference, Model model) {
        if (sitePreference == SitePreference.NORMAL) {
            logger.info("Site preference is normal");
            return "home";
        } else if (sitePreference == SitePreference.MOBILE) {
            logger.info("Site preference is mobile");
            return "home-mobile";
        } else if (sitePreference == SitePreference.TABLET) {
            logger.info("Site preference is tablet");
            return "home-tablet";
        } else {
            logger.info("no site preference");
            return "home";
        }
    }

}
                

Use the mDot factory method to construct a SiteSwitcher that redirects mobile users to m.${serverName}; for example, m.myapp.com:

<interceptors>
  <!-- On pre-handle, resolve the device that originated the web request -->
  <bean class="org.springframework.mobile.device.DeviceResolverHandlerInterceptor" />
  <!-- On pre-handle, redirects mobile users to "m.myapp.com" (declare after DeviceResolverHandlerInterceptor) -->
  <bean class="org.springframework.mobile.device.switcher.SiteSwitcherHandlerInterceptor" 
      factory-method="mDot">
    <constructor-arg index="0" type="java.lang.String" value="myapp.com"/>
  </bean>
</interceptors>
                

By default, tablet devices see the 'normal' site. A second constructor argument is available for specifying that tablet devices are redirected to the 'mobile' site:

<interceptors>
  <!-- On pre-handle, resolve the device that originated the web request -->
  <bean class="org.springframework.mobile.device.DeviceResolverHandlerInterceptor" />
  <!-- On pre-handle, redirects mobile users to "m.myapp.com" (declare after DeviceResolverHandlerInterceptor) -->
  <bean class="org.springframework.mobile.device.switcher.SiteSwitcherHandlerInterceptor" 
      factory-method="mDot">
    <constructor-arg index="0" type="java.lang.String" value="myapp.com"/>
    <constructor-arg index="1" type="java.lang.Boolean" value="true"/>
  </bean>
</interceptors>
                

Java-based configuration is also available:

@Bean
public DeviceResolverHandlerInterceptor deviceResolverHandlerInterceptor() {
    return new DeviceResolverHandlerInterceptor();
}

@Bean
public SiteSwitcherHandlerInterceptor siteSwitcherHandlerInterceptor() {
    return SiteSwitcherHandlerInterceptor.mDot("myapp.com", true);
}

@Override
public void addInterceptors(InterceptorRegistry registry) {
    registry.addInterceptor(deviceResolverHandlerInterceptor());
    registry.addInterceptor(siteSwitcherHandlerInterceptor());
}
                

Use the dotMobi factory method to construct a SiteSwitcher that redirects mobile users to ${serverName - lastDomain}.mobi; for example, myapp.mobi:

<interceptors>
  <!-- On pre-handle, resolve the device that originated the web request -->
  <bean class="org.springframework.mobile.device.DeviceResolverHandlerInterceptor" />
  <!-- On pre-handle, redirects mobile users to "myapp.mobi" (declare after DeviceResolverHandlerInterceptor) -->
  <bean class="org.springframework.mobile.device.switcher.SiteSwitcherHandlerInterceptor" 
      factory-method="dotMobi">
    <constructor-arg index="0" type="java.lang.String" value="myapp.com"/>
  </bean>
</interceptors>
                

As described earlier with the mDot factory method, tablet devices see the 'normal' site. A second constructor argument is available for specifying that tablet devices are redirected to the 'mobile' site:

<interceptors>
  <!-- On pre-handle, resolve the device that originated the web request -->
  <bean class="org.springframework.mobile.device.DeviceResolverHandlerInterceptor" />
  <!-- On pre-handle, redirects mobile users to "myapp.mobi" (declare after DeviceResolverHandlerInterceptor) -->
  <bean class="org.springframework.mobile.device.switcher.SiteSwitcherHandlerInterceptor" 
      factory-method="dotMobi">
    <constructor-arg index="0" type="java.lang.String" value="myapp.com"/>
    <constructor-arg index="1" type="java.lang.Boolean" value="true"/>
  </bean>
</interceptors>
                

Java-based configuration is also available:

@Bean
public DeviceResolverHandlerInterceptor deviceResolverHandlerInterceptor() {
    return new DeviceResolverHandlerInterceptor();
}

@Bean
public SiteSwitcherHandlerInterceptor siteSwitcherHandlerInterceptor() {
    return SiteSwitcherHandlerInterceptor.dotMobi("myapp.com", true);
}

@Override
public void addInterceptors(InterceptorRegistry registry) {
    registry.addInterceptor(deviceResolverHandlerInterceptor());
    registry.addInterceptor(siteSwitcherHandlerInterceptor());
}
                

For a more customized configuration of the mDot or dotMobi strategies, the standard factory method is available. Construct a SiteSwitcher that redirects mobile and tablet users to a specified schema:

<interceptors>
  <!-- On pre-handle, resolve the device that originated the web request -->
  <bean class="org.springframework.mobile.device.DeviceResolverHandlerInterceptor" />
  <!-- On pre-handle, redirects mobile users to "m.myapp.com" (declare after DeviceResolverHandlerInterceptor) -->
  <bean class="org.springframework.mobile.device.switcher.SiteSwitcherHandlerInterceptor" 
      factory-method="standard">
    <constructor-arg value="app.com"/>
    <constructor-arg value="mobile.app.com"/>
    <constructor-arg value="tablet.app.com"/>
    <constructor-arg value=".app.com"/>
  </bean>
</interceptors>
                

Java-based configuration is also available:

@Bean
public DeviceResolverHandlerInterceptor deviceResolverHandlerInterceptor() {
    return new DeviceResolverHandlerInterceptor();
}

@Bean
public SiteSwitcherHandlerInterceptor siteSwitcherHandlerInterceptor() {
    return SiteSwitcherHandlerInterceptor.standard("app.com", 
        "mobile.app.com", "tablet.app.com", ".app.com");
}

@Override
public void addInterceptors(InterceptorRegistry registry) {
    registry.addInterceptor(deviceResolverHandlerInterceptor());
    registry.addInterceptor(siteSwitcherHandlerInterceptor());
}
                

Use the urlPath factory method to construct a SiteSwitcher that redirects mobile users to a different path within the application. Unlike mDot and dotMobi, this SiteSwitcher does not require setting up a different DNS entry for a mobile site.

<interceptors>
  <!-- On pre-handle, resolve the device that originated the web request -->
  <bean class="org.springframework.mobile.device.DeviceResolverHandlerInterceptor" />
  <!-- On pre-handle, redirects mobile users to "myapp.com/m" (declare after DeviceResolverHandlerInterceptor) -->
  <bean class="org.springframework.mobile.device.switcher.SiteSwitcherHandlerInterceptor" 
      factory-method="urlPath">
    <constructor-arg index="0" type="java.lang.String" value="/m" />
  </bean>
</interceptors>
                    

@Bean
public DeviceResolverHandlerInterceptor deviceResolverHandlerInterceptor() {
    return new DeviceResolverHandlerInterceptor();
}

@Bean
public SiteSwitcherHandlerInterceptor siteSwitcherHandlerInterceptor() {
    return SiteSwitcherHandlerInterceptor.urlPath("/m");
}

@Override
public void addInterceptors(InterceptorRegistry registry) {
    registry.addInterceptor(deviceResolverHandlerInterceptor());
    registry.addInterceptor(siteSwitcherHandlerInterceptor());
}
                    

<interceptors>
  <!-- On pre-handle, resolve the device that originated the web request -->
  <bean class="org.springframework.mobile.device.DeviceResolverHandlerInterceptor" />
  <!-- On pre-handle, redirects mobile users to "myapp.com/showcase/m" (declare after DeviceResolverHandlerInterceptor) -->
  <bean class="org.springframework.mobile.device.switcher.SiteSwitcherHandlerInterceptor" 
      factory-method="urlPath">
    <constructor-arg index="0" type="java.lang.String" value="/m" />
    <constructor-arg index="1" type="java.lang.String" value="/showcase" />
  </bean>
</interceptors>
                    

@Bean
public DeviceResolverHandlerInterceptor deviceResolverHandlerInterceptor() {
    return new DeviceResolverHandlerInterceptor();
}

@Bean
public SiteSwitcherHandlerInterceptor siteSwitcherHandlerInterceptor() {
    return SiteSwitcherHandlerInterceptor.urlPath("/m", "/showcase");
}

@Override
public void addInterceptors(InterceptorRegistry registry) {
    registry.addInterceptor(deviceResolverHandlerInterceptor());
    registry.addInterceptor(siteSwitcherHandlerInterceptor());
}
                    

<interceptors>
  <!-- On pre-handle, resolve the device that originated the web request -->
  <bean class="org.springframework.mobile.device.DeviceResolverHandlerInterceptor" />
  <!-- On pre-handle, redirects mobile users to "myapp/showcase/m" (declare after DeviceResolverHandlerInterceptor) -->
  <bean class="org.springframework.mobile.device.switcher.SiteSwitcherHandlerInterceptor" 
      factory-method="urlPath">
    <constructor-arg index="0" type="java.lang.String" value="/m" />
    <constructor-arg index="1" type="java.lang.String" value="/t" />
    <constructor-arg index="2" type="java.lang.String" value="/showcase" />
  </bean>
</interceptors>
                    

@Bean
public DeviceResolverHandlerInterceptor deviceResolverHandlerInterceptor() {
    return new DeviceResolverHandlerInterceptor();
}

@Bean
public SiteSwitcherHandlerInterceptor siteSwitcherHandlerInterceptor() {
    return SiteSwitcherHandlerInterceptor.urlPath("/m", "/t", "/showcase");
}

@Override
public void addInterceptors(InterceptorRegistry registry) {
    registry.addInterceptor(deviceResolverHandlerInterceptor());
    registry.addInterceptor(siteSwitcherHandlerInterceptor());
}
                    

<servlet-mapping>
  <servlet-name>appServlet</servlet-name>
  <url-pattern>/</url-pattern>
  <url-pattern>/m/*</url-pattern>
  <url-pattern>/t/*</url-pattern>
</servlet-mapping>
                

Spring Mobile includes AbstractDeviceDelegatingViewResolver, an abstract ViewResolver wrapper that delegates to another view resolver implementation, allowing for resolution of device specific view names without the need for a dedicated mapping to be defined for each view. A lightweight implementation is provided, which supports adjusting view names based on whether the calling device is normal, mobile, or tablet based.

Within your application, you can then create alternate views for normal, mobile or tablet devices, and given the proper configuration, Spring Mobile will adjust the view name to resolve to the correct one. This happens internally, without the need to add conditional logic through your controllers. The following table illustrates the behavior of the LiteDeviceDelegatingViewResolver when receiving a request for the "home" view and adjusting it to use a prefix. This allows you to store "mobile" views in a subdirectory, for example.

Alternatively, the LiteDeviceDelegatingViewResolver also supports adjusting views with suffixes. The following table shows the results of receiving a request for the "home" view. For example, this allows you to store all your views in the same folder, and distinguish between them by using different suffixes.

The following example illustrates how to configure a site that delegates to an InternalResourceViewResolver. It is configurated to adjust the view name by adding a mobile/ or tablet/ prefix if the requesting device is determined to be mobile or tablet respectively.

XML configuration:

<bean class="org.springframework.mobile.device.view.LiteDeviceDelegatingViewResolver">
  <constructor-arg>
    <bean class="org.springframework.web.servlet.view.InternalResourceViewResolver">
      <property name="prefix" value="/WEB-INF/views/" />
      <property name="suffix" value=".jsp" />
    </bean>
  </constructor-arg>
  <property name="mobilePrefix" value="mobile/" />
  <property name="tabletPrefix" value="tablet/" />
</bean>
                

Java-based configuration:

@Bean
public LiteDeviceDelegatingViewResolver liteDeviceAwareViewResolver() {
    InternalResourceViewResolver delegate = new InternalResourceViewResolver();
    delegate.setPrefix("/WEB-INF/views/");
    delegate.setSuffix(".jsp");
    LiteDeviceDelegatingViewResolver resolver = new LiteDeviceDelegatingViewResolver(delegate);
    resolver.setMobilePrefix("mobile/");
    resolver.setTabletPrefix("tablet/");
    return resolver;
}
                

Because using a ViewResolver will apply the view name strategy to your entire site, there may be times when some of your views do not have separate implementations for different device types or you do not need different versions. In this case, you can enable fallback support. Enabling fallback support means if an adjusted view name cannot be resolved, the ViewResolver will attempt to resolve the original view request. This feature is only supported if the delegate ViewResolver returns null from a call to resolveViewName when attempting to resolve a view that does not exist.

Enable fallback support by setting the enableFallback property.

XML configuration:

<bean class="org.springframework.mobile.device.view.LiteDeviceDelegatingViewResolver">
    ...
    <property name="enableFallback" value="true" />
    ...
</bean>
                

Java-based configuration:

@Bean
public LiteDeviceDelegatingViewResolver liteDeviceAwareViewResolver() {
    ...
    resolver.setEnableFallback(true);
    ...
    return resolver;
}