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 Java Virtual Machine. 32 * The VmIdentifier, or vmid, provides a convenient string representation 33 * of the information needed to locate and communicate with a target 34 * Java Virtual Machine. The string, based on a {@link URI}, may specify 35 * the communications protocol, host name, local vm identifier, and protocol 36 * specific information for a target Java Virtual Machine. The format for 37 * a VmIdentifier string is: 38 * <pre> 39 * [<I>protocol</I>:][<I>//</I>]<I><B>lvmid</B></I>[<I>@hostname</I>][<I>:port</I>][<I>/servername</I>] 40 * </pre> 41 * The only required component of this string is the Local Virtual Machine 42 * Identifier, or <tt>lvmid</tt>, which uniquely identifies the target 43 * Java Virtual Machine on a host. The optional components of the VmIdentifier 44 * include: 45 * <ul> 46 * <li><p><tt>protocol</tt> - The communications protocol. A VmIdentifier 47 * omitting the protocol must be resolved against a HostIdentifier 48 * using {@link HostIdentifier#resolve}. 49 * </p></li> 50 * <li><p><tt>hostname</tt> - A hostname or IP address indicating the target 51 * host. A VmIdentifier omitting the protocol must be resolved 52 * against a HostIdentifier using {@link HostIdentifier#resolve}. 53 * </p></li> 54 * <li><p><tt>port</tt> - The port for the communications protocol. 55 * Treatment of the <tt>port</tt> parameter is implementation 56 * (protocol) specific. A VmIdentifier omitting the protocol should 57 * be resolved against a HostIdentifier using 58 * {@link HostIdentifier#resolve}. 59 * </p></li> 60 * <li><p><tt>servername</tt> - The treatment of the Path, Query, and 61 * Fragment components of the VmIdentifier are implementation 62 * (protocol) dependent. A VmIdentifier omitting the protocol should 63 * be resolved against a HostIdentifier using 64 * {@link HostIdentifier#resolve}. 65 * </p></li> 66 * </ul> 67 * <p> 68 * All VmIdentifier instances are constructed as absolute, hierarchical URIs. 69 * The constructors will accept relative (and even some malformed, 70 * though convenient) URI strings. Such strings are transformed into 71 * legitimate, absolute URI strings. 72 * </p> 73 * <p> 74 * With the exception of <em>file:</em> based VmIdentifier strings, all 75 * VmIdentifier strings must include a <tt>lvmid</tt>. Attempting to construct 76 * a non-file based VmIdentifier that doesn't include a <tt>lvmid</tt> 77 * component will result in a <tt>MonitorException</tt>. 78 * </p> 79 * <p> 80 * Here are some examples of VmIdentifier strings. 81 * <ul> 82 * <li><p>Relative URIs</p></li> 83 * <ul> 84 * <li><p><em>1234</em> - Specifies the Java Virtual Machine 85 * identified by lvmid <em>1234</em> on an unnamed host. 86 * This string is transformed into the absolute form 87 * <em>//1234</em>, which must be resolved against a 88 * HostIdentifier. 89 * </p></li> 90 * <li><p><em>1234@hostname</em> - Specifies the Java Virtual 91 * Machine identified by lvmid <em>1234</em> on host 92 * <em>hostname</em> with an unnamed protocol. 93 * This string is transformed into the absolute form 94 * <em>//1234@hostname</em>, which must be resolved against 95 * a HostIdentifier. 96 * </p></li> 97 * <li><p><em>1234@hostname:2099</em> - Specifies the Java Virtual 98 * Machine identified by lvmid <em>1234</em> on host 99 * <em>hostname</em> with an unnamed protocol, but with 100 * port <em>2099</em>. This string is transformed into 101 * the absolute form <em>//1234@hostname:2099</em>, which 102 * must be resolved against a HostIdentifier. 103 * </p></li> 104 * </ul> 105 * <li><p>Absolute URIs</p></li> 106 * <ul> 107 * <li><p><em>rmi://1234@hostname:2099/remoteobjectname</em> - 108 * Specifies the Java Virtual Machine identified by lvmid 109 * <em>1234</em> on host <em>hostname</em> accessed 110 * using the <em>rmi:</em> protocol through the rmi remote 111 * object named <em>remoteobjectname</em> as registered with 112 * the <em>rmiserver</em> on port <em>2099</em> on host 113 * <em>hostname</em>. 114 * </p></li> 115 * <li><p><em>file:/path/file</em> - Identifies a Java Virtual Machine 116 * through accessing a special file based protocol to use as 117 * the communications mechanism. 118 * </p></li> 119 * </ul> 120 * </ul> 121 * </p> 122 * 123 * @see URI 124 * @see HostIdentifier 125 * @author Brian Doherty 126 * @since 1.5 127 */ 128 public class VmIdentifier { 129 private URI uri; 130 131 /** 132 * creates a canonical representation of the uriString. This method 133 * performs certain translations depending on the type of URI generated 134 * by the string. 135 */ 136 private URI canonicalize(String uriString) throws URISyntaxException { 137 if (uriString == null) { 138 uriString = "local://0@localhost"; 139 return new URI(uriString); 140 } 141 219 * @param uri a well formed, absolute URI indicating the 220 * target Java Virtual Machine. 221 * @throws URISyntaxException Thrown if the URI is missing some 222 * required component. 223 */ 224 public VmIdentifier(URI uri) throws URISyntaxException { 225 this.uri = uri; 226 validate(); 227 } 228 229 /** 230 * Return the corresponding HostIdentifier for this VmIdentifier. 231 * <p> 232 * This method constructs a HostIdentifier object from the VmIdentifier. 233 * If the VmIdentifier is not specific about the protocol or other 234 * components of the URI, then the resulting HostIdentifier will 235 * be constructed based on this missing information. Typically, the 236 * missing components will have result in the HostIdentifier assigning 237 * assumed defaults that allow the VmIdentifier to be resolved according 238 * to those defaults. 239 * </p> 240 * <p> 241 * For example, a VmIdentifier that specifies only a <tt>lvmid</tt> 242 * will result in a HostIdentifier for <em>localhost</em> utilizing 243 * the default local protocol, <em>local:</em>. A VmIdentifier that 244 * specifies both a <tt>vmid</tt> and a <tt>hostname</tt> will result 245 * in a HostIdentifier for the specified host with the default remote 246 * protocol, <em>rmi:</em>, using the protocol defaults for the 247 * <tt>port</tt> and <tt>servername</tt> components. 248 * </p> 249 * 250 * @return HostIdentifier - the host identifier for the host containing 251 * the Java Virtual Machine represented by this 252 * VmIdentifier. 253 * @throws URISyntaxException Thrown if a bad host URI is constructed. 254 * This exception may get encapsulated into 255 * a MonitorException in a future version. 256 */ 257 public HostIdentifier getHostIdentifier() throws URISyntaxException { 258 StringBuilder sb = new StringBuilder(); 259 if (getScheme() != null) { 260 sb.append(getScheme()).append(":"); 261 } 262 sb.append("//").append(getHost()); 263 if (getPort() != -1) { 264 sb.append(":").append(getPort()); 265 } 266 if (getPath() != null) { 267 sb.append(getPath()); 268 } | 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 Java Virtual Machine. 32 * The VmIdentifier, or vmid, provides a convenient string representation 33 * of the information needed to locate and communicate with a target 34 * Java Virtual Machine. The string, based on a {@link URI}, may specify 35 * the communications protocol, host name, local vm identifier, and protocol 36 * specific information for a target Java Virtual Machine. The format for 37 * a VmIdentifier string is: 38 * <pre> 39 * [<I>protocol</I>:][<I>//</I>]<I><B>lvmid</B></I>[<I>@hostname</I>][<I>:port</I>][<I>/servername</I>] 40 * </pre> 41 * The only required component of this string is the Local Virtual Machine 42 * Identifier, or {@code lvmid}, which uniquely identifies the target 43 * Java Virtual Machine on a host. The optional components of the VmIdentifier 44 * include: 45 * <ul> 46 * <li>{@code protocol} - The communications protocol. A VmIdentifier 47 * omitting the protocol must be resolved against a HostIdentifier 48 * using {@link HostIdentifier#resolve}. 49 * </li> 50 * <li>{@code hostname} - A hostname or IP address indicating the target 51 * host. A VmIdentifier omitting the protocol must be resolved 52 * against a HostIdentifier using {@link HostIdentifier#resolve}. 53 * </li> 54 * <li>{@code port} - The port for the communications protocol. 55 * Treatment of the {@code port} parameter is implementation 56 * (protocol) specific. A VmIdentifier omitting the protocol should 57 * be resolved against a HostIdentifier using 58 * {@link HostIdentifier#resolve}. 59 * </li> 60 * <li>{@code servername} - The treatment of the Path, Query, and 61 * Fragment components of the VmIdentifier are implementation 62 * (protocol) dependent. A VmIdentifier omitting the protocol should 63 * be resolved against a HostIdentifier using 64 * {@link HostIdentifier#resolve}. 65 * </li> 66 * </ul> 67 * <p> 68 * All VmIdentifier instances are constructed as absolute, hierarchical URIs. 69 * The constructors will accept relative (and even some malformed, 70 * though convenient) URI strings. Such strings are transformed into 71 * legitimate, absolute URI strings. 72 * <p> 73 * With the exception of <em>file:</em> based VmIdentifier strings, all 74 * VmIdentifier strings must include a {@code lvmid}. Attempting to construct 75 * a non-file based VmIdentifier that doesn't include a {@code lvmid} 76 * component will result in a {@code MonitorException}. 77 * <p> 78 * Here are some examples of VmIdentifier strings. 79 * <ul> 80 * <li>Relative URIs 81 * <ul> 82 * <li><em>1234</em> - Specifies the Java Virtual Machine 83 * identified by lvmid <em>1234</em> on an unnamed host. 84 * This string is transformed into the absolute form 85 * <em>//1234</em>, which must be resolved against a 86 * HostIdentifier. 87 * </li> 88 * <li><em>1234@hostname</em> - Specifies the Java Virtual 89 * Machine identified by lvmid <em>1234</em> on host 90 * <em>hostname</em> with an unnamed protocol. 91 * This string is transformed into the absolute form 92 * <em>//1234@hostname</em>, which must be resolved against 93 * a HostIdentifier. 94 * </li> 95 * <li><em>1234@hostname:2099</em> - Specifies the Java Virtual 96 * Machine identified by lvmid <em>1234</em> on host 97 * <em>hostname</em> with an unnamed protocol, but with 98 * port <em>2099</em>. This string is transformed into 99 * the absolute form <em>//1234@hostname:2099</em>, which 100 * must be resolved against a HostIdentifier. 101 * </li> 102 * </ul> 103 * </li> 104 * <li>Absolute URIs 105 * <ul> 106 * <li><em>rmi://1234@hostname:2099/remoteobjectname</em> - 107 * Specifies the Java Virtual Machine identified by lvmid 108 * <em>1234</em> on host <em>hostname</em> accessed 109 * using the <em>rmi:</em> protocol through the rmi remote 110 * object named <em>remoteobjectname</em> as registered with 111 * the <em>rmiserver</em> on port <em>2099</em> on host 112 * <em>hostname</em>. 113 * </li> 114 * <li><em>file:/path/file</em> - Identifies a Java Virtual Machine 115 * through accessing a special file based protocol to use as 116 * the communications mechanism. 117 * </li> 118 * </ul> 119 * </li> 120 * </ul> 121 * 122 * @see URI 123 * @see HostIdentifier 124 * @author Brian Doherty 125 * @since 1.5 126 */ 127 public class VmIdentifier { 128 private URI uri; 129 130 /** 131 * creates a canonical representation of the uriString. This method 132 * performs certain translations depending on the type of URI generated 133 * by the string. 134 */ 135 private URI canonicalize(String uriString) throws URISyntaxException { 136 if (uriString == null) { 137 uriString = "local://0@localhost"; 138 return new URI(uriString); 139 } 140 218 * @param uri a well formed, absolute URI indicating the 219 * target Java Virtual Machine. 220 * @throws URISyntaxException Thrown if the URI is missing some 221 * required component. 222 */ 223 public VmIdentifier(URI uri) throws URISyntaxException { 224 this.uri = uri; 225 validate(); 226 } 227 228 /** 229 * Return the corresponding HostIdentifier for this VmIdentifier. 230 * <p> 231 * This method constructs a HostIdentifier object from the VmIdentifier. 232 * If the VmIdentifier is not specific about the protocol or other 233 * components of the URI, then the resulting HostIdentifier will 234 * be constructed based on this missing information. Typically, the 235 * missing components will have result in the HostIdentifier assigning 236 * assumed defaults that allow the VmIdentifier to be resolved according 237 * to those defaults. 238 * <p> 239 * For example, a VmIdentifier that specifies only a {@code lvmid} 240 * will result in a HostIdentifier for <em>localhost</em> utilizing 241 * the default local protocol, <em>local:</em>. A VmIdentifier that 242 * specifies both a {@code vmid} and a {@code hostname} will result 243 * in a HostIdentifier for the specified host with the default remote 244 * protocol, <em>rmi:</em>, using the protocol defaults for the 245 * {@code port} and {@code servername} components. 246 * 247 * @return HostIdentifier - the host identifier for the host containing 248 * the Java Virtual Machine represented by this 249 * VmIdentifier. 250 * @throws URISyntaxException Thrown if a bad host URI is constructed. 251 * This exception may get encapsulated into 252 * a MonitorException in a future version. 253 */ 254 public HostIdentifier getHostIdentifier() throws URISyntaxException { 255 StringBuilder sb = new StringBuilder(); 256 if (getScheme() != null) { 257 sb.append(getScheme()).append(":"); 258 } 259 sb.append("//").append(getHost()); 260 if (getPort() != -1) { 261 sb.append(":").append(getPort()); 262 } 263 if (getPath() != null) { 264 sb.append(getPath()); 265 } |