The Artima Developer Community
Articles | Discuss | Print | Email | First Page | Previous | Next
This article is sponsored by Business Objects.

Using a Decision Tree to Navigate Complex APIs
by Colin Gray
May 26, 2005

<<  Page 2 of 2


An interactive object model decision tree

The interactive decision tree application walks developers through a series of questions related to application requirements. It asks a developer the level of reporting functionality required in an application. Each question guides the developer to a new level within the object model hierarchy.

As a developer works her way down the decision tree, each API box in the path represents an API that should be considered for the desired functionality. Color-coding, consisting of dark and light blue, indicates the products that include the referenced API. [For the differences between Business Objects products and APIs, see the Sidebar].

The user interface is dynamic: If a user clicks on an API or question box, the right panel shows related instructions and information. The right panel also contains an access point for detailed navigation of the API. Each object in the API is also dynamic—a single click reveals related help on each object.

For example, say you are responsible for a web application and you have a new requirement to allow users of your web app to export documents to different formats, such as Adobe PDF or Microsoft Word. You are looking around for tools to help you implement that enhancement, and are completely unfamiliar with Crystal Reports' API. How would you figure out what classes, properties, and methods in Crystal Report's API offer the report exporting functionality?

Using the interactive object model decision tree, you first answer a few simple questions, then select documentation subsets that become visible as you navigate the decision tree. Figure 1 provides a thumbnail view of the decision tree user interface.

Figure 1. The Crystal Reports object model decision tree.

Finding the report exporting API is just a few answers away:

  1. In which environment will you develop your application?

    The options here are Java, .NET, and COM/VB. For this example, say you follow the .NET path.

  2. Will the report processing occur on the client side or the server- side?

    Since you're building a web app, the processing will occur on the server side. You follow the "SERVER" branch.

  3. Will your application enable end-users to perform advanced report creation and modification at runtime?

    You're not sure what "advanced" means, but you suspect you want to provide advanced report creation, so you choose the "Y" branch. (When in doubt, you can click on the question's text box to display a detailed explanation of the question.)

  4. Will you be incorporating reporting services such as report security, scheduling, and management into your application?

    For this app, you don't provide such features. Since your choice is NO, you've come to the end of the decision tree.

As mentioned previously, each blue box that you traverse as you navigate the decision tree is an API you should consider. In this example, the YES branch in question 3 took you to a box labeled "RAS," and the NO branch in question 4 took you to a box labeled CR.NET. You can now start exploring these two APIs to see if they will help you accomplish your goals.

If you click on the RAS box, you'll learn in the right hand frame that the RAS API provides access to the .RPT report object model. Following a brief overview of the RAS API in that frame, you'll see a thumbnail view of the RAS API diagram, as shown in figure 2.

Figure 2. Thumbnail of RAS API diagram .

Clicking on that thumbnail now replaces the main screen section with detailed information about the RAS API and SDK.

Figure 3. A detailed view the RAS API.

The object model diagram itself is dynamic HTML that presents a collapsible tree. Clicking on the Open label expands the tree's first-level branches. With the top-level objects in full view, the PrintOutputController object stands out as a possible candidate to control report exporting. Clicking on a box representing that object reveals the object's further details, including that "PrintOutputController is used to export reports to a specific format, such as Excel, RTF, or PDF and to modify various formatting options." The detailed object view also shows the object's method, including Export() that performs report exporting.

Figure 4. Detailed view of the PrintOutputController API.


Organizations are finding it increasingly necessary to deploy more complex software solutions just to stay competitive. More capable software presents new complexity to be tamed. That increasing complexity challenges developers, marketers, and users alike. Developers must struggle to keep things as simple as possible, to keep the code understandable and manageable. Marketers must figure out how to explain complex products to potential customers. Users must invest effort to determine which complex product best fits their needs.

Documentation tools must become more interactive to help developers tame the burden that comes with increased choices. Recent efforts to make JavaDoc more developer-friendly, and the dynamic HTML object model developed by Business Objects is an example of such interactive documentation. While traveling light is not always an option, such interactive documentation tools can make a developer's life happier.

The Crystal Reports interactive object model decision tree had, at the time of this writing, live on the Business Objects Developer Zone for two months. Sixty percent of the developers who visited the Developer Zone over the first month viewed the decision tree. Based on a poll conducted with over 700 users of the decision tree, almost 70% indicated that the tool had either provided guidance related to API use with their reporting projects, or that they expect it will do so in their future projects.


To access the live decision tree application please visit:

To access the Crystal Reports Developer Zone visit:

Writing JavaDoc comments:

An open-source JavaDoc search tool:

JavaLobby's collection of annotated, searchable JavaDocs:

Wind, Sand, and Stars, by Antoine de Saint-Exupéry

About the author

Colin Gray is the America's developer marketing manager for Business Objects. Colin has been in technical sales, product management and developer marketing roles with Business Objects (Crystal Decisions pre-acquisition) for 16 years. Over this tenure one of the most daunting communication hurdles has been helping developers map their project requirements to the solutions that Business Objects offers. This goal gave birth to The Interactive Object Model Tree.

Sidebar: Crystal choices

Crystal Reports is a banded-style report writer for accessing and formatting data into actionable information. Over the years, the Crystal Reports solution has become more complex. Users can choose to design reports within one of three editions of Crystal Reports, and manage those reports with one of two deployment options. Crystal reports customers are developers and business managers that need to understand how the various Crystal Reports reporting options relate to their existing requirements.

The first decision for a prospective user is to choose the right Crystal Reports edition. While each edition shares the same report designer, editions vary in their abilities to connect to data and how they integrate reports into applications.

The most basic edition is the Standard edition that allows connecting to data from PC databases, such as MS Access, Pervasive, or Paradox. If a Crystal Reports user is interested in accessing SQL-level data as well, she would select the Professional edition. Finally, a Developer edition is available for users interested in integrating reports into applications, and is the only one to include such integration APIs.

For out-of-the-box management and secure delivery of reports to departments or entire organizations, Business Objects offers two additional products that act as a framework around the report files. Both are built on the same enterprise reporting platform. The small business, or "light," edition is called Crystal Reports Server, and the enterprise edition is named BusinessObjects Enterprise.

Developers wanting to integrate reporting into their applications can use various Crystal Reports APIs. APIs exist for Java, .NET, VB platforms. Some of these APIs allow report integration without having to write reporting code. For example, a developer could embed one of three report component engines into an application, and use the related APIs to pass that engine instructions at runtime, instead of having to code the report processing logic of an application.

If a fuller reporting solution is desired—with a shared portal for report access, security and report object management, for instance—the enterprise reporting services of Crystal Reports Server or BusinessObjects Enterprise can be employed. Embedding the enterprise reporting services via an API means that those more complex reporting services need not be created via code, but instead can be integrated with the core application and accessed via the API.

Business Objects owns the following U.S. patents, which may cover products that are offered and licensed by Business Objects: 5,555,403; 6,247,008 B1; 6,578,027 B2; 6,490,593; and 6,289,352. Business Objects and the Business Objects logo, BusinessObjects, Crystal Reports, Crystal Enterprise, Crystal Analysis, WebIntelligence, RapidMarts, and BusinessQuery are trademarks or registered trademarks of Business Objects SA or its affiliated companies in the United States and other countries. All other names mentioned herein may be trademarks of their respective owners. Copyright © 2005 Business Objects. All rights reserved.

<<  Page 2 of 2

Articles | Discuss | Print | Email | First Page | Previous | Next

This article is sponsored by Business Objects.

Sponsored Links

Copyright © 1996-2018 Artima, Inc. All Rights Reserved. - Privacy Policy - Terms of Use