org.kahina.lp.bridge
Class LogicProgrammingBridge

java.lang.Object
  org.kahina.core.bridge.KahinaBridge
      org.kahina.lp.bridge.LogicProgrammingBridge

All Implemented Interfaces:

KahinaListener

Direct Known Subclasses:

PrologBridge, TraleSLDBridge

public class LogicProgrammingBridge
extends KahinaBridge

The logic programming bridge is the most important object that you work with when you connect a logic programming system to Kahina that has tracing capabilities following the procedure box model. Its public methods take information about the control flow and properties of procedure boxes ("steps" in Kahina terminology) and turn it into information that can be displayed by Kahina's views.

Logic programming systems that have been connected to Kahina using specialized subclasses of LogicProgrammingBridge so far include TRALE, QType and, experimentally, SWI-Prolog and SICStus Prolog. The connection typically involves some Prolog code that hooks into the tracer of the respective LP system and calls Kahina's Java API via a Prolog/Java connection layer such as Jasper or JPL.

A Kahina "session" corresponds to the execution of one query in a LP system. A new bridge is created, and all views are cleared, when a new session is started. A session is started by calling the KahinaInstance.startNewSession() method of an instance of the KahinaInstance subclass that is specialized for the respective LP system. This method returns the bridge for that session. The bridge is then used to transmit all tracing information about a query to Kahina.

Field Summary

protected char	bridgeState
protected int	currentID
protected int	parentCandidateID
protected int	selectedID
protected boolean	skipFlag
protected int	skipID
protected LogicProgrammingState	state
protected HashMap<Integer,Integer>	stepIDConv
protected int	waitingForReturnFromSkip

Fields inherited from class org.kahina.core.bridge.KahinaBridge

kahina

Constructor Summary

LogicProgrammingBridge(LogicProgrammingInstance<?,?,?> kahina)

Method Summary

void	call(int extID) Called, typically following a call to #step(int, String, Stirng, String) very soon, to indicate that the call port of the procedure box with the given ID has been reached.
protected boolean	canSkipOrAutocomplete()
protected int	convertStepID(int extID) convert external step IDs to internal IDs corresponding to tree nodes uses entries in stepIDConv table, extending it together with the tree if no entry was found
void	end(int extID) Call this to indicate that the top query succeeded or failed, providing the step ID of the top query.
void	exception(int extID, String message) Called to indicate that the exception port of the procedure box with the given ID has been reached.
void	exit(int extID, boolean deterministic)
void	exit(int extID, boolean deterministic, String newDescription)
void	exit(int extID, boolean deterministic, String newDescription, String newConsoleMessage) Called to indicate that the exit port of the procedure box with the given ID has been reached.
void	fail(int extID) Called to indicate that the fail port of the procedure box with the given ID has been reached.
protected LogicProgrammingStep	generateStep()
char	getAction()
protected boolean	isQueryRoot(int stepID) Call to check if a given step has the special property of being the query root, i.e.
void	linkNodes(int anchor, int target) Introduces a "secondary edge" to the control flow tree, e.g.
protected void	processBreakPointMatch(int nodeID, KahinaBreakpoint bp)
protected void	processControlEvent(KahinaControlEvent e)
protected void	processCreepPointMatch(int nodeID, KahinaBreakpoint bp)
protected void	processFailPointMatch(int nodeID, KahinaBreakpoint bp)
protected void	processSelectionEvent(KahinaSelectionEvent e)
protected void	processSkipPointMatch(int nodeID, KahinaBreakpoint bp)
protected void	processSystemEvent(KahinaSystemEvent e)
protected void	processWarnEvent(KahinaWarnEvent e)
void	redo(int extID) Called to indicate that the redo port of the procedure box with the given ID has been reached.
void	registerLayer(int extID, int layer)
void	registerStepSourceCodeLocation(int extID, String absolutePath, int lineNumber) Registers the source code location connected to a step for display in the source code view.
void	select(int extID) Call this to force the GUI to select the indicated step and update, e.g.
protected void	selectIfPaused(int stepID) Selects the given step and updates the GUI if the debugger is not currently leaping or autocompleting.
void	step(int extID, String type) Variant of step(int, String, String, String) that uses the same string for type, description and console message.
void	step(int extID, String predicate, String description) Variant of step(int, String, String, String) that uses the same string for description and console message.
void	step(int extID, String type, String description, String consoleMessage) For each new procedure box that is created, this method or one of its variants must first be called.
void	warning(String message)

Methods inherited from class org.kahina.core.bridge.KahinaBridge

processEvent, processEvent, processProfilePointMatch

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

stepIDConv

protected HashMap<Integer,Integer> stepIDConv

currentID

protected int currentID

parentCandidateID

protected int parentCandidateID

selectedID

protected int selectedID

bridgeState

protected volatile char bridgeState

skipFlag

protected boolean skipFlag

waitingForReturnFromSkip

protected int waitingForReturnFromSkip

skipID

protected int skipID

state

protected LogicProgrammingState state

Constructor Detail

LogicProgrammingBridge

public LogicProgrammingBridge(LogicProgrammingInstance<?,?,?> kahina)

Method Detail

step

public void step(int extID,
                 String type,
                 String description,
                 String consoleMessage)

For each new procedure box that is created, this method or one of its variants must first be called. It is separate from call(int) for historic reasons and for flexibility, e.g. it can be overloaded with various arguments representing all kinds of information about a step without touching the call method. Note however that information about a step that is not absolutely central, such as source code locations, should be sent to Kahina using specialized methods following the call to the step method.

Parameters:

extID - An ID identifying the procedure box uniquely.

type - A string identifying the type of the step, e.g. a Prolog predicate identifier such as append/3. Will be used for categorizing and counting steps in the profiler.

description - A full description of the step, such as append([1,2],[3,4],X). Will be used for labeling nodes in the control flow graph.

consoleMessage - A more extensive description of the (type of) the step, such as a prose description of what append/3 does. Will be displayed in the message console.

step

public void step(int extID,
                 String predicate,
                 String description)

Variant of step(int, String, String, String) that uses the same string for description and console message.

Parameters:

extID -

predicate -

description -

step

public void step(int extID,
                 String type)

Variant of step(int, String, String, String) that uses the same string for type, description and console message.

Parameters:

extID -

type -

registerStepSourceCodeLocation

public void registerStepSourceCodeLocation(int extID,
                                           String absolutePath,
                                           int lineNumber)

Registers the source code location connected to a step for display in the source code view. TODO: Different ports of a procedure box may have different source code locations.

Parameters:

extID -

absolutePath -

lineNumber -

registerLayer

public void registerLayer(int extID,
                          int layer)

call

public void call(int extID)

Called, typically following a call to #step(int, String, Stirng, String) very soon, to indicate that the call port of the procedure box with the given ID has been reached. This will cause the corresponding node to appear in Kahina's control flow graph.

Parameters:

extID -

redo

public void redo(int extID)

Called to indicate that the redo port of the procedure box with the given ID has been reached. This will create a copy of the original step in Kahina's data model, and a new node in Kahina's control flow graph, distinct from nodes created by previous calls and redos of the box, but labeled with the same ID. Internally, Kahina uses a different set of IDs to distinguish different "instantiations" of the same procedure box when it is redone.

Parameters:

extID -

exit

public void exit(int extID,
                 boolean deterministic)

exit

public void exit(int extID,
                 boolean deterministic,
                 String newDescription)

exit

public void exit(int extID,
                 boolean deterministic,
                 String newDescription,
                 String newConsoleMessage)

Called to indicate that the exit port of the procedure box with the given ID has been reached.

Parameters:

extID -

deterministic - true if the box has exited deterministically, i.e. is guaranteed never to be redone again. If you cannot get this information from your LP system, the recommended default is false.

isQueryRoot

protected boolean isQueryRoot(int stepID)

Call to check if a given step has the special property of being the query root, i.e. when it exits (deterministically) or fails, the whole session is over.

Parameters:

stepID -

Returns:

fail

public void fail(int extID)

Called to indicate that the fail port of the procedure box with the given ID has been reached.

Parameters:

extID -

exception

public void exception(int extID,
                      String message)

Called to indicate that the exception port of the procedure box with the given ID has been reached.

Parameters:

extID -

warning

public void warning(String message)

linkNodes

public void linkNodes(int anchor,
                      int target)

Introduces a "secondary edge" to the control flow tree, e.g. for marking the corresponding blocking step (target) for a given unblocking step (anchor).

Parameters:

anchor -

target -

end

public void end(int extID)

Call this to indicate that the top query succeeded or failed, providing the step ID of the top query. The bridge will then go back into creep mode.

select

public void select(int extID)

Call this to force the GUI to select the indicated step and update, e.g. before pausing to present the user with a result.

Parameters:

extID -

getAction

public char getAction()

Returns:

the action command for the tracer. Currently supported are: 'c' for creep, 's' for skip, 'f' for fail, 'a' for abort and 'n' if there is no action available yet, e.g. because the user hasn't clicked a button yet. In this case, clients should wait a few milliseconds and call this method again.

convertStepID

protected int convertStepID(int extID)

convert external step IDs to internal IDs corresponding to tree nodes uses entries in stepIDConv table, extending it together with the tree if no entry was found

Returns:

an internal step ID corresponding to the external ID

selectIfPaused

protected void selectIfPaused(int stepID)

Selects the given step and updates the GUI if the debugger is not currently leaping or autocompleting.

generateStep

protected LogicProgrammingStep generateStep()

Overrides:

generateStep in class KahinaBridge

processSystemEvent

protected void processSystemEvent(KahinaSystemEvent e)

Overrides:

processSystemEvent in class KahinaBridge

processWarnEvent

protected void processWarnEvent(KahinaWarnEvent e)

Overrides:

processWarnEvent in class KahinaBridge

processControlEvent

protected void processControlEvent(KahinaControlEvent e)

Overrides:

processControlEvent in class KahinaBridge

canSkipOrAutocomplete

protected boolean canSkipOrAutocomplete()

processSelectionEvent

protected void processSelectionEvent(KahinaSelectionEvent e)

Overrides:

processSelectionEvent in class KahinaBridge

processSkipPointMatch

protected void processSkipPointMatch(int nodeID,
                                     KahinaBreakpoint bp)

Overrides:

processSkipPointMatch in class KahinaBridge

processCreepPointMatch

protected void processCreepPointMatch(int nodeID,
                                      KahinaBreakpoint bp)

Overrides:

processCreepPointMatch in class KahinaBridge

processFailPointMatch

protected void processFailPointMatch(int nodeID,
                                     KahinaBreakpoint bp)

Overrides:

processFailPointMatch in class KahinaBridge

processBreakPointMatch

protected void processBreakPointMatch(int nodeID,
                                      KahinaBreakpoint bp)

Overrides:

processBreakPointMatch in class KahinaBridge