Package org.zkoss.zk.ui.ext

## Class Scopes

- java.lang.Object
- - org.zkoss.zk.ui.ext.Scopes

-     public class Scopes
      extends java.lang.Object

  Utilities to manage the current scope (`Scope`).

  Since 10.0.0, there two library properties to control the scope lock cache:

  1. org.zkoss.zk.ui.ext.Scopes.maxLockSize: the maximum number of locks to be cached. (Default: 10,000)
  2. org.zkoss.zk.ui.ext.Scopes.maxTimeout: the maximum time a lock can be cached in minutes after accessing it. (Default: 60 minutes)
  Since:
    5.0.0
  Author:
    tomyeh

- - ### Method Summary

    All Methods Static Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `static void` | `afterInterpret()` | Used with `beforeInterpret(org.zkoss.zk.ui.ext.Scope)` to clean up implicit variables.
    `static Scope` | `beforeInterpret​(Scope scope)` | Prepares implicit variable before calling `Page.interpret(java.lang.String, java.lang.String, org.zkoss.zk.ui.ext.Scope)`.
    `static Scope` | `getCurrent​(Page page)` | Returns the current scope.
    `static java.lang.Object` | `getImplicit​(java.lang.String name, java.lang.Object defValue)` | Returns the implicit object.
    `static java.lang.Object` | `getLockForScopeIfAny​(Scope scope)` | Returns a consistent lock for a given scope, if available.
    `static void` | `setImplicit​(java.lang.String name, java.lang.Object value)` | Sets an implicit object.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Method Detail

    - #### getLockForScopeIfAny

          public static java.lang.Object getLockForScopeIfAny​(Scope scope)

      Returns a consistent lock for a given scope, if available.

      The method returns a lock object specific to the provided scope, allowing for fine-grained synchronization control. If no lock is associated with the scope, the method returns a fallback lock instead.

      Usage of this method is preferred over manual synchronization or lock management, as it provides a standardized approach to handling concurrency in a scope-based context.

      Parameters:
        `scope` - The scope for which the lock is to be acquired.
      Returns:
        The lock object associated with the given scope, if any; otherwise, a static fallback lock.
      Since:
        10.0.0

    - #### beforeInterpret

          public static final Scope beforeInterpret​(Scope scope)

      Prepares implicit variable before calling `Page.interpret(java.lang.String, java.lang.String, org.zkoss.zk.ui.ext.Scope)`.

      Typical use:

                  final Scope scope = Scopes.beforeInterpret(comp);
                  try {
                  Scopes.setImplicit("some", value);
                  page.interpret(zslang, zscript, scope); //it will push scope as the current scope
                  } finally {
                  Scopes.afterInterpret();
                  }

      Another example:

                  Scopes.beforeInterpret(comp);
                  try {
                  constr.validate(comp); //if constr might be an instance of a class implemented in zscript
                  } finally {
                  Scopess.afterInterpret();
                  }

      If you need to set some implicit variables, you can invoke `setImplicit(java.lang.String, java.lang.Object)` between `beforeInterpret(org.zkoss.zk.ui.ext.Scope)` and `afterInterpret()`.

      Parameters:
        `scope` - the scope, never null.
      Returns:
        the scope used for interpretation. It is the same as the scope parameter if it is not null. Otherwise, a temporary scope is created.

    - #### afterInterpret

          public static final void afterInterpret()

      Used with `beforeInterpret(org.zkoss.zk.ui.ext.Scope)` to clean up implicit variables.

    - #### setImplicit

          public static void setImplicit​(java.lang.String name,
                                         java.lang.Object value)

      Sets an implicit object. It can be called only between `beforeInterpret(org.zkoss.zk.ui.ext.Scope)` and `afterInterpret()`.

    - #### getImplicit

          public static java.lang.Object getImplicit​(java.lang.String name,
                                                     java.lang.Object defValue)

      Returns the implicit object.

      It searches the implicit object stored with `setImplicit(java.lang.String, java.lang.Object)`, and also searches the system implicit objects by use of `Components.getImplicit(Page, Component, String)`.

      Parameters:
        `name` - the variable to retrieve
        `defValue` - the default vale that is used if the implicit object is not defined.

    - #### getCurrent

          public static final Scope getCurrent​(Page page)

      Returns the current scope. The current scope is the event target's scope if this thread is processing an event (`Event.getTarget()`. Otherwise, the scope of the page specified is assumed.

      This method is used only to implement `Interpreter`. You rarely need to access it other than implementing an interpreter.

      Parameters:
        `page` - the page. It is used if `beforeInterpret(org.zkoss.zk.ui.ext.Scope)` is not called before. If null, the current page (`ExecutionCtrl.getCurrentPage()` is assumed.