/*
* 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.events.FaultEvent;
/**
* A Variable is any ActionScript variable, such as a String, Number, etc.
* It encapsulates the concept of a type and a value.
*/
public interface Variable
{
/**
* The name of the variable.
*/
public String getName();
/**
* The fully qualified name of the variable, i.e. "namespace::name"
* if there is a namespace, or just "name" if not.
*/
public String getQualifiedName();
/**
* The namespace of the variable. This is everything before the
* "::". For example:
*
* <ul>
* <li> If a variable was declared "private var x", then the
* namespace is "ClassName$3", where "3" might be
* any number. </li>
* <li> If a variable was declared within a namespace, e.g.
* "mynamespace var x", then the namespace might be
* "http://blahblah::x", where "http://blahblah" is the URL
* of the namespace.
* <li> If a variable was declared neither public nor private
* (and is therefore "internal"), and it is inside of a
* package, then the namespace might be
* "packagename". </li>
* </ul>
*
* @return namespace or "", never <code>null</code>
*/
public String getNamespace();
/**
* Returns just the scope bits of the attributes. The scope values from
* VariableAttribute (PUBLIC_SCOPE etc.) are NOT bitfields, so the returned
* value can be compared directly to VariableAttribute.PUBLIC_SCOPE, etc.
* using "==".
*
* @see VariableAttribute
*/
public int getScope();
/**
* For a member variable of an instance of some class, its "level" indicates
* how far up the class hierarchy it is from the actual class of the instance.
* For example, suppose you have this code:
*
* <pre>
* class A { int a }
* class B extends A { int b }
* class C extends B { int c }
* var myObject: C
* </pre>
*
* In this case, for <code>myObject</code>, the "level" of variable <code>c</code>
* is 0; the level of <code>b</code> is 1; and the level of <code>a</code> is 2.
*/
public int getLevel();
/**
* The class in which this member was actually defined. For example, if class
* B extends class A, and class A has member variable V, then for variable
* V, the defining class is always "A", even though the parent variable might
* be an instance of class B.
*/
public String getDefiningClass();
/**
* 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 the value of the variable.
*/
public Value getValue();
/**
* Returns whether the value of the variable has changed since the last
* time the program was suspended. If the previous value of the
* variable is unknown, this function will return <code>false</code>.
*/
public boolean hasValueChanged(Session s);
/**
* Changes the value of a variable. New members cannot be added to a Variable,
* only the value of existing scalar members can be modified.
*
* @param type
* the type of the member which is being set. Use
* VariableType.UNDEFINED in order to set the variable to an
* undefined state; the contents of 'value' will be ignored.
* @param value
* the string value of the member. May be 'true' or 'false' for
* Boolean types or any valid number for Number types.
* @return null, if set was successful; or a FaultEvent if a setter was
* invoked and the setter threw an exception. In that case, look at
* FaultEvent.information to see the error text of the exception
* that occurred.
* @throws NoResponseException
* if times out
* @throws NotSuspendedException
* if Player is running
* @throws NotConnectedException
* if Player is disconnected from Session
*/
public FaultEvent setValue(Session s, int type, String value) throws NotSuspendedException, NoResponseException, NotConnectedException;
/**
* @return True if this variable has a getter, and the getter has not yet been invoked.
*/
public boolean needsToInvokeGetter();
/**
* Executes the getter for this variable, and changes its value accordingly. Note that
* the <code>HAS_GETTER</code> flag is not affected by this call -- even after this
* call, <code>HAS_GETTER</code> will still be true. If you want to test whether the
* getter has already been executed, call <code>needsToInvokeGetter()</code>.
* <p>
* Has no effect if <code>needsToInvokeGetter()</code> is false.
*
* @throws NotSuspendedException
* @throws NoResponseException
* @throws NotConnectedException
*/
public void invokeGetter(Session s) throws NotSuspendedException, NoResponseException, NotConnectedException;
/**
* Get the worker id of the isolate to which this value belongs.
*/
public int getIsolateId();
}