/*
* Copyright (c) 2019, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Oracle designates this
* particular file as subject to the "Classpath" exception as provided
* by Oracle in the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
* or visit www.oracle.com if you need additional information or have any
* questions.
*/
package org.graalvm.tools.insight.test;
// @formatter:off
import java.util.Map;
import java.util.function.Predicate;
import org.graalvm.tools.insight.Insight;
// BEGIN: InsightAPI
Instance of this class is accessible via insight variable in the Insight scripts registered to the instrument. /** Instance of this class is accessible via {@code insight} variable
* in the Insight scripts registered to the instrument.
*/
public interface InsightAPI {
ID of the instrument. Version 0.5 has been released as part of GraalVM 20.1 release. Returns: same value of Insight.ID - e.g. "insight" Since: 0.3
/** ID of the instrument. Version {@code 0.5} has been released as
* part of GraalVM 20.1 release.
*
* @return same value of {@link Insight#ID} - e.g. {@code "insight"}
* @since 0.3
*/
String id();
Version of the API. Version 0.1 has been released as part of GraalVM 19.3.0 release. Returns: same value of Insight.VERSION Since: 0.1
/** Version of the API. Version {@code 0.1} has been released as
* part of GraalVM 19.3.0 release.
*
* @return same value of {@link Insight#VERSION}
* @since 0.1
*/
String version();
Marker interface for any handler.
Since: 0.1
/** Marker interface for any handler.
* @since 0.1
*/
interface Handler {
}
interface SourceInfo {
Name of the OnSourceLoadedHandler.sourceLoaded. Returns: name of the loaded source Since: 0.1
/** Name of the {@link OnSourceLoadedHandler#sourceLoaded}.
* @return name of the loaded source
* @since 0.1
*/
String name();
Character content of the OnSourceLoadedHandler.sourceLoaded. Returns: content of the loaded source Since: 0.1
/** Character content of the {@link OnSourceLoadedHandler#sourceLoaded}.
* @return content of the loaded source
* @since 0.1
*/
String characters();
Identification of this source's language.
Returns: String representing the language ID Since: 0.1
/** Identification of this source's language.
* @return String representing the language ID
* @since 0.1
*/
String language();
Mime type of this source.
Returns: given mime type or null Since: 0.1
/** Mime type of this source.
* @return given mime type or {@code null}
* @since 0.1
*/
String mimeType();
URI uniquely identifying the source.
Returns: the URI Since: 0.1
/** URI uniquely identifying the source.
* @return the URI
* @since 0.1
*/
String uri();
}
@FunctionalInterface
interface OnSourceLoadedHandler extends Handler {
Called when a new source is loaded into the system.
Params: - info – information about the loaded source
Since: 0.1
/** Called when a new source is loaded into the system.
* @param info information about the loaded source
* @since 0.1
*/
void sourceLoaded(SourceInfo info);
}
Register a handler to be notified when a source is loaded.
Params: - event – has to be
"source" string - handler – a callback that takes
one argument
/** Register a handler to be notified when a source is loaded.
*
* @param event has to be {@code "source"} string
* @param handler a callback that takes
* {@link SourceInfo one argument}
*/
void on(String event, OnSourceLoadedHandler handler);
@FunctionalInterface
interface OnEventHandler extends Handler {
interface Context {
Name of the enclosing function.
Returns: the name of the enclosing function Since: 0.1
/** Name of the enclosing function.
* @return the name of the enclosing function
* @since 0.1
*/
String name();
Information about surrounding source.
Returns: information about the surrounding source Since: 0.4
/** Information about surrounding source.
* @return information about the surrounding source
* @since 0.4
*/
SourceInfo source();
Characters of the location.
Returns: the characters of this Context Since: 0.4
/** Characters of the location.
* @return the characters of this {@link Context}
* @since 0.4
*/
String characters();
Line of this location. The same as startLine(). Returns: line number counting from one Since: 0.4
/** Line of this location. The same as {@link #startLine()}.
*
* @return line number counting from one
* @since 0.4
*/
int line();
Staring line of this location.
Returns: line number counting from one Since: 0.4
/** Staring line of this location.
*
* @return line number counting from one
* @since 0.4
*/
int startLine();
Final line of this location.
Returns: line number counting from one Since: 0.4
/** Final line of this location.
*
* @return line number counting from one
* @since 0.4
*/
int endLine();
Column of this location. The same as startColumn(). Returns: column number counting from one Since: 0.4
/** Column of this location. The same as {@link #startColumn()}.
*
* @return column number counting from one
* @since 0.4
*/
int column();
Starting column of this location.
Returns: column number counting from one Since: 0.4
/** Starting column of this location.
*
* @return column number counting from one
* @since 0.4
*/
int startColumn();
Final column of this location.
Returns: column number counting from one Since: 0.4
/** Final column of this location.
*
* @return column number counting from one
* @since 0.4
*/
int endColumn();
The current return value to be returned unless returnNow is called. The only meaningful values can be expected inside of on("return", ...) handlers. Params: - frame – object with variables provided as a second parameter to
event method
Returns: the current return value or null, if not applicable Since: 0.7
/** The current return value to be returned unless
* {@link #returnNow} is called. The only meaningful
* values can be expected inside of {@link #on on("return", ...)}
* handlers.
*
* @param frame object with variables provided
* as a second parameter to {@link OnEventHandler#event event}
* method
* @return the current return value or {@code null},
* if not applicable
* @since 0.7
*/
Object returnValue(Map<String, Object> frame);
Immediatelly exits the current handler and returns to the caller. Calling this method aborts execution of the current handler. It bypasses language sematics and immediatelly returns the provided value to the caller. If there are multiple calls to returnNow (from different handlers) the first call defines the return value. Params: - value – the value to return to the caller
See Also: Since: 0.7
/** Immediatelly exits the current handler and returns to the
* caller. Calling this method aborts execution of the current
* handler. It bypasses language sematics and immediatelly
* returns the provided value to the caller. If there are multiple
* calls to {@code returnNow} (from different handlers) the
* first call defines the return value.
*
* @param value the value to return to the caller
* @since 0.7
* @see #returnValue(java.util.Map)
*/
void returnNow(Object value);
}
void event(Context ctx, Map<String, Object> frame);
}
class OnConfig {
public boolean expressions;
public boolean statements;
public boolean roots;
String with a regular expression to match name of functions. Prior to version 0.6 this had to be a Function<String,Boolean>. /** String with a regular expression to match name of functions.
* Prior to version 0.6 this had to be a
* {@code Function<String,Boolean>}.
*/
public String rootNameFilter;
/* @since 0.4 */
public Predicate<SourceInfo> sourceFilter;
}
Register a handler on a particular elements in the source code.
Params: - event – one of
"enter", "return" strings - handler – callback
function with two arguments - config – config object to identify locations to listen to
/** Register a handler on a particular elements in the source code.
*
* @param event one of {@code "enter"}, {@code "return"} strings
* @param handler callback
* {@link OnEventHandler#event function with two arguments}
* @param config config object to identify locations to listen to
*/
void on(String event, OnEventHandler handler, OnConfig config);
@FunctionalInterface
interface OnCloseHandler extends Handler {
void closed();
}
Register on close handler.
Params: - event – must be
"close" string - handler – no args function to be notified when execution ends
/** Register on close handler.
*
* @param event must be {@code "close"} string
* @param handler no args function to be notified when execution ends
*/
void on(String event, OnCloseHandler handler);
Unregisters a handler.
Params: - event – the event type to unregister from
- handler – the instance of handler registered by one of the
on methods
Since: 0.2
/** Unregisters a handler.
*
* @param event the event type to unregister from
* @param handler the instance of handler registered
* by one of the {@code on} methods
* @since 0.2
*/
void off(String event, Handler handler);
}
// END: InsightAPI