/*******************************************************************************
* Copyright (c) 2000, 2011 IBM Corporation and others.
* All rights reserved. This program and the accompanying materials
* are made available under the terms of the Eclipse Public License v1.0
* which accompanies this distribution, and is available at
* http://www.eclipse.org/legal/epl-v10.html
*
* Contributors:
* IBM Corporation - initial API and implementation
*******************************************************************************/
package org.eclipse.jdt.debug.core;
import org.eclipse.debug.core.DebugException;
/**
* Represents the type of an object in a virtual machine - including classes,
* interfaces and array types.
*
* @since 3.0
* @noimplement This interface is not intended to be implemented by clients.
* @noextend This interface is not intended to be extended by clients.
*/
public interface IJavaReferenceType extends IJavaType {
/**
* Returns a variable representing the static field in this type with the
* given name, or <code>null</code> if there is no field with the given
* name, or the name is ambiguous.
*
* @param name
* field name
* @return the variable representing the static field, or <code>null</code>
* @exception DebugException
* if this method fails. Reasons include:
* <ul>
* <li>Failure communicating with the VM. The
* DebugException's status code contains the underlying
* exception responsible for the failure.</li>
* </ul>
*/
public IJavaFieldVariable getField(String name) throws DebugException;
/**
* Returns the class object associated with this type.
*
* @return the class object associated with this type
* @exception DebugException
* if this method fails. Reasons include:
* <ul>
* <li>Failure communicating with the VM. The
* DebugException's status code contains the underlying
* exception responsible for the failure.</li>
* </ul>
*/
public IJavaClassObject getClassObject() throws DebugException;
/**
* Returns a collection of strata available for this type.
*
* @return a collection of strata available for this type
* @throws DebugException
* if unable to retrieve available strata
*/
public String[] getAvailableStrata() throws DebugException;
/**
* Returns the default stratum for this type.
*
* @return the default stratum for this type
* @throws DebugException
* if unable to retrieve the default stratum
*/
public String getDefaultStratum() throws DebugException;
/**
* Returns a collection of the names of the fields declared in this type.
*
* @return a collection of the names of the field declared in this type
* @throws DebugException
* if unable to retrieve declared field names
*/
public String[] getDeclaredFieldNames() throws DebugException;
/**
* Returns a collection of the names of all of the fields declared in this
* type, all of its super classes, implemented interfaces and super
* interfaces.
*
* @return a collection of the names of all of the fields declared in this
* type, all of its super classes, implemented interfaces and super
* interfaces
* @throws DebugException
* if unable to retrieve field names
*/
public String[] getAllFieldNames() throws DebugException;
/**
* Returns the class loader object that loaded the class corresponding to
* this type, or <code>null</code> if this type was loaded by the bootstrap
* loader.
*
* @return the class loader object that loaded the class corresponding to
* this type or <code>null</code>
* @throws DebugException
* if unable to get the class loader
* @since 3.1
*/
public IJavaObject getClassLoaderObject() throws DebugException;
/**
* Returns the generic signature as defined in the JVM specification for
* this type. Returns <code>null</code> if this type is not a generic type.
*
* @return signature, or <code>null</code> if generic signature not
* available
* @exception DebugException
* if this method fails. Reasons include:
* <ul>
* <li>Failure communicating with the VM. The
* DebugException's status code contains the underlying
* exception responsible for the failure.</li>
* <ul>
* @since 3.1
*/
public String getGenericSignature() throws DebugException;
/**
* Returns the unqualified name of the source file corresponding to this
* type, or <code>null</code> if source name debug attribute is not present.
* The source name returned is based on this target's default stratum.
*
* @return unqualified source file name or <code>null</code>
* @throws DebugException
* if an exception occurs retrieving the source name
* @since 3.2
*/
public String getSourceName() throws DebugException;
/**
* Returns the unqualified names of the source files corresponding to this
* type in the specified stratum, or <code>null</code> if the source name
* debug attribute is not present.
*
* @param stratum
* stratum identifier or <code>null</code> to use this type's
* default stratum
* @return unqualified source file names or <code>null</code>
* @throws DebugException
* if an exception occurs retrieving the source name
* @since 3.2
*/
public String[] getSourceNames(String stratum) throws DebugException;
/**
* Returns the qualified names of the source files corresponding to this
* type in the specified stratum, or <code>null</code> if the source name
* debug attribute is not present.
*
* @param stratum
* stratum identifier or <code>null</code> to use this type's
* default stratum
* @return qualified source file names or <code>null</code>
* @throws DebugException
* if an exception occurs retrieving the source name
* @since 3.2
*/
public String[] getSourcePaths(String stratum) throws DebugException;
/**
* Retrieves and returns instances of this reference type.
*
* @param max
* the maximum number of instances to retrieve or 0 to retrieve
* all instances
* @return instances of this reference type
* @throws DebugException
* on failure
* @since 3.3
*/
public IJavaObject[] getInstances(long max) throws DebugException;
/**
* Returns the number of instances of this type currently allocated in the
* target virtual machine, or -1 if instance counts are not supported by the
* target.
*
* @return number of instances of this type, or -1 if unsupported
* @throws DebugException
* on failure
* @since 3.6
*/
public long getInstanceCount() throws DebugException;
}