The handling of resources in OpenUI5 is divided in a client-side and a server-side part. The two parts are complementary and don't depend on each other.
The server-side resource handling is an optional component to improve the client-server interaction by providing a server-side locale fallback instead of a client-side fallback with multiple requests. The server-side resource handling is mainly used in Eclipse to support the modularized development of OpenUI5 applications and libraries.
OpenUI5 provides the following mechanism for handling resources on the client:
-
Modularization of JavaScript files, see Modules and Dependencies
-
Localization of application texts with resource bundles, see Resource Bundles
In both cases, OpenUI5 loads additional resources from a server. This server can be any kind of web server (simple, Java, ABAP, ...). Both do not depend on a specific server-side technology.
For the Java server and the integration into Eclipse, OpenUI5 provides a resource handler to improve the interaction between client and server, for example by providing a server-side locale fallback for the language to avoid multiple requests to get the correct language. It's also used to support modularized development of OpenUI5 applications and libraries. The Java resource handler is aligned with the concept of the JavaServer Faces. The following prerequisites apply:
-
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 OpenUI5 resource handler extends this concept to support standard and test-relevant resources. The resources are therefore packaged 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 that are samples and only relevant for testing purposes, for example, the content of the OpenUI5 test suite.
The resource handler in OpenUI5 provides the following additional features:
-
Theme fallback:
If resources aren't available for a theme, the resource handler automatically checks the base theme for such resources and returns them instead of a 404 error message.
-
Resource bundle fallback:
This fallback is 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 of issuing a 404 error, for example:
messagebundle_en_US.properties > messagebundle_en.properties > messagebundle.properties
For Java Servlet containers, OpenUI5 provides a ResourceServlet to manage the access to OpenUI5 resources within the web application and the various UI libraries in the classpath. The following snippet shows how to enable the resource servlet for OpenUI5:
<!-- ============================================================ -->
<!-- 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 use it, make sure that the ResourceServlet is available in the classpath as JAR file.
The resource handler is configured via context parameters, which are defined in the web.xml. The following table gives an overview about configuration parameters:
|
Key |
Description |
|---|---|
|
|
Flag for resource cache enabling; default: |
|
|
Specifies the maximum age of resources in milliseconds; default: |
|
|
List of accepted origins, for example |
|
|
Flag development mode enabling; default: |
|
|
Specifies path to template for resource listing; default: |
|
|
Specifies verbosity of the resource handler; default: |
|
|
Specifies the location that is used to proxy requests to resources that aren't available locally; default: empty |
|
|
Flag to resolve the resource from the remote location before fallback to classpath; default: |
|
|
Flag to enable caching of any resources in resource servlet; default: |
Configuration parameters are added as context parameters to the web.xml.
When you're starting to develop OpenUI5 controls and modules being located inside the servlet paths resources/ or test-resources/, it makes the development process easier to disable the caching of such resources as well as to enable the resource browsing. To activate the development mode, add the following context parameter:
<!-- 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 -->If the development mode is active, you can browse resources as follows via the resource browser:
%SERVER_URL%!/resources/%SERVER_URL%/test-resources/
You can use the ResourceServlet to tunnel/proxy requests to another server that provides SAPUI5 resources instead of referring to OpenUI5 from a remote location inside the bootstrap script tag and thus avoid cross domain issues. To activate the remote location tunneling/proxying, add the following context parameter to the web.xml of your application:
<context-param>
<param-name>com.sap.ui5.resource.REMOTE_LOCATION</param-name>
<param-value>http://%server%:%port%/sapui5</param-value>
</context-param>This dispatches the requests from resources/sap/m/Button.js to http://%server%:%port%/sapui5/resources/sap/m/Button.js.
If you are located behind a proxy and the remote location is outside your localnetwork, 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. By default, it uses the configured com.sap.ui5.resource.MAX_AGE to avoid too much load on the ResourceServlet.
Verify that a Resource was Retrieved from Remote Location
When in development mode, it's 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
Resource packaging for web applications and Java modules can be any kind of JAR file, for example OpenUI5 UI library that is available in the classpath of the web application.
Store the resources as follows:
-
Web application:
WebContent/ resources/ **/** test-resources/ **/** -
OpenUI5 UI libraries:
META-INF/ resources/ **/** test-resources/ **/**For custom JAR files, you need to apply to this on your own.
When you run OpenUI5 as an OSGi web bundle and reference the UI libraries as OSGi bundles, you need to determine the OpenUI5 OSGi bundles as follows:
-
Extend the
ResourceServletin the OSGi servlet container by using an OSGi fragment that is responsible to add the OSGi flavor for the determination of UI libraries. Now, theResourceServletis aware of the OSGi bundles and can search within the OSGi servlet container for UI libraries. -
The
OSGiResourceServletuses the following entry in theMANIFEST.MFof the UI library's JAR files to determine the relevant UI libraries:x-sap-ui5-ContentTypes: UILibrary