1 /* 2 * Copyright (c) 1998, 2013, 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 name="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 @jdk.Exported 90 public interface Location extends Mirror, Comparable<Location> { 91 92 /** 93 * Gets the type to which this Location belongs. Normally 94 * the declaring type is a {@link ClassType}, but executable 95 * locations also may exist within the static initializer of an 96 * {@link InterfaceType}. 97 * 98 * @return the {@link ReferenceType} containing this Location. 99 */ declaringType()100 ReferenceType declaringType(); 101 102 /** 103 * Gets the method containing this Location. 104 * 105 * @return the location's {@link Method}. 106 */ method()107 Method method(); 108 109 /** 110 * Gets the code position within this location's method. 111 * 112 * @return the long representing the position within the method 113 * or -1 if location is within a native method. 114 */ codeIndex()115 long codeIndex(); 116 117 /** 118 * Gets an identifing name for the source corresponding to 119 * this location. 120 * <P> 121 * This method is equivalent to 122 * <code>sourceName(vm.getDefaultStratum())</code> - 123 * see {@link #sourceName(String)} 124 * for more information. 125 * 126 * @return a string specifying the source 127 * @throws AbsentInformationException if the source name is not 128 * known 129 */ sourceName()130 String sourceName() throws AbsentInformationException; 131 132 133 /** 134 * Gets an identifing name for the source corresponding to 135 * this location. Interpretation of this string is the 136 * responsibility of the source repository mechanism. 137 * <P> 138 * Returned name is for the specified <i>stratum</i> 139 * (see the {@link Location class comment} for a 140 * description of strata). 141 * <P> 142 * The returned string is the unqualified name of the source 143 * file for this Location. For example, 144 * <CODE>java.lang.Thread</CODE> would return 145 * <CODE>"Thread.java"</CODE>. 146 * 147 * @param stratum The stratum to retrieve information from 148 * or <code>null</code> for the declaring type's 149 * default stratum. 150 * 151 * @return a string specifying the source 152 * 153 * @throws AbsentInformationException if the source name is not 154 * known 155 * 156 * @since 1.4 157 */ sourceName(String stratum)158 String sourceName(String stratum) 159 throws AbsentInformationException; 160 161 /** 162 * Gets the path to the source corresponding to this 163 * location. 164 * <P> 165 * This method is equivalent to 166 * <code>sourcePath(vm.getDefaultStratum())</code> - 167 * see {@link #sourcePath(String)} 168 * for more information. 169 * 170 * @return a string specifying the source 171 * 172 * @throws AbsentInformationException if the source name is not 173 * known 174 */ sourcePath()175 String sourcePath() throws AbsentInformationException; 176 177 178 /** 179 * Gets the path to the source corresponding to this 180 * location. Interpretation of this string is the 181 * responsibility of the source repository mechanism. 182 * <P> 183 * Returned path is for the specified <i>stratum</i> 184 * (see the {@link Location class comment} for a 185 * description of strata). 186 * <P> 187 * In the reference implementation, for strata which 188 * do not explicitly specify source path (the Java 189 * programming language stratum never does), the returned 190 * string is the package name of {@link #declaringType()} 191 * converted to a platform dependent path followed by the 192 * unqualified name of the source file for this Location 193 * ({@link #sourceName sourceName(stratum)}). 194 * For example, on a 195 * Windows platform, <CODE>java.lang.Thread</CODE> 196 * would return 197 * <CODE>"java\lang\Thread.java"</CODE>. 198 * 199 * @param stratum The stratum to retrieve information from 200 * or <code>null</code> for the declaring type's 201 * default stratum. 202 * 203 * @return a string specifying the source 204 * 205 * @throws AbsentInformationException if the source name is not 206 * known 207 * 208 * @since 1.4 209 */ sourcePath(String stratum)210 String sourcePath(String stratum) 211 throws AbsentInformationException; 212 213 /** 214 * Gets the line number of this Location. 215 * <P> 216 * This method is equivalent to 217 * <code>lineNumber(vm.getDefaultStratum())</code> - 218 * see {@link #lineNumber(String)} 219 * for more information. 220 * 221 * @return an int specifying the line in the source, returns 222 * -1 if the information is not available; specifically, always 223 * returns -1 for native methods. 224 */ lineNumber()225 int lineNumber(); 226 227 /** 228 * The line number of this Location. The line number is 229 * relative to the source specified by 230 * {@link #sourceName(String) sourceName(stratum)}. 231 * <P> 232 * Returned line number is for the specified <i>stratum</i> 233 * (see the {@link Location class comment} for a 234 * description of strata). 235 * 236 * @param stratum The stratum to retrieve information from 237 * or <code>null</code> for the declaring type's 238 * default stratum. 239 * 240 * @return an int specifying the line in the source, returns 241 * -1 if the information is not available; specifically, always 242 * returns -1 for native methods. 243 * 244 * @since 1.4 245 */ lineNumber(String stratum)246 int lineNumber(String stratum); 247 248 /** 249 * Compares the specified Object with this Location for equality. 250 * 251 * @return true if the Object is a Location and if it refers to 252 * the same point in the same VM as this Location. 253 */ equals(Object obj)254 boolean equals(Object obj); 255 256 /** 257 * Returns the hash code value for this Location. 258 * 259 * @return the integer hash code 260 */ hashCode()261 int hashCode(); 262 } 263