Adding support for streams in CLI

Version 2

Created by jdenise on Jul 7, 2016 4:24 AM. Last modified by jdenise on Jul 29, 2016 7:13 AM.

Analysis

Summary

Today there is no out of the box support for streams attached to an operation. User can develop their own Command handler and deal with attachments but low level operations don’t have such support.

Here we are proposing a way to support low level operations attachments.

Requirements

The support for streams is expected to work in batch and non batch mode.
All kind of workflows (if, try) must support attachments.
File System attachments must be supported. Other kind of attachments are outside the scope of this feature.
Files to be attached must be discovered by completion wherever the location of the file path (Operation argument, inside a List, a complex type, …)
In addition, completion for target-path must be supported for Incremental deployment (EAP7-204). Target-path are not streams but paths inside an exploded deployment.

Design Notes

A new Descriptor “attached-streams” is introduced. INT Property annotated with this descriptor and “filesystem-path” descriptor are considered to be candidate for stream attachment.
At command completion time, File System completion is offered for any annotated property (wherever its location). This is the expected behavior for property annotated with “filesystem-path”.
At command execution time, the user provided file system path are replaced by INT indexes, and the File InputStream is attached to the Operation.
In batch mode, all Attachments are aggregated inside the current active batch. This means that a unique index is to be computed for each attachment inside a given batch.
To support completion for paths inside a given exploded deployment, the descriptor “relative-to” is used. For property annotated with this descriptor completion based on the content of the exploded deployment is offered.
A bunch of new unit tests are to be developed to support Attachments and Completion. Unit tests will have a dependency on the Exploded deployment feature.

Documentation

Incremental deployment with the CLI

It can be desirable to incrementally create and(or) update a WildFly deployment. This piece of documentation details how this can be achieved using the WildFly CLI tool.

Steps to create an empty deployment and add an index html file.

1- Create an empty deployment named myapp:

[standalone@localhost:9990 /] /deployment=myapp:add(empty)

2- Add an index.html to myapp:

[standalone@localhost:9990 /] /deployment=myapp:add-content(content=[{input-stream-index=<press TAB>

Use completion to navigate to your index.html file.

3- Provide a target name for index.html inside the deployment and execute the operation:

[standalone@localhost:9990 /] /deployment=myapp:add-content(content=[{input-stream-index=./index.html, target-path=index.xhtml}]

4- Your content has been added, you can browse the content of a deployment using the browse-content operation:

[standalone@localhost:9990 /] /deployment=myapp:browse-content(path=./)

5- You can remove content from a deployment:

/deployment=myapp:remove-content(paths=[./index.xhtml])

Tips: add-content allows you to add more than one file (content argument is a list of complex types). CLI offers completion for browse-content's path and remove-content's paths brgument. You can safely use operations that are using attached streams in batch operations. In the case of batch operations, streams are attached to the batch associated composite operation.

Notes for server side operation Handler implementors

In order to benefit from CLI support for attached file streams and file system completion, you need to properly structure your operation arguments.

For example, imagine you want to create an operation that receives a list of file streams attached to the operation.

1) Define your operation argument as a LIST of INT (The LIST value-type must be of type INT).

2) In the description of your argument, add the 2 following boolean descriptors: filesystem-path and attached-streams

When your operation is called from the CLI, file system completion will be automatically proposed for your argument. At execution time, the file system paths will be automatically converted onto the index of the attached streams.