Issue analysis and design document for the feature request to support browsing over the content repository.

Overview

The intent of this feature is to have equivalent read content semantics to what WildFly/EAP current provides for exploded managed deployments, but instead for deployments and sub-deployments still in archive. Instead of the user needing to explode the deployment, the user would invoke operations against the WildFly/EAP management API to read and list content.

Background

The WildFly/EAP management layer supports deployments presented to it by the user either in the form of a single zipped archive file, or in the form of a directory structure whose structure corresponds to an unzipped version of the archive. The latter is referred to as an "exploded deployment". Exploded deployments have some advantages, particularly the ability to update static content files (e.g. .html and .css files) and have that updated content reflected in the running application without needing to redeploy the application.

WildFly/EAP also supports both managed and unmanaged deployments. With a managed deployment the server takes the deployment content and copies it into an internal content repository and thereafter uses that copy of the content, not the original user-provided content. The server is thereafter responsible for the content it uses. With an unmanaged deployment the user provides the local filesystem path of deployment content, and the server directly uses that content. However the user is responsible for ensuring that content, e.g. for making sure that no changes are made to it that will negatively impact the functioning of the deployed application.

Managed deployments have a number of benefits over unmanaged:

• They can be manipulated by remote management clients, not requiring access to the server filesystem.
• In a managed domain, WildFly/EAP will take responsibility for replicating a copy of the deployment to all hosts/servers in the domain where it is needed. With an unmanaged deployment, it is the user's responsibility to have the deployment available on the local filesystem on all relevant hosts, at a consistent path.
• The deployment content actually used is stored on the filesystem in the internal content repository, which should help shelter it from unintended changes.
  

WildFly/EAP currently supports both managed and unmanaged archive deployments, and unmanaged exploded deployments. This RFE is to add support for content read access on the archive managed deployments.

Issue Metadata

EAP ISSUE: https://issues.jboss.org/browse/EAP7-516

RELATED ISSUES: [WFCORE-379] Give option to make the content repository browsable - JBoss Issue Tracker and [WFCORE-380] Operations to read content from the content repository - JBoss Issue Tracker

DEV CONTACTS: Emmanuel Hugonnet (primary), Brian Stansberry (secondary), Jean-François Denise (CLI), Claudio Miranda (HAL)

QE CONTACTS: Michal Jurc

AFFECTED PROJECTS OR COMPONENTS: WildFly Core kernel, CLI ([WFCORE-1726] CLI support for response attachments - JBoss Issue Tracker), [HAL-1172] Support read-content / browse-content operations

OTHER INTERESTED PARTIES: JBDS

FORUM THREAD: Download content?

Requirements

Hard Requirements

These items must be satisfied in order to have a satisfactory feature.

• The deployment resource's management API will include a read-content operation with a nullable path parameter. The return value will be the index of an associated stream from which the content at the given path can be read
• This operation will fail if the deployment is not managed.
• This operation will fail if the content referred to by the path parameter doesn't exist.
• This operation will fail if the content referred to by the path parameter is a directory.
• If the path is null the returned content will be the full deployment if the deployment is an archive, otherwise it will fail (since it is a directory).
• The return value will be the content that is present in the content repository, which will not necessarily be equivalent to the content installed in the runtime.
  • For example, if an overlay changes the file we are trying to read we would get the original one not the result of the overlay.
• The read-content operation must be handled as a read-only operation but it also must not be interfered with by any content repository activity (writing or deleting files). This means the existing mechanism of locking the operation out of the repository using the ModelController's exclusive write lock is insufficient; some additional safeguards within the repository itself are probably needed. (The exclusive MC lock is probably still fine for preventing conflicts between gc and content writes, though.)
• Support for a browse-content operation that would return a tree of all the files / directories with the relative specified path parameter for a depth parameter and maybe an archive parameter that would only list expendable files. This could help completion for the CLI as well as cover related issues.
• The archive files will be returned as one entry of the list.
• The path may contains multiple archive files in which case the target path will be resolved from their content.
• This operation will fail if the deployment is not managed.
• This operation will fail if the content referred to by the path parameter doesn't exist.
• The return value will be the list of contents relative to the path in the content in the repository, which will not necessarily be equivalent to the content installed in the runtime.
  • For example, if an overlay changes the file we are trying to read we would get the original one not the result of the overlay.
• The browse-content operation must be handled as a read-only operation but it also must not be interfered with by any content repository activity (writing or deleting files). This means the existing mechanism of locking the operation out of the repository using the ModelController's exclusive write lock is insufficient; some additional safeguards within the repository itself are probably needed. (The exclusive MC lock is probably still fine for preventing conflicts between gc and content writes, though.)
• The browse-content operation will return a list of a complex type that will provides some informations about the path. It will have:
  • a relative-path attribute : the relative path to the content for the specified browsing start point.
  • a file attribute of type boolean to indicate if it is a file or a folder
  • a size attribute (we won't compute the size of folder at the moment)

Affected Components

The CLI would have to support some way to save or display the content returned when this is a stream. This behaviour is CLI 'only' in that the server doesn't have to be aware of what the CLI is going to do with the returned content.