001: /*
002: * uDig - User Friendly Desktop Internet GIS client
003: * http://udig.refractions.net
004: * (C) 2004, Refractions Research Inc.
005: *
006: * This library is free software; you can redistribute it and/or
007: * modify it under the terms of the GNU Lesser General Public
008: * License as published by the Free Software Foundation;
009: * version 2.1 of the License.
010: *
011: * This library is distributed in the hope that it will be useful,
012: * but WITHOUT ANY WARRANTY; without even the implied warranty of
013: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
014: * Lesser General Public License for more details.
015: *
016: */
017: package net.refractions.udig.core.internal;
018:
019: // J2SE dependencies
020: import java.io.BufferedReader;
021: import java.io.File;
022: import java.io.FileNotFoundException;
023: import java.io.IOException;
024: import java.io.InputStreamReader;
025: import java.net.URL;
026: import java.net.URLDecoder;
027:
028: /**
029: * Utility methods for dealing with class data, included with jar.
030: * <p>
031: * Data should be located in a folder with a dash in the name, similar to the javadoc "doc-files"
032: * convention. This ensures that data directories don't look anything like normal java packages.
033: * </p>
034: * <p>
035: * Example:
036: *
037: * <pre><code>
038: * class MyClass {
039: * public ImageDescriptor example() {
040: * return ImageDescriptor.create(TestData.url(this, "test-data/test.png")).getImage();
041: * }
042: * }
043: * </code></pre>
044: *
045: * Where:
046: * <ul>
047: * <li>MyClass.java
048: * <li>
049: * <li>test-data/test.png</li>
050: * </ul>
051: * </ul>
052: * </p>
053: * <p>
054: * By convention you should try and locate data near the class that uses it.
055: * </p>
056: *
057: * @see TestData
058: * @author Jody Garnett
059: * @since 0.7.0
060: */
061: public class Data {
062: /**
063: * Provided a {@link BufferedReader} for named test data. It is the caller responsability to
064: * close this reader after usage.
065: *
066: * @param caller The class of the object associated with named data.
067: * @param name of test data to load.
068: * @return The reader, or <code>null</code> if the named test data are not found.
069: * @throws IOException if an error occurs during an input operation.
070: */
071: public static final BufferedReader reader(final Class caller,
072: final String name) throws IOException {
073: final URL url = url(caller, name);
074: if (url == null) {
075: return null; // echo handling of getResource( ... )
076: }
077: return new BufferedReader(new InputStreamReader(url
078: .openStream()));
079: }
080:
081: /**
082: * Provided a {@link BufferedReader} for named test data. It is the caller responsability to
083: * close this reader after usage.
084: *
085: * @param host Object associated with named data
086: * @param name of test data to load
087: * @return The reader, or <code>null</code> if the named test data are not found.
088: * @throws IOException if an error occurs during an input operation.
089: */
090: public static final BufferedReader reader(final Object host,
091: final String name) throws IOException {
092: return reader(host.getClass(), name);
093: }
094:
095: /**
096: * Locate named test-data resource for caller.
097: *
098: * @param caller Class used to locate test-data.
099: * @param name name of test-data.
100: * @return URL or null of named test-data could not be found.
101: * @todo Should this be getURL() - or simply url? I tend to save getX method for accessors.
102: */
103: public static final URL url(final Class caller, String name) {
104: return caller.getResource(name);
105: }
106:
107: /**
108: * Locate named test-data resource for caller.
109: *
110: * @param caller Object used to locate test-data
111: * @param name name of test-data
112: * @return URL or null of named test-data could not be found
113: * @todo Should this be getURL() - or simply url? I tend to save getX method for accessors.
114: */
115: public static final URL url(final Object caller, final String name) {
116: return url(caller.getClass(), name);
117: }
118:
119: /**
120: * Access to <code>url(caller, path)</code> as a {@link File}.
121: * <p>
122: *
123: * <pre><code>
124: * Data.file(this, null)
125: * </code></pre>
126: *
127: * </p>
128: *
129: * @param caller Calling object used to locate data
130: * @param path Path to file in testdata
131: * @return File
132: * @throws IOException if the file is not found.
133: */
134: public static final File file(final Object caller, final String path)
135: throws IOException {
136: final URL url = url(caller, path);
137: if (url != null) {
138: // Based SVGTest
139: final File file = new File(URLDecoder.decode(url.getFile(),
140: "UTF-8")); //$NON-NLS-1$
141: if (file.exists()) {
142: return file;
143: }
144: }
145: throw new FileNotFoundException("Could not locate:" + path); //$NON-NLS-1$
146: }
147:
148: /**
149: * Access to <code>url(caller, path)</code> as a {@link File}.
150: * <p>
151: *
152: * <pre><code>
153: * Data.file(this, null)
154: * </code></pre>
155: *
156: * </p>
157: *
158: * @param caller Calling class used to locate data
159: * @param path Path to file in testdata
160: * @return File
161: * @throws IOException if the file is not found.
162: */
163: public static final File file(Class caller, final String path)
164: throws IOException {
165: final URL url = url(caller, path);
166: if (url != null) {
167: // Based SVGTest
168: final File file = new File(URLDecoder.decode(url.getFile(),
169: "UTF-8")); //$NON-NLS-1$
170: if (file.exists()) {
171: return file;
172: }
173: }
174: throw new FileNotFoundException("Could not locate:" + path); //$NON-NLS-1$
175: }
176:
177: /**
178: * Creates a temporary file with the given name.
179: *
180: * @param caller
181: * @param name
182: * @return File if available for name
183: * @throws IOException
184: */
185: public static final File temp(final Object caller, final String name)
186: throws IOException {
187: File testData = file(caller, null);
188: int split = name.lastIndexOf('.');
189: String prefix = split == -1 ? name : name.substring(0, split);
190: String suffix = split == -1 ? null : name.substring(split + 1);
191: File tmp = File.createTempFile(prefix, suffix, testData);
192: tmp.deleteOnExit();
193: return tmp;
194: }
195: }
|