1 package org.apache.turbine.services.ui; 2 3 /* 4 * Licensed to the Apache Software Foundation (ASF) under one 5 * or more contributor license agreements. See the NOTICE file 6 * distributed with this work for additional information 7 * regarding copyright ownership. The ASF licenses this file 8 * to you under the Apache License, Version 2.0 (the 9 * "License"); you may not use this file except in compliance 10 * with the License. You may obtain a copy of the License at 11 * 12 * http://www.apache.org/licenses/LICENSE-2.0 13 * 14 * Unless required by applicable law or agreed to in writing, 15 * software distributed under the License is distributed on an 16 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 17 * KIND, either express or implied. See the License for the 18 * specific language governing permissions and limitations 19 * under the License. 20 */ 21 22 import java.io.File; 23 import java.io.InputStream; 24 import java.util.Properties; 25 import java.util.concurrent.ConcurrentHashMap; 26 27 import org.apache.commons.configuration.Configuration; 28 import org.apache.commons.io.IOUtils; 29 import org.apache.commons.io.filefilter.DirectoryFileFilter; 30 import org.apache.commons.lang.StringUtils; 31 import org.apache.commons.logging.Log; 32 import org.apache.commons.logging.LogFactory; 33 import org.apache.turbine.Turbine; 34 import org.apache.turbine.services.InitializationException; 35 import org.apache.turbine.services.TurbineBaseService; 36 import org.apache.turbine.services.TurbineServices; 37 import org.apache.turbine.services.pull.PullService; 38 import org.apache.turbine.services.pull.tools.UITool; 39 import org.apache.turbine.services.servlet.ServletService; 40 import org.apache.turbine.util.ServerData; 41 import org.apache.turbine.util.uri.DataURI; 42 43 /** 44 * The UI service provides for shared access to User Interface (skin) files, 45 * as well as the ability for non-default skin files to inherit properties from 46 * a default skin. Use TurbineUI to access skin properties from your screen 47 * classes and action code. UITool is provided as a pull tool for accessing 48 * skin properties from your templates. 49 * 50 * @author <a href="mailto:jvanzyl@periapt.com">Jason van Zyl</a> 51 * @author <a href="mailto:james_coltman@majorband.co.uk">James Coltman</a> 52 * @author <a href="mailto:hps@intermeta.de">Henning P. Schmiedehausen</a> 53 * @author <a href="mailto:seade@backstagetech.com.au">Scott Eade</a> 54 * @author <a href="thomas.vandahl@tewisoft.de">Thomas Vandahl</a> 55 * @version $Id$ 56 * @see UIService 57 * @see UITool 58 */ 59 public class TurbineUIService 60 extends TurbineBaseService 61 implements UIService 62 { 63 /** Logging. */ 64 private static Log log = LogFactory.getLog(TurbineUIService.class); 65 66 /** 67 * The location of the skins within the application resources directory. 68 */ 69 private static final String SKINS_DIRECTORY = "/ui/skins"; 70 71 /** 72 * The name of the directory where images are stored for this skin. 73 */ 74 private static final String IMAGES_DIRECTORY = "/images"; 75 76 /** 77 * Property tag for the default skin that is to be used for the web 78 * application. 79 */ 80 private static final String SKIN_PROPERTY = "tool.ui.skin"; 81 82 /** 83 * Property tag for the image directory inside the skin that is to be used 84 * for the web application. 85 */ 86 private static final String IMAGEDIR_PROPERTY = "tool.ui.dir.image"; 87 88 /** 89 * Property tag for the skin directory that is to be used for the web 90 * application. 91 */ 92 private static final String SKINDIR_PROPERTY = "tool.ui.dir.skin"; 93 94 /** 95 * Property tag for the css file that is to be used for the web application. 96 */ 97 private static final String CSS_PROPERTY = "tool.ui.css"; 98 99 /** 100 * Property tag for indicating if relative links are wanted for the web 101 * application. 102 */ 103 private static final String RELATIVE_PROPERTY = "tool.ui.want.relative"; 104 105 /** 106 * Default skin name. This name refers to a directory in the 107 * WEBAPP/resources/ui/skins directory. There is a file called skin.props 108 * which contains the name/value pairs to be made available via the skin. 109 */ 110 public static final String SKIN_PROPERTY_DEFAULT = "default"; 111 112 /** 113 * The skins directory, qualified by the resources directory (which is 114 * relative to the webapp context). This is used for constructing URIs and 115 * for retrieving skin files. 116 */ 117 private String skinsDirectory; 118 119 /** 120 * The file within the skin directory that contains the name/value pairs for 121 * the skin. 122 */ 123 private static final String SKIN_PROPS_FILE = "skin.props"; 124 125 /** 126 * The file name for the skin style sheet. 127 */ 128 private static final String DEFAULT_SKIN_CSS_FILE = "skin.css"; 129 130 /** 131 * The servlet service. 132 */ 133 private ServletService servletService; 134 135 /** 136 * The directory within the skin directory that contains the skin images. 137 */ 138 private String imagesDirectory; 139 140 /** 141 * The name of the css file within the skin directory. 142 */ 143 private String cssFile; 144 145 /** 146 * The flag that determines if the links that are returned are are absolute 147 * or relative. 148 */ 149 private boolean wantRelative = false; 150 151 /** 152 * The skin Properties store. 153 */ 154 private ConcurrentHashMap<String, Properties> skins = new ConcurrentHashMap<String, Properties>(); 155 156 /** 157 * Refresh the service by clearing all skins. 158 */ 159 @Override 160 public void refresh() 161 { 162 clearSkins(); 163 } 164 165 /** 166 * Refresh a particular skin by clearing it. 167 * 168 * @param skinName the name of the skin to clear. 169 */ 170 @Override 171 public void refresh(String skinName) 172 { 173 clearSkin(skinName); 174 } 175 176 /** 177 * Retrieve the Properties for a specific skin. If they are not yet loaded 178 * they will be. If the specified skin does not exist properties for the 179 * default skin configured for the webapp will be returned and an error 180 * level message will be written to the log. If the webapp skin does not 181 * exist the default skin will be used and id that doesn't exist an empty 182 * Properties will be returned. 183 * 184 * @param skinName the name of the skin whose properties are to be 185 * retrieved. 186 * @return the Properties for the named skin or the properties for the 187 * default skin configured for the webapp if the named skin does not exist. 188 */ 189 private Properties getSkinProperties(String skinName) 190 { 191 Properties skinProperties = skins.get(skinName); 192 return null != skinProperties ? skinProperties : loadSkin(skinName); 193 } 194 195 /** 196 * Retrieve a skin property from the named skin. If the property is not 197 * defined in the named skin the value for the default skin will be 198 * provided. If the named skin does not exist then the skin configured for 199 * the webapp will be used. If the webapp skin does not exist the default 200 * skin will be used. If the default skin does not exist then 201 * <code>null</code> will be returned. 202 * 203 * @param skinName the name of the skin to retrieve the property from. 204 * @param key the key to retrieve from the skin. 205 * @return the value of the property for the named skin (defaulting to the 206 * default skin), the webapp skin, the default skin or <code>null</code>, 207 * depending on whether or not the property or skins exist. 208 */ 209 @Override 210 public String get(String skinName, String key) 211 { 212 Properties skinProperties = getSkinProperties(skinName); 213 return skinProperties.getProperty(key); 214 } 215 216 /** 217 * Retrieve a skin property from the default skin for the webapp. If the 218 * property is not defined in the webapp skin the value for the default skin 219 * will be provided. If the webapp skin does not exist the default skin 220 * will be used. If the default skin does not exist then <code>null</code> 221 * will be returned. 222 * 223 * @param key the key to retrieve. 224 * @return the value of the property for the webapp skin (defaulting to the 225 * default skin), the default skin or <code>null</code>, depending on 226 * whether or not the property or skins exist. 227 */ 228 @Override 229 public String get(String key) 230 { 231 return get(getWebappSkinName(), key); 232 } 233 234 /** 235 * Provide access to the list of available skin names. 236 * 237 * @return the available skin names. 238 */ 239 @Override 240 public String[] getSkinNames() 241 { 242 File skinsDir = new File(servletService.getRealPath(skinsDirectory)); 243 return skinsDir.list(DirectoryFileFilter.INSTANCE); 244 } 245 246 /** 247 * Clear the map of stored skins. 248 */ 249 private void clearSkins() 250 { 251 skins.clear(); 252 log.debug("All skins were cleared."); 253 } 254 255 /** 256 * Clear a particular skin from the map of stored skins. 257 * 258 * @param skinName the name of the skin to clear. 259 */ 260 private void clearSkin(String skinName) 261 { 262 if (!skinName.equals(SKIN_PROPERTY_DEFAULT)) 263 { 264 skins.remove(SKIN_PROPERTY_DEFAULT); 265 } 266 skins.remove(skinName); 267 log.debug("The skin \"" + skinName 268 + "\" was cleared (will also clear \"default\" skin)."); 269 } 270 271 /** 272 * Load the specified skin. 273 * 274 * @param skinName the name of the skin to load. 275 * @return the Properties for the named skin if it exists, or the skin 276 * configured for the web application if it does not exist, or the default 277 * skin if that does not exist, or an empty Parameters object if even that 278 * cannot be found. 279 */ 280 private Properties loadSkin(String skinName) 281 { 282 Properties defaultSkinProperties = null; 283 284 if (!StringUtils.equals(skinName, SKIN_PROPERTY_DEFAULT)) 285 { 286 defaultSkinProperties = getSkinProperties(SKIN_PROPERTY_DEFAULT); 287 } 288 289 // The following line is okay even for default. 290 Properties skinProperties = new Properties(defaultSkinProperties); 291 292 StringBuilder sb = new StringBuilder(); 293 sb.append('/').append(skinsDirectory); 294 sb.append('/').append(skinName); 295 sb.append('/').append(SKIN_PROPS_FILE); 296 if (log.isDebugEnabled()) 297 { 298 log.debug("Loading selected skin from: " + sb.toString()); 299 } 300 301 InputStream is = null; 302 303 try 304 { 305 // This will NPE if the directory associated with the skin does not 306 // exist, but it is handled correctly below. 307 is = servletService.getResourceAsStream(sb.toString()); 308 skinProperties.load(is); 309 } 310 catch (Exception e) 311 { 312 log.error("Cannot load skin: " + skinName + ", from: " 313 + sb.toString(), e); 314 if (!StringUtils.equals(skinName, getWebappSkinName()) 315 && !StringUtils.equals(skinName, SKIN_PROPERTY_DEFAULT)) 316 { 317 log.error("Attempting to return the skin configured for " 318 + "webapp instead of " + skinName); 319 return getSkinProperties(getWebappSkinName()); 320 } 321 else if (!StringUtils.equals(skinName, SKIN_PROPERTY_DEFAULT)) 322 { 323 log.error("Return the default skin instead of " + skinName); 324 return skinProperties; // Already contains the default skin. 325 } 326 else 327 { 328 log.error("No skins available - returning an empty Properties"); 329 return new Properties(); 330 } 331 } 332 finally 333 { 334 IOUtils.closeQuietly(is); 335 } 336 337 // Replace in skins HashMap 338 skins.put(skinName, skinProperties); 339 340 return skinProperties; 341 } 342 343 /** 344 * Get the name of the default skin name for the web application from the 345 * TurbineResources.properties file. If the property is not present the 346 * name of the default skin will be returned. Note that the web application 347 * skin name may be something other than default, in which case its 348 * properties will default to the skin with the name "default". 349 * 350 * @return the name of the default skin for the web application. 351 */ 352 @Override 353 public String getWebappSkinName() 354 { 355 return Turbine.getConfiguration() 356 .getString(SKIN_PROPERTY, SKIN_PROPERTY_DEFAULT); 357 } 358 359 /** 360 * Retrieve the URL for an image that is part of a skin. The images are 361 * stored in the WEBAPP/resources/ui/skins/[SKIN]/images directory. 362 * 363 * <p>Use this if for some reason your server name, server scheme, or server 364 * port change on a per request basis. I'm not sure if this would happen in 365 * a load balanced situation. I think in most cases the image(String image) 366 * method would probably be enough, but I'm not absolutely positive. 367 * 368 * @param skinName the name of the skin to retrieve the image from. 369 * @param imageId the id of the image whose URL will be generated. 370 * @param serverData the serverData to use as the basis for the URL. 371 */ 372 @Override 373 public String image(String skinName, String imageId, ServerData serverData) 374 { 375 return getSkinResource(serverData, skinName, imagesDirectory, imageId); 376 } 377 378 /** 379 * Retrieve the URL for an image that is part of a skin. The images are 380 * stored in the WEBAPP/resources/ui/skins/[SKIN]/images directory. 381 * 382 * @param skinName the name of the skin to retrieve the image from. 383 * @param imageId the id of the image whose URL will be generated. 384 */ 385 @Override 386 public String image(String skinName, String imageId) 387 { 388 return image(skinName, imageId, Turbine.getDefaultServerData()); 389 } 390 391 /** 392 * Retrieve the URL for the style sheet that is part of a skin. The style is 393 * stored in the WEBAPP/resources/ui/skins/[SKIN] directory with the 394 * filename skin.css 395 * 396 * <p>Use this if for some reason your server name, server scheme, or server 397 * port change on a per request basis. I'm not sure if this would happen in 398 * a load balanced situation. I think in most cases the style() method would 399 * probably be enough, but I'm not absolutely positive. 400 * 401 * @param skinName the name of the skin to retrieve the style sheet from. 402 * @param serverData the serverData to use as the basis for the URL. 403 */ 404 @Override 405 public String getStylecss(String skinName, ServerData serverData) 406 { 407 return getSkinResource(serverData, skinName, null, cssFile); 408 } 409 410 /** 411 * Retrieve the URL for the style sheet that is part of a skin. The style is 412 * stored in the WEBAPP/resources/ui/skins/[SKIN] directory with the 413 * filename skin.css 414 * 415 * @param skinName the name of the skin to retrieve the style sheet from. 416 */ 417 @Override 418 public String getStylecss(String skinName) 419 { 420 return getStylecss(skinName, Turbine.getDefaultServerData()); 421 } 422 423 /** 424 * Retrieve the URL for a given script that is part of a skin. The script is 425 * stored in the WEBAPP/resources/ui/skins/[SKIN] directory. 426 * 427 * <p>Use this if for some reason your server name, server scheme, or server 428 * port change on a per request basis. I'm not sure if this would happen in 429 * a load balanced situation. I think in most cases the style() method would 430 * probably be enough, but I'm not absolutely positive. 431 * 432 * @param skinName the name of the skin to retrieve the image from. 433 * @param filename the name of the script file. 434 * @param serverData the serverData to use as the basis for the URL. 435 */ 436 @Override 437 public String getScript(String skinName, String filename, 438 ServerData serverData) 439 { 440 return getSkinResource(serverData, skinName, null, filename); 441 } 442 443 /** 444 * Retrieve the URL for a given script that is part of a skin. The script is 445 * stored in the WEBAPP/resources/ui/skins/[SKIN] directory. 446 * 447 * @param skinName the name of the skin to retrieve the image from. 448 * @param filename the name of the script file. 449 */ 450 @Override 451 public String getScript(String skinName, String filename) 452 { 453 return getScript(skinName, filename, Turbine.getDefaultServerData()); 454 } 455 456 private String stripSlashes(final String path) 457 { 458 if (StringUtils.isEmpty(path)) 459 { 460 return ""; 461 } 462 463 String ret = path; 464 int len = ret.length() - 1; 465 466 if (ret.charAt(len) == '/') 467 { 468 ret = ret.substring(0, len); 469 } 470 471 if (len > 0 && ret.charAt(0) == '/') 472 { 473 ret = ret.substring(1); 474 } 475 476 return ret; 477 } 478 479 /** 480 * Construct the URL to the skin resource. 481 * 482 * @param serverData the serverData to use as the basis for the URL. 483 * @param skinName the name of the skin. 484 * @param subDir the sub-directory in which the resource resides or 485 * <code>null</code> if it is in the root directory of the skin. 486 * @param resourceName the name of the resource to be retrieved. 487 * @return the path to the resource. 488 */ 489 private String getSkinResource(ServerData serverData, String skinName, 490 String subDir, String resourceName) 491 { 492 StringBuilder sb = new StringBuilder(skinsDirectory); 493 sb.append("/").append(skinName); 494 if (subDir != null) 495 { 496 sb.append("/").append(subDir); 497 } 498 sb.append("/").append(stripSlashes(resourceName)); 499 500 DataURI du = new DataURI(serverData); 501 du.setScriptName(sb.toString()); 502 return wantRelative ? du.getRelativeLink() : du.getAbsoluteLink(); 503 } 504 505 // ---- Service initilization ------------------------------------------ 506 507 /** 508 * Initializes the service. 509 */ 510 @Override 511 public void init() throws InitializationException 512 { 513 Configuration cfg = Turbine.getConfiguration(); 514 515 servletService = (ServletService)TurbineServices.getInstance().getService(ServletService.SERVICE_NAME); 516 PullService pullService = (PullService)TurbineServices.getInstance().getService(PullService.SERVICE_NAME); 517 // Get the resources directory that is specified in the TR.props or 518 // default to "resources", relative to the webapp. 519 StringBuilder sb = new StringBuilder(); 520 sb.append(stripSlashes(pullService.getResourcesDirectory())); 521 sb.append("/"); 522 sb.append(stripSlashes( 523 cfg.getString(SKINDIR_PROPERTY, SKINS_DIRECTORY))); 524 skinsDirectory = sb.toString(); 525 526 imagesDirectory = stripSlashes( 527 cfg.getString(IMAGEDIR_PROPERTY, IMAGES_DIRECTORY)); 528 cssFile = cfg.getString(CSS_PROPERTY, DEFAULT_SKIN_CSS_FILE); 529 wantRelative = cfg.getBoolean(RELATIVE_PROPERTY, false); 530 531 setInit(true); 532 } 533 534 /** 535 * Returns to uninitialized state. 536 */ 537 @Override 538 public void shutdown() 539 { 540 clearSkins(); 541 setInit(false); 542 } 543 }