Using the Web Objects API

This section provides information on using the Web Objects API to help you perform intermediate to advanced customization tasks. The depth of information provided is not relevant for performing basic customization tasks, but it provides a starting point for learning about Web Objects  API. The Web Objects API section includes a sample Web Objects application that demonstrates the use of the Web Objects to connect to MicroStrategy Intelligence Server.

The Web Objects API exposes object-oriented programming interfaces that can be used for developing Web as well as client-server based applications that include MicroStrategy functionality.

MicroStrategy Web communicates with Intelligence Server through the API. The functionality exposed by the API is therefore a superset of the functionality exposed in the MicroStrategy Web application. This functionality includes authentication and security, report execution and manipulation, and a set of administrative features such as connecting to a project and setting the connection properties.

The Web Objects API is a granular level API used by many of the MicroStrategy Web products'  Web Beans and other Web Components to access MicroStrategy Intelligence Server. It is recommended that, wherever possible, these Web Components be used to gain access to the relevant functionality as this provides a simpler development and upgrade path.

This section describes the structure and the usage of the Web Objects API. In particular, the section focuses on those areas of the API that are often useful for designing custom transforms. These activities are related to report manipulations such as pivoting, sorting, and object editing.

Refer to the API Reference for detailed information on the interfaces, classes, methods and so on.

Web Objects fundamentals

This section describes the following key elements of the Web Objects API. These Web Objects form a part of the Web Objects layer and are responsible for XML construction and data representation. For information on how Web Objects fit into the MicroStrategy Web architecture, refer to the Web Objects Layer section.

• Creating new object instances  

• Source objects  

• Exception handling  

• Collecting data  

• Packages and resource files

Creating new object instances

In Java, all Web Objects operations start with the WebObjectsFactory class. This object is the single point of access to the interfaces of the API. A WebObjectsFactory is created using the static getInstance() method.

WebObjectsFactory factory=WebObjectsFactory.getInstance();

Source objects

The starting points for particular groups of functionality are the source objects. Operations such as object management, report execution, and report manipulation all have their operations accessible from their respective source objects. These source objects are created using a WebObjectsFactory instance.

The following table lists the source objects and class names along with their functionality description.

Source Object	Class Names	Functionality Description
Document	WebDocumentSource	Executing and displaying document objects
Element	WebElementSource	Retrieving attribute lists from Intelligence Server
Inbox	WebInboxSource	Displaying the Inbox, and related functionality such as retrieving, adding, and removing messages from Inbox
Object	WebObjectSource	Managing objects. For example, folder browsing and saving
Project	WebProjectSource	Retrieving available projects for a given cluster
Report	WebReportSource	Executing, displaying and manipulating reports
Schedule	WebScheduleSource	Scheduling operations with Intelligence Server
Subscription	WebSubscriptionsSource	E-mail subscriptions

Exception handling

Most of the checked exceptions raised by the Web Objects API are instances of WebObjectsException, though a few Web Objects API related to report manipulation throw instances of WebReportValidationException.

The WebObjectsExeception is a subclass of the MSTRCheckedException class defined under com.microstrategy.utils package. The MSTRCheckedException class extends java.lang.Exception and provides support for retrieving the error code using getErrorCode(), retrieving the error message using getMessage(), and retrieving information about any embedded exceptions.

Other exceptions can be raised in certain situations such as passing invalid arguments to the interface. However, these exceptions are not explicitly thrown by the API.

The difference between unchecked exceptions and the checked WebObjectsException is as follows. The unchecked exceptions mostly represent programming errors such as passing an object which does not exist as an argument to a collection method, or unexpected errors thrown by Intelligence Server.  Checked exceptions are commonly expected error conditions or conditions which can be predicted by Intelligence Server such as Intelligence Server being down, and so on.

Collecting data

In order to collect data, you must use the populate call  and set the appropriate flags. The information returned is based on the specific flags that are set. Since some objects may have been restored with a minimal state, use the populate call if more information about the object is required.

Packages and resource files

The Web Objects API is contained within the com.microstrategy.web.objects package contained in the WebObjects.jar resource file. In addition, the Web Objects API requires the presence of the XML API layer, contained in the com.microstrategy.webapi package, which in turn is located in the JavaWebAPI.jar resource file. The Web Objects API also requires WebUtils.jar and WebXMLUtils.jar, and in addition has a dependency on the Xerces XML parser and Xalan XSL processor.