1 /*
2 * Copyright (c) 2004, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26 package sun.jvmstat.monitor;
27
28 import java.net.*;
29
30 /**
31 * An abstraction that identifies a target host and communications
32 * protocol. The HostIdentifier, or hostid, provides a convenient string
33 * representation of the information needed to locate and communicate with
34 * a target host. The string, based on a {@link URI}, may specify the
35 * the communications protocol, host name, and protocol specific information
36 * for a target host. The format for a HostIdentifier string is:
37 * <pre>
38 * [<I>protocol</I>:][[<I>//</I>]<I>hostname</I>][<I>:port</I>][<I>/servername</I>]
39 * </pre>
40 * There are actually no required components of this string, as a null string
41 * is interpreted to mean a local connection to the local host and is equivalent
42 * to the string <em>local://localhost</em>. The components of the
43 * HostIdentifier are:
44 * <ul>
45 * <li><p><tt>protocol</tt> - The communications protocol. If omitted,
46 * and a hostname is not specified, then default local protocol,
47 * <em>local:</em>, is assumed. If the protocol is omitted and a
48 * hostname is specified then the default remote protocol,
49 * <em>rmi:</em> is assumed.
50 * </p></li>
51 * <li><p><tt>hostname</tt> - The hostname. If omitted, then
52 * <em>localhost</em> is assumed. If the protocol is also omitted,
53 * then default local protocol <em>local:</em> is also assumed.
54 * If the hostname is not omitted but the protocol is omitted,
55 * then the default remote protocol, <em>rmi:</em> is assumed.
56 * </p></li>
57 * <li><p><tt>port</tt> - The port for the communications protocol.
58 * Treatment of the <tt>port</tt> parameter is implementation
59 * (protocol) specific. It is unused by the default local protocol,
60 * <em>local:</em>. For the default remote protocol, <em>rmi:</em>,
61 * <tt>port</tt> indicates the port number of the <em>rmiregistry</em>
62 * on the target host and defaults to port 1099.
63 * </p></li>
64 * <li><p><tt>servername</tt> - The treatment of the Path, Query, and
65 * Fragment components of the HostIdentifier are implementation
66 * (protocol) dependent. These components are ignored by the
67 * default local protocol, <em>local:</em>. For the default remote
68 * protocol, <em>rmi</em>, the Path component is interpreted as
69 * the name of the RMI remote object. The Query component may
70 * contain an access mode specifier <em>?mode=</em> specifying
71 * <em>"r"</em> or <em>"rw"</em> access (write access currently
72 * ignored). The Fragment part is ignored.
73 * </p></li>
74 * </ul>
75 * <p>
76 * All HostIdentifier objects are represented as absolute, hierarchical URIs.
77 * The constructors accept relative URIs, but these will generally be
78 * transformed into an absolute URI specifying a default protocol. A
79 * HostIdentifier differs from a URI in that certain contractions and
80 * illicit syntactical constructions are allowed. The following are all
81 * valid HostIdentifier strings:
82 *
83 * <ul>
84 * <li>{@code <null>} - transformed into "//localhost"</li>
85 * <li>localhost - transformed into "//localhost"</li>
86 * <li>hostname - transformed into "//hostname"</li>
87 * <li>hostname:port - transformed into "//hostname:port"</li>
88 * <li>proto:hostname - transformed into "proto://hostname"</li>
89 * <li>proto:hostname:port - transformed into
90 * "proto://hostname:port"</li>
91 * <li>proto://hostname:port</li>
92 * </ul>
93 *
94 * @see URI
95 * @see VmIdentifier
96 *
97 * @author Brian Doherty
98 * @since 1.5
99 */
100 public class HostIdentifier {
101 private URI uri;
102
103 /**
104 * creates a canonical representation of the uriString. This method
105 * performs certain translations depending on the type of URI generated
106 * by the string.
107 */
108 private URI canonicalize(String uriString) throws URISyntaxException {
109 if ((uriString == null) || (uriString.compareTo("localhost") == 0)) {
110 uriString = "//localhost";
111 return new URI(uriString);
112 }
113
114 URI u = new URI(uriString);
115
116 if (u.isAbsolute()) {
117 if (u.isOpaque()) {
118 /*
119 * this code is here to deal with a special case. For ease of
120 * use, we'd like to be able to handle the case where the user
121 * specifies hostname:port, not requiring the scheme part.
122 * This introduces some subtleties.
123 * hostname:port - scheme = hostname
124 * - schemespecificpart = port
125 * - hostname = null
126 * - userinfo=null
127 * however, someone could also enter scheme:hostname:port and
128 * get into this code. the strategy is to consider this
129 * syntax illegal and provide some code to defend against it.
130 * Basically, we test that the string contains only one ":"
131 * and that the ssp is numeric. If we get two colons, we will
132 * attempt to insert the "//" after the first colon and then
133 * try to create a URI from the resulting string.
134 */
135 String scheme = u.getScheme();
136 String ssp = u.getSchemeSpecificPart();
137 String frag = u.getFragment();
138 URI u2 = null;
139
140 int c1index = uriString.indexOf(':');
141 int c2index = uriString.lastIndexOf(':');
142 if (c2index != c1index) {
143 /*
144 * this is the scheme:hostname:port case. Attempt to
145 * transform this to scheme://hostname:port. If a path
146 * part is part of the original strings, it will be
147 * included in the SchemeSpecificPart. however, the
148 * fragment part must be handled separately.
149 */
150 if (frag == null) {
151 u2 = new URI(scheme + "://" + ssp);
152 } else {
153 u2 = new URI(scheme + "://" + ssp + "#" + frag);
154 }
155 return u2;
156 }
157 /*
158 * here we have the <string>:<string> case, possibly with
159 * optional path and fragment components. we assume that
160 * the part following the colon is a number. we don't check
161 * this condition here as it will get detected later anyway.
162 */
163 u2 = new URI("//" + uriString);
164 return u2;
165 } else {
166 return u;
167 }
168 } else {
169 /*
170 * This is the case where we were given a hostname followed
171 * by a path part, fragment part, or both a path and fragment
172 * part. The key here is that no scheme part was specified.
173 * For this case, if the scheme specific part does not begin
174 * with "//", then we prefix the "//" to the given string and
175 * attempt to create a URI from the resulting string.
176 */
177 String ssp = u.getSchemeSpecificPart();
178 if (ssp.startsWith("//")) {
179 return u;
180 } else {
181 return new URI("//" + uriString);
182 }
183 }
184 }
185
186 /**
187 * Create a HostIdentifier instance from a string value.
188 *
189 * @param uriString a string representing a target host. The syntax of
190 * the string must conform to the rules specified in the
191 * class documentation.
192 *
193 * @throws URISyntaxException Thrown when the uriString or its canonical
194 * form is poorly formed. This exception may
195 * get encapsulated into a MonitorException in
196 * a future version.
197 *
198 */
199 public HostIdentifier(String uriString) throws URISyntaxException {
200 uri = canonicalize(uriString);
201 }
202
203 /**
204 * Create a HostIdentifier instance from component parts of a URI.
205 *
206 * @param scheme the {@link URI#getScheme} component of a URI.
207 * @param authority the {@link URI#getAuthority} component of a URI.
208 * @param path the {@link URI#getPath} component of a URI.
209 * @param query the {@link URI#getQuery} component of a URI.
210 * @param fragment the {@link URI#getFragment} component of a URI.
211 *
212 * @throws URISyntaxException Thrown when the uriString or its canonical
213 * form is poorly formed. This exception may
214 * get encapsulated into a MonitorException in
215 * a future version.
216 * @see URI
217 */
218 public HostIdentifier(String scheme, String authority, String path,
219 String query, String fragment)
220 throws URISyntaxException {
221 uri = new URI(scheme, authority, path, query, fragment);
222 }
223
224 /**
225 * Create a HostIdentifier instance from a VmIdentifier.
226 *
227 * The necessary components of the VmIdentifier are extracted and
228 * reassembled into a HostIdentifier. If a "file:" scheme (protocol)
229 * is specified, the returned HostIdentifier will always be
230 * equivalent to HostIdentifier("file://localhost").
231 *
232 * @param vmid the VmIdentifier use to construct the HostIdentifier.
233 */
234 public HostIdentifier(VmIdentifier vmid) {
235 /*
236 * Extract all components of the VmIdentifier URI except the
237 * user-info part of the authority (the lvmid).
238 */
239 StringBuilder sb = new StringBuilder();
240 String scheme = vmid.getScheme();
241 String host = vmid.getHost();
242 String authority = vmid.getAuthority();
243
244 // check for 'file:' VmIdentifiers and handled as a special case.
245 if ((scheme != null) && (scheme.compareTo("file") == 0)) {
246 try {
247 uri = new URI("file://localhost");
248 } catch (URISyntaxException e) { };
249 return;
250 }
251
252 if ((host != null) && (host.compareTo(authority) == 0)) {
253 /*
254 * this condition occurs when the VmIdentifier specifies only
255 * the authority (i.e. the lvmid ), and not a host name.
256 */
257 host = null;
258 }
259
260 if (scheme == null) {
261 if (host == null) {
262 scheme = "local"; // default local scheme
263 } else {
264 /*
265 * rmi is the default remote scheme. if the VmIdentifier
266 * specifies some other protocol, this default is overridden.
267 */
268 scheme = "rmi";
269 }
270 }
271
272 sb.append(scheme).append("://");
273
274 if (host == null) {
275 sb.append("localhost"); // default host name
276 } else {
277 sb.append(host);
278 }
279
280 int port = vmid.getPort();
281 if (port != -1) {
282 sb.append(":").append(port);
283 }
284
285 String path = vmid.getPath();
286 if ((path != null) && (path.length() != 0)) {
287 sb.append(path);
288 }
289
290 String query = vmid.getQuery();
291 if (query != null) {
292 sb.append("?").append(query);
293 }
294
295 String frag = vmid.getFragment();
296 if (frag != null) {
297 sb.append("#").append(frag);
298 }
299
300 try {
301 uri = new URI(sb.toString());
302 } catch (URISyntaxException e) {
303 // shouldn't happen, as we were passed a valid VmIdentifier
304 throw new RuntimeException("Internal Error", e);
305 }
306 }
307
308 /**
309 * Resolve a VmIdentifier with this HostIdentifier. A VmIdentifier, such
310 * as <em>1234</em> or <em>1234@hostname</em> or any other string that
311 * omits certain components of the URI string may be valid, but is certainly
312 * incomplete. They are missing critical information for identifying the
313 * the communications protocol, target host, or other parameters. A
314 * VmIdentifier of this form is considered <em>unresolved</em>. This method
315 * uses components of the HostIdentifier to resolve the missing components
316 * of the VmIdentifier.
317 * <p>
318 * Specified components of the unresolved VmIdentifier take precedence
319 * over their HostIdentifier counterparts. For example, if the VmIdentifier
320 * indicates <em>1234@hostname:2099</em> and the HostIdentifier indicates
321 * <em>rmi://hostname:1099/</em>, then the resolved VmIdentifier will
322 * be <em>rmi://1234@hostname:2099</em>. Any component not explicitly
323 * specified or assumed by the HostIdentifier, will remain unresolved in
324 * resolved VmIdentifier.
325 * <p>
326 * A VmIdentifier specifying a <em>file:</em> scheme (protocol), is
327 * not changed in any way by this method.
328 *
329 * @param vmid the unresolved VmIdentifier.
330 * @return VmIdentifier - the resolved VmIdentifier. If vmid was resolved
331 * on entry to this method, then the returned
332 * VmIdentifier will be equal, but not identical, to
333 * vmid.
334 */
335 public VmIdentifier resolve(VmIdentifier vmid)
336 throws URISyntaxException, MonitorException {
337 String scheme = vmid.getScheme();
338 String host = vmid.getHost();
339 String authority = vmid.getAuthority();
340
341 if ((scheme != null) && (scheme.compareTo("file") == 0)) {
342 // don't attempt to resolve a file based VmIdentifier.
343 return vmid;
344 }
345
346 if ((host != null) && (host.compareTo(authority) == 0)) {
347 /*
348 * this condition occurs when the VmIdentifier specifies only
349 * the authority (i.e. an lvmid), and not a host name.
350 */
351 host = null;
352 }
353
354 if (scheme == null) {
355 scheme = getScheme();
356 }
357
358 URI nuri = null;
359
360 StringBuilder sb = new StringBuilder();
361
362 sb.append(scheme).append("://");
363
364 String userInfo = vmid.getUserInfo();
365 if (userInfo != null) {
366 sb.append(userInfo);
367 } else {
368 sb.append(vmid.getAuthority());
369 }
370
371 if (host == null) {
372 host = getHost();
373 }
374 sb.append("@").append(host);
375
376 int port = vmid.getPort();
377 if (port == -1) {
378 port = getPort();
379 }
380
381 if (port != -1) {
382 sb.append(":").append(port);
383 }
384
385 String path = vmid.getPath();
386 if ((path == null) || (path.length() == 0)) {
387 path = getPath();
388 }
389
390 if ((path != null) && (path.length() > 0)) {
391 sb.append(path);
392 }
393
394 String query = vmid.getQuery();
395 if (query == null) {
396 query = getQuery();
397 }
398 if (query != null) {
399 sb.append("?").append(query);
400 }
401
402 String fragment = vmid.getFragment();
403 if (fragment == null) {
404 fragment = getFragment();
405 }
406 if (fragment != null) {
407 sb.append("#").append(fragment);
408 }
409
410 String s = sb.toString();
411 return new VmIdentifier(s);
412 }
413
414 /**
415 * Return the Scheme, or protocol, portion of this HostIdentifier.
416 *
417 * @return String - the scheme for this HostIdentifier.
418 * @see URI#getScheme()
419 */
420 public String getScheme() {
421 return uri.isAbsolute() ? uri.getScheme() : null;
422 }
423
424 /**
425 * Return the Scheme Specific Part of this HostIdentifier.
426 *
427 * @return String - the scheme specific part for this HostIdentifier.
428 * @see URI#getSchemeSpecificPart()
429 */
430 public String getSchemeSpecificPart() {
431 return uri.getSchemeSpecificPart();
432 }
433
434 /**
435 * Return the User Info part of this HostIdentifier.
436 *
437 * @return String - the user info part for this HostIdentifier.
438 * @see URI#getUserInfo()
439 */
440 public String getUserInfo() {
441 return uri.getUserInfo();
442 }
443
444 /**
445 * Return the Host part of this HostIdentifier.
446 *
447 * @return String - the host part for this HostIdentifier, or
448 * "localhost" if the URI.getHost() returns null.
449 * @see URI#getUserInfo()
450 */
451 public String getHost() {
452 return (uri.getHost() == null) ? "localhost" : uri.getHost();
453 }
454
455 /**
456 * Return the Port for of this HostIdentifier.
457 *
458 * @return String - the port for this HostIdentifier
459 * @see URI#getPort()
460 */
461 public int getPort() {
462 return uri.getPort();
463 }
464
465 /**
466 * Return the Path part of this HostIdentifier.
467 *
468 * @return String - the path part for this HostIdentifier.
469 * @see URI#getPath()
470 */
471 public String getPath() {
472 return uri.getPath();
473 }
474
475 /**
476 * Return the Query part of this HostIdentifier.
477 *
478 * @return String - the query part for this HostIdentifier.
479 * @see URI#getQuery()
480 */
481 public String getQuery() {
482 return uri.getQuery();
483 }
484
485 /**
486 * Return the Fragment part of this HostIdentifier.
487 *
488 * @return String - the fragment part for this HostIdentifier.
489 * @see URI#getFragment()
490 */
491 public String getFragment() {
492 return uri.getFragment();
493 }
494
495 /**
496 * Return the mode indicated in this HostIdentifier.
497 *
498 * @return String - the mode string. If no mode is specified, then "r"
499 * is returned. otherwise, the specified mode is returned.
500 */
501 public String getMode() {
502 String query = getQuery();
503 if (query != null) {
504 String[] queryArgs = query.split("\\+");
505 for (int i = 0; i < queryArgs.length; i++) {
506 if (queryArgs[i].startsWith("mode=")) {
507 int index = queryArgs[i].indexOf('=');
508 return queryArgs[i].substring(index+1);
509 }
510 }
511 }
512 return "r";
513 }
514
515 /**
516 * Return the URI associated with the HostIdentifier.
517 *
518 * @return URI - the URI.
519 * @see URI
520 */
521 public URI getURI() {
522 return uri;
523 }
524
525 /**
526 * Return the hash code for this HostIdentifier. The hash code is
527 * identical to the hash code for the contained URI.
528 *
529 * @return int - the hashcode.
530 * @see URI#hashCode()
531 */
532 public int hashCode() {
533 return uri.hashCode();
534 }
535
536 /**
537 * Test for quality with other objects.
538 *
539 * @param object the object to be test for equality.
540 * @return boolean - returns true if the given object is of type
541 * HostIdentifier and its URI field is equal to this
542 * object's URI field. Otherwise, returns false.
543 *
544 * @see URI#equals(Object)
545 */
546 public boolean equals(Object object) {
547 if (object == this) {
548 return true;
549 }
550 if (!(object instanceof HostIdentifier)) {
551 return false;
552 }
553 return uri.equals(((HostIdentifier)object).uri);
554 }
555
556
557 /**
558 * Convert to a string representation. Conversion is identical to
559 * calling getURI().toString(). This may change in a future release.
560 *
561 * @return String - a String representation of the HostIdentifier.
562 *
563 * @see URI#toString()
564 */
565 public String toString() {
566 return uri.toString();
567 }
568 }