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

Fields

Modifier and Type	Field and Description
protected int	currentID
protected int	selectedID
protected boolean	skipFlag
protected int	skipID
protected LogicProgrammingState	state
protected java.util.HashMap<java.lang.Integer,java.lang.Integer>	stepIDConv
protected int	waitingForReturnFromSkip

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

kahina

Constructor Summary

Constructors

Constructor and Description
LogicProgrammingBridge(LogicProgrammingInstance<?,?,?,?> kahina)

Method Summary

Methods

Modifier and Type	Method and Description
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	deregister()
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, java.lang.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, java.lang.String newDescription)
void	exit(int extID, boolean deterministic, java.lang.String newDescription, java.lang.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()
char	getBridgeState()
protected int	getParentCandidateID()
protected boolean	isPaused()
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	maybeUpdateStepCount(boolean firstEncounter) Update step count in GUI.
protected void	performBreakAction(java.lang.String agentString)
protected void	performCompleteAction(java.lang.String agentString)
protected void	performCreepAction(java.lang.String agentString)
protected void	performFailAction(java.lang.String agentString)
protected void	performSkipAction(java.lang.String agentString)
protected void	processControlEvent(KahinaControlEvent e)
void	processEvent(KahinaEvent e)
protected void	processSelectionEvent(KahinaSelectionEvent e)
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, java.lang.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	setBridgeState(char bridgeState)
protected void	setParentCandidateID(int parentCandidateID)
void	step(int extID, java.lang.String type) Variant of step(int, String, String, String) that uses the same string for type, description and console message.
void	step(int extID, java.lang.String predicate, java.lang.String description) Variant of step(int, String, String, String) that uses the same string for description and console message.
void	step(int extID, java.lang.String type, java.lang.String description, java.lang.String consoleMessage) For each new procedure box that is created, this method or one of its variants must first be called.
int	virtualRedo(int stepID)
void	warning(java.lang.String message)

Methods inherited from class java.lang.Object

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

Field Detail

stepIDConv

protected java.util.HashMap<java.lang.Integer,java.lang.Integer> stepIDConv

currentID

protected int currentID

selectedID

protected int selectedID

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

deregister

public void deregister()

Overrides:

deregister in class KahinaBridge

step

public void step(int extID,
        java.lang.String type,
        java.lang.String description,
        java.lang.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,
        java.lang.String predicate,
        java.lang.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,
        java.lang.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,
                                  java.lang.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 -

virtualRedo

public int virtualRedo(int stepID)

exit

public void exit(int extID,
        boolean deterministic)

exit

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

exit

public void exit(int extID,
        boolean deterministic,
        java.lang.String newDescription,
        java.lang.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,
             java.lang.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(java.lang.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

isPaused

protected boolean isPaused()

selectIfPaused

protected void selectIfPaused(int stepID)

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

maybeUpdateStepCount

protected void maybeUpdateStepCount(boolean firstEncounter)

Update step count in GUI. In fast-forward mode, this is only done every 100 steps to reduce graphics load.

Parameters:

firstEncounter - Should be true at call and redo goals, false otherwise. The latter avoids unnecessary multiple updates per step.

generateStep

protected LogicProgrammingStep generateStep()

Overrides:

generateStep in class KahinaBridge

processEvent

public void processEvent(KahinaEvent e)

Specified by:

processEvent in interface KahinaListener

Overrides:

processEvent 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

performSkipAction

protected void performSkipAction(java.lang.String agentString)

performCompleteAction

protected void performCompleteAction(java.lang.String agentString)

performCreepAction

protected void performCreepAction(java.lang.String agentString)

performFailAction

protected void performFailAction(java.lang.String agentString)

performBreakAction

protected void performBreakAction(java.lang.String agentString)

setBridgeState

public void setBridgeState(char bridgeState)

getBridgeState

public char getBridgeState()

getParentCandidateID

protected int getParentCandidateID()

setParentCandidateID

protected void setParentCandidateID(int parentCandidateID)