6852-draft doc for loose applications-comm-inc-4

6852-draft doc for loose applications-comm-inc-4

#6852

modules/ROOT/pages/loose-applications.adoc

@@ -15,7 +15,7 @@
 
 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.
 
-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.
+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. Using loose applications, the content of an application can be split between multiple physical locations.
 
 
 == Loose application
@@ -29,13 +29,14 @@ Specify the XML file in the location attribute of the application configuration
 
 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 xref:reference/command/server-package.adoc[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. Variable substitution does not take place when you use the `server package` command.
+
+
+When you run the xref:reference/pages/command/server-package.adoc[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. Variable substitution does not take place when you use the `server package` command.
 
 
 == Loose application configuration file
 
-When using a loose application, the Open Liberty server uses a loose application configuration to locate application content, rather than locating the application content from a root directory or root archive. You can use the loose application configuration to locate application content in the following ways:
+When using a loose application, the Open Liberty server employs a loose application configuration to locate application content, instead of locating it from a root directory or root archive. You can use this loose application configuration to locate application content in the following ways:
 
 - Map any physical directory to any location within the application.
 - Map any physical file to any location within the application.
@@ -45,10 +46,10 @@ When using a loose application, the Open Liberty server uses a loose application
 For example:
 
 - Map the root of the virtual application 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 one or more `bin/output` folders onto the `WEB-INF/classes` folder. A mapped folder may be needed, for example, because of workspace preferences, corporate guidelines, or source control project layout guidelines. Multiple mapped folders may be needed because a project has multiple output locations, or because multiple projects are mapped onto the same `WEB-INF/classes` folder.
 - 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`.
+* The output of a Java project, packaged as a `JAR` file, and created at a physical location outside of the virtual application.
 * 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.
 
 
@@ -62,39 +63,6 @@ You can configure three different elements in the loose application configuratio
 
 NOTE: The application name is taken from the application location. For example, if the application is located at `apps/myApp.war.xml`, the application name will be derived from `myApp.war`.
 
-- Configured Application:
-
-* Application configuration:
-+
-[source,xml]
-----
-<application location="myApp.war"/>
-----
-+
-* Actual application location:
-+
-[source,bash]
-----
-<application location="myApp.war"/>
-----
-+
-* Application name: `myApp` or possibly `myApp.war`
-
-- Dropins Application:
-
-* Application configuration:
-+
-NONE
-+
-* Actual application location:
-+
-[source,bash]
-----
-dropins/myApp.war.xml
-----
-
-* Application name: `myApp` or possibly `myApp.war`
-
 ===  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.
@@ -103,7 +71,7 @@ The archive elements can be nested recursively. For `archive` elements nested un
 
 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:
+The following is an example of the root `archive` element with another `archive` element nested under it:
 
 
 [source,xml]
@@ -123,11 +91,11 @@ The following code is an example of the root `archive` element with another `arc
 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.
+- `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 `sourceOnDisk` attribute value is an absolute location. You can use Open Liberty variables such as `${example.dir}`.
 
-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:
+The following 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]
 ----
@@ -140,7 +108,7 @@ The following code is an example of a file in `C:/devFolder/myApplication.zip` t
 ===  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`:
+The following 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]
 ----
@@ -165,9 +133,9 @@ In both of the previous examples, all files that are in `${example.dir}/applicat
 
 == 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.
+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 physical file name.
 
-The following code is an example of how you can configure `${example.dir}/applicationFiles/newfile.txt` to appear in the archive as `/application.txt`:
+The following is an example of how you can configure `${example.dir}/applicationFiles/newfile.txt` to appear in the archive as `/application.txt`:
 
 [source,xml]
 ----
@@ -179,7 +147,7 @@ The following code is an example of how you can configure `${example.dir}/applic
 
 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`:
+The following 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]
 ----
@@ -231,18 +199,18 @@ To use the contents of an application archive as the contents of the virtual arc
 
 == 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 you have two folders mapped to 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 to be used, reorder the XML so that the element that contains the version of the file you want is processed first. 
 
-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.
+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.
+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 behave unexpectedly.
 
-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.
+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. You can use `ServletContext.getRealPath` in your 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.
+NOTE: When using loose applications, `ServletContext.getRealPath` is unreliable for accessing physical files. Loose applications might merge multiple directories to provide content at one virtual path visible to the application, and `ServletContext.getRealPath` can provide only one of the mapped physical paths.
 
 Consider the following configuration:
 
@@ -264,7 +232,7 @@ These considerations apply only if your applications attempt to directly access
 
 == Complex example
 
-The following code is a more complex example of loose application configuration. This example uses the elements and creates a complex mapping of files and directories.
+The following is a more complex example of loose application configuration. This example uses the elements and creates a complex mapping of files and directories.
 
 [source,xml]
 ----