Snap for 8822995 from 696ef143 to tm-qpr1-release

            try {

                root.setView(view, wparams, panelParentView, userId);

            } catch (RuntimeException e) {

                final int viewIndex = findViewLocked(view, false);

                // BadTokenException or InvalidDisplayException, clean up.

                if (index >= 0) {

                    removeViewLocked(index, true);

                if (viewIndex >= 0) {

                    removeViewLocked(viewIndex, true);

                }

                throw e;

            }

The dagger modules in this directory can be included by the host SysUI using the Shell library for

explicity injection of Shell components. Apps using this library are not required to use these

dagger modules for setup, but it is recommended for them to include them as needed.

The modules are currently inherited as such:

+- WMShellBaseModule (common shell features across SysUI)

   |

   +- WMShellModule (handheld)

   |

   +- TvPipModule (tv pip)

      |

      +- TvWMShellModule (tv)

 No newline at end of file

# Window Manager Shell Readme

The following docs present more detail about the implementation of the WMShell library (in no

particular order):

1) [What is the Shell](overview.md)

2) [Integration with SystemUI & Launcher](sysui.md)

3) [Usage of Dagger](dagger.md)

4) [Threading model in the Shell](threading.md)

5) [Making changes in the Shell](changes.md)

6) [Extending the Shell for Products/OEMs](extending.md)

7) [Debugging in the Shell](debugging.md)

8) [Testing in the Shell](testing.md)

Todo

- Per-feature docs

- Feature flagging

- Best practices

 No newline at end of file

# Making changes in the Shell

---

## Code reviews

In addition to the individual reviewers who are most familiar with the changes you are making,

please also add [wm-code-reviewers@google.com](http://g/wm-code-reviewers) to keep other WM folks

in the loop.

## Adding new code

### Internal Shell utility classes

If the new component is used only within the WMShell library, then there are no special

considerations, go ahead and add it (in the `com.android.wm.shell.common` package for example)

and make sure the appropriate [unit tests](testing.md) are added.

### Internal Shell components

If the new component is to be used by other components/features within the Shell library, then

you can create an appropriate package for this component to add your new code. The current

pattern is to have a single `<Component name>Controller` that handles the initialization of the

component.

As mentioned in the [Dagger usage](dagger.md) docs, you need to determine whether it should go into:

- `WMShellBaseModule` for components that other base & product components will depend on

- or `WMShellModule`, `TvWmShellModule`, etc. for product specific components that no base

  components depend on

### SysUI accessible components

In addition to doing the above, you will also need to provide an interface for calling to SysUI

from the Shell and vice versa.  The current pattern is to have a parallel `Optional<Component name>`

interface that the `<Component name>Controller` implements and handles on the main Shell thread.

In addition, because components accessible to SysUI injection are explicitly listed, you'll have to

add an appropriate method in `WMComponent` to get the interface and update the `Builder` in

`SysUIComponent` to take the interface so it can be injected in SysUI code.  The binding between

the two is done in `SystemUIFactory#init()` which will need to be updated as well.

### Launcher accessible components

Because Launcher is not a part of SystemUI and is a separate process, exposing controllers to

Launcher requires a new AIDL interface to be created and implemented by the controller.  The

implementation of the stub interface in the controller otherwise behaves similar to the interface

to SysUI where it posts the work to the main Shell thread.

### Component initialization

To initialize the component:

- On the Shell side, update `ShellInitImpl` to get a signal to initialize when the SysUI is started

- On the SysUI side, update `WMShell` to setup any bindings for the component that depend on

  SysUI code

### General Do's & Dont's

Do:

- Do add unit tests for all new components

- Do keep controllers simple and break them down as needed

Don't:

- **Don't** do initialization in the constructor, only do initialization in the init callbacks.

  Otherwise it complicates the building of the dependency graph.

- **Don't** create dependencies from base-module components on specific features (the base module

  is intended for use with all products)

  - Try adding a mechanism to register and listen for changes from the base module component instead

- **Don't** add blocking synchronous calls in the SysUI interface between Shell & SysUI

  - Try adding a push-mechanism to share data, or an async callback to request data

### Exposing shared code for use in Launcher

Launcher doesn't currently build against the Shell library, but needs to have access to some shared

AIDL interfaces and constants.  Currently, all AIDL files, and classes under the

`com.android.wm.shell.util` package are automatically built into the `SystemUISharedLib` that

Launcher uses.

If the new code doesn't fall into those categories, they can be added explicitly in the Shell's

[Android.bp](frameworks/base/libs/WindowManager/Shell/Android.bp) file under the

`wm_shell_util-sources` filegroup.

 No newline at end of file

# Usage of Dagger in the Shell library

---

## Dependencies

Dagger is not required to use the Shell library, but it has a lot of obvious benefits:

- Not having to worry about how to instantiate all the dependencies of a class, especially as

  dependencies evolve (ie. product controller depends on base controller)

- Can create boundaries within the same app to encourage better code modularity

As such, the Shell also tries to provide some reasonable out-of-the-box modules for use with Dagger.

## Modules

All the Dagger related code in the Shell can be found in the `com.android.wm.shell.dagger` package,

this is intentional as it keeps the "magic" in a single location.  The explicit nature of how

components in the shell are provided is as a result a bit more verbose, but it makes it easy for

developers to jump into a few select files and understand how different components are provided

(especially as products override components).

The module dependency tree looks a bit like:

- [WMShellConcurrencyModule](frameworks/base/libs/WindowManager/Shell/src/com/android/wm/shell/dagger/WMShellConcurrencyModule.java)

  (provides threading-related components)

  - [WMShellBaseModule](frameworks/base/libs/WindowManager/Shell/src/com/android/wm/shell/dagger/WMShellBaseModule.java)

    (provides components that are likely common to all products, ie. DisplayController,

    Transactions, etc.)

    - [WMShellModule](frameworks/base/libs/WindowManager/Shell/src/com/android/wm/shell/dagger/WMShellModule.java)

      (phone/tablet specific components only)

    - [TvPipModule](frameworks/base/libs/WindowManager/Shell/src/com/android/wm/shell/dagger/TvPipModule.java)

      (PIP specific components for TV)

      - [TvWMShellModule](frameworks/base/libs/WindowManager/Shell/src/com/android/wm/shell/dagger/TvWMShellModule.java)

        (TV specific components only)

  - etc.

Ideally features could be abstracted out into their own modules and included as needed by each

product.

## Overriding base components

In some rare cases, there are base components that can change behavior depending on which

product it runs on.  If there are hooks that can be added to the component, that is the

preferable approach.

The alternative is to use the [@DynamicOverride](frameworks/base/libs/WindowManager/Shell/src/com/android/wm/shell/dagger/DynamicOverride.java)

annotation to allow the product module to provide an implementation that the base module can

reference.  This is most useful if the existence of the entire component is controlled by the

product and the override implementation is optional (there is a default implementation).  More

details can be found in the class's javadoc.

 No newline at end of file