When an application that uses partial or completely overlapping stacked canvases is implemented using Java, it usually
requires creating a lightweight panel for each stacked canvas and
adding all those panels as children of some top level lightweight
window. Each panel can in turn contain a number of components.

During application execution, those canvases need to be raised
and lowered programmatically. A common case is that the user
uses the keyboard to navigate to a text component on a canvas
which is currently obscured by an xxxxx  canvas, and therefore
needs that canvas to come to the top of the Z-order.

The current implementation of Z-ordering in a container is static
in the sense that Z-order of each child relative to the  xxxxx s is
decided once at the time the child is added to the container, and
never altered. This means the only way we can alter the Z-order
of existing components in a container is by removing some set of
components and adding them again to the same container at with
different indices. This is not ideal, because the removal process
causes handlers to be called, resources to be destroyed, and focus
to shift, which in turn requires a workarounds to get everything
back to the state where it was before the Z-order modification.

We propose that an API be added to the Container class to allow
Z-order to be changed dynamically. _Raising_ a child component in
the Z-order of its parent container using this API should not
generate focus events or cause any  xxxxx  unnecessary handlers
to be called, though lowering a child could potentially have
more ramifications, and perhaps it might make sense to add new
listeners and events to track movement in the Z direction.

This API could mirror "add(component, index)" on Container and
perhaps be called "setZOrder(component, index)".
(Review ID: 136396) 
======================================================================

Given a container A, and components B and C added to the container
in that order, it is currently possible to raise C in the Z-order
using the following code:

A.remove(C);
A.add(C, 0);

In many cases the component we wish to raise will have focus, so
in reality one would need another component D which is unaffected
by the Z-order changes, to be used as a focus placeholder:

D.requestFocus();
A.remove(C);
A.add(C, 0);
C.requestFocus();

In JDK 1.4 and beyond where the focus model becomes asynchronous
for lightweight components, this workaround is even messier due
to the fact that there could be pending focus requests at the
time we need to change the Z-order, and in that case we may not
know where to request focus after we complete the workaround. It
is not clear at this time whether the problem even _can_ be fully
worked around in JDK 1.4, thus this enhancement request.
======================================================================

I believe add(Component, index) was originally intended to be the Z-order 
API for components inside the same container (4014938).  
 xxxxx@xxxxx  2001-11-29

Commit to fix in Tiger (feature requested by Oracle).  
 xxxxx@xxxxx  2002-02-08

Here is the link to specification.
http://javaweb/engineering/awt-core/Tiger/zorderspec_SQE.txt
 xxxxx@xxxxx  2003-01-23

Bug 4061458 has been marked as a duplicate of this bug, but 
I don't think it is the same since it refers to the z-order 
of top level containers rather than their children.