1 /*
2 * Copyright 2006-2016 The JGUIraffe Team.
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License")
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16 package net.sf.jguiraffe.locators;
17
18 import java.io.File;
19 import java.net.URL;
20
21 /**
22 * <p>
23 * A concrete <code>Locator</code> class that represents files.
24 * </p>
25 * <p>
26 * Instances of this class can be initialized with either a <code>File</code>
27 * object or with the name of a file. Based on this data the locator methods are
28 * implemented in an appropriate way.
29 * </p>
30 * <p>
31 * Note that this class does not check whether the passed in file exists. So if
32 * an input stream is to be obtained for this file, it is possible that a file
33 * not found exception gets thrown.
34 * </p>
35 * <p>
36 * Instances of this class are created using the <code>getInstance()</code>
37 * factory methods. They are immutable and thus can be shared between multiple
38 * threads.
39 * </p>
40 *
41 * @author Oliver Heger
42 * @version $Id: FileLocator.java 205 2012-01-29 18:29:57Z oheger $
43 */
44 public final class FileLocator extends AbstractLocator
45 {
46 /** Stores the represented file object. */
47 private final File file;
48
49 /**
50 * Creates a new instance of <code>FileLocator</code> and initializes it
51 * with the represented file. For creating an instance clients have to call
52 * the <code>getInstance()</code> factory methods.
53 *
54 * @param file the file
55 */
56 private FileLocator(File file)
57 {
58 this.file = file;
59 }
60
61 /**
62 * Returns a <code>FileLocator</code> instance for the specified file.
63 *
64 * @param file the file (must not be <b>null</b>)
65 * @return the <code>FileLocator</code> instance for this file
66 * @throws IllegalArgumentException if the file is <b>null</b>
67 */
68 public static FileLocator getInstance(File file)
69 {
70 if (file == null)
71 {
72 throw new IllegalArgumentException("File must not be null!");
73 }
74
75 return new FileLocator(file);
76 }
77
78 /**
79 * Returns a <code>FileLocator</code> instance for the specified file name.
80 *
81 * @param fileName the file name (must not be <b>null</b>)
82 * @return the <code>FileLocator</code> instance for this file
83 * @throws IllegalArgumentException if the file name is <b>null</b>
84 */
85 public static FileLocator getInstance(String fileName)
86 {
87 if (fileName == null)
88 {
89 throw new IllegalArgumentException("File name must not be null!");
90 }
91
92 return new FileLocator(new File(fileName));
93 }
94
95 /**
96 * Returns the URL for the represented file.
97 *
98 * @return the URL
99 * @throws LocatorException if an error occurs
100 */
101 public URL getURL()
102 {
103 return LocatorUtils.fileURL(getFile());
104 }
105
106 /**
107 * Returns the represented file resource.
108 *
109 * @return the file
110 */
111 @Override
112 public File getFile()
113 {
114 return file;
115 }
116
117 /**
118 * Returns the name of the represented file. This is an absolute file path.
119 *
120 * @return the file name
121 */
122 public String getFileName()
123 {
124 return getFile().getAbsolutePath();
125 }
126
127 /**
128 * Compares this object with another one. Two instances of this class are
129 * considered equal if and only if they point to the same file.
130 *
131 * @param obj the object to compare to
132 * @return a flag whether the objects are equal
133 */
134 @Override
135 public boolean equals(Object obj)
136 {
137 if (this == obj)
138 {
139 return true;
140 }
141 if (!(obj instanceof FileLocator))
142 {
143 return false;
144 }
145
146 FileLocator c = (FileLocator) obj;
147 return getFile().equals(c.getFile());
148 }
149
150 /**
151 * Returns a hash code for this object.
152 *
153 * @return a hash code
154 */
155 @Override
156 public int hashCode()
157 {
158 return getFile().hashCode();
159 }
160
161 /**
162 * Returns a string representation for this object. This string will at
163 * least contain the path to the file as returned by
164 * <code>getFileName()</code>.
165 *
166 * @return a string for this object
167 */
168 @Override
169 public String toString()
170 {
171 return LocatorUtils.locatorToString(this, "file = " + getFileName());
172 }
173 }