1/*
2 * Copyright (c) 1998, 2017, 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 com.sun.jdi.request.BreakpointRequest;
29
30/**
31 * A proxy used by a debugger to examine or manipulate some entity
32 * in another virtual machine. Mirror is the root of the
33 * interface hierarchy for this package. Mirrors can be proxies for objects
34 * in the target VM ({@link ObjectReference}), primitive values
35 * (for example, {@link IntegerValue}), types (for example,
36 * {@link ReferenceType}), dynamic application state (for example,
37 * {@link StackFrame}), and even debugger-specific constructs (for example,
38 * {@link BreakpointRequest}).
39 * The {@link VirtualMachine} itself is also considered a mirror,
40 * representing the composite state of the target VM.
41 * <P>
42 * There is no guarantee that a particular entity in the target VM will map
43 * to a single instance of Mirror. Implementors are free to decide
44 * whether a single mirror will be used for some or all mirrors. Clients
45 * of this interface should always use <code>equals</code> to compare
46 * two mirrors for equality.
47 * <p>
48 * Any method on a {@link Mirror} that takes a <code>Mirror</code> as an
49 * parameter directly or indirectly (e.g., as a element in a <code>List</code>) will
50 * throw {@link VMMismatchException} if the mirrors are from different
51 * virtual machines.
52 *
53 * @see VirtualMachine
54 *
55 * @author Robert Field
56 * @author Gordon Hirsch
57 * @author James McIlree
58 * @since  1.3
59 */
60public 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}
78