View Javadoc

1   /*
2    * Licensed to the Apache Software Foundation (ASF) under one
3    * or more contributor license agreements.  See the NOTICE file
4    * distributed with this work for additional information
5    * regarding copyright ownership.  The ASF licenses this file
6    * to you under the Apache License, Version 2.0 (the
7    * "License"); you may not use this file except in compliance
8    * with the License.  You may obtain a copy of the License at
9    *
10   *   http://www.apache.org/licenses/LICENSE-2.0
11   *
12   * Unless required by applicable law or agreed to in writing,
13   * software distributed under the License is distributed on an
14   * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
15   * KIND, either express or implied.  See the License for the
16   * specific language governing permissions and limitations
17   * under the License.
18   */
19  package org.apache.myfaces.trinidad.skin;
20  
21  import java.util.List;
22  import java.util.Map;
23  import java.util.MissingResourceException;
24  
25  import org.apache.myfaces.trinidad.context.LocaleContext;
26  import org.apache.myfaces.trinidad.context.RenderingContext;
27  
28  /**
29   * Defines the components (icons, styles, etc)
30   * which are used to implement a particular skin.
31   *
32   * @see SkinProvider
33   *
34   * @version $Name:  $ ($Revision: adfrt/faces/adf-faces-impl/src/main/java/oracle/adfinternal/view/faces/skin/Skin.java#0 $) $Date: 10-nov-2005.18:58:54 $
35   */
36  abstract public class Skin
37  {
38    /**
39     * Returns an string identifier which uniquely identies
40     * this Skin implementation.  Skin implementations
41     * can be retrieved by id via SkinFactory.getSkin().
42     * @see org.apache.myfaces.trinidad.skin.SkinFactory#getSkin
43     */
44    abstract public String getId();
45  
46    /**
47     * Returns the name of the skin "family" for this skin.
48     * The family name is used when specifying a preferred skin
49     * in trinidad-config.xml.
50     * This provides a way to refer to a group of
51     * related skin implementations while allowing the
52     * particular skin instance to be selected based on the
53     * current render-kit-id.
54     */
55    abstract public String getFamily();
56    
57  
58    /**
59     * Returns the (@link SkinVersion} instance of the "version" for this skin.
60     * When a Skin instance is created, a SkinVersion instance can be a part of it.
61     * In trinidad-skins.xml this is the version element. In the trinidad-config.xml, 
62     * the application developer can set the skin-version to a skin version, or to 'default'.
63     * This returns SkinVersion.EMPTY_SKIN_VERSION if no version is set.
64     */
65    public SkinVersion getVersion()
66    {
67      return SkinVersion.EMPTY_SKIN_VERSION;
68    }
69  
70    /**
71     * Returns the renderKitId for the Skin.
72     */
73    abstract public String getRenderKitId();
74    
75    /**
76     * Returns the id of the Skin's stylesheet document.
77     */
78    abstract public String getStyleSheetDocumentId(RenderingContext arc);
79  
80    /**
81     * Returns the style class map, or null if there is no map.
82     * It should be a map that contains the full style class name as 
83     * the key, and the value could be a shortened style class name,
84     * or a portlet style class name, etc.
85     */
86    abstract public Map<String, String> getStyleClassMap(RenderingContext arc);
87  
88    /**
89     * Returns the name of the style sheet for this Skin.
90     */
91    abstract public String getStyleSheetName();
92  
93    /**
94     * Gets the rendering features specified for the skin.
95     * @return a collection containing all features enabled for the skin
96     */
97    public Map<String, String> getSkinFeatures()
98    {
99      return null;
100   }
101   
102 
103   /**
104    * Returns a translated String in the LocaleContext's translation Locale.
105    */
106   abstract public String getTranslatedString(
107     LocaleContext lContext,
108     String        key
109     ) throws MissingResourceException;
110 
111   /**
112    * Returns a translated value in the LocaleContext's translation Locale.
113    * This value may or may not be a String, and developers should avoid
114    * calling toString() unless absolutely necessary.
115    * @param lContext The LocaleContext which provides the translation Locale.
116    *                 Cannot be null.
117    * @param key The key of the translation to retrieve. Cannot be null.
118    * @throws NullPointerException if lContext or key is null.
119    */
120   abstract public Object getTranslatedValue(
121     LocaleContext lContext,
122     String        key
123     ) throws MissingResourceException;
124 
125   /**
126    * Our renderers call this to get the icon. This returns a renderable
127    * icon. (ReferenceIcons are resolved -- the real icon they point to is
128    * returned)
129    */
130   abstract public Icon getIcon(String  iconName);
131 
132   /**
133    * Returns an Icon object; can be a ReferenceIcon.
134    * @param iconName  The name of the icon to retrieve. Cannot be null
135    * @throws NullPointerException if iconName is null.
136    */
137   abstract public Icon getIcon(
138     String  iconName,
139     boolean resolveIcon);
140 
141   /**
142    * Retrieves a property that was set via a call to setProperty().
143    * Some Renderer implementations may store properties on the
144    * Skin instance to avoid having to re-compute Skin-specific
145    * values on each render.
146    */
147   abstract public Object getProperty(Object key);
148 
149   /**
150    * Sets a value for the specified property key.
151    * Some Renderer implementations may store properties on the
152    * Skin instance to avoid having to re-compute Skin-specific
153    * values on each render.
154    */
155   abstract public void setProperty(
156     Object key,
157     Object value);
158 
159   /**
160    * Registers an Icon for the specified icon name.
161    * @param iconName  The name of the icon. Cannot be null.
162    * @param icon      The Icon to register.
163    * @throws NullPointerException if iconName is null.
164    */
165   abstract public void registerIcon(
166     String  iconName,
167     Icon    icon);
168 
169   /**
170    * Registers a style sheet which defines extension-specific
171    * styles.  The styles specified by this style sheet will be
172    * merged with the Skin's own styles.
173    * @param styleSheetName The name of the style sheet which
174    *          defines the extension's styles.
175    * @throws NullPointerException if styleSheetName is null.
176    * @deprecated Use addSkinAddition(SkinAddition) instead.
177    * @see #addSkinAddition(SkinAddition)
178    */
179   @Deprecated
180   abstract public void registerStyleSheet(
181     String styleSheetName
182     );
183     
184   /**
185    * Adds a SkinAddition on this Skin. You can call this method as many times 
186    * as you like for the Skin, and it will add the SkinAddition to the list of 
187    * SkinAdditions.
188    * However, it does not make sense to call this method more than once
189    * with the same SkinAddition object.
190    * This is meant for the skin-addition use-cases, where a custom component 
191    * developer has a style sheet and/or resource bundle for their custom   
192    * components, and they want the style sheet and/or resource bundle 
193    * to work for this Skin and the children Skins.
194    * The stylesheets specified in the SkinAdditions will be merged with the 
195    * Skin's own styles.
196    * The resource bundles specified in the SkinAdditions will be looked into 
197    * if the translated key is not found in the Skin's own resource bundle 
198    * during the call to getTranslatedString or getTranslatedValue.
199    * 
200    * @param skinAddition The SkinAddition object to add to the Skin.
201    * @throws NullPointerException if SkinAddition is null.
202    */
203   abstract public void addSkinAddition (
204     SkinAddition skinAddition
205     );
206     
207   /**
208    * Gets a List of SkinAdditions that have been added on this Skin.
209    * @return List a List of SkinAdditions.
210    */
211   abstract public List<SkinAddition> getSkinAdditions ();
212 
213   /**
214    * Check to see if this Skin has been marked dirty.
215    * The only way to mark a Skin dirty is to call setDirty(true).
216    * @return true if the Skin is marked dirty.
217    * @deprecated use isDirty(boolean checkAncestorSkins) instead.
218    */
219   @Deprecated
220   abstract public boolean isDirty();
221 
222   /**
223    * Check to see if this Skin is dirty with an optional check if any of its ancestor skins is dirty
224    * The only way to mark a Skin dirty is to call setDirty(true).
225    * @param checkAncestors, option to check if any ancestor skins are dirty
226    * @return true if the Skin is dirty, or optionally if any of its ancestor skin is dirty.
227    */
228   public boolean isDirty(boolean checkAncestors)
229   {
230     return isDirty();
231   }
232 
233   /**
234    * Sets the dirty flag of the Skin. Use this if you want to regenerate the skin.
235    * During rendering, if isDirty is true,
236    * the skin's css file will be reprocessed regardless of whether the css file has been modified
237    * or if the CHECK_FILE_MODIFICATION flag was set. 
238    * The Skinning Framework calls setDirty(false) after the skin has been reprocessed.
239    */
240   abstract public void setDirty(boolean dirty);
241 
242   /**
243    * Returns the base Skin which this custom Skin
244    * "extends".
245    * Returns null if there is no base skin.
246    */
247   public Skin getBaseSkin()
248   {
249     return null;
250   }
251 }