Views
AgileBrowser
Download AgileBrowser installer: File:AgileBrowser.zip
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 in Windows, Mac, Linux, etc. anywhere 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.
- 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.
Please check if the example queries can help you ("Views and queries" menu)
Open file launches a local file or a directory if it can be found on the computer, using Symbian development environment specific method, so this is not applicable in the context.
Show view in Global Folder View activates the selected element in the leftmost tree view.
Menu functionality
New creates an empty model.
Open model file opens a model file to be loaded in the tool. The formats currently supported are: Architecture XML models, line based : delimited text file, and special trace files (.txt). The type of input is detected automatically.
Open model from a URL opens a model file to be downloaded and opened from a given URL. Currently supported formats: Architecture XML models, line based : delimited text file, and special trace files (.txt). The type of input is detected automatically.
Open model from System Definition 3.0 file... opens local System Definition file and represents its in graphical format.
Save model to System Definition 3.0 file... saves currently active mode into System Definition file.
Save view to System Definition 3.0 file... saves currently visible graph view into System Definition file.
Inject Attributes from CSV file... adds attributes into the active model from a separate attribute file. CSV file must have element id in the first column (containing / characters, e.g. /sf/app/phone). Other columns are handled as attributes and the corresponding column header is interpreted as the name of the attribute.
Import any data from local file on top of current model... Imports data from local file on top of current model without loosing any existing data.
Import any data from URL on top of current model... Imports data from URL on top of current model without loosing any existing data.
Save View As.. saves current view to a file. File save supports these formats: .svg, .svgz, .jpg, .png, .gif, .ygf, .gml, .graphml. Use one of these extensions as the output file extension to select your desired format.
Save Model As .txt... Saves model in FullDeps format into .txt file. txt model can be opened again from the 'Open model file'.
Report Wizard Contains different types of reporting tools. Currently available only Dependency Info Report.
Export Wizard Contains different types of exporting methods. Currently contains:
- Export Elements exports all visible elements or only selected elements into a CSV or XML file. Element export allows grouping attribute by another attribute.
- Export Dependencies exports global the dependency set or only visible dependencies into a file (XML or CSV).
- Export Counts exports element specific usage counts or referred element counts into a file (XML or CSV).
Refresh reloads the view based on the last used query and view parameters.
Load Panel Layout Loads user configured panel layout (positions where all the UI panels are docked)
Save Panel Layout Saves user configuration for panel layout (saves the positions for UI panels) and sets this layout to be default.
Reset Panel Layout to Default Resets panel layout to factory layout.
Backward steps backward in the browsing history.
Forward steps forward in the browsing history.
Show Elements Table for Current View Shows the current visible view in a table format.
Show All Elements Table Shows the whole model in a table format.
Show Dependency Table for Current View Shows the current dependencies visible in the view in a table format.
Show All Dependency Table Shows the all dependencies in the model in a table format.
Hide Edges Hides all the visible dependencies from the current graph view.
Several layout algorithms may be invoked for the active view. Hierarchical layout is optimal for well structured and preferably tree type graphs.
Orthogonal layout provides optimal layout for dependency graphs without hierarchical alignment, but tales significantly more time than the other algorithms.
Organic layout is suitable for big and complex structures as it is quick and provides compact output. Most dependent elements will be centered.
Smart organic layout gives better control for defining compactness of the layout.
Organic Edge Router is useful for rerouting edges in the graph. It also makes the graph less compact in case of overlapping edges.
Orthogonal Edge Router is useful for rerouting edges in the graph that is orthogonally structured.
Channel Edge Router enables channel style edges between elements.
Preferences contains general, system, tooltip and node configurations.
- General contains search related configurations; what are included in search etc.
- System contains system settings like Download XML folder, Local working directory, Analysis script directory and Disk Cache Limit.
- Tooltip contains tooltip information that what attributes (with values) are displayed in element and in dependency tooltips.
- Nodes contains configuration for element label style and what attributes (with values) are displayed inside the element.
Model Information displays the detailed information of the model in textual format.
Transform contains methods for different transformation like:
- Propagate which includes several ways to propagate attribute values from elements descendants.
- Flatten Model at High Level performs flattening operation for the model, which can be used to remove high level elements. This function does not write changes to the loaded model file.
- Flatten Model at Leaf Level performs flattening operation so that model depth is reduced. This function does not write changes to the loaded model file.
- Remove Element(s) removes elements from the model. This function does not write changes to the loaded model file.
- Remove All But removes all elements excluding the given elements. This function does not write changes to the loaded model file.
- Create Attribute Data attribute data can be created based on the elements covered by the current view. Detail level is needed for restricting the set of the target elements. This function does not write changes to the loaded model file.
- Relocate APIs Together with Implementing Component not applicable for MeeGo models
- Expand Details Into Model expands file, class and function information into model if possible. This function does not write changes to the loaded model file.
Run Analysis Locally contains different methods for different analysis e.g for C/C++, Python, PHP, XSL, Java and Doxygen.
Find... (current view) searches keyword from the labels of the visible nodes.
Find from the attributes... (current view) searches the given keyword incasesensitively from the attributes of the visible nodes.
View Compare compares the current view with the corresponding view in another build.
Compare Model Against Local Model File compares the current model against the another model located in local file system.
Propose Dependency Changes in Current View traverses all the dependencies in the current view, and if cycles are found those are colored with red color.
Propose Dependency Changes in Model traverses all the dependencies in the current whole model, and if cycles are found those are colored with red color.
Open Locally Decoded MobileCrash File Opens locally decoded MobileCrash file and maps the symbols from the call stack to the current architecture model, finally visualizing the call stack in the tool. This functionality can be used multiple times without reloading the model and all crash call stacks can be visualized with search query '@mobilecrash'
File Browser scans the file system and creates a structure model with some attribute information about the files.
Copy View Parameters provides a quick way to share views with other users of AgileBrowser. Copied view parameters can be also used locally for manual bookmarking purposes.
Paste View Parameters pastes the parameters from clipboard and loads the corresponding view.
Copy Visible Elements to Clipboard as Text copies the full identifiers of the visible elements to clipboard as text
Copy Selected Elements to Clipboard as Text copies the full identifiers of the selected elements to clipboard as text.
Copy View to Clipboard as PNG copies the current view as a PNG image file to the clipboard.
Copy copies the selected element(s).
Paste pastes the copied element(s).
View Parameter concept is originally done for parametrizing the Web Start functionality of AgileBrowser 2, therefore the view parameters are transcoded as URL which contains Nokia specific part.
For example:
http://swdocwiki.nokia.com/agilebrowser2/index.php?requested=%22/sf%22&dataFile=SF.MCL_200918.xml&requestedDepth=3&depsLevel=0&dir=both&layoutName=default
This menu contains educational views on different aspects of the model. The different views show how query language works, what kind of filtering can be done and representation options.
Model Comparison
Agile Browser 2.0 supports model comparison between two models. Model Comparison is a powerful tool for getting the difference between two models. There are two different types of comparison; Numeric Comparison and Graphic/Table Comparison.
More information about Agile Browser's Model Comparison can be found from Model Comparison.
Forward Planning
Agile Browser 2.0 has limited support for forward planning. User is able to view and modify local plans. This feature is highly experimental. More information about Forward Planning can be found from Forward Planning.
View Construction
View Construction is a feature in AgileBrowser that allows incremental and more powerful construction of views, both programmatically and UI-wise. A view is a set of elements and dependencies and their metadata. View Construction is operation oriented, which means that each view is produced out of a set of operations.
More information about View Construction can be found from View Construction.
Supported Data Formats
Agile Browser 2.0 supports basically 3 different data formats; Architecture Interchange XML, Deps format and Attribute file format.
Model and dependencies (architecture hierarchy, architecture element attribute information and dependencies) information can be imported flexible to Agile Browser by using Architecture Interchange XML format or by Deps mini format. Deps miniformat is simplified data format for architecture data. The latter format supports adding any custom attribute data. Architecture Interchange XML format is focused for software architecture information.
Custom attribute data is used for importing custom data to Agile Browser for visualization on top of the basic architecture model. Examples of such attributes: ”owner”, ”team”, ”tech_domain”. Each element can have several different attributes.
More detailed information about supported data formats can be found from Supported Data Formats.
Metrics
How To
Here are some use case how tos. These pages are updated all the time to gain a good collection of different how to -instructions.
Take a look of the How To -section.
Troubleshooting
Known issues
If the tool does not start up
Please try with launching the start.bat or start.sh file from command prompt at AgileBrowser installation directory. If that complains about java net CookieManager, too old Java is used (e.g. Java 5) is used at the startup. The problem is solved this way: first ensure the latest Java is installed. Then try again, and if that does not work you will need to modify start.bat (or start.sh) file to point to the correct java executable of Java 6. That is done by defining full path of java.exe instead of just plain java, as it is now.
The other way to solve the problem is to modify Java settings under Control Panel (or similar) so that only Java 6 runtime is enabled at the operating system, but there has been some difficulties getting the Java settings really work.