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