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 * 042 */ 043public class HomeDirectoryLocationStrategy implements FileLocationStrategy { 044 /** Constant for the system property with the user's home directory. */ 045 private static final String PROP_HOME = "user.home"; 046 047 /** The home directory to be searched for the requested file. */ 048 private final String homeDirectory; 049 050 /** The flag whether the base path is to be taken into account. */ 051 private final boolean evaluateBasePath; 052 053 /** 054 * Creates a new instance of {@code HomeDirectoryLocationStrategy} and initializes it with the specified settings. 055 * 056 * @param homeDir the path to the home directory (can be <b>null</b>) 057 * @param withBasePath a flag whether the base path should be evaluated 058 */ 059 public HomeDirectoryLocationStrategy(final String homeDir, final boolean withBasePath) { 060 homeDirectory = fetchHomeDirectory(homeDir); 061 evaluateBasePath = withBasePath; 062 } 063 064 /** 065 * Creates a new instance of {@code HomeDirectoryLocationStrategy} and initializes the base path flag. The home 066 * directory is set to the user's home directory. 067 * 068 * @param withBasePath a flag whether the base path should be evaluated 069 */ 070 public HomeDirectoryLocationStrategy(final boolean withBasePath) { 071 this(null, withBasePath); 072 } 073 074 /** 075 * Creates a new instance of {@code HomeDirectoryLocationStrategy} with default settings. The home directory is set to 076 * the user's home directory. The base path flag is set to <b>false</b> (which means that the base path is ignored). 077 */ 078 public HomeDirectoryLocationStrategy() { 079 this(false); 080 } 081 082 /** 083 * Returns the home directory. In this directory the strategy searches for files. 084 * 085 * @return the home directory used by this object 086 */ 087 public String getHomeDirectory() { 088 return homeDirectory; 089 } 090 091 /** 092 * Returns a flag whether the base path is to be taken into account when searching for a file. 093 * 094 * @return the flag whether the base path is evaluated 095 */ 096 public boolean isEvaluateBasePath() { 097 return evaluateBasePath; 098 } 099 100 /** 101 * {@inheritDoc} This implementation searches in the home directory for a file described by the passed in 102 * {@code FileLocator}. If the locator defines a base path and the {@code evaluateBasePath} property is <b>true</b>, a 103 * sub directory of the home directory is searched. 104 */ 105 @Override 106 public URL locate(final FileSystem fileSystem, final FileLocator locator) { 107 if (StringUtils.isNotEmpty(locator.getFileName())) { 108 final String basePath = fetchBasePath(locator); 109 final File file = FileLocatorUtils.constructFile(basePath, locator.getFileName()); 110 if (file.isFile()) { 111 return FileLocatorUtils.convertFileToURL(file); 112 } 113 } 114 115 return null; 116 } 117 118 /** 119 * Determines the base path to be used for the current locate() operation. 120 * 121 * @param locator the {@code FileLocator} 122 * @return the base path to be used 123 */ 124 private String fetchBasePath(final FileLocator locator) { 125 if (isEvaluateBasePath() && StringUtils.isNotEmpty(locator.getBasePath())) { 126 return FileLocatorUtils.appendPath(getHomeDirectory(), locator.getBasePath()); 127 } 128 return getHomeDirectory(); 129 } 130 131 /** 132 * Obtains the home directory to be used by a new instance. If a directory name is provided, it is used. Otherwise, the 133 * user's home directory is looked up. 134 * 135 * @param homeDir the passed in home directory 136 * @return the directory to be used 137 */ 138 private static String fetchHomeDirectory(final String homeDir) { 139 return homeDir != null ? homeDir : System.getProperty(PROP_HOME); 140 } 141}