View Javadoc
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  /**
29   * A proxy used by a debugger to examine or manipulate some entity
30   * in another virtual machine. Mirror is the root of the
31   * interface hierarchy for this package. Mirrors can be proxies for objects
32   * in the target VM ({@link ObjectReference}), primitive values
33   * (for example, {@link IntegerValue}), types (for example,
34   * {@link ReferenceType}), dynamic application state (for example,
35   * {@link StackFrame}), and even debugger-specific constructs (for example,
36   * {@link com.sun.jdi.request.BreakpointRequest}).
37   * The {@link VirtualMachine} itself is also
38   * considered a mirror, representing the composite state of the
39   * target VM.
40   * <P>
41   * There is no guarantee that a particular entity in the target VM will map
42   * to a single instance of Mirror. Implementors are free to decide
43   * whether a single mirror will be used for some or all mirrors. Clients
44   * of this interface should always use <code>equals</code> to compare
45   * two mirrors for equality.
46   * <p>
47   * Any method on a {@link com.sun.jdi.Mirror} that takes a <code>Mirror</code> as an
48   * parameter directly or indirectly (e.g., as a element in a <code>List</code>) will
49   * throw {@link com.sun.jdi.VMMismatchException} if the mirrors are from different
50   * virtual machines.
51   *
52   * @see VirtualMachine
53   *
54   * @author Robert Field
55   * @author Gordon Hirsch
56   * @author James McIlree
57   * @since  1.3
58   */
59  @jdk.Exported
60  public interface Mirror {
61  
62      /**
63       * Gets the VirtualMachine to which this
64       * Mirror belongs. A Mirror must be associated
65       * with a VirtualMachine to have any meaning.
66       *
67       * @return the {@link VirtualMachine} for which this mirror is a proxy.
68       */
69      VirtualMachine virtualMachine();
70  
71      /**
72       * Returns a String describing this mirror
73       *
74       * @return a string describing this mirror.
75       */
76      String toString();
77  }