AgileBrowser

Revision as of 07:33, 17 May 2011

Download AgileBrowser installer

Introduction

Agile Browser is a free architecture management tool. It abstracts and visualizes software models of MeeGo OS. The main focus is to provide easier access to up-to-date architecture information gathered from multiple sources. The models contain stuctural and dependendency information. There are several types of external attributes to be attached to the information. Users of AgileBrowser can navigate, search, highlight with colors, share and export diagrams in various abstraction levels according to their individual needs.

Installing and running Agile Browser

Installer package is available in this wiki: File:AgileBrowser.zip

Agile Browser can be run on Windows, Mac, Linux, etc., anywhere where Java is supported. The most important requirement is that the tool is memory expensive so it is recommended to have 1 GB RAM or fast swapping.

Using Agile Browser

The following image is the overview of the Agile Browser. Diagram highlights the main areas of the Agile Browser user interface. Each section is is described in detail below.

Graph View basics and Navigation buttons

• Double click an element to view it or its neighbourhood
• Zoom with the mouse wheel or + and - buttons
• Use detail level in the right side screen to define how detailed views are generated. Detail integer represents the depth of model hierarchy.
• Use the Navigation mode (cross) button or arrow buttons to pan around without zooming. Also moving the area in Small View pans the view.
• To fit content on the graph is done either by refreshing (F5) from the View menu or by pressing the circle between the navigation arrows on the screen.
• Back and Forward in the toolbar work just as with an internet browser.
• Fullscreen mode (4th button from the left) is to obtain the maximized area of the screen for the graph (double clicking an element works also here).
• Advanced Search (5th button from the left) is for constructing search language phrases in graphical format.
• Home button resets the graph to package level (root with detail level 3).
• Star is for managing bookmarks. From here user can add/remove favourite bookmarks.
• Quick Help is to get help for small problems.

Examining dependency graphs

For visualizing incoming dependencies, use Dependencies setting with value Incoming. As an opposite of that, view outgoing dependencies with Outgoing. In case you want to visualize both incoming (users) and outgoing, select In and Out.

In addition to Dependencies selection, dependency view can be activated from context menu. E.g. there are External Users View (same as incoming deps) and Externally Used Elements View (outgoing deps).

Model browsing in tree views

There is structure browsing enabled in Model tree view.

Locating SW elements

Use query field at the top of the screen with element name.

Search Tree

AgileBrowser Search Tree displays all the search results. Tree is updated when search query is entered to search field or when user surfs in the model. Search results are categorized in tree.

There are 3 different types of search matches (those can be seen from the Search Tree image):

• Attribute match ('a' in tree) indicates that there was some attribute match in this element.
• Element match ('e' in tree) indicates that there was element naming match.
• Dependency match ('d' in tree) indicates that there was some dependency match in this element.

All these results contain a tooltip which shows what was match type and what was matched (matched string with capital letters).

Search Tree actions

Search Tree contains following actions that user can do:

• by double clicking an element graph is updated and double clicked element is shown.
• Show Selected Items as a Graph via mouse popup shows the selected items as a graph. Multiple items can be selected from the tree by holding CTRL.
• Show Users as a Graph draws all the incoming dependencies to selected element.
• Show Used as a Graph draws all the outcoming dependencies from the selected element.
• Expand All expands the whole search result tree.
• Collapse All collapses the whole search result tree.

Info View

Info View is for obtaining more information of the selected element. If no elements are selected Info panel is empty. Once some element is selected (a SW element or a dependency arrow, doesn't support multiple selection mode) in the main Graph View, the Info panel shows all related attributes. The set of available attributes depends on the model, the type of the selected SW element and the availability of optional, separate attribute files. The following basic attributes are widely available:

Legend View

Legend View is for displaying all the matching colors and values for selected attributes that user wants to highlight from the graph. If user selects e.g some string valued attribute to be as coloring method. Then Legend View is updated and show all the matching colors with attribute values. Also it is possible to change color by double clicking color from the legend view and then selecting a new color from the RGB picker.

From the figure below it is possible to see how the Legend View looks if type attribute is selected to be as coloring method.

Basic attributes for SW elments

• type Open-ended type of selected SW element, e.g. layer, package, collection, component, binary (e.g. executable), API etc..
• description Short description of the selected SW element.
• members Member functions, variables and enumerations. Not available in MeeGo models.
• sources Source code files of the element. Not available in MeeGo models.
• owner Owner of the element.
• maintainer Maintainer of the element.
• name Element name.
• user_count Count of the user elements of the element.
• used_count Count of the used elements by the element.
• coupling coupling metric that is calculated on model load. High values (near to 1) represent an element that is easily movable.

Basic attributes for dependencies

• type or typelist Type of selected dependency. Typelist replaces type if the selected dependency is a composition of several lower-level dependency types. Typelist also contains counts for each listed dependency type.
• count Number of lower level dependencies the selected dependency arrow consists of. This number is also reflected in the arrow thickness in Graph View.

Graph View Parameters (Properties)

Properties pane in AgileBrowser contains all the content rules for constructing the graph, automatic layouting and attribute highlighting functions. Properties panel looks like following:

Filtering

Detail level. This parameter adjusts depth of hierarchy in the current view. You can see a description of the current detail level in a tooltip by pointing to this item. "If only one element is visible, try increasing the depth to see what it contains!"

Dependencies. This parameter defines how far the dependency network is traversed.

• No Dependencies means that no dependencies are shown, only the elements.
• Internal means that dependencies are shown only if they are between the elements matching the search field. E.g. "internal" dependencies of the selected scope.
• Incoming determines that all elements that are using on of the scoped elements are also shown, with the dependency edges.
• Outgoing determines that all elements that are used by the scoped elements are also shown, with the dependency edges.
• In and Out combines the previous two into single view.

Post Filter. Filter that is applied in the last phase of graph construction. Visible items can be filtered out using the same rules than in Search Field. See Search language for detailed information.

Dependency types in the model

Dependency types are visible in graphs and as tooltips. The dependency types currently available are:

• dynamic a dynamic dependency exists only run-time.
• TODO Complete full descriptions

Automatic layout

Automatic layout is used for layouting the currently visible graph. Default layout is default layout and other layouts are applied only when dependencies are available in the graph. Currently following automatic layouts are available:

• default
• hierarchic
• orthogonal
• organic
• left-to-right

Attribute highlighting

Attribute highlighting is for element representation. Elements can be colored by attributes, restrict coloring to specific detail level, elements area/height/width can be scaled by using some numeric attributes and Condensed view mode can be toggled on/off.

• Coloring

If numeric attribute is selected to be as element coloring method then coloring uses a green, yellow and red scale to highlight the attribute. Red is used for maximum value and green for the minimum value.

If textual attribute is selected to be as element colouring method then random colours are used and Legend View shows the matching attribute with value to the color.

• Force Colors

Restricts coloring to some detail level. Means that if level 3 is chosen to be force color level, then colored elements are only available in detail levels 0-3.

• Area/Height/Width

Attributes that have numeric values can be represented as element area size, element width or as element height. Bigger the value then the area/height/width is bigger.

• Condensed

Condensed view mode is a representaton mode where all the child elements are listed inside the leaf element. This is used to get more information into graph in more compact way.

Search Field

Search Field is used to search some content from the build and represent results in a graphical format. Also the results are displayed in tree format in Search Tree.

The field has a dual role: it may either contain an absolute Element ID, e.g the "address" of an SW element in the SW build, such as "/sf/app/camera" for the camera Package. Or it may contain a search string which can be for example:

• a binary name
• a folder name or element name, e.g. /sf/app
• part of a name, e.g. contacts
• a class name or part of it
• a method name or part of it
• a combined Class::Method name
• some text that is contained in a description
• combination of many search strings separated with AND/OR/NOT operations.

|}} Note: {{#if: Note: text matching of the search functionality needs to be set up from menu: Tools->Preferences->General.|Note: text matching of the search functionality needs to be set up from menu: Tools->Preferences->General.

Search language

Search language provides filtering nodes or dependencies. For example, query phoneapp AND uicontrol means that both of these texts must be found in the element ID. This query is an example of a node filter.

Dependencies can be searched with a dependency operator, (-->) e.g. Query '/sf/app/phone --> /sf/mw produces all immediate dependencies between these elements or their descendants (actual binaries).

The following language elements are supported in the expression/query:

• Anything that is inside quotation marks is interpreted as an exact search.
• parentheses ()
• Logical or: OR Example usage: phoneapp OR phoneengine
• Logical and: AND Example usage: phoneapp AND uicontrol
• Logical not: NOT Example usage: phoneapp AND NOT voip
• Equals: = Example usage: @attributename=somevalue
• Not equals: != Example usage: @attributename!=somevalue
• Greater than: > Example usage: @attributename>10
• Less than: <: Example usage: @attributename<10
• Dependency search: --> Example usage: /sf/app --> /sf/os
• Dependency search with a dependency type filter: -type->: Example usage: /sf/app -dynamic-> /sf/mw
• Undirected dependency search: --: Example usage: /sf/app/phone -- /sf/os
• Undirected dependency search with an attribute filter : --: Example usage: /sf/app/phone -- /sf/os@category=platform
• Undirected dependency search with a dependency type filter: -type-: Example usage: /sf/app/phone -ecom- /sf/mw

Combining expressions is possible:

• ( @used_count>50 OR @user_count>50 ) AND /os/
  • This means that every element is selected under /os/ (which happens to be layer in SF) which has either HSE metric more than 10 or bug estimate percent more than 10.
• dlna OR upnp OR @tech_domain=ma
  • Elements containing DLNA or UPNP terms in their name (or in description if configured so) or from tech_domain ma.
• @type=interface AND /mw/
  • All elements which id contains /mw/ and attribute named type has value interface.

{{#if: Note:

• When using binary operators <, >, = and != do not put whitespace around them.
• Dependency search is most useful with Dependency Level set to 1.|
  |}} Note: {{#if: Note:
• When using binary operators <, >, = and != do not put whitespace around them.
• Dependency search is most useful with Dependency Level set to 1.|Note:
• When using binary operators <, >, = and != do not put whitespace around them.
• Dependency search is most useful with Dependency Level set to 1.