You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@myfaces.apache.org by de...@apache.org on 2017/09/17 12:30:09 UTC

[myfaces-trinidad] 28/30: Checkpoint: ripped out redundant class doc now that all of this is doc'ed in the dev guide.

This is an automated email from the ASF dual-hosted git repository.

deki pushed a commit to branch andys-skin-pregen
in repository https://gitbox.apache.org/repos/asf/myfaces-trinidad.git

commit 211f713cbe6b8e043bada3cfa0d3dea2c8f1305b
Author: Andy Schwartz <an...@apache.org>
AuthorDate: Wed Mar 21 01:18:05 2012 +0000

    Checkpoint: ripped out redundant class doc now that all of this is doc'ed in the dev guide.
---
 .../skin/pregen/SkinPregenerationService.java      | 68 +--------------
 .../style/util/StableNameUtils.java                | 96 +---------------------
 2 files changed, 4 insertions(+), 160 deletions(-)

diff --git a/trinidad-impl/src/main/java/org/apache/myfaces/trinidadinternal/skin/pregen/SkinPregenerationService.java b/trinidad-impl/src/main/java/org/apache/myfaces/trinidadinternal/skin/pregen/SkinPregenerationService.java
index 4dca116..366f7d3 100644
--- a/trinidad-impl/src/main/java/org/apache/myfaces/trinidadinternal/skin/pregen/SkinPregenerationService.java
+++ b/trinidad-impl/src/main/java/org/apache/myfaces/trinidadinternal/skin/pregen/SkinPregenerationService.java
@@ -41,72 +41,8 @@ import org.apache.myfaces.trinidadinternal.skin.pregen.config.PregenConfig;
 /**
  * InternalView implementation that provides skin pregeneration service.
  *
- * Skin pregeneration is enabled by specifying the following system
- * property:
- *
- *  -Dorg.apache.myfaces.trinidad.SKIN_PREGENERATION_SERVICE=on
- *
- * When enabled, a request to the "-pregenerate-skins" view id can be
- * used to force pregeneration for specific skins.  Each request must
- * specifiy a single "id" query parameter.  The value of this query parameter
- * must be an id of one of the skins registered with trinidad (eg. via
- * an "id" element in a trinidad-skins.xml file).
- *
- * For example, in an application that uses prefix mapping for the FacesServlet,
- * enabling the skin pregeneration service exposes the following uri:
- *
- *   - /context root/faces/-pregenerate-skins?id=minimal.desktop
- *
- * Which triggers pregeneration of style sheets for the minimal.desktop skin
- * when hit.
- * 
- * By default, only style sheets for common variant values are generated.
- * In particular:
- * 
- * - plaform: android | iphone | linux | macos | windows
- * - agent: ie | gecko | webkit
- * - locale: default (unmatched) locale
- * - reading direction: ltr
- * - accessibility: standard contrast, medium fonts
- *
- * The "variants" request parameter can be used to force generation of all
- * possible variants, eg:
- * 
- *    - "/context root/faces/-pregenerate-skins?id=minimal.desktop?variants=all
- *    
- * The following optional request parameters may also be used to provide contextual
- * information about how the pregeneration should be performed:
- *
- * - containerType: servlet | portlet. (Defaults to "servlet".)
- * - requestType: nonsecure | secure.  (Defaults to "nonsecure".)
- * - styleClassType: compressed | uncompressed.  (Defaults to "compressed".)
- *
- * All of the contextual request parameters support multiple values.  For example,
- * the following request:
- * 
- *  /-pregenerate-skins?id=minimal.desktop&styleClassType=compressed&styleClassType=uncompressed
- *  
- * Pregenerates both servlet and portlet style sheets for the common variants of the the
- * minimal.desktop skin.
- *
- * By default, pregenerated style sheets are written into the web application's
- * style sheet cache directory (typically, tmpdir/adf/styles/cache).  However,
- * a target directory for the pregenerated output can be specified via the
- * following system property:
- * 
- * -Dorg.apache.myfaces.trinidad.SKIN_PREGENERATION_SERVICE_TARGET_DIRECTORY=directory path
- * 
- * 
- * Requests that result in successful skin pregeneration result in status 200
- * responses.  Failed requests (eg. for invalid skin ids) result in non-200
- * status codes.
- * 
- * For security purposes, pregeneration must never be enabled in end user facing,
- * production deployments - ie. skin pregeneration is CPU and I/O intensive, and
- * must not be exposed to arbitrary users.  To avoid the potential for abuse,
- * enabling skin pregeneration has the side effect of disabling the rest of the
- * application.  As such, applications that are enabled for skin pregeneration 
- * can only be used for this single purpose.
+ * See the "Pre-generating Skin Style Sheets" section in the Skinning chapter
+ * of the Trinidad Developer's Guide for the specification of this service.
  */
 public class SkinPregenerationService extends InternalView
 { 
diff --git a/trinidad-impl/src/main/java/org/apache/myfaces/trinidadinternal/style/util/StableNameUtils.java b/trinidad-impl/src/main/java/org/apache/myfaces/trinidadinternal/style/util/StableNameUtils.java
index 4d6ab57..39667ab 100644
--- a/trinidad-impl/src/main/java/org/apache/myfaces/trinidadinternal/style/util/StableNameUtils.java
+++ b/trinidad-impl/src/main/java/org/apache/myfaces/trinidadinternal/style/util/StableNameUtils.java
@@ -47,100 +47,8 @@ import org.apache.myfaces.trinidadinternal.util.nls.LocaleUtils;
  * that produces "stable" file names.  This ensures that generated style sheets will be
  * named in a consistent manner that is not dependent on the order in which requests arrives.
  * 
- * With NameUtils.getContextName(), a skin that contains the following locale-specific
- * definition:
- * 
- * @locale ja, cz, ko { ... }
- * 
- * May share a generated .css file across Japanese, Chinese and Korean end users.  The name
- * of this generated style sheet depends on which locale is specified when the style sheet is
- * first generated.  For example, if the style sheet is generated in response from a request
- * for a Korean-locale user, the file name will include the "ko" locale token.  This file
- * will then be shared by Japanese, Chinese and Korean end users.  However, if the server is
- * subsequently bounced and the first post-bounce request is from a Japanese end user, the file
- * will be re-generated with the "ja" token.
- * 
- * As a result of this behavior, file names are not predictable across runs.  The lack of
- * stable file names makes it difficult/impossible to support use cases where we want to
- * share generated style sheets across applications - eg. by pregenerating style sheets
- * and deploying them to some common server (or a CDN).
- * 
- * StableNameUtils.getContextName() solves this problem by producing names for generated
- * style sheet files that are not dependent on request ordering.
- * 
- * The file names produced by StableNameUtils.getContextName() are broken up into three
- * major sections:
- * 
- * 1. The skin identifier.
- * 2. Variant identifiers (eg. agent, locale, etc...)
- * 3. Contextual identifiers (eg. portlet vs. servlet)
- * 
- * These major sections are separated by double dashes ("--").
- * 
- * Within each major section, minor subsections appear in a predictable order, separated
- * by single dashs ("-").
- * 
- * The skin identifier section (section #1) contains the following subsections:
- * 
- *   <id>-<hash>
- *   
- * Where:
- * 
- * - id: the skin id.  Note that the skin id itself may include dash characters
- *     (eg. "simple-desktop").
- * - hash: a hash of the skin contents
- * 
- * The variant identifiers section (section #2) contains the following subsections:
- * 
- *   <platform>-<agent>-<version>-<locale>-<direction>-<accessibility>
- * 
- * Where:
- * 
- * - platform: the platform name (eg. linux, windows, iphone)
- * - agent: the agent name (eg. ie, gecko, safari)
- * - version: the agent version (eg. 7, 1.9.2, 534)
- * - locale: the locale (eg. en, en_US, ja).
- * - direction: the reading direction (ltr|rtl)
- * - accessibility: accessibility profile preferences (hc|lf|hclf for high contrast|
- *     large fonts|high contrast + large fonts).
- *     
- * In the event that no @-rule variant is expicitly matched, only default styles
- * (ie. styles that apply to all requests) are included in the generated style sheet.
- * The token "d" is used to identify this case.  For example, if the skin does not
- * define any @locale rules, the locale portion of the file name will be "d".
- * 
- * In some cases it is not possible to determine a unique value
- * for a particular variant, because only @-rules that specify multiple values
- * are matched.  In this case, a combination of the matched values will be used
- * for the segment.  For example, if the
- * skin defines a single @locale rule matching the ja, cz, and ko locales, the 
- * locale portion of the file name for generated style sheets corresponding to these
- * locales will be "ca_ja_ko".
- * 
- * The contextual identifiers section (section #3) contains the following subsections:
- * 
- * - container type: identifies whether the application is hosted within a servlet or
- *     portlet (s|p).
- * - request type: identifies whether the style sheet is used for a secure or non-secure
- *     request (s|n).
- * - style class type: identifies whether the style sheet is generated with compressed or
- *     uncompressed style classes (c|u).
- * 
- * In case where skins are pregenerated and shared across applications, it may be necessary
- * to write regular expressions against the above format in order to rewrite style sheet
- * uris to point to some other host.  When doing so, the following recommendations should
- * be observed:
- * 
- * - The identifier section contains a variable number of subsection separators: skin
- *   ids may contain dashes.  As such, when writing regular expressions that target items
- *   in the subsequent major sections, it is best to anchor these regular expressions
- *   to the major section separators (double-dash).
- *   
- * - In the future it is possible that new subsections may need to be added to the
- *   variant or contextual identifier sections.  If the need for additional
- *   information arises, new subsections will be added at the end of the appropriate
- *   major section.  As such, regular expressions should be written in a way that they
- *   can tolerate new subsections later appearing at the end of each major section.
+ * See the "Structure of Stable Style Sheet Names" section in the Skinning chapter of the
+ * Trinidad Developer's Guide for the specification of stable style sheet names.
  */
 public final class StableNameUtils
 {

-- 
To stop receiving notification emails like this one, please contact
"commits@myfaces.apache.org" <co...@myfaces.apache.org>.