Resource Handling

On the client-side SAPUI5 provides the following mechanism for resources:

• Modularization Concept (!Require/Declare for JavaScript files)

• Localization Concept (Resource Bundles)

Both concepts are loading additional resources from a server where this server might be any kind of web server (simple, Java, ABAP, ...). It does not depend on any server side technology.

For the Java server and also the integration into the Eclipse IDE SAPUI5 provides a resource handler. This resource handler is aligned with the concept of the JavaServer Faces - Resource Handler:

• The default implementation must support packaging resources in the web application root under the path resources/<resourceIdentifier> relative to the web app root.

• Resources packaged in the classpath must reside under the JAR entry name META-INF/resources/<resourceIdentifier>

The SAPUI5 resource handler extends this concept to support standard and test-relevant resources. Therefore we package our resources into the following paths:

• resources/**

  Resources are all kind of JavaScript, CSS, Mimes, Resource Bundles, which are relevant for the runtime.

• test-resources/**

  Test resources are resources which are samples and only relevant for testing purposes e.g. the content of the SAPUI5 test suite.

Other additional features of the resource handler are:

• Theme fallback:

  If resources are not available for the current theme it automatically checks the base theme for such resources and returns this resource instead without returning a 404.

• Resource bundle fallback:

  Similar to the client-side mechanism for loading resource bundles but it negotiates the request on the server and returns the best found resource bundle instead without 404, e.g.:

  messagebundle_en_US.properties > messagebundle_en.properties > messagebundle.properties

For Java Servlet containers SAPUI5 provides a ResourceServlet which manages the access to SAPUI5 resources within the web application and the various UI libraries in the classpath. The following snippet shows how to enable the resource servlet for SAPUI5:

#!text/xml

  <!-- ============================================================ -->
  <!-- SAPUI5 resource servlet used to handle application resources -->
  <!-- ============================================================ -->
   

  <servlet>

    <display-name>ResourceServlet</display-name>

    <servlet-name>ResourceServlet</servlet-name>

    <servlet-class>com.sap.ui5.resource.ResourceServlet</servlet-class>

  </servlet>

  <servlet-mapping>

    <servlet-name>ResourceServlet</servlet-name>

    <url-pattern>/resources/*</url-pattern>

  </servlet-mapping>

  <servlet-mapping>

    <servlet-name>ResourceServlet</servlet-name>

    <url-pattern>/test-resources/*</url-pattern>

  </servlet-mapping>

Before you can use it you need to make sure that the ResourceServlet is available in the classpath as JAR file.

The resource handler is configured via context parameter which are defined in the web.xml. The following table gives an overview about configuration parameters:

Key	Description
com.sap.ui5.resource.USE_CACHE	flag to enable resource cache or not (default: "true")
com.sap.ui5.resource.MAX_AGE	max age of resources in millis (default: "604800000" - 1 week)
com.sap.ui5.resource.ACCEPTED_ORIGINS	list of accepted origins, e.g. * or *sap.corp,vesapui5.dhcp.wdf.sap.corp (default: empty)
com.sap.ui5.resource.DEV_MODE	flag to enable the development mode (default: "false")
com.sap.ui5.resource.TEMPLATE_PATH	template for the resource listing (default: "/templates/listing.html")
com.sap.ui5.resource.VERBOSE	verbosity of the resource handler (default: "false")
com.sap.ui5.resource.REMOTE_LOCATION	location which is used to proxy requests to for resources not being located locally (default: empty)
com.sap.ui5.resource.PREFER_REMOTE_LOCATION	flag to prefer resolving the resource from the remote location before fallback to the classpath (default: false)

Configuration parameters are added as context parameters to the web.xml.

When starting to develop SAPUI5 controls and modules being located inside the servlet paths resources/ or test-resources/ it makes simplifies this development process by disabling the caching of such resources as well as enabling the resource browsing. To activate the development mode you need to add the following context parameter.

#!text/xml

  <!-- BEGIN: DEV MODE -->
  <context-param>
    <param-name>com.sap.ui5.resource.DEV_MODE</param-name>
    <param-value>true</param-value>
  </context-param>
  <!-- END: DEV MODE -->

In case of having the development mode turned on you can browse resources via the resource browser:

• %SERVER_URL%/resources/
• %SERVER_URL%/test-resources/

The ResourceServlet offers the opportunity to tunnel/proxy requests to another server providing SAPUI5 resources. This is the alternative instead for referring to SAPUI5 from remote location inside the bootstrap script tag to avoid cross domain issues. To activate this remote location tunneling/proxying you need to add the following context parameter to the web.xml of your application:

#!text/xml
  <context-param>
    <param-name>com.sap.ui5.resource.REMOTE_LOCATION</param-name>
    <param-value>http://%server%:%port%/sapui5</param-value>
  </context-param>

This will dispatch requests from resources/sap/ui/commons/Button.js to http://%server%:%port%/sapui5/resources/sap/ui/commons/Button.js.

If you are located behind a proxy and the remote location is outside your local network you can configure the proxy settings via the standard Java Networking and Proxy configurations by setting the system properties (for HTTP): http.proxyHost, http.proxyPort, http.nonProxyHosts, or (for HTTPS) https.proxyHost, https.proxyPort, https.nonProxyHosts of your Java runtime environment.

In general for the resources returned from the proxy the ResourceServlet is enabling caching. It by default uses the configured com.sap.ui5.resource.MAX_AGE to avoid to much load on the ResourceServlet.

Verify that a Resource was Retrieved from Remote Location

When in development mode it is possible to verify that a resource was retrieved from the desired remote location by checking the response header of the respective request. In this case the response header has an entry x-sap-ResourceUrl = remote resource URL, for example:

x-sap-ResourceUrl = http://%server%:%port%/sap/public/bc/ui5_ui5/resources/sap-ui-core.js

This section describes the resource packaing for web applications and Java modules which could be any kind of a JAR file (SAPUI5 UI library, ...) available in the classpath of the web application.

• For a web application this means you have to store the resources in the following way:

  WebContent/
    resources/
      **/**
    test-resources/
      **/**

• For the SAPUI5 UI libraries we store the resources in the following way:

  META-INF/
    resources/
      **/**
    test-resources/
      **/**

  For custom JAR files you need to apply to this on your own.

When running SAPUI5 as an OSGi Web Bundle and referencing the UI libraries as OSGi bundles you may need to know about a technical detail how SAPUI5 OSGi bundles are determined:

• In the OSGi servlet container we extend the ResourceServlet by using an OSGi fragment which is responsible to add the OSGi flavor for the determination of UI libaries. Now the ResourceServlet is aware about the OSGi bundles and can search within the OSGi Servlet Container for UI libraries.

• The MANIFEST.MF of UI library JAR files contains a special entry which is used for the determination:

  x-sap-ui5-ContentTypes: UILibrary
  

  This is used by the OSGiResourceServlet to determine the relevant UI libraries.