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