1 /* 2 * Copyright (c) 1998, 2017, 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 com.sun.jdi; 27 28 /** 29 * A point within the executing code of the target VM. 30 * Locations are used to identify the current position of 31 * a suspended thread (analogous to an instruction pointer or 32 * program counter register in native programs). They are also used 33 * to identify the position at which to set a breakpoint. 34 * <p> 35 * The availability of a line number for a location will 36 * depend on the level of debugging information available from the 37 * target VM. 38 * <p> 39 * Several mirror interfaces have locations. Each such mirror 40 * extends a {@link Locatable} interface. 41 * <p> 42 * <a id="strata"><b>Strata</b></a> 43 * <p> 44 * The source information for a Location is dependent on the 45 * <i>stratum</i> which is used. A stratum is a source code 46 * level within a sequence of translations. For example, 47 * say the baz program is written in the programming language 48 * "Foo" then translated to the language "Bar" and finally 49 * translated into the Java programming language. The 50 * Java programming language stratum is named 51 * <code>"Java"</code>, let's say the other strata are named 52 * "Foo" and "Bar". A given location (as viewed by the 53 * {@link #sourceName()} and {@link #lineNumber()} methods) 54 * might be at line 14 of "baz.foo" in the <code>"Foo"</code> 55 * stratum, line 23 of "baz.bar" in the <code>"Bar"</code> 56 * stratum and line 71 of the <code>"Java"</code> stratum. 57 * Note that while the Java programming language may have 58 * only one source file for a reference type, this restriction 59 * does not apply to other strata - thus each Location should 60 * be consulted to determine its source path. 61 * Queries which do not specify a stratum 62 * ({@link #sourceName()}, {@link #sourcePath()} and 63 * {@link #lineNumber()}) use the VM's default stratum 64 * ({@link VirtualMachine#getDefaultStratum()}). 65 * If the specified stratum (whether explicitly specified 66 * by a method parameter or implicitly as the VM's default) 67 * is <code>null</code> or is not available in the declaring 68 * type, the declaring type's default stratum is used 69 * ({@link #declaringType()}.{@link ReferenceType#defaultStratum() 70 * defaultStratum()}). Note that in the normal case, of code 71 * that originates as Java programming language source, there 72 * will be only one stratum (<code>"Java"</code>) and it will be 73 * returned as the default. To determine the available strata 74 * use {@link ReferenceType#availableStrata()}. 75 * 76 * @see com.sun.jdi.request.EventRequestManager 77 * @see StackFrame 78 * @see com.sun.jdi.event.BreakpointEvent 79 * @see com.sun.jdi.event.ExceptionEvent 80 * @see Locatable 81 * 82 * @author Robert Field 83 * @author Gordon Hirsch 84 * @author James McIlree 85 * @since 1.3 86 */ 87 public interface Location extends Mirror, Comparable<Location> { 88 89 /** 90 * Gets the type to which this Location belongs. Normally 91 * the declaring type is a {@link ClassType}, but executable 92 * locations also may exist within the static initializer of an 93 * {@link InterfaceType}. 94 * 95 * @return the {@link ReferenceType} containing this Location. 96 */ 97 ReferenceType declaringType(); 98 99 /** 100 * Gets the method containing this Location. 101 * 102 * @return the location's {@link Method}. 103 */ 104 Method method(); 105 106 /** 107 * Gets the code position within this location's method. 108 * 109 * @return the long representing the position within the method 110 * or -1 if location is within a native method. 111 */ 112 long codeIndex(); 113 114 /** 115 * Gets an identifing name for the source corresponding to 116 * this location. 117 * <P> 118 * This method is equivalent to 119 * <code>sourceName(vm.getDefaultStratum())</code> - 120 * see {@link #sourceName(String)} 121 * for more information. 122 * 123 * @return a string specifying the source 124 * @throws AbsentInformationException if the source name is not 125 * known 126 */ 127 String sourceName() throws AbsentInformationException; 128 129 /** 130 * Gets an identifing name for the source corresponding to 131 * this location. Interpretation of this string is the 132 * responsibility of the source repository mechanism. 133 * <P> 134 * Returned name is for the specified <i>stratum</i> 135 * (see the {@link Location class comment} for a 136 * description of strata). 137 * <P> 138 * The returned string is the unqualified name of the source 139 * file for this Location. For example, 140 * <CODE>java.lang.Thread</CODE> would return 141 * <CODE>"Thread.java"</CODE>. 142 * 143 * @param stratum The stratum to retrieve information from 144 * or <code>null</code> for the declaring type's 145 * default stratum. 146 * 147 * @return a string specifying the source 148 * 149 * @throws AbsentInformationException if the source name is not 150 * known 151 * 152 * @since 1.4 153 */ 154 String sourceName(String stratum) throws AbsentInformationException; 155 156 /** 157 * Gets the path to the source corresponding to this 158 * location. 159 * <P> 160 * This method is equivalent to 161 * <code>sourcePath(vm.getDefaultStratum())</code> - 162 * see {@link #sourcePath(String)} 163 * for more information. 164 * 165 * @return a string specifying the source 166 * 167 * @throws AbsentInformationException if the source name is not 168 * known 169 */ 170 String sourcePath() throws AbsentInformationException; 171 172 /** 173 * Gets the path to the source corresponding to this 174 * location. Interpretation of this string is the 175 * responsibility of the source repository mechanism. 176 * <P> 177 * Returned path is for the specified <i>stratum</i> 178 * (see the {@link Location class comment} for a 179 * description of strata). 180 * <P> 181 * In the reference implementation, for strata which 182 * do not explicitly specify source path (the Java 183 * programming language stratum never does), the returned 184 * string is the package name of {@link #declaringType()} 185 * converted to a platform dependent path followed by the 186 * unqualified name of the source file for this Location 187 * ({@link #sourceName sourceName(stratum)}). 188 * For example, on a 189 * Windows platform, <CODE>java.lang.Thread</CODE> 190 * would return 191 * <CODE>"java\lang\Thread.java"</CODE>. 192 * 193 * @param stratum The stratum to retrieve information from 194 * or <code>null</code> for the declaring type's 195 * default stratum. 196 * 197 * @return a string specifying the source 198 * 199 * @throws AbsentInformationException if the source name is not 200 * known 201 * 202 * @since 1.4 203 */ 204 String sourcePath(String stratum) throws AbsentInformationException; 205 206 /** 207 * Gets the line number of this Location. 208 * <P> 209 * This method is equivalent to 210 * <code>lineNumber(vm.getDefaultStratum())</code> - 211 * see {@link #lineNumber(String)} 212 * for more information. 213 * 214 * @return an int specifying the line in the source, returns 215 * -1 if the information is not available; specifically, always 216 * returns -1 for native methods. 217 */ 218 int lineNumber(); 219 220 /** 221 * The line number of this Location. The line number is 222 * relative to the source specified by 223 * {@link #sourceName(String) sourceName(stratum)}. 224 * <P> 225 * Returned line number is for the specified <i>stratum</i> 226 * (see the {@link Location class comment} for a 227 * description of strata). 228 * 229 * @param stratum The stratum to retrieve information from 230 * or <code>null</code> for the declaring type's 231 * default stratum. 232 * 233 * @return an int specifying the line in the source, returns 234 * -1 if the information is not available; specifically, always 235 * returns -1 for native methods. 236 * 237 * @since 1.4 238 */ 239 int lineNumber(String stratum); 240 241 /** 242 * Compares the specified Object with this Location for equality. 243 * 244 * @return true if the Object is a Location and if it refers to 245 * the same point in the same VM as this Location. 246 */ 247 boolean equals(Object obj); 248 249 /** 250 * Returns the hash code value for this Location. 251 * 252 * @return the integer hash code 253 */ 254 int hashCode(); 255 }