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 * Provides access to an array object and its components in the target VM. 32 * Each array component is mirrored by a {@link Value} object. 33 * The array components, in aggregate, are placed in {@link java.util.List} 34 * objects instead of arrays for consistency with the rest of the API and 35 * for interoperability with other APIs. 36 * 37 * @author Robert Field 38 * @author Gordon Hirsch 39 * @author James McIlree 40 * @since 1.3 41 */ 42 @jdk.Exported 43 public interface ArrayReference extends ObjectReference { 44 45 /** 46 * Returns the number of components in this array. 47 * 48 * @return the integer count of components in this array. 49 */ length()50 int length(); 51 52 /** 53 * Returns an array component value. 54 * 55 * @param index the index of the component to retrieve 56 * @return the {@link Value} at the given index. 57 * @throws java.lang.IndexOutOfBoundsException if 58 * <CODE><I>index</I></CODE> is outside the range of this array, 59 * that is, if either of the following are true: 60 * <PRE> 61 * <I>index</I> < 0 62 * <I>index</I> >= {@link #length() length()} </PRE> 63 */ getValue(int index)64 Value getValue(int index); 65 66 /** 67 * Returns all of the components in this array. 68 * 69 * @return a list of {@link Value} objects, one for each array 70 * component ordered by array index. For zero length arrays, 71 * an empty list is returned. 72 */ getValues()73 List<Value> getValues(); 74 75 /** 76 * Returns a range of array components. 77 * 78 * @param index the index of the first component to retrieve 79 * @param length the number of components to retrieve, or -1 to 80 * retrieve all components to the end of this array. 81 * @return a list of {@link Value} objects, one for each requested 82 * array component ordered by array index. When there are 83 * no elements in the specified range (e.g. 84 * <CODE><I>length</I></CODE> is zero) an empty list is returned 85 * 86 * @throws java.lang.IndexOutOfBoundsException if the range 87 * specified with <CODE><I>index</I></CODE> and 88 * <CODE><I>length</I></CODE> is not within the range of the array, 89 * that is, if either of the following are true: 90 * <PRE> 91 * <I>index</I> < 0 92 * <I>index</I> > {@link #length() length()} </PRE> 93 * or if <CODE><I>length</I> != -1</CODE> and 94 * either of the following are true: 95 * <PRE> 96 * <I>length</I> < 0 97 * <I>index</I> + <I>length</I> > {@link #length() length()}</PRE> 98 */ getValues(int index, int length)99 List<Value> getValues(int index, int length); 100 101 /** 102 * Replaces an array component with another value. 103 * <p> 104 * Object values must be assignment compatible with the component type 105 * (This implies that the component type must be loaded through the 106 * declaring class's class loader). Primitive values must be 107 * either assignment compatible with the component type or must be 108 * convertible to the component type without loss of information. 109 * See JLS section 5.2 for more information on assignment 110 * compatibility. 111 * 112 * @param value the new value 113 * @param index the index of the component to set 114 * @throws java.lang.IndexOutOfBoundsException if 115 * <CODE><I>index</I></CODE> is outside the range of this array, 116 * that is, if either of the following are true: 117 * <PRE> 118 * <I>index</I> < 0 119 * <I>index</I> >= {@link #length() length()} </PRE> 120 * @throws InvalidTypeException if the type of <CODE><I>value</I></CODE> 121 * is not compatible with the declared type of array components. 122 * @throws ClassNotLoadedException if the array component type 123 * has not yet been loaded 124 * through the appropriate class loader. 125 * @throws VMCannotBeModifiedException if the VirtualMachine is read-only - see {@link VirtualMachine#canBeModified()}. 126 * 127 * @see ArrayType#componentType() 128 */ setValue(int index, Value value)129 void setValue(int index, Value value) 130 throws InvalidTypeException, 131 ClassNotLoadedException; 132 133 /** 134 * Replaces all array components with other values. If the given 135 * list is larger in size than the array, the values at the 136 * end of the list are ignored. 137 * <p> 138 * Object values must be assignment compatible with the element type 139 * (This implies that the component type must be loaded through the 140 * enclosing class's class loader). Primitive values must be 141 * either assignment compatible with the component type or must be 142 * convertible to the component type without loss of information. 143 * See JLS section 5.2 for more information on assignment 144 * compatibility. 145 * 146 * @param values a list of {@link Value} objects to be placed 147 * in this array. If <CODE><I>values</I>.size()</CODE> is 148 * less that the length of the array, the first 149 * <CODE><I>values</I>.size()</CODE> elements are set. 150 * @throws InvalidTypeException if any of the 151 * new <CODE><I>values</I></CODE> 152 * is not compatible with the declared type of array components. 153 * @throws ClassNotLoadedException if the array component 154 * type has not yet been loaded 155 * through the appropriate class loader. 156 * @throws VMCannotBeModifiedException if the VirtualMachine is read-only - see {@link VirtualMachine#canBeModified()}. 157 * 158 * @see ArrayType#componentType() 159 */ setValues(List<? extends Value> values)160 void setValues(List<? extends Value> values) 161 throws InvalidTypeException, 162 ClassNotLoadedException; 163 164 /** 165 * Replaces a range of array components with other values. 166 * <p> 167 * Object values must be assignment compatible with the component type 168 * (This implies that the component type must be loaded through the 169 * enclosing class's class loader). Primitive values must be 170 * either assignment compatible with the component type or must be 171 * convertible to the component type without loss of information. 172 * See JLS section 5.2 for more information on assignment 173 * compatibility. 174 * 175 * @param index the index of the first component to set. 176 * @param values a list of {@link Value} objects to be placed 177 * in this array. 178 * @param srcIndex the index of the first source value to use. 179 * @param length the number of components to set, or -1 to set 180 * all components to the end of this array or the end of 181 * <CODE><I>values</I></CODE> (whichever comes first). 182 * @throws InvalidTypeException if any element of 183 * <CODE><I>values</I></CODE> 184 * is not compatible with the declared type of array components. 185 * @throws java.lang.IndexOutOfBoundsException if the 186 * array range specified with 187 * <CODE><I>index</I></CODE> and <CODE><I>length</I></CODE> 188 * is not within the range of the array, 189 * or if the source range specified with 190 * <CODE><I>srcIndex</I></CODE> and <CODE><I>length</I></CODE> 191 * is not within <CODE><I>values</I></CODE>, 192 * that is, if any of the following are true: 193 * <PRE> 194 * <I>index</I> < 0 195 * <I>index</I> > {@link #length() length()} 196 * <I>srcIndex</I> < 0 197 * <I>srcIndex</I> > <I>values</I>.size() </PRE> 198 * or if <CODE><I>length</I> != -1</CODE> and any of the 199 * following are true: 200 * <PRE> 201 * <I>length</I> < 0 202 * <I>index</I> + <I>length</I> > {@link #length() length()} 203 * <I>srcIndex</I> + <I>length</I> > <I>values</I>.size() </PRE> 204 * @throws VMCannotBeModifiedException if the VirtualMachine is read-only - see {@link VirtualMachine#canBeModified()}. 205 * @see ArrayType#componentType() 206 */ setValues(int index, List<? extends Value> values, int srcIndex, int length)207 void setValues(int index, List<? extends Value> values, int srcIndex, int length) 208 throws InvalidTypeException, 209 ClassNotLoadedException; 210 } 211