-
Notifications
You must be signed in to change notification settings - Fork 47
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
6852-draft doc for loose applications
6852-draft doc for loose applications #6852
- Loading branch information
1 parent
b7a44c1
commit c1086ee
Showing
1 changed file
with
249 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,249 @@ | ||
| // Copyright (c) 2022 IBM Corporation and others. | ||
| // Licensed under Creative Commons Attribution-NoDerivatives | ||
| // 4.0 International (CC BY-ND 4.0) | ||
| // https://creativecommons.org/licenses/by-nd/4.0/ | ||
| // | ||
| // Contributors: | ||
| // IBM Corporation | ||
| // | ||
| :page-description: Loose applications are applications that are assembled from multiple physical locations, which are provided to the run time through an XML file. Loose applications are compatible with Java EE and OSGi applications and offer advantages in a development environment. | ||
| :seo-title: Loose applications | ||
| :page-layout: general-reference | ||
| :page-type: general | ||
|
|
||
| = Loose applications | ||
|
|
||
| Loose applications are applications that are assembled from multiple physical locations, which are provided to the run time through an XML file. Loose applications are compatible with Java EE and OSGi applications and offer advantages in a development environment. | ||
|
|
||
|
|
||
| == Normal application | ||
|
|
||
| Normally an application is contained under one directory or in one archive, with its content, modules, resources, classdata, and metadata at known locations within that directory. For example, the location of resources for a web application is as follows: | ||
|
|
||
| * 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 defined as a virtual directory that represents the application, where information can be located anywhere. It enables development tools, such as WebSphere Application Server Developer Tools, to run applications where the related files are sourced directly from the workspace, bypassing the need for exporting. Such related files might be Java classes, JavaServer Pages, or images. Loading these files straight from the workspace leads to a quicker build-run-debug cycle. The content is not located in a single directory, but might originate from various locations. These locations are detailed in an XML configuration file. | ||
|
|
||
| The two ways to provide the XML file to the runtime are: | ||
|
|
||
| - Using the location attribute. | ||
|
|
||
| Specify the XML file in the location attribute of the application configuration section, and make sure that the file name ends with `.xml`. If you specify `<application location="myapp.war" />`, the runtime searches for a file named `myapp.war.xml`. However, if both `myapp.war` and `myapp.war.xml` exist, the Open Liberty server prioritizes `myapp.war` for running the application. The search rules for this method align with those of an application directory or an archive. | ||
|
|
||
| - Using the application dropins folder. | ||
|
|
||
| Directly place the XML file into the application dropins folder, adhering to the folder naming conventions and appending `.xml` to the end of the file name. | ||
|
|
||
| When you run the `server package` command with a loose application `my_app.war.xml` file that uses server variable substitution, those parts of the loose application having variable substitution are not packaged. The server is not started at the time of packaging and has no way to access the needed variable information. Variable substitution does not take place when you use the `server package` command . | ||
|
|
||
|
|
||
| == Loose application configuration file | ||
|
|
||
| The Open Liberty server uses the loose application configuration file to obtain the application content, rather than locating it from a root directory or single archive. Using the appropriate XML, you can take the following actions: | ||
|
|
||
| - 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, also known as merging. | ||
|
|
||
| For example: | ||
|
|
||
| - 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. This **external** `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 runtime. | ||
|
|
||
|
|
||
| == Loose application configuration file examples | ||
|
|
||
| You can configure three different elements in the loose application configuration file: | ||
|
|
||
| - `<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. | ||
|
|
||
| The archive elements can be nested recursively. For `<archive>` elements nested under the root `<archive>` element, you can set the `targetInArchive` attribute. The `targetInArchive` attribute defines the path where the archive appears within the loose defined enclosing archive. You cannot map an archive on the file system as an archive in the application with an `<archive>` element. To use loose application configuration to map an archive on disk, use a `<file>` element instead. | ||
|
|
||
| The `targetInArchive` attribute value is an absolute path with a leading forward slash `/`. | ||
|
|
||
| The following code is an example of the root `<archive>` element with another `<archive>` element nested under it: | ||
|
|
||
|
|
||
| [source,xml] | ||
| ---- | ||
| <archive> | ||
| <archive targetInArchive="/jarName.jar"> | ||
| <!-- more objects can be embedded here--> | ||
| </archive> | ||
| </archive> | ||
| ---- | ||
|
|
||
|
|
||
| === 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` attribute defines the path where the archive appears within the loose defined enclosing archive. | ||
| - `sourceOnDisk`` attribute defines the actual location of your file on your file system. | ||
|
|
||
| The `sourceOnDisk` attribute value is an absolute location. You can use Open Liberty variables such as `${example.dir}`, which are resolved correctly. | ||
|
|
||
| The following code is an example of a file in `C:/devFolder/myApplication.zip` that is represented as `/apps/webApplication.war` by the loose application configuration: | ||
|
|
||
| [source,xml] | ||
| ---- | ||
| <file targetInArchive="/apps/webApplication.war" | ||
| sourceOnDisk="C:/devFolder/myApplication.zip" /> | ||
| ---- | ||
|
|
||
| === 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. | ||
|
|
||
| The following code is an example of a directory that the loose application configuration shows as being in `/META-INF` and on your file system in `${example.dir}/applicationData/myApplication`: | ||
|
|
||
| [source,xml] | ||
| ---- | ||
| <dir targetInArchive="/META-INF" | ||
| sourceOnDisk="${example.dir}/applicationData/myApplication" /> | ||
| ---- | ||
|
|
||
| To add the directory to an archive so it appears to be in `/apps/jarName.jar/META-INF`, embed the `<dir>` element as follows: | ||
|
|
||
|
|
||
| [source,xml] | ||
| ---- | ||
| <archive targetInArchive="/apps/jarName.jar"> | ||
| <dir targetInArchive="/META-INF" | ||
| sourceOnDisk="${example.dir}/applicationData/myApplication" /> | ||
| </archive> | ||
| ---- | ||
|
|
||
| In both of the previous examples, all files that are in `${example.dir}/applicationData/myApplication` are mapped and visible in the loose application configuration under the directory that is mapped by the `targetInArchive` attribute. | ||
|
|
||
|
|
||
| == 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 the disk. | ||
|
|
||
| The following code is an example of how you can configure `${example.dir}/applicationFiles/newfile.txt` to appear in the archive as `/application.txt`: | ||
|
|
||
| [source,xml] | ||
| ---- | ||
| <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. | ||
|
|
||
| The following code is an example of how you can make `${example.dir}/applicationFiles/newfile.txt` appear in the archive as `/only/available/in/application.txt`: | ||
|
|
||
| [source,xml] | ||
| ---- | ||
| <archive> | ||
| <file targetInArchive="/only/available/in/application.txt" | ||
| sourceOnDisk="${example.dir}/applicationFiles/newfile.txt"/> | ||
| </archive> | ||
| ---- | ||
|
|
||
| In each case, the open Liberty server sees the resource by the name and path declared by the `targetInArchive` attribute. The Open Liberty server can navigate the directory hierarchy declared, even if the hierarchy contains only virtual elements, as in the previous example. | ||
|
|
||
| [source,xml] | ||
| ---- | ||
| <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, 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 the `<dir>` elements and files that are defined in the `<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 access their resources directly and anticipate them to be organized on the disk in the same manner as an expanded `war` or `ear` layout, they could display 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. | ||
|
|
||
| The `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. | ||
|
|
||
| Consider the following configuration: | ||
|
|
||
| [source,xml] | ||
| ---- | ||
| <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 | ||
|
|
||
| The following code is a more complex example of loose application configuration. This example uses all of the elements and creates a complex mapping of files and directories: | ||
|
|
||
| [source,xml] | ||
| ---- | ||
| <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> | ||
| ---- |