Listener 2.x Static Resources and i.war

Oracle Application Express (APEX) relies on a set of static resources to function properly. These static resources contain the JavaScript, CSS, and images that the APEX user interface needs to render and function correctly. The static resources are located in the /images folder in the APEX distribution. Typically the resources are made available at the /i/ path on an APEX web server.

In the Oracle Application Express Listener (Listener) 1.x.x series the process for deploying the /i/ bundle was to manually zip the contents of /images into an archive named i.war and then to deploy that archive on the same application server as Listener.

This meant that every time the static resources were modified (for example to add custom stylesheets or images), the archive needed to be recreated and then redeployed on the application server.

In the Listener 2.x.x series the process was improved. Rather than creating the archive manually the static sub-command of apex.war is used to generate i.war as documented here, and reproduced below:

Use the static command to create a web archive file named i.war:

java -jar apex.war static <apex directory>/images


<apex directory> is the directory location of Oracle Application Express.

The created images WAR does not contain the static resources, instead it references the location where the static resources are stored. Therefore the static resources must be available at the specified path on the server where the WAR is deployed.

Note the emphasis in the last paragraph above. In contrast to Listener 1.x.x, in 2.x.x the static resources are not included in the archive. Instead functionality in Oracle WebLogic and Oracle GlassFish is leveraged to create an i.war that references the path where the static resource are located. This means that the static resources can be updated without having to recreate and redeploy i.war.

Thus when i.war is deployed on WebLogic or GlassFish, and a request for a resource is made within the /i/ path then the application server looks for the corresponding resource within the <apex directory>/images folder specified above. It looks for the path in the file system of the server where i.war is deployed. Therefore it is imperative that the APEX static resources are copied to the application server at the exact path specified when using the static command.

For example if i.war is created using the following command:

java -jar apex.war static /usr/local/apex/4.2.2/apex/images

then the path /usr/local/apex/4.2.2/apex/images must exist on the server where i.war is deployed and it must contain all the static resources for the version of APEX installed in the database. It is not sufficient that the files exist on a local development box where the i.war was created, they must be copied to the application server machine’s file system as well.

Deploying static resources at custom path

Occasionally you may need to deploy the APEX static resources at a path other than the default of /i/. To do this use the --context-path argument of the static command, for example to deploy static resources at /apex-images you would do the following:

java -jar apex.war static --context-path /apex-images /usr/local/apex/4.2.2/apex/images

which will produce output similar to the following:

WAR Generation complete
 WAR location     : /home/cdivilly/apex-images.war
 Context path     : /apex-images
 Static resources : /usr/local/apex/4.2.2/apex/images

Note that this time the archive is named apex-images.war. Note however it is not the name of the archive that determines it’s context-path, rather it is a setting in the deployment descriptor in the archive that determines this. In this case the value of that setting is /apex-images. You could rename the archive to abc.war and it would still be delpoyed at /apex-images. A previous post provides more detail on these deployment descriptors.

See Also

  • To learn more detail on the WebLogic and GlassFish functionality that enables i.war to refer to resources located in the file system, see this post.
  • If you are having problems with APEX static resources not being found and APEX pages not displaying properly, see this post