1 /* 2 * Licensed to the Apache Software Foundation (ASF) under one or more 3 * contributor license agreements. See the NOTICE file distributed with 4 * this work for additional information regarding copyright ownership. 5 * The ASF licenses this file to You under the Apache License, Version 2.0 6 * (the "License"); you may not use this file except in compliance with 7 * the License. You may obtain a copy of the License at 8 * 9 * http://www.apache.org/licenses/LICENSE-2.0 10 * 11 * Unless required by applicable law or agreed to in writing, software 12 * distributed under the License is distributed on an "AS IS" BASIS, 13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14 * See the License for the specific language governing permissions and 15 * limitations under the License. 16 */ 17 package org.apache.commons.io.filefilter; 18 19 import java.io.File; 20 import java.io.Serializable; 21 import java.nio.file.FileVisitResult; 22 import java.nio.file.Files; 23 import java.nio.file.Path; 24 import java.nio.file.attribute.BasicFileAttributes; 25 26 /** 27 * This filter accepts {@link File}s that are symbolic links. 28 * <p> 29 * For example, here is how to print out a list of the real files 30 * within the current directory: 31 * </p> 32 * <h2>Using Classic IO</h2> 33 * <pre> 34 * File dir = FileUtils.current(); 35 * String[] files = dir.list(SymbolicLinkFileFilter.INSTANCE); 36 * for (String file : files) { 37 * System.out.println(file); 38 * } 39 * </pre> 40 * 41 * <h2>Using NIO</h2> 42 * <pre> 43 * final Path dir = PathUtils.current(); 44 * final AccumulatorPathVisitor visitor = AccumulatorPathVisitor.withLongCounters(SymbolicLinkFileFilter.INSTANCE); 45 * // 46 * // Walk one dir 47 * Files.<b>walkFileTree</b>(dir, Collections.emptySet(), 1, visitor); 48 * System.out.println(visitor.getPathCounters()); 49 * System.out.println(visitor.getFileList()); 50 * // 51 * visitor.getPathCounters().reset(); 52 * // 53 * // Walk dir tree 54 * Files.<b>walkFileTree</b>(dir, visitor); 55 * System.out.println(visitor.getPathCounters()); 56 * System.out.println(visitor.getDirList()); 57 * System.out.println(visitor.getFileList()); 58 * </pre> 59 * <h2>Deprecating Serialization</h2> 60 * <p> 61 * <em>Serialization is deprecated and will be removed in 3.0.</em> 62 * </p> 63 * 64 * @since 2.11.0 65 * @see FileFilterUtils#fileFileFilter() 66 */ 67 public class SymbolicLinkFileFilter extends AbstractFileFilter implements Serializable { 68 /* 69 * Note to developers: The unit test needs to create symbolic links to files. However, on 70 * Windows, this can't be done without admin privileges. This class is designed to allow a 71 * unit test to works around this by doing two things: 1) This separates the class logic from 72 * the call to identify a symbolic link, and 2) It allows the unit test to override that 73 * symbolic link call on Windows only. 74 * This means we can write unit tests that will run on all machines. On Windows, the unit test 75 * can't create a symbolic link without admin privileges, so the unit tests won't 76 * completely test all the necessary behavior on Windows, but they will still test the class 77 * logic. Be careful not to break this, but be aware of it when writing unit tests. You can 78 * still maintain this class and its unit tests on Windows. The one method that won't get 79 * tested on Windows is not likely to change, and will be tested properly when it gets run 80 * on Apache servers. 81 */ 82 83 /** 84 * Singleton instance of file filter. 85 */ 86 public static final SymbolicLinkFileFilter INSTANCE = new SymbolicLinkFileFilter(); 87 88 private static final long serialVersionUID = 1L; 89 90 /** 91 * Restrictive constructor. 92 */ 93 protected SymbolicLinkFileFilter() { 94 } 95 96 /** 97 * Constructs a new instance. 98 * 99 * @param onAccept What to do on acceptance. 100 * @param onReject What to do on rejection. 101 * @since 2.12.0. 102 */ 103 public SymbolicLinkFileFilter(final FileVisitResult onAccept, final FileVisitResult onReject) { 104 super(onAccept, onReject); 105 } 106 107 /** 108 * Checks to see if the file is a symbolic link. 109 * 110 * @param file the File to check 111 * @return true if the file exists and is a symbolic link to either another file or a directory, 112 * false otherwise. 113 */ 114 @Override 115 public boolean accept(final File file) { 116 return isSymbolicLink(file.toPath()); 117 } 118 119 /** 120 * Checks to see if the file is a symbolic link. 121 * 122 * @param path the File Path to check 123 * @return {@code onAccept} from {@link #SymbolicLinkFileFilter(FileVisitResult, FileVisitResult)} if the file exists and is a symbolic link to either 124 * another file or a directory; returns {@code onReject} otherwise. 125 */ 126 @Override 127 public FileVisitResult accept(final Path path, final BasicFileAttributes attributes) { 128 return toFileVisitResult(isSymbolicLink(path)); 129 } 130 131 /** 132 * Delegates to {@link Files#isSymbolicLink(Path)} for testing. 133 * <p> 134 * Using package access for unit tests. To facilitate unit testing, all calls to test if the file is a symbolic should go through this method. (See the unit 135 * test for why.) 136 * </p> 137 * 138 * @param filePath The filePath to test 139 * @return true if the file exists and is a symbolic link to either a file or directory, false otherwise. 140 */ 141 boolean isSymbolicLink(final Path filePath) { 142 return Files.isSymbolicLink(filePath); 143 } 144 }