Loose applications
Loose applications are applications that are composed from multiple physical locations, which are provided to the run time via an XML file. Loose applications are supported for Java™ EE and OSGi applications and are particularly beneficial in a development environment.
Normal application
- Library Java archive (JAR) files are stored in WEB-INF/lib
- Classes are either in library JAR files or in WEB-INF/classes
- The deployment descriptor is in WEB-INF/web.xml
- Content to be served is located from the root of the directory
Loose application
A loose application is
described as a virtual directory that represents the application,
where information might be in any location
. It enables development
tools, such as WebSphere® Application
Server Developer Tools, to run applications where the associated files
are loaded directly from the workspace, rather than being exported.
Examples of associated files are Java classes,
JavaServer Pages, or images. If you load the associated files directly
from the workspace, it results in a faster build-run-debugging cycle.
The content is not present under one directory, but can come from
other locations. These locations are specified in an XML configuration
file.
- By placing the XML file in the
location
attribute in an application configuration element with an appended .xml suffix - By placing the XML file directly into the application dropins folder
Loose application configuration file
- Map any physical directory to any location within the application
- Map any physical file to any location within the application
- Map any physical JAR file or directory to any location as a nested archive
- Map multiple physical sources to a single target location (merging)
- Map the root of the archive to one location on disk, such as a folder in an Eclipse project.
- Map a Java bin/output folder
that is not in the
usual
location into the WEB-INF/classes folder. This location might be in a different folder due to your workspace preferences, corporate guidelines, source control project layout guidelines, and so on. You might have multiple Java source and output locations in the same project, and want to map them both to WEB-INF/classes. - Map an
external
JAR file into the application. Thisexternal
JAR file might be one of the following:- A separate Java project that you want to treat like a JAR file in WEB-INF/lib
- A utility JAR file somewhere else on your hard disk drive that
you built the
.war
file against, and need to include in WEB-INF/lib at run time
Loose application configuration file examples
<archive>
for archives<file>
for files<dir>
for directories
- Archives
- The
<archive>
element is always used as the root of the loose application configuration file. It is also the root of the virtual file system that is represented in the XML. You can nest any of the three elements under the root<archive>
element. The root<archive>
element does not have any attributes. - Files
- You can use the
<file>
element to map a file on your hard disk to a file in your loose application configuration. You can set the following attributes on the<file>
element:targetInArchive
defines the path where the archive appears within the loose defined enclosing archive.sourceOnDisk
defines the actual location of your file on your file system.Note: ThesourceOnDisk
attribute value is an absolute location. You can use Liberty variables such as${example.dir}
, which are resolved correctly.
- Directories
- You can use the
<dir>
element to map a directory, and all of its contents on disk, to a directory location in the loose application configuration. The element has the same attributes as the<file>
element and you use it in a similar way.
Virtual paths and file names
If you add <file>
or <dir>
elements
to an archive, the name of the file or directory in the loose archive
does not need to be the same as the actual name on disk.
${example.dir}/applicationFiles/newfile.txt
to appear in the archive as /application.txt
:<archive>
<file targetInArchive="/application.txt"
sourceOnDisk="${example.dir}/applicationFiles/newfile.txt"/>
</archive>
The same concept also holds true for the path of any added file or directory. The physical resource on disk does not need to be in a directory hierarchy that corresponds to the one being declared.
${example.dir}/applicationFiles/newfile.txt
appear in the archive as /only/available/in/application.txt
:<archive>
<file targetInArchive="/only/available/in/application.txt"
sourceOnDisk=""${example.dir}/applicationFiles/newfile.txt"/>
</archive>
targetInArchive
attribute. The Liberty server can navigate the directory
hierarchy declared, even if the hierarchy contains only virtual elements, as in the previous
example.<archive>
<file targetInArchive="/only/available/in/red.txt"
sourceOnDisk="${example.dir}/applicationFiles/newfile.txt" />
<archive targetInArchive="/apps/jarName.jar">
<dir targetInArchive="/META-INF"
sourceOnDisk="${example.dir}/applicationData/myApplication" />
</arhive>
</archive>
Folders and files with the same name
If you have two folders with the same name in the same virtual location in the loose application configuration, the folders are merged, and the contents of both folders are available. If you have two files with the same target location in the loose archive, the first occurrence of the file is used. The first occurrence is based on a top-down approach to reading the elements of the loose application configuration file.
If
the first file found is the wrong file, reorder the XML so that the
element that contains the version of the file you want is processed
first. The first occurrence applies to files defined in <dir>
elements
and files that are defined in <file>
elements.
The first occurrence of a file with the same name and virtual location
is the one returned from the virtual file system.
Considerations for loose applications
For
all loose configured applications, the files are not on disk in the
hierarchy that they are declared to be. If your applications directly
access their own resources, and expect them to be arranged on disk
as they would be with an expanded war
or ear
layout,
they might exhibit unexpected behavior.
You can use ServletContext.getRealPath
in
your applications to discover physical resource paths. ServletContext.getRealPath
can
discover file paths to open to read or write data, and obtain directories.
However, if you use ServletContext.getRealPath
in
web applications to obtain a path for /
, you cannot use this
path to navigate the application on disk.
ServletContext.getRealPath
allows
only a single physical path to be returned, and the loose application
might have merged multiple directories to form one path visible to
the application.
<archive>
<dir targetInArchive="/"
sourceOnDisk="c:\myapplication" />
<dir targetInArchive="/web/pages"
sourceOnDisk="c:\webpagesforapplication" />
</archive>
An application that directly accesses /web/pages
and
then navigates up the directory hierarchy, finds that the parent of
the physical path of /web/pages
is c:\
and
not /web
. c:\
has no pages directory
and no parent directory.
These considerations apply only if your applications attempt to directly access the content on disk, and perform their own path navigation based on an assumption of a corresponding hierarchical layout on disk. The same applications also encounter issues if they are deployed as an archive. These applications generally experience issues with portability.
Complex example
<archive>
<dir targetInArchive="/appResources"
sourceOnDisk="${example.dir}/applicationFiles" />
<archive targetInArchive="application.jar">
<dir targetInArchive="/src"
sourceOnDisk="${example.dir}/applicationCode/src" />
</archive>
<archive targetInArchive="webApp.war">
<dir targetInArchive="/META-INF"
sourceOnDisk="${example.dir}/manifestFiles/" />
<dir targetInArchive="/WEB-INF"
sourceOnDisk="c:/myWorkspace/webAppProject/web-inf" />
<archive targetInArchive="/WEB-INF/lib/myUtility.jar">
<dir targetInArchive="/"
sourceOnDisk="c:/myWorkspace/myUtilityProject/src" />
<file targetInArchive="/someJar.jar"
sourceOnDisk="c:/myWorkspace/myUtilityProject/aJar.jar" />
</archive>
</archive>
<file targetInArchive="/myjar.jar"
sourceOnDisk="${example.dir}/apps/application.zip" />
</archive>