browse-by-query home antlersoft free software sourceforge project page

Browse-by-Query for Java Quick Start

Thanks for your interest in the Browse-by-Query concept.  The aim is to bring a robust code-querying capability to as many platforms, IDE's and other tools as possible.  BBQ is designed for advanced developers, and assumes you know your way around your chosen development environment.  This document provides some details for getting BBQ up and running and integrated properly.

Please make use of SourceForge to pass along your questions and comments so we can make this document and BBQ as useful as possible.

For all environments, you compose queries as described in the Browse-by-Query Language for Java manual.

Table of Contents

[1] Browse-by-Query for Java Quick Start

[1.1] Eclipse Quick Start

[1.1.1] Builder

[1.1.2] Query View

[1.1.3] Search View

[1.1.4] User-Set View

[1.2] JBuilder Quick Start

[1.2.1] Analyzing your project

[1.2.2] Querying

[1.2.3] Using the Results

[1.3] Standalone Quick Start

[1.3.1] Adding Code to the Database

[1.3.2] Querying

[1.3.3] Using the Results

Eclipse Quick Start

You can install the plug-in by adding the update site listed on the BBQ home page, or by downloading bbq_eclipse_site_x.y.z.jar (where x.y.z is the current version number) from the Sourceforge download page and adding that as a local update site.

Their are four basic parts to the Eclipse plugin-- A builder that adds information about your classes to the Browse-by-Query database, a query window, a result pane in the search window, and the User-Set View that lists your saved expressions.

Builder

The first step is to activate the builder.  You activate it separately for each project in your workspace.  To activate the builder for a project, right-click the project in the workspace tree,  and check the option: Include in Browse-by-Query Database.  Then, with each subsequent build, the .class files in your project will be analyzed and added to the BBQ database, and you will be able to retrieve information about the project in BBQ queries.

Query View

Once your project's information is in the database, you'll want to query it.  To do that, you'll need to open the Browse-by-Query Query View from the Open View... option in the Window menu.  The Query View has two main panes, one above the other, and works best in a vertical orientation.  The top pane has a text box where you can type your query.  The bottom pane has a list of the queries you've already run, so you can re-run a query easily.  A good test query to enter is "count all classes".  Press the Query button to run the query.

Search View

The query result will appear in the search view (at this point, BBQ does not automatically open the search view, so if it isn't visible when you run the query, the search result won't be visible either.)  If you've entered "count all classes" for your query, and you have data in your database, it should show a non-zero number.

If you query for classes, methods, fields, calls or field references (for example, calls to methods in class "javax.swing.JTable") the list of results will appear in the Browse-by-Query pane in the Search view, with one result per line.  Double-click on an item and it will open the appropriate file in the editor window at the appropriate point.

User-Set View

If you want to see a table that lists the names and values of BBQ expressions you may have saved, you can add the User Set view to your perspective.  To do that, you'll need to open the User-Set BBQ view from the Open View... option in the Window menu.  This view works best in the horizontal orientation, as in the result dock.

JBuilder Quick Start

Download the bbqopentool_x.y.z.jar file (where x.y.z is the latest BBQ version) from the Sourceforge download page and add it to your JBuilder environment.

The JBuilder plugin adds a new icon in the project tree, a question mark.  Open this object and the Browse-by-Query editor pane appears.  The editor pane has two buttons, Query and Analyze, and three text areas: a query entry area, a query history area, and a result area.

Analyzing your project

The first step is to press the Analyze button to load the information about your project's classes into the BBQ database.  The plugin is not integrated with JBuilder's build system, so you need to press this button every time you want the database updated; it will load all the class files that have changed since the last time you pressed it.

Querying

Once your project's information is in the database, you'll want to query it.  You type the query into the text area next to the buttons. A good test query to enter is "count all classes".  Press the Query button to run the query.  The query result will appear in the result area below the query history area.  If you've entered "count all classes" for your query, and you have data in your database, it should show a non-zero number.

Using the Results

If you query for classes, methods, fields, calls or field references (for example,calls to methods in class "javax.swing.JTable") the list of results will appear in the result area, with one result per line.  Double-click on an item, or right click and make the menu selection, and the plugin will open the appropriate file in the editor window at the appropriate point.

Standalone Quick Start

Get the standalone version by downloading bbqstandalone_<version>.jar from the Sourceforge download page, where <version> is the most recent version of Browse-by-Query.

Start BBQ standalone with the command line: java -jar bbqstandalone_<version>.jar [dbpath]

[dbpath] is an optional folder name where BBQ will put its database files.  If the folder does not exist, BBQ will create it.  If you don't specify a folder, BBQ will create the sub-folder test.bbq within the current folder.  Depending on your environment, you may be able to start standalone BBQ with the default database path just by clicking on the jar file.

The standalone window features a prominent Query button along with four boxes of adjustable size: the top box is for entering queries; the box below it lists your history of queries.  The little box to the right lists any named SetExpressions you've created.  The large box at the bottom lists the query results.

Adding Code to the Database

BBQ reads and analyzes .class files and indexes and adds the information to its database.  It can traverse directory trees and look inside .jar and .zip files to find the .class files.  From the File menu, select Analyze jar / directory / class files command.  Then select a jar, directory or .class file to add to the database.

Querying

Once your project's information is in the database, you'll want to query it.  You type the query into the text area next to the buttons. A good test query to enter is "count all classes".  Press the Query button to run the query.  The query result will appear in the result area below the query history area. If you've entered "count all classes" for your query, and you have data in your database, it should show a non-zero number.

Using the Results

If you query for classes, methods, fields, calls or field references (for example,calls to methods in class "javax.swing.JTable") the list of results will appear in the result area, with one result per line.  Since the standalone tool is not integrated with a development environment, it will just list the file and line for each result-- it can't open it automatically.

browse-by-query home antlersoft free software sourceforge project page