| /* |
| * Copyright (c) 1998, 2013, Oracle and/or its affiliates. All rights reserved. |
| * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. |
| * |
| * This code is free software; you can redistribute it and/or modify it |
| * under the terms of the GNU General Public License version 2 only, as |
| * published by the Free Software Foundation. Oracle designates this |
| * particular file as subject to the "Classpath" exception as provided |
| * by Oracle in the LICENSE file that accompanied this code. |
| * |
| * This code is distributed in the hope that it will be useful, but WITHOUT |
| * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or |
| * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License |
| * version 2 for more details (a copy is included in the LICENSE file that |
| * accompanied this code). |
| * |
| * You should have received a copy of the GNU General Public License version |
| * 2 along with this work; if not, write to the Free Software Foundation, |
| * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. |
| * |
| * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA |
| * or visit www.oracle.com if you need additional information or have any |
| * questions. |
| */ |
| |
| package com.sun.jdi; |
| |
| import java.util.List; |
| |
| /** |
| * Provides access to an array object and its components in the target VM. |
| * Each array component is mirrored by a {@link Value} object. |
| * The array components, in aggregate, are placed in {@link java.util.List} |
| * objects instead of arrays for consistency with the rest of the API and |
| * for interoperability with other APIs. |
| * |
| * @author Robert Field |
| * @author Gordon Hirsch |
| * @author James McIlree |
| * @since 1.3 |
| */ |
| @jdk.Exported |
| public interface ArrayReference extends ObjectReference { |
| |
| /** |
| * Returns the number of components in this array. |
| * |
| * @return the integer count of components in this array. |
| */ |
| int length(); |
| |
| /** |
| * Returns an array component value. |
| * |
| * @param index the index of the component to retrieve |
| * @return the {@link Value} at the given index. |
| * @throws java.lang.IndexOutOfBoundsException if |
| * <CODE><I>index</I></CODE> is outside the range of this array, |
| * that is, if either of the following are true: |
| * <PRE> |
| * <I>index</I> < 0 |
| * <I>index</I> >= {@link #length() length()} </PRE> |
| */ |
| Value getValue(int index); |
| |
| /** |
| * Returns all of the components in this array. |
| * |
| * @return a list of {@link Value} objects, one for each array |
| * component ordered by array index. For zero length arrays, |
| * an empty list is returned. |
| */ |
| List<Value> getValues(); |
| |
| /** |
| * Returns a range of array components. |
| * |
| * @param index the index of the first component to retrieve |
| * @param length the number of components to retrieve, or -1 to |
| * retrieve all components to the end of this array. |
| * @return a list of {@link Value} objects, one for each requested |
| * array component ordered by array index. When there are |
| * no elements in the specified range (e.g. |
| * <CODE><I>length</I></CODE> is zero) an empty list is returned |
| * |
| * @throws java.lang.IndexOutOfBoundsException if the range |
| * specified with <CODE><I>index</I></CODE> and |
| * <CODE><I>length</I></CODE> is not within the range of the array, |
| * that is, if either of the following are true: |
| * <PRE> |
| * <I>index</I> < 0 |
| * <I>index</I> > {@link #length() length()} </PRE> |
| * or if <CODE><I>length</I> != -1</CODE> and |
| * either of the following are true: |
| * <PRE> |
| * <I>length</I> < 0 |
| * <I>index</I> + <I>length</I> > {@link #length() length()}</PRE> |
| */ |
| List<Value> getValues(int index, int length); |
| |
| /** |
| * Replaces an array component with another value. |
| * <p> |
| * Object values must be assignment compatible with the component type |
| * (This implies that the component type must be loaded through the |
| * declaring class's class loader). Primitive values must be |
| * either assignment compatible with the component type or must be |
| * convertible to the component type without loss of information. |
| * See JLS section 5.2 for more information on assignment |
| * compatibility. |
| * |
| * @param value the new value |
| * @param index the index of the component to set |
| * @throws java.lang.IndexOutOfBoundsException if |
| * <CODE><I>index</I></CODE> is outside the range of this array, |
| * that is, if either of the following are true: |
| * <PRE> |
| * <I>index</I> < 0 |
| * <I>index</I> >= {@link #length() length()} </PRE> |
| * @throws InvalidTypeException if the type of <CODE><I>value</I></CODE> |
| * is not compatible with the declared type of array components. |
| * @throws ClassNotLoadedException if the array component type |
| * has not yet been loaded |
| * through the appropriate class loader. |
| * @throws VMCannotBeModifiedException if the VirtualMachine is read-only - see {@link VirtualMachine#canBeModified()}. |
| * |
| * @see ArrayType#componentType() |
| */ |
| void setValue(int index, Value value) |
| throws InvalidTypeException, |
| ClassNotLoadedException; |
| |
| /** |
| * Replaces all array components with other values. If the given |
| * list is larger in size than the array, the values at the |
| * end of the list are ignored. |
| * <p> |
| * Object values must be assignment compatible with the element type |
| * (This implies that the component type must be loaded through the |
| * enclosing class's class loader). Primitive values must be |
| * either assignment compatible with the component type or must be |
| * convertible to the component type without loss of information. |
| * See JLS section 5.2 for more information on assignment |
| * compatibility. |
| * |
| * @param values a list of {@link Value} objects to be placed |
| * in this array. If <CODE><I>values</I>.size()</CODE> is |
| * less that the length of the array, the first |
| * <CODE><I>values</I>.size()</CODE> elements are set. |
| * @throws InvalidTypeException if any of the |
| * new <CODE><I>values</I></CODE> |
| * is not compatible with the declared type of array components. |
| * @throws ClassNotLoadedException if the array component |
| * type has not yet been loaded |
| * through the appropriate class loader. |
| * @throws VMCannotBeModifiedException if the VirtualMachine is read-only - see {@link VirtualMachine#canBeModified()}. |
| * |
| * @see ArrayType#componentType() |
| */ |
| void setValues(List<? extends Value> values) |
| throws InvalidTypeException, |
| ClassNotLoadedException; |
| |
| /** |
| * Replaces a range of array components with other values. |
| * <p> |
| * Object values must be assignment compatible with the component type |
| * (This implies that the component type must be loaded through the |
| * enclosing class's class loader). Primitive values must be |
| * either assignment compatible with the component type or must be |
| * convertible to the component type without loss of information. |
| * See JLS section 5.2 for more information on assignment |
| * compatibility. |
| * |
| * @param index the index of the first component to set. |
| * @param values a list of {@link Value} objects to be placed |
| * in this array. |
| * @param srcIndex the index of the first source value to use. |
| * @param length the number of components to set, or -1 to set |
| * all components to the end of this array or the end of |
| * <CODE><I>values</I></CODE> (whichever comes first). |
| * @throws InvalidTypeException if any element of |
| * <CODE><I>values</I></CODE> |
| * is not compatible with the declared type of array components. |
| * @throws java.lang.IndexOutOfBoundsException if the |
| * array range specified with |
| * <CODE><I>index</I></CODE> and <CODE><I>length</I></CODE> |
| * is not within the range of the array, |
| * or if the source range specified with |
| * <CODE><I>srcIndex</I></CODE> and <CODE><I>length</I></CODE> |
| * is not within <CODE><I>values</I></CODE>, |
| * that is, if any of the following are true: |
| * <PRE> |
| * <I>index</I> < 0 |
| * <I>index</I> > {@link #length() length()} |
| * <I>srcIndex</I> < 0 |
| * <I>srcIndex</I> > <I>values</I>.size() </PRE> |
| * or if <CODE><I>length</I> != -1</CODE> and any of the |
| * following are true: |
| * <PRE> |
| * <I>length</I> < 0 |
| * <I>index</I> + <I>length</I> > {@link #length() length()} |
| * <I>srcIndex</I> + <I>length</I> > <I>values</I>.size() </PRE> |
| * @throws VMCannotBeModifiedException if the VirtualMachine is read-only - see {@link VirtualMachine#canBeModified()}. |
| * @see ArrayType#componentType() |
| */ |
| void setValues(int index, List<? extends Value> values, int srcIndex, int length) |
| throws InvalidTypeException, |
| ClassNotLoadedException; |
| } |