001/* 002 * Licensed to the Apache Software Foundation (ASF) under one or more 003 * contributor license agreements. See the NOTICE file distributed with 004 * this work for additional information regarding copyright ownership. 005 * The ASF licenses this file to You under the Apache License, Version 2.0 006 * (the "License"); you may not use this file except in compliance with 007 * the License. You may obtain a copy of the License at 008 * 009 * http://www.apache.org/licenses/LICENSE-2.0 010 * 011 * Unless required by applicable law or agreed to in writing, software 012 * distributed under the License is distributed on an "AS IS" BASIS, 013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 014 * See the License for the specific language governing permissions and 015 * limitations under the License. 016 */ 017package org.apache.commons.configuration2.io; 018 019import java.io.File; 020import java.net.URL; 021 022import org.apache.commons.lang3.StringUtils; 023 024/** 025 * <p> 026 * A specialized implementation of {@code FileLocationStrategy} which searches for files in the user's home directory or 027 * another special configurable directory. 028 * </p> 029 * <p> 030 * This strategy implementation ignores the URL stored in the passed in {@link FileLocator}. It constructs a file path 031 * from the configured home directory (which is the user's home directory per default, but can be changed to another 032 * path), optionally the base path, and the file name. If the resulting path points to an existing file, its URL is 033 * returned. 034 * </p> 035 * <p> 036 * When constructing an instance it can be configured whether the base path should be taken into account. If this option 037 * is set, the base path is appended to the home directory if it is not <b>null</b>. This is useful for instance to 038 * select a specific sub directory of the user's home directory. If this option is set to <b>false</b>, the base path is 039 * always ignored, and only the file name is evaluated. 040 * </p> 041 */ 042public class HomeDirectoryLocationStrategy implements FileLocationStrategy { 043 /** Constant for the system property with the user's home directory. */ 044 private static final String PROP_HOME = "user.home"; 045 046 /** The home directory to be searched for the requested file. */ 047 private final String homeDirectory; 048 049 /** The flag whether the base path is to be taken into account. */ 050 private final boolean evaluateBasePath; 051 052 /** 053 * Creates a new instance of {@code HomeDirectoryLocationStrategy} and initializes it with the specified settings. 054 * 055 * @param homeDir the path to the home directory (can be <b>null</b>) 056 * @param withBasePath a flag whether the base path should be evaluated 057 */ 058 public HomeDirectoryLocationStrategy(final String homeDir, final boolean withBasePath) { 059 homeDirectory = fetchHomeDirectory(homeDir); 060 evaluateBasePath = withBasePath; 061 } 062 063 /** 064 * Creates a new instance of {@code HomeDirectoryLocationStrategy} and initializes the base path flag. The home 065 * directory is set to the user's home directory. 066 * 067 * @param withBasePath a flag whether the base path should be evaluated 068 */ 069 public HomeDirectoryLocationStrategy(final boolean withBasePath) { 070 this(null, withBasePath); 071 } 072 073 /** 074 * Creates a new instance of {@code HomeDirectoryLocationStrategy} with default settings. The home directory is set to 075 * the user's home directory. The base path flag is set to <b>false</b> (which means that the base path is ignored). 076 */ 077 public HomeDirectoryLocationStrategy() { 078 this(false); 079 } 080 081 /** 082 * Gets the home directory. In this directory the strategy searches for files. 083 * 084 * @return the home directory used by this object 085 */ 086 public String getHomeDirectory() { 087 return homeDirectory; 088 } 089 090 /** 091 * Returns a flag whether the base path is to be taken into account when searching for a file. 092 * 093 * @return the flag whether the base path is evaluated 094 */ 095 public boolean isEvaluateBasePath() { 096 return evaluateBasePath; 097 } 098 099 /** 100 * {@inheritDoc} This implementation searches in the home directory for a file described by the passed in 101 * {@code FileLocator}. If the locator defines a base path and the {@code evaluateBasePath} property is <b>true</b>, a 102 * sub directory of the home directory is searched. 103 */ 104 @Override 105 public URL locate(final FileSystem fileSystem, final FileLocator locator) { 106 if (StringUtils.isNotEmpty(locator.getFileName())) { 107 final String basePath = fetchBasePath(locator); 108 final File file = FileLocatorUtils.constructFile(basePath, locator.getFileName()); 109 if (file.isFile()) { 110 return FileLocatorUtils.convertFileToURL(file); 111 } 112 } 113 114 return null; 115 } 116 117 /** 118 * Determines the base path to be used for the current locate() operation. 119 * 120 * @param locator the {@code FileLocator} 121 * @return the base path to be used 122 */ 123 private String fetchBasePath(final FileLocator locator) { 124 if (isEvaluateBasePath() && StringUtils.isNotEmpty(locator.getBasePath())) { 125 return FileLocatorUtils.appendPath(getHomeDirectory(), locator.getBasePath()); 126 } 127 return getHomeDirectory(); 128 } 129 130 /** 131 * Obtains the home directory to be used by a new instance. If a directory name is provided, it is used. Otherwise, the 132 * user's home directory is looked up. 133 * 134 * @param homeDir the passed in home directory 135 * @return the directory to be used 136 */ 137 private static String fetchHomeDirectory(final String homeDir) { 138 return homeDir != null ? homeDir : System.getProperty(PROP_HOME); 139 } 140}