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.io.IOException;
20 import java.io.InputStream;
21 import java.net.URL;
22
23 /**
24 * <p>
25 * Definition of the base <code>Locator</code> interface.
26 * </p>
27 * <p>
28 * A <em>Locator</em> is an object that points to a resource to be loaded by
29 * an application. There are many ways how such a resource can be specified,
30 * including
31 * <ul>
32 * <li>plain strings representing file paths or URLs</li>
33 * <li><code>File</code> objects</li>
34 * <li><code>URL</code> objects</li>
35 * </ul>
36 * and lots of more.
37 * </p>
38 * <p>
39 * Typically to be fully compatible with all kinds of clients and to be
40 * convenient to use a service class that needs to load resources has to deal
41 * with all these various ways. As an implementor of such services classes you
42 * find yourself often writing similar code for converting <code>File</code>s
43 * to <code>URL</code>s, strings to both or vice versa.
44 * </p>
45 * <p>
46 * To make the handling of resources easier the <code>Locator</code> interface
47 * was introduced. A <em>Locator</em> provides an abstract view on a resource
48 * specification. Concrete implementations will deal with specific ways of
49 * describing resources, e.g. as URLs or files or loaded from the class path. So
50 * a service class need not deal with conversion between the different formats
51 * any longer, but just queries the provided locator.
52 * </p>
53 * <p>
54 * The <code>Locator</code> interface defines some methods for returning a
55 * pointer to the represented resource, but the only method that must be
56 * implemented is the <code>getURL()</code> method. So URLs are the native
57 * format. If a stream to the represented resource is to be opened, this task
58 * should be delegated to the <code>{@link LocatorUtils}</code> class, which
59 * contains static utility methods for exactly this purpose. These methods will
60 * test, which of the locator's methods return defined values and then use those
61 * to open the stream.
62 * </p>
63 *
64 * @author Oliver Heger
65 * @version $Id: Locator.java 205 2012-01-29 18:29:57Z oheger $
66 */
67 public interface Locator
68 {
69 /**
70 * Returns a URL to the resource represented by this locator. This method
71 * must return a non <b>null</b> value.
72 *
73 * @return a URL for the represented resource
74 * @throws LocatorException if an internal error occurs while determining
75 * the URL
76 */
77 URL getURL();
78
79 /**
80 * Returns a file for the resource represented by this locator. This is an
81 * optional method that can return <b>null</b> if a file makes no sense for
82 * the represented resource.
83 *
84 * @return a <code>File</code> object for the represented resource
85 * @throws LocatorException if an internal error occurs
86 */
87 File getFile();
88
89 /**
90 * Returns an input stream for the represented resource. This method is
91 * called first when a stream to the locator is to be obtained. It is an
92 * optional method that can return <b>null</b>. In this case the
93 * <code>getFile()</code> and, last but not least, the
94 * <code>getURL()</code> methods will be tried.
95 *
96 * @return an input stream to the represented resource
97 * @throws LocatorException if an internal error occurs
98 * @throws IOException if an IO error occurs when opening the stream
99 */
100 InputStream getInputStream() throws IOException;
101 }