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 SkinFactory
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     * Returns a translated String in the LocaleContext's translation Locale.
95     */
96    abstract public String getTranslatedString(
97      LocaleContext lContext,
98      String        key
99      ) throws MissingResourceException;
100 
101   /**
102    * Returns a translated value in the LocaleContext's translation Locale.
103    * This value may or may not be a String, and developers should avoid
104    * calling toString() unless absolutely necessary.
105    * @param lContext The LocaleContext which provides the translation Locale.
106    *                 Cannot be null.
107    * @param key The key of the translation to retrieve. Cannot be null.
108    * @throws NullPointerException if lContext or key is null.
109    */
110   abstract public Object getTranslatedValue(
111     LocaleContext lContext,
112     String        key
113     ) throws MissingResourceException;
114 
115   /**
116    * Our renderers call this to get the icon. This returns a renderable
117    * icon. (ReferenceIcons are resolved -- the real icon they point to is
118    * returned)
119    */
120   abstract public Icon getIcon(String  iconName);
121 
122   /**
123    * Returns an Icon object; can be a ReferenceIcon.
124    * @param iconName  The name of the icon to retrieve. Cannot be null
125    * @throws NullPointerException if iconName is null.
126    */
127   abstract public Icon getIcon(
128     String  iconName,
129     boolean resolveIcon);
130 
131   /**
132    * Retrieves a property that was set via a call to setProperty().
133    * Some Renderer implementations may store properties on the
134    * Skin instance to avoid having to re-compute Skin-specific
135    * values on each render.
136    */
137   abstract public Object getProperty(Object key);
138 
139   /**
140    * Sets a value for the specified property key.
141    * Some Renderer implementations may store properties on the
142    * Skin instance to avoid having to re-compute Skin-specific
143    * values on each render.
144    */
145   abstract public void setProperty(
146     Object key,
147     Object value);
148 
149   /**
150    * Registers an Icon for the specified icon name.
151    * @param iconName  The name of the icon. Cannot be null.
152    * @param icon      The Icon to register.
153    * @throws NullPointerException if iconName is null.
154    */
155   abstract public void registerIcon(
156     String  iconName,
157     Icon    icon);
158 
159   /**
160    * Registers a style sheet which defines extension-specific
161    * styles.  The styles specified by this style sheet will be
162    * merged with the Skin's own styles.
163    * @param styleSheetName The name of the style sheet which
164    *          defines the extension's styles.
165    * @throws NullPointerException if styleSheetName is null.
166    * @deprecated Use addSkinAddition(SkinAddition) instead.
167    * @see #addSkinAddition(SkinAddition)
168    */
169   @Deprecated
170   abstract public void registerStyleSheet(
171     String styleSheetName
172     );
173     
174   /**
175    * Adds a SkinAddition on this Skin. You can call this method as many times 
176    * as you like for the Skin, and it will add the SkinAddition to the list of 
177    * SkinAdditions.
178    * However, it does not make sense to call this method more than once
179    * with the same SkinAddition object.
180    * This is meant for the skin-addition use-cases, where a custom component 
181    * developer has a style sheet and/or resource bundle for their custom   
182    * components, and they want the style sheet and/or resource bundle 
183    * to work for this Skin and the children Skins.
184    * The stylesheets specified in the SkinAdditions will be merged with the 
185    * Skin's own styles.
186    * The resource bundles specified in the SkinAdditions will be looked into 
187    * if the translated key is not found in the Skin's own resource bundle 
188    * during the call to getTranslatedString or getTranslatedValue.
189    * 
190    * @param skinAddition The SkinAddition object to add to the Skin.
191    * @throws NullPointerException if SkinAddition is null.
192    */
193   abstract public void addSkinAddition (
194     SkinAddition skinAddition
195     );
196     
197   /**
198    * Gets a List of SkinAdditions that have been added on this Skin.
199    * @return List a List of SkinAdditions.
200    */
201   abstract public List<SkinAddition> getSkinAdditions ();
202   
203   /**
204    * Check to see if this Skin has been marked dirty. 
205    * The only way to mark a Skin dirty is to call setDirty(true).
206    * @return true if the Skin is marked dirty. 
207    */
208   abstract public boolean isDirty();
209 
210   /**
211    * Sets the dirty flag of the Skin. Use this if you want to regenerate the skin. 
212    * During rendering, if isDirty is true, 
213    * the skin's css file will be reprocessed regardless of whether the css file has been modified 
214    * or if the CHECK_FILE_MODIFICATION flag was set. 
215    * The Skinning Framework calls setDirty(false) after the skin has been reprocessed.
216    */
217   abstract public void setDirty(boolean dirty);
218   
219 }