Package org.zkoss.zk.ui

## Interface IdSpace

- All Superinterfaces:
    `Scope`
  All Known Subinterfaces:
    `Macro`, `Page`
  All Known Implementing Classes:
    `AbstractPage`, `FileuploadDlg`, `HtmlMacroComponent`, `Idspace`, `Include`, `MessageboxDlg`, `PageImpl`, `VolatileIPage`, `VolatilePage`, `Window`, `XmlMacroComponent`

      public interface IdSpace
      extends Scope

  Implemented by a component (`Component`) and a page (`Page`) to denote that all its descendant and itself forms an independent ID space.

  In an ID space, ID of each component (`Component.getId()`) must be unique. And, you could retrieve any component in the same ID space by calling `getFellow(java.lang.String)` upon any component of the same ID space.

  For sake of description, components in the same ID space are called fellows. If the component has an ancestor which implements `IdSpace`, we say a component belongs to the ID space owned by the ancestor. If no such ancestor exists, the component belongs to the ID space owned by the page. The ancestor and the page is called the owner (`Component.getSpaceOwner()`).

  For sake of description, we also call the ID space as space X, if the owner is component X (or page X). If component Y is a child of X and also implements `IdSpace` (a.k.a., another owner), then space X includes component Y, but EXCLUDES descendants of Y. In other words, Y belongs to space X and space Y. Thus, to get a child Z in the Y space, you shall X.getFellow('Y').getFellow('Z').

  Example: Assumes component A is a child of B, B a child of C and C a child of D. If only C implements `IdSpace`, A, B and C are all belonged to the C space. D doesn't belong any space.

  If both C and D implements `IdSpace`, C and D belongs to the D space while A, B and C belongs to the C space.

  Note: to make a component (deriving from `AbstractComponent`) an ID space owner, all it needs to do is to implement this interface.

  Author:
    tomyeh

- - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `Component` | `getFellow​(java.lang.String id)` | Returns a component of the specified ID in this ID space.
    `Component` | `getFellow​(java.lang.String id, boolean recurse)` | Returns a component of the specified ID in this ID space.
    `Component` | `getFellowIfAny​(java.lang.String id)` | Returns a component of the specified ID in this ID space, or null if not found.
    `Component` | `getFellowIfAny​(java.lang.String id, boolean recurse)` | Returns a component of the specified ID in this ID space, or null if not found.
    `java.util.Collection<Component>` | `getFellows()` | Returns all fellows in this ID space.
    `boolean` | `hasFellow​(java.lang.String id)` | Returns whether there is a fellow named with the specified component ID.
    `boolean` | `hasFellow​(java.lang.String id, boolean recurse)` | Returns whether there is a fellow named with the specified component ID.

    - ### Methods inherited from interface org.zkoss.zk.ui.ext.Scope

      `addScopeListener, getAttribute, getAttribute, getAttributes, hasAttribute, hasAttribute, removeAttribute, removeAttribute, removeScopeListener, setAttribute, setAttribute`

- - ### Method Detail

    - #### getFellow

          Component getFellow​(java.lang.String id)
                       throws ComponentNotFoundException

      Returns a component of the specified ID in this ID space. Components in the same ID space are called fellows.

      Unlike `getFellowIfAny(String)`, it throws `ComponentNotFoundException` if not found.

      Throws:
        `ComponentNotFoundException` - is thrown if this component doesn't belong to any ID space

    - #### getFellow

          Component getFellow​(java.lang.String id,
                              boolean recurse)
                       throws ComponentNotFoundException

      Returns a component of the specified ID in this ID space.

      Unlike `getFellowIfAny(String, boolean)`, it throws `ComponentNotFoundException` if not found.

      Parameters:
        `recurse` - whether to look up the parent ID space for the existence of the fellow
      Throws:
        `ComponentNotFoundException` - is thrown if this component doesn't belong to any ID space
      Since:
        5.0.0

    - #### getFellowIfAny

          Component getFellowIfAny​(java.lang.String id)

      Returns a component of the specified ID in this ID space, or null if not found.

      Unlike `getFellow(String)`, it returns null if not found.

    - #### getFellowIfAny

          Component getFellowIfAny​(java.lang.String id,
                                   boolean recurse)

      Returns a component of the specified ID in this ID space, or null if not found.

      Unlike `getFellow(String, boolean)`, it returns null if not found.

      Parameters:
        `recurse` - whether to look up the parent ID space for the existence of the fellow
      Since:
        5.0.0

    - #### getFellows

          java.util.Collection<Component> getFellows()

      Returns all fellows in this ID space. The returned collection is readonly.
      Since:
        3.0.6

    - #### hasFellow

          boolean hasFellow​(java.lang.String id)

      Returns whether there is a fellow named with the specified component ID.
      Since:
        3.5.2

    - #### hasFellow

          boolean hasFellow​(java.lang.String id,
                            boolean recurse)

      Returns whether there is a fellow named with the specified component ID.
      Parameters:
        `recurse` - whether to look up the parent ID space for the existence of the fellow
      Since:
        5.0.0