javax.faces.lifecycle

## Class ClientWindow

- java.lang.Object
- - javax.faces.lifecycle.ClientWindow

- Direct Known Subclasses:
    ClientWindowWrapper

      public abstract class ClientWindow
      extends Object

  This class represents a client window, which may be a browser tab, browser window, browser pop-up, portlet, or anything else that can display a `UIComponent` hierarchy rooted at a `UIViewRoot`.

  Modes of Operation

  none mode

  The generation of `ClientWindow` is controlled by the value of the `context-param` named by the value of `CLIENT_WINDOW_MODE_PARAM_NAME`. If this `context-param` is not specified, or its value is "none", no `ClientWindow` instances will be generated, and the entire feature is effectively disabled for the entire application.

  Other modes

  To accomadate the widest possible range of implementation choices to support this feature, explicit names for modes other than "none" and "url" are not specified. However, for all values of `CLIENT_WINDOW_MODE_PARAM_NAME`, the lifetime of a `ClientWindow` starts on the first request made by a particular client window (or tab, or pop-up, etc) to the JSF runtime and persists as long as that window remains open or the session expires, whichever comes first. A client window is always associated with exactly one `UIViewRoot` instance at a time, but may display many different `UIViewRoot`s during its lifetime.

  The `ClientWindow` instance is associated with the incoming request during the `Lifecycle.attachWindow(javax.faces.context.FacesContext)` method. This method will cause a new instance of `ClientWindow` to be created, assigned an id, and passed to `ExternalContext.setClientWindow(javax.faces.lifecycle.ClientWindow)`.

  During state saving, regardless of the window id mode, or state saving mode, for ajax and non-ajax requests, a hidden field must be written whose name, id and value are given as specified in `ResponseStateManager.CLIENT_WINDOW_PARAM`.

  In addition to the hidden field already described. The runtime must ensure that any component that renders a hyperlink that causes the user agent to send a GET request to the Faces server when it is clicked has a query parameter with a name and value specified in `ResponseStateManager.CLIENT_WINDOW_URL_PARAM`. This requirement is met by several of the "encode" methods on `ExternalContext`. See `ExternalContext.encodeActionURL(java.lang.String)` for details.

  Since:
    2.2

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static String` | `CLIENT_WINDOW_MODE_PARAM_NAME` The context-param that controls the operation of the `ClientWindow` feature.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `ClientWindow()`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `abstract void` | `decode(FacesContext context)` The implementation is responsible for examining the incoming request and extracting the value that must be returned from the `getId()` method.
    `void` | `disableClientWindowRenderMode(FacesContext context)` Components that permit per-use disabling of the appending of the ClientWindow in generated URLs must call this method first before rendering those URLs.
    `void` | `enableClientWindowRenderMode(FacesContext context)` Components that permit per-use disabling of the appending of the ClientWindow in generated URLs must call this method first after rendering those URLs.
    `abstract String` | `getId()` Return a String value that uniquely identifies this `ClientWindow` within the scope of the current session.
    `abstract Map<String,String>` | `getQueryURLParameters(FacesContext context)` This method will be called whenever a URL is generated by the runtime where client window related parameters need to be inserted into the URL.
    `boolean` | `isClientWindowRenderModeEnabled(FacesContext context)` Methods that append the ClientWindow to generated URLs must call this method to see if they are permitted to do so.

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

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

- - ### Field Detail

    - #### CLIENT_WINDOW_MODE_PARAM_NAME

          public static final String CLIENT_WINDOW_MODE_PARAM_NAME

      The context-param that controls the operation of the `ClientWindow` feature. The runtime must support the values "none" and "url", without the quotes, but other values are possible. If not specified, or the value is not understood by the implementation, "none" is assumed.

      Since:
        2.2
      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### ClientWindow

          public ClientWindow()

  - ### Method Detail

    - #### getQueryURLParameters

          public abstract Map<String,String> getQueryURLParameters(FacesContext context)

      This method will be called whenever a URL is generated by the runtime where client window related parameters need to be inserted into the URL. This guarantees custom `ClientWindow` implementations that they will have the opportunity to insert any additional client window specific information in any case where a URL is generated, such as the rendering of hyperlinks. The returned map must be immutable. The default implementation of this method returns the empty map.

      Parameters:
        `context` - the `FacesContext` for this request.
      Returns:
        `null` or a map of parameters to insert into the URL query string.
      Since:
        2.2

    - #### getId

          public abstract String getId()

      Return a String value that uniquely identifies this `ClientWindow` within the scope of the current session. See `decode(javax.faces.context.FacesContext)` for the specification of how to derive this value.

      Since:
        2.2

    - #### decode

          public abstract void decode(FacesContext context)

      The implementation is responsible for examining the incoming request and extracting the value that must be returned from the `getId()` method. If `CLIENT_WINDOW_MODE_PARAM_NAME` is "none" this method must not be invoked. If `CLIENT_WINDOW_MODE_PARAM_NAME` is "url" the implementation must first look for a request parameter under the name given by the value of `ResponseStateManager.CLIENT_WINDOW_PARAM`. If no value is found, look for a request parameter under the name given by the value of `ResponseStateManager.CLIENT_WINDOW_URL_PARAM`. If no value is found, fabricate an id that uniquely identifies this `ClientWindow` within the scope of the current session. This value must be made available to return from the `getId()` method. The value must be suitable for inclusion as a hidden field or query parameter. If a value is found, decrypt it using the key from the session and make it available for return from `getId()`.

      Parameters:
        `context` - the `FacesContext` for this request.
      Since:
        2.2

    - #### disableClientWindowRenderMode

          public void disableClientWindowRenderMode(FacesContext context)

      Components that permit per-use disabling of the appending of the ClientWindow in generated URLs must call this method first before rendering those URLs. The caller must call `enableClientWindowRenderMode(javax.faces.context.FacesContext)` from a `finally` block after rendering the URL. If `CLIENT_WINDOW_MODE_PARAM_NAME` is "url" without the quotes, all generated URLs that cause a GET request must append the ClientWindow by default. This is specified as a static method because callsites need to access it without having access to an actual `ClientWindow` instance.

      Parameters:
        `context` - the `FacesContext` for this request.
      Since:
        2.2

    - #### enableClientWindowRenderMode

          public void enableClientWindowRenderMode(FacesContext context)

      Components that permit per-use disabling of the appending of the ClientWindow in generated URLs must call this method first after rendering those URLs. If `CLIENT_WINDOW_MODE_PARAM_NAME` is "url" without the quotes, all generated URLs that cause a GET request must append the ClientWindow by default. This is specified as a static method because callsites need to access it without having access to an actual `ClientWindow` instance.

      Parameters:
        `context` - the `FacesContext` for this request.
      Since:
        2.2

    - #### isClientWindowRenderModeEnabled

          public boolean isClientWindowRenderModeEnabled(FacesContext context)

      Methods that append the ClientWindow to generated URLs must call this method to see if they are permitted to do so. If `CLIENT_WINDOW_MODE_PARAM_NAME` is "url" without the quotes, all generated URLs that cause a GET request must append the ClientWindow by default. This is specified as a static method because callsites need to access it without having access to an actual `ClientWindow` instance.

      Parameters:
        `context` - the `FacesContext` for this request.
      Since:
        2.2

Copyright © 1996-2013, Oracle and/or its affiliates. All Rights Reserved. Use is subject to license terms.