org.apache.myfaces.trinidad.skin

## Class SkinProvider

- java.lang.Object
- - org.apache.myfaces.trinidad.skin.SkinProvider

-     public abstract class SkinProvider
      extends Object

  SkinProvider SPI is used to create, load, manage, and dispose skins. SkinProvider introduces lazy / on-demand loading of skins as opposed to eager loading done by SkinFactory. SkinProvider also introduces the flexibility to create and manage external skin repositories. Thus we have better manageability of Skins and clear separation of external skins and trinidad provided / supported skins.

  For each such skin repository externally maintained, the user should register their SkinProvider as an SPI. Classes implementing this abstraction should be listed in the jar's /META-INF/services folder inside of a text file named "org.apache.myfaces.trinidad.skin.SkinProvider". These services will then be run by trinidad skin framework and be used for all SkinProvider#getSkin or SkinProvider#getSkinMetadata calls.

  A SkinProvider implementation shall return a Skin object in response to SkinProvider#getSkin API call, if a Skin matching the skinMetadata requested is available in the particular implementation. The SkinProvider implementer can make use of SkinFactory#createSkin API to create a Skin object instead of implementing the abstract Skin APIs. For this, information about the new skin and its base skin has to be passed to SkinFactory#createSkin. See SkinFactory#createSkin documentation for details. SkinProvider#getSkin API implementation can decide to return a cached skin or a new skin object for subsequent request for the same Skin. It can also choose not to return a skin for a criteria which it served before (if the implementation finds that the Skin is now deleted or discontinued). Thus the SkinProvider implementation needs to manage the lifecycle of the Skin by creating, modifying and destroying it.

  If a Skin supported by the implementation is modified (by the Skin file change or any other change in Skin properties), the SkinProvider implementation needs to convey this to trinidad skinning framework so that the Skin can be reloaded. This can be done using Skin.setDirty() method. Calling this method sets the Skin as dirty and trinidad skinning framework will reload the skin and regenerate the css for the skin.

  SkinProvider implementation can optionally publish a list of supported skins by returning a Collection of SkinMetadata objects from SkinProvider#getSkinMetadata API. The collection can be built by the SkinProvider implementations beforehand. This also helps in publishing the information about the skins that it intends to support. See SkinMetadata documentation for details. SkinMetadata created for this method should be done without creating the actual Skin objects. Thus the implementation will support lazy loading of Skins.
  See Also:
    `SkinFactory`, `SkinMetadata`

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static String` | `SKIN_PROVIDER_INSTANCE_KEY` Key for the SkinProvider stored in ExternalContext

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `SkinProvider()`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `static SkinProvider` | `getCurrentInstance(javax.faces.context.ExternalContext externalContext)` static factory method to get hold of the current SkinProvider instance.
    `abstract Skin` | `getSkin(javax.faces.context.ExternalContext context, SkinMetadata skinMetadata)` Returns the Skin for the given skin metadata The returned skin is not cached by the framework and thus it is the responsibility of the provider to return the same instance of the skin should it desire so.
    `Collection<SkinMetadata>` | `getSkinMetadata(javax.faces.context.ExternalContext context)` A provider can optionally return information about some or all of the skins it provides.

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

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

- - ### Field Detail

    - #### SKIN_PROVIDER_INSTANCE_KEY

          public static final String SKIN_PROVIDER_INSTANCE_KEY

      Key for the SkinProvider stored in ExternalContext
      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### SkinProvider

          public SkinProvider()

  - ### Method Detail

    - #### getSkin

          public abstract Skin getSkin(javax.faces.context.ExternalContext context,
                     SkinMetadata skinMetadata)

      Returns the Skin for the given skin metadata

      The returned skin is not cached by the framework and thus it is the responsibility of the provider to return the same instance of the skin should it desire so.
      Parameters:
        `context` - valid ExternalContext
        `skinMetadata` - search criteria object containing the information of skin to be queried id, family, renderKit, version are the information used from skin metadata to perform search for the skin requested. Other fields do not participate in the search.
      Returns:
        Skin matching the search criteria

    - #### getSkinMetadata

          public Collection<SkinMetadata> getSkinMetadata(javax.faces.context.ExternalContext context)

      A provider can optionally return information about some or all of the skins it provides. Typically this information is generated without loading the skins as this is a quick way to find out about the Skins in the provider and also thereby supporting lazy loading of Skins. SkinMetadata for a Skin should contain only features and metadata that it explicitly supports. It should not contain the features and metadata that belongs only to its parent skins.
      Parameters:
        `context` - valid ExternalContext
      Returns:
        Collection of SkinMetadata representing the Skins supported by this SkinProvider

    - #### getCurrentInstance

          public static SkinProvider getCurrentInstance(javax.faces.context.ExternalContext externalContext)

      static factory method to get hold of the current SkinProvider instance. This can be used to get a SkinProvider to query for a skin or metadata
      Parameters:
        `externalContext` - valid ExternalContext
      Returns:
        SkinProvider instance

Copyright © 2001-2017 The Apache Software Foundation. All Rights Reserved.