Migrate the loose application from WebSphere Liberty doc to OL.io doc

[gkwan-ibm]

Migrate the loose application from WebSphere Liberty doc to OL.io doc

[ramkumar-k-9286]

Hi David @dmuelle

A draft document has been added for loose applications:

Link: https://docs-draft-openlibertyio.mqj6zf7jocq.us-south.codeengine.appdomain.cloud/docs/latest/loose-applications.html

Please review the same.

Regards,
Ramkumar.

[dmuelle]

@ramkumar-k-9286 - some initial feedback-

• I dont think we need Normal/Loose Application headings, or the example list in the Normal section. Just keep the first sentence in that section and combine it with the Loose applications section make an intro with no other heading.
• run time ---> runtime
• dont mention WebSphere Application Server Developer Tools
• use definition list formatting for the two ways to provide xml file
• link to the server package command doc
• try to combine the two lists in the config file section- put the examples with the corresponding actions
• dont enclose the elements in <brackets> in the text
• link to the config element docs for each element on first mention
• add noun descriptors for all code entities in the text
• run acrolinx

I'll wait on further comments until we have dev review-

[dmuelle]

one thing that is not clear is where the config file exists and what it's relationship to the server.xml is- how does the runtime find the loose app?

[ramkumar-k-9286]

Hi Thomas @tbitonti

A draft document has been added for loose applications:

Link: https://docs-draft-openlibertyio.mqj6zf7jocq.us-south.codeengine.appdomain.cloud/docs/latest/loose-applications.html

Please review the same and add the Developer Reviewed label if satisfied with the document.

Please feel free to add comments here for changes that need to be made to the document.

Regards,
Ramkumar.

[ramkumar-k-9286]

Review comments received on slack:

Review notes:

"It enables development tools ..."
==>
"Use of loose applications enables development tools ..."
(Remove ambiguous "it".)

---

"provide the XML file to the runtime"
==>
"provide the XML file to the Liberty Server"
("runtime" is less meaningful for Liberty servers)

---

Should "when you run the server package command" be indented?

Maybe drop the sentence "The server is not started at the time of packaging and has no way to access the needed variable information." That sentence may not be 100% accurate. The sentence that follows it is accurate.

---

"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."
==>
"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."

---

"Using the appropriate XML, you can take the following actions:"
==>
"You can use the loose application configuration to locate application content in the following ways:"

---

"Map the root of the archive"
==>
"Map the root of the virtual application archive"

---

Under "Loose application configuration file examples", I'd make a note to say that the application name is taken from the application location. Continuing the examples,

Configured Application:

Application configuration:

Actual application location:
apps/myApp.war.xml
Application name: "myApp" (maybe "myApp.war"?)

Dropins application:
Application configuration:
** NONE **
Actual application location:
dropins/myApp.war.xml
Application name: "myApp" (maybe "myApp.war"?)

---

Under "Virtual paths and file names": An example mapping a file or an archive to the root of the enclosing archive would be useful. (This structure is used in "Considerations for loose applications".)

Something like:

If you add file or dir elements to an archive, the name of the file or directory in the loose archive can be the root location, "/".

For example, to use the contents of a folder as the contents of the virtual archive:

To use the contents of a application archive as the contents of the virtual archive:

[ramkumar-k-9286]

Additional comments received on Slack

Would adding a sentence after "Normally .." be helpful? That would create a parallal to "Normally", adding balance to the paragraph:
"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.
(Added)
"Alternatively, using loose applications, the content of an application may be split between multiple physical locations."
(I'm not sure if "Alternatively" is necessary.)

---

For "When you run the server package command", does this apply to both ways to provide the XML file? Having indentation groups the statement with "Using the application dropins folder".
This switches between passive and active ("when using" vs "you can use"):
"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:"
I'd change:
"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."
To:
"Map one or more bin/output folders onto the WEB-INF/classes folder. A mapped folder may needed, for example, because of workspace preferences, coporate 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 be mapped onto the same WEB-INF/classes folder."
Note the change of "into" to "onto": The contents of the bin/output folder become the content of the WEB-INF/classes folder. "output" does NOT become a child folder of WEB-INF/classes.
I'd change:
"A separate Java project that you want to treat like a JAR file in WEB-INF/lib."
To:
"The output of a Java project, packaged as a JAR file, and created at a physical location outside of the virtual application."
I'd drop the sections with "Configred Application" and "Dropins Application" (but leave the NOTE!) The NOTE seems a sufficient summary of the examples that were provided.
Maybe change "The following code is" to "The following is" or "Here is"? Calling the XML text "code" is confusing to me. (There are two occurrences.)
Under "Files", "sourceOnDisk`" has a stray apostrophe.
I'd remove the text ", which are resolved correctly".
Maybe use "the physical file name" instead of "the actual name on the disk"
Replace:
"If you have two folders with the same name, the same virtual location in the loose application configuration,"
With:
"If you have two folders mapped to the same virtual location in the loose application configuration,"
A "location" includes both the path to the location and the simple name of the location.
I'd clarify how the file is "wrong", changing:
"If the first file found is the wrong file,"
To:
"If the first file found is the wrong file to be used,"
Or maybe remove "wrong"?
Also, I'd move that sentence to the preceding paragraph, starting the second paragraph with the sentence:
"The first occurrence applies to files defined in the dir elements"

Maybe change:
"could display unexpected behavior."
To:
"could behave unexpectedly."
"display" seems to centered on visible behavior.
The text "in web applications" is unnecessary in:
"However, if you use ServletContext.getRealPath in web applications to obtain a"
Maybe, change "applications" to "web applications" in the first sentence:
"You can use ServletContext.getRealPath in your web applications"

I'd change:
"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."
To:
"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."
Maybe add a bold CAUTION here?

[ramkumar-k-9286]

Hi Thomas @tbitonti

The suggested comments have been incorporated.

The draft document Link: https://docs-draft-openlibertyio.mqj6zf7jocq.us-south.codeengine.appdomain.cloud/docs/latest/loose-applications.html

Please review the same and add the Developer Reviewed label if satisfied with the document.

Please feel free to add comments here if you need me to make any changes to the document.

Regards,
Ramkumar.