frysk.dom
Class DOMFrysk

java.lang.Object
  frysk.dom.DOMFrysk

public class DOMFrysk
extends Object

DOMFrysk serves as an access point to the document object model for the frysk source window. The Frysk DOM(Document Object Model) is used to model the underlying source code being debugged so that the GUI can accurately display information about it in the source window. The DOM is a dynamic model that can change depending on user actions. A tree-based API for processing XML documents, JDOM, was chosen to implement the Frysk DOM for it was found to be far easier and more intuitive to use than other open source XML manipulation APIs. Since both the Frysk GUI and JDOM are written in Java, using it just made sense from that standpoint too. For more information regarding JDOM, see http://www.jdom.org. The DOM is under constant construction during this phase of development. As more features are added to Frysk, more items will be added to the DOM. This is just a snapshot of the DOM as it exists now (01/07/07), although we will endeavor to keep it as current as possible. Class Structure The following diagram is the current "class" structure of the Frysk DOM. As can be seen from the tree below, the top class is the executable image itself and below it are the subclasses hanging off of it. DOMFrysk - the overall DOM DOMImage - the source images associated with this DOM DOMFunction - all functions defined for this source image DOMSource - a particular source image DOMLine - contains the info associated with each line within the source DOMInlineInstance - contains info about inline functions on a particuar source line Each one of these classes/subclasses has a set of methods to create/modify/access the information in the DOM. Here is a more detailed version of the above diagram with the methods associated with each class. In the following class/method listing, the backend code would mainly be using the setXxxx methods and the GUI part would be using the getXxxx methods. DOM Structure The following is a mock-up of what a DOM looks like with all of its nodes/elements. DOM |--PC - current program counter |--PID - Process ID of debugged process |-- attr: value - the process ID number |--Image - element: image |--attr: name - name associated with this image |--attr: filename - name of the executable |--attr: CCPATH - path to the executable |--Source - element: source |--attr: filename - name of the source file |--attr: filepath - path to the source file |--attr: include paths - list of comma-separated include paths |--attr: parsed - boolean to indicate if the GUI has parsed this source |--Function - element: function |--attr: name - name associated with this function |--attr: source name - nmae of the source file thsi comes from |--attr: char start - starting character from beginning of source file |--attr: char end - ending character from beginning of source file |--attr: line start - starting line number |--attr: end line - ending line number |--Line - element: line |--attr: number - line number to be added |--attr: pc - address where this line's executable code begins |--attr: offset - offset in characters from the beginning of the file |--attr: length - number of characters in this line |--attr: executable - boolean indicating if this line is executable |--attr: has_break - boolean indicating if this line is a breakpoint |--Tag - element: tag |--attr: type - type of tag this is(variable, keyword, etc.) |--attr: start - starting character from beginning of the file for tag |--attr: length - no. of chars the tag will encompass |--attr: token - |--Inline - element: function |--attr: function_name - name of the inline function |--attr: source - source where this function came from |--attr: start - starting char this inline function begins from the beginning of the file |--attr: end - ending char this inline function ends at |--attr: line_start - line no. where this function begins in the source file |--attr: line_end - line no. where this function ends in the source file |--attr: line_num - line of source code where this inlined code begins Debugging Scenario When a processe is debugged, no matter how activated, here are the steps that need to happen: Frysk backend identifies the PID or the executable that is to be debugged Frysk backend grabs the source code and creates a DOM adds the image adds a source file adds all functions found adds each line of the source file sends DOM to GUI sends pointer to source code to GUI GUI parses source and marks up the DOM with code highlighting information GUI brings up the source window GUI and backend communicate so GUI can update affected windows

Field Summary

private Document	data
private HashMap	imageMap Keep a cached reference to each of the requested DOMImages, thus saving a lot of work in terms of trying to find requested images and being able to return them faster after the first request through this map.
private static String	PC_ATTR
private Element	pcName
private static String	PID_ATTR The pid of the process this DOM represents
private static Element	pidValue
private static String	value

Constructor Summary

DOMFrysk(Document doc)

DOMFrysk(String name)
Creates a new DOMFrysk using the DOM contained in data

Method Summary

boolean	addImage(DOMImage image) Adds the given image to the DOM
boolean	addImage(String image_name, String CCPATH, String source_path) adds an image element to the DOM
boolean	addPID(int pid) Add the PID to the DOM
private boolean	checkImageDup(String image) checkImageDup - check to see if there is a duplicate image name
Document	getDOMFrysk() returns the DOMFrysk document
protected Element	getElement() get the root element of the DOM
DOMImage	getImage(String name) Attempts to fetch an image of the given name from the DOM.
BigInteger	getPC() get the PC(program counter)
int	getPID() get the PID associated with this DOMFrysk
void	setPC(BigInteger pc) Set the PC counter value in the DOM

Methods inherited from class java.lang.Object

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

Field Detail

PID_ATTR

private static final String PID_ATTR

The pid of the process this DOM represents

See Also:

Constant Field Values

pidValue

private static final Element pidValue

PC_ATTR

private static final String PC_ATTR

See Also:

Constant Field Values

value

private static final String value

See Also:

Constant Field Values

pcName

private final Element pcName

data

private Document data

imageMap

private HashMap imageMap

Keep a cached reference to each of the requested DOMImages, thus saving a lot of work in terms of trying to find requested images and being able to return them faster after the first request through this map.

Constructor Detail

DOMFrysk

public DOMFrysk(String name)

Creates a new DOMFrysk using the DOM contained in data

Parameters:

name - TODO

DOMFrysk

public DOMFrysk(Document doc)

Method Detail

addImage

public boolean addImage(String image_name,
                        String CCPATH,
                        String source_path)

adds an image element to the DOM

Parameters:

image_name - = the name of the image to be added

CCPATH - = the CCPATH associated with this image

source_path - = the path to the source of this image

Returns:

true if able to add the image, false if not

addImage

public boolean addImage(DOMImage image)

Adds the given image to the DOM

Parameters:

image - The DOMImage to add

Returns:

true if able to add the image, false if not

addPID

public boolean addPID(int pid)

Add the PID to the DOM

Parameters:

an - int containing the PID

Returns:

true if able to add PID, false if not

checkImageDup

private boolean checkImageDup(String image)

checkImageDup - check to see if there is a duplicate image name

Parameters:

image - is name of the image to check for

Returns:

true if there already an image of the same name, false if not

getImage

public DOMImage getImage(String name)

Attempts to fetch an image of the given name from the DOM. If no image is found returns null. Initially attempts to retrieve the image from the above HashMap cache; if the image is not contained in there but is found after some iteration through the children of this node, then it is added to the cache for future reference.

Parameters:

name - The name of the image to look for

Returns:

The DOMImage corresponding to the element, or null if no such element exists

getPID

public int getPID()

get the PID associated with this DOMFrysk

Returns:

The PID of the process that this DOM represents

getElement

protected Element getElement()

get the root element of the DOM

Returns:

The root element of the DOM

getPC

public BigInteger getPC()

get the PC(program counter)

Returns:

BigInteger program counter

setPC

public void setPC(BigInteger pc)

Set the PC counter value in the DOM

Parameters:

pc - is what the PC should be set to

getDOMFrysk

public Document getDOMFrysk()

returns the DOMFrysk document

Returns:

the DOMFrysk document