KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > eclipse > debug > core > model > IMemoryBlockExtension


1 /*******************************************************************************
2  * Copyright (c) 2004, 2006 IBM Corporation and others.
3  * All rights reserved. This program and the accompanying materials
4  * are made available under the terms of the Eclipse Public License v1.0
5  * which accompanies this distribution, and is available at
6  * http://www.eclipse.org/legal/epl-v10.html
7  *
8  * Contributors:
9  * IBM Corporation - initial API and implementation
10  *******************************************************************************/

11 package org.eclipse.debug.core.model;
12
13 import java.math.BigInteger JavaDoc;
14
15 import org.eclipse.debug.core.DebugException;
16
17 /**
18  * Extensions to {@link org.eclipse.debug.core.model.IMemoryBlock}. Allows
19  * for bytes to be accessed in a larger address space, and for state information
20  * to be provided for each byte.
21  * <p>
22  * Clients may optionally implement this interface when providing implementations of
23  * {@link org.eclipse.debug.core.model.IMemoryBlock}.
24  * </p>
25  * @since 3.1
26  * @see org.eclipse.debug.core.model.MemoryByte
27  */

28 public interface IMemoryBlockExtension extends IMemoryBlock {
29     
30     /**
31      * Returns the expression used to create this memory block. An expression can
32      * be used as name for a memory block and typically represents an expression
33      * used to compute a base address for a memory block.
34      *
35      * @return the expression used to create this memory block
36      */

37     public String JavaDoc getExpression();
38     
39     /**
40      * Returns the base address of this memory block as a big integer. The
41      * address is in terms of addressable units.
42      *
43      * @return the base address of this memory block
44      * @throws DebugException if unable to retrieve the base address
45      */

46     public BigInteger JavaDoc getBigBaseAddress() throws DebugException;
47     
48     /**
49      * Returns the hard start address of this memory block as a big integer, or
50      * <code>null</code> if none. A <code>null</code> start address indicates that
51      * memory may be retrieved at any address less than this memory block's base
52      * address.
53      *
54      * @return the hard start address of this memory block or <code>null</code>
55      * @throws DebugException if unable to retrieve the start address of this memory block.
56      */

57     public BigInteger JavaDoc getMemoryBlockStartAddress() throws DebugException;
58     
59     /**
60      * Returns the hard end address of this memory block as a big integer, or
61      * <code>null</code> if none. A <code>null</code> end address indicates that
62      * memory may be retrieved from any positive offset relative to the base address
63      * of this memory block.
64      *
65      * @return the hard end address of this memory block or <code>null</code>
66      * @throws DebugException if unable to retrieve the end address of this memory block.
67      */

68     public BigInteger JavaDoc getMemoryBlockEndAddress() throws DebugException;
69     
70     /**
71      * Returns the length of this memory block, or -1 if unbounded.
72      * Returns "end address - start address" for a memory block with a fixed
73      * length (i.e. when both start and end address are known).
74      * Returns -1 for an unbounded memory block (i.e. when start or end address is
75      * <code>null</code>).
76      *
77      * @return length of this memory block or -1 if unbounded
78      * @throws DebugException if unable to retrieve the length of this memory block.
79      */

80     public BigInteger JavaDoc getBigLength() throws DebugException;
81     
82     /**
83      * Returns the address size of this memory block in number of bytes. The address
84      * size indicates the number of bytes used to construct an address.
85      *
86      * @return address size in number of bytes
87      * @throws DebugException if unable to retrieve the address size
88      */

89     public int getAddressSize() throws DebugException;
90     
91     /**
92      * Returns whether the base address of this memory block can be modified.
93      *
94      * @return whether the base address of this memory block can be modified
95      * @throws DebugException is unable to determine if base address modification is supported
96      */

97     public boolean supportBaseAddressModification() throws DebugException;
98     
99     /**
100      * Returns whether this memory block manages the change state of its bytes.
101      * <p>
102      * If a memory block manages changes the memory block is responsible for
103      * setting the <code>CHANGED</code> state of its <code>MemoryByte</code>'s
104      * returned from <code>getBytesFromAddress</code> and
105      * <code>getBytesFromOffset</code>. The changed state of a byte should
106      * be updated each time a thread suspends in a memory block's target.
107      * </p>
108      * @return whether this memory block manages the change state of its bytes
109      */

110     public boolean supportsChangeManagement();
111     
112     /**
113      * Sets the base address of this memory block to the given address.
114      *
115      * @param address new base address
116      * @throws DebugException if unable to modify the base address, or modification
117      * of the base address fails
118      */

119     public void setBaseAddress(BigInteger JavaDoc address) throws DebugException;
120
121     /**
122      * Returns bytes from this memory block based on the base address and
123      * addressable size of this memory block.
124      * <p>
125      * A memory block may be asked to retrieve bytes beyond it's start
126      * or end address. If a memory block is unable to retrieve memory outside
127      * these boundaries, implementations should return memory bytes with
128      * the <code>READABLE</code> bit turned off for each byte outside
129      * the of the accessible range. An exception should not be thrown in this
130      * case.
131      * </p>
132      * @param unitOffset zero based offset into this memory block at which to start
133      * retrieving bytes in terms of addressable units. Client should retrieve
134      * memory starting from "base address + offset".
135      * @param addressableUnits the number of addressable units to retrieve
136      * @return an array of bytes from this memory block based on the given offset
137      * and number of units. The size of the array returned must to be equal to
138      * <code>units</code> * <code>getAddressableSize()</code>.
139      * @throws DebugException if unable to retrieve the specified bytes due to
140      * a failure communicating with the target
141      * @see MemoryByte
142      */

143     public MemoryByte[] getBytesFromOffset(BigInteger JavaDoc unitOffset, long addressableUnits) throws DebugException;
144     
145     /**
146      * Returns bytes from this memory block based on the given address and the
147      * addressable size of this memory block.
148      * <p>
149      * A memory block may be asked to retrieve bytes beyond it's start
150      * or end address. If a memory block is unable to retrieve memory outside
151      * these boundaries, implementations should return memory bytes with
152      * the <code>READABLE</code> bit turned off for each byte outside
153      * the of the accessible range. An exception should not be thrown in this
154      * case.
155      * </p>
156      * @param address address at which to begin retrieving bytes in terms
157      * of addressable units
158      * @param units is the number of addressable units of memory to retrieve
159      * @return an array of bytes from this memory block based on the given address
160      * and number of units. The size of the array returned must to be equal to
161      * <code>units</code> * <code>getAddressableSize()</code>.
162      * @throws DebugException if unable to retrieve the specified bytes due to
163      * a failure communicating with the target
164      * @see MemoryByte
165      */

166     public MemoryByte[] getBytesFromAddress(BigInteger JavaDoc address, long units) throws DebugException;
167
168     /**
169      * Sets bytes in this memory block at the specified offset within this memory block to
170      * the specified bytes. The offset is zero based. After successfully modifying the
171      * specified bytes, a debug event should be fired with a kind of <code>CHANGE</code>.
172      *
173      * @param offset the zero based offset at which to set the new value. Modify
174      * the memory starting from base address + offset.
175      * @param bytes replacement bytes
176      * @exception DebugException if this method fails. Reasons include:
177      * <ul><li>Failure communicating with the debug target. The DebugException's
178      * status code contains the underlying exception responsible for
179      * the failure.</li>
180      * <li>This memory block does not support value modification</li>
181      * <li>The specified offset is greater than or equal to the length
182      * of this memory block, or the number of bytes specified goes
183      * beyond the end of this memory block (index of out of range)</li>
184      * </ul>
185      * @see org.eclipse.debug.core.DebugEvent
186      */

187     public void setValue(BigInteger JavaDoc offset, byte[] bytes) throws DebugException;
188
189     /**
190      * Connects the given client to this memory block. Allows a memory block
191      * to know when it is being monitored. Has no effect if an identical
192      * client is already connected.
193      * <p>
194      * Memory blocks supporting change management may selectively turn off
195      * change management when no clients are connected, for reasons of
196      * efficiency. Clients that require access to change state information
197      * are required to connect to a memory block before change information
198      * is considered to be valid.
199      * </p>
200      * @param client the client to connect
201      */

202     public void connect(Object JavaDoc client);
203     
204     /**
205      * Disconnects the given client from this memory block. Has no effect if
206      * an identical client is not already connected.
207      *
208      * @param client the client to disconnect
209      */

210     public void disconnect(Object JavaDoc client);
211     
212     /**
213      * Returns the possibly empty list of clients currently connected to this
214      * memory block.
215      *
216      * @return the possibly empty list of clients currently connected to this
217      * memory block
218      */

219     public Object JavaDoc[] getConnections();
220     
221     /**
222      * Dispose this memory block. Connected clients are disconnected.
223      * @throws DebugException if the memory block cannot be disposed.
224      */

225     public void dispose() throws DebugException;
226     
227     /**
228      * Returns the origin of this memory block.
229      *
230      * @return the origin of this memory block
231      */

232     public IMemoryBlockRetrieval getMemoryBlockRetrieval();
233     
234     /**
235      * Returns this memory block's addressable size in number of bytes. The addressable size
236      * of memory block indicates the minimum number of bytes that can be retrieved as
237      * a single unit.
238      *
239      * @return this memory block's addressable size
240      * @throws DebugException if the addressable size cannot be obtained.
241      */

242     public int getAddressableSize() throws DebugException;
243 }
244
Popular Tags