/*
* Licensed to the Apache Software Foundation (ASF) under one or more
* contributor license agreements. See the NOTICE file distributed with
* this work for additional information regarding copyright ownership.
* The ASF licenses this file to You under the Apache License, Version 2.0
* (the "License"); you may not use this file except in compliance with
* the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package flash.tools.debugger;
import flash.tools.debugger.concrete.DVariable;
/**
* An ActionScript value, for example, the value of a variable or constant.
*
* @author mmorearty
*/
public interface Value
{
/**
* A special object representing ActionScript's "undefined" value.
*/
public static final Object UNDEFINED = new Object() {
@Override
public String toString() {
return "undefined"; //$NON-NLS-1$
}
};
/**
* The value returned if somone calls getId() for a Variable
* which stores a variable of simple type such as String or
* integer, rather than an Object or MovieClip.
* @see getId()
*/
public static final long UNKNOWN_ID = -1;
/**
* The special ID for pseudo-variable "_global". (Note, this only
* exists in AS2, not AS3.)
* @see getId()
*/
public static final long GLOBAL_ID = -2;
/**
* The special ID for pseudo-variable "this".
* @see getId()
*/
public static final long THIS_ID = -3;
/**
* The special ID for pseudo-variable "_root". (Note, this only
* exists in AS2, not AS3.)
* @see getId()
*/
public static final long ROOT_ID = -4;
/**
* The special ID for the top frame of the stack. Locals and
* arguments are "members" of this pseudo-variable.
*
* All the stack frames have IDs counting down from here. For example,
* the top stack frame has ID <code>BASE_ID</code>; the next
* stack frame has ID <code>BASE_ID - 1</code>; and so on.
*
* @see getId()
*/
public static final long BASE_ID = -100;
/**
* _level0 == LEVEL_ID, _level1 == LEVEL_ID-1, ...
*
* all IDs below this line are dynamic.
*/
public static final long LEVEL_ID = -300;
/**
* The return value of getTypeName() if this value represents the traits of a class.
*/
public static final String TRAITS_TYPE_NAME = "traits"; //$NON-NLS-1$
/**
* Variable type can be one of VariableType.OBJECT,
* VariableType.FUNCTION, VariableType.NUMBER, VariableType.STRING,
* VariableType.UNDEFINED, VariableType.NULL.
*/
public int getType();
/**
* The type name of the value:
*
* <ul>
* <li> <code>"Number"</code> </li>
* <li> <code>"Boolean"</code> </li>
* <li> <code>"String"</code> </li>
* <li> <code>"null"</code> </li>
* <li> <code>"undefined"</code> </li>
* <li> <code>Value.TRAITS_TYPE_NAME</code> if this value represents the
* traits of a class </li>
* <li> <code>"[package::]Classname@hexaddr"</code> if this value
* represents an instance of a non-primitive object. For example, if this is
* an instance of mx.core.Application, the type name might be
* "mx.core::Application@1234abcd". </li>
* </ul>
*/
public String getTypeName();
/**
* The class name of the value. This isn't actually very useful, and should
* probably go away; it had more relevant in ActionScript 2, when the return
* value from this function could have been any one of the strings returned
* by {@link DVariable#classNameFor(long, boolean)}.
*
* In the AS3 world, the only possible return values from this function are:
*
* <ul>
* <li> <code>"Object"</code> for instances of non-primitive classes such
* as Object, Array, etc. </li>
* <li> <code>""</code> all primitive values (Number, Boolean, String,
* null, undefined), or the traits of a class. </li>
* </ul>
*/
public String getClassName();
/**
* Variable attributes define further information
* regarding the variable. They are bitfields identified
* as VariableAttribute.xxx
*
* @see VariableAttribute
*/
public int getAttributes();
/**
* @see VariableAttribute
*/
public boolean isAttributeSet(int variableAttribute);
/**
* Returns a unique ID for the object referred to by this variable.
* If two variables point to the same underlying object, their
* getId() functions will return the same value.
*
* This is only meaningful for variables that store an Object or
* MovieClip. For other types of variables (e.g. integers and
* strings), this returns <code>UNKNOWN_ID</code>.
*/
public long getId();
/**
* Returns the value of the variable, as an Object. The return
* value will always be one of the following:
*
* <ul>
* <li> <code>null</code> </li>
* <li> <code>Value.UNDEFINED</code> </li>
* <li> a <code>Boolean</code> </li>
* <li> a <code>Double</code> (careful, it might be <code>Double.NaN</code>) </li>
* <li> a <code>String</code> </li>
* <li> a <code>Long</code> if this value represents a non-primitive
* type, such as an Object. If it is a Long, then it is the id of
* the Value (the same value returned by <code>getId()</code>).
* </ul>
*/
public Object getValueAsObject();
/**
* Returns the value of the variable, converted to a string. Strings
* are returned as the exact value of the string itself, with no
* extra quotation marks and no escaping of characters within the
* string.
*/
public String getValueAsString();
/**
* Returns all child members of this variable. Can only be called for
* variables of type Object or MovieClip.
* @throws NotConnectedException
* @throws NoResponseException
* @throws NotSuspendedException
*/
public Variable[] getMembers(Session s) throws NotSuspendedException, NoResponseException, NotConnectedException;
/**
* Returns a specific child member of this variable. Can only be called for
* variables of type <code>Object<code> or <code>MovieClip<code>.
* @param s the session
* @param name just a varname name, without its namespace (see <code>getName()</code>)
* @return the specified child member, or null if there is no such child.
* @throws NotConnectedException
* @throws NoResponseException
* @throws NotSuspendedException
*/
public Variable getMemberNamed(Session s, String name) throws NotSuspendedException, NoResponseException, NotConnectedException;
/**
* Returns the number of child members of this variable. If called for
* a variable which has a simple type such as integer or string,
* returns zero.
* @throws NotConnectedException
* @throws NoResponseException
* @throws NotSuspendedException
*/
public int getMemberCount(Session s) throws NotSuspendedException, NoResponseException, NotConnectedException;
/**
* Returns the list of classes that contributed members to this object, from
* the class itself all the way down to <code>Object</code> (or, if
* allLevels == false, down to the lowest-level class that actually
* contributed members).
*
* @param allLevels
* if <code>true</code>, the caller wants the entire class
* hierarchy. If <code>false</code>, the caller wants only
* that portion of the class hierarchy that actually contributed
* member variables to the object. For example,
* <code>Object</code> has no members, so if the caller passes
* <code>true</code> then the returned array of strings will
* always end with <code>Object</code>, but if the caller
* passes <code>false</code> then the returned array of strings
* will <em>never</em> end with <code>Object</code>.
* @return an array of fully qualified class names.
*/
public String[] getClassHierarchy(boolean allLevels);
/**
* Returns all child members of this variable that are private and are present
* in its inheritance chain. Only relevant after a call to getMembers().
*
* Warning: This may contain variables with the same name (when there is more
* than two level inheritance).
*/
public Variable[] getPrivateInheritedMembers();
/**
* Get all the private variables with the given name. Usually one, but more
* may be present if the inheritance chain is long.
* @param name Variable name.
*/
public Variable[] getPrivateInheritedMemberNamed(String name);
/**
* Get the worker id of the isolate to which this value belongs.
*/
public int getIsolateId();
}