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 }