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.net.MalformedURLException;
19 import java.net.URL;
20
21 /**
22 * <p>
23 * A specialized {@link Locator} implementation that operates on URLs.
24 * </p>
25 * <p>
26 * This is a straight forward implementation of the <code>Locator</code>
27 * interface that is based on a URL. New instances can be created using one of
28 * the <code>getInstance()</code> methods by either passing in a URL or its
29 * string representation. The implementation of the <code>getURL()</code> method
30 * then directly returns this URL. Other methods defined in the
31 * <code>Locator</code> interface are implemented as empty stubs only.
32 * </p>
33 * <p>
34 * Instances of this class are immutable and thus can be shared between multiple
35 * threads.
36 * </p>
37 *
38 * @author Oliver Heger
39 * @version $Id: URLLocator.java 205 2012-01-29 18:29:57Z oheger $
40 */
41 public final class URLLocator extends AbstractLocator
42 {
43 /** Stores the underlying URL. */
44 private final URL url;
45
46 /**
47 * Creates a new instance of <code>URLLocator</code> and initializes it with
48 * the underlying URL. Clients use the static factory methods for creating
49 * instances.
50 *
51 * @param u the URL
52 */
53 private URLLocator(URL u)
54 {
55 url = u;
56 }
57
58 /**
59 * Returns a <code>URLLocator</code> instance for the specified URL.
60 *
61 * @param url the URL (must not be <b>null</b>)
62 * @return the <code>URLLocator</code> instance for this URL
63 * @throws IllegalArgumentException if the URL is <b>null</b>
64 */
65 public static URLLocator getInstance(URL url)
66 {
67 if (url == null)
68 {
69 throw new IllegalArgumentException("URL must not be null!");
70 }
71
72 return new URLLocator(url);
73 }
74
75 /**
76 * Returns a <code>URLLocator</code> instance for the URL specified as
77 * string. This method converts the given string into a URL and returns a
78 * corresponding <code>URLLocator</code>.
79 *
80 * @param sUrl the URL as string
81 * @return the <code>URLLocator</code> for this URL
82 * @throws LocatorException if the string cannot be transformed into a URL
83 * @throws IllegalArgumentException if the string is <b>null</b>
84 */
85 public static URLLocator getInstance(String sUrl)
86 {
87 if (sUrl == null)
88 {
89 throw new IllegalArgumentException("URL must not be null!");
90 }
91
92 try
93 {
94 return new URLLocator(new URL(sUrl));
95 }
96 catch (MalformedURLException mex)
97 {
98 throw new LocatorException(mex);
99 }
100 }
101
102 /**
103 * Returns the URL represented by this locator. This is simply the URL that
104 * was specified when this instance was created.
105 *
106 * @return the URL represented by this locator
107 */
108 public URL getURL()
109 {
110 return url;
111 }
112
113 /**
114 * Compares this object with another one. Two instance of this class are
115 * equal if an only if they refer to the same URL.
116 *
117 * @param obj the object to compare to
118 * @return a flag whether these objects are equal
119 */
120 @Override
121 public boolean equals(Object obj)
122 {
123 if (this == obj)
124 {
125 return true;
126 }
127 if (!(obj instanceof URLLocator))
128 {
129 return false;
130 }
131
132 URLLocator c = (URLLocator) obj;
133 return getURL().toExternalForm().equals(c.getURL().toExternalForm());
134 }
135
136 /**
137 * Returns a hash code for this object.
138 *
139 * @return a hash code
140 */
141 @Override
142 public int hashCode()
143 {
144 return getURL().toExternalForm().hashCode();
145 }
146
147 /**
148 * Returns a string representation of this object. This string will contain
149 * the URL underlying this locator.
150 *
151 * @return a string for this object
152 */
153 @Override
154 public String toString()
155 {
156 return LocatorUtils.locatorToString(this, "url = " + getURL());
157 }
158 }