MicroStrategy ONE

WebDrillInstance

The WebDrillInstance interface is responsible for the majority of drilling-related tasks from the WebReportInstance object. An object of the WebDrillInstance interface can be obtained using the getDrillInstance() method exposed by the WebReportInstance object. This method expects the report results to be ready when invoked or else it throws a WebObjectsException. The WebDrillInstance interface allows an application to specify the options or settings that should be used on a base report instance to be able to drill on it and generate a new WebReportInstance, if needed.

The methods used to execute the drilling operation on the base report instance are drill() and drill(String drillXML). Both methods return the new WebReportInstance object generated as a result of drilling on the base WebReportInstance object. drill(String drillXML) uses a drill XML passed explicitly by the application while drill() generates a drill XML using the options set by the application on the WebDrillInstance object and uses the generated drill XML to drill. At a given state, the drill XML for a WebDrillInstance object can be obtained by the application using getDrillXML().

The following options or settings are available for drilling:  

  • WebTemplateUnit— Specifies the template unit on the base report instance from where the application wants to drill. setDrillTemplateUnit(int axis, int position) can be used to set the source WebTemplate unit for the drill instance. getDrillTemplateUnit() can be used to retrieve the source WebTemplate unit. To clear the template unit, setDrillTemplateUnit(WebTemplateUnit tu) can be used with a value of NULL for tu.  

  • WebDrillElements— Specifies the user filter which is a collection of the WebDrillElement objects. getDrillElements() gets the WebDrillElements object for the drill instance. The selected elements can be set and subsequently read as WebDrillElement objects on this object. Also, for this object, the add method takes the element identifier that can be obtained using the WebHeader::getDrillElement() corresponding to the selected element.  

  • WebDrillActions— Specifies the drill actions which represent the target and type of drilling. A linear collection of drill actions can be associated with a WebDrillInstance. The WebDrillActions object is used to store the collection of WebDrillAction objects.

    • getDrillActions() is used to retrieve the WebDrillActions object for adding and subsequently reading the drill actions. A drill action added to this collection gets added to the end of the collection.

    • Once a DrillAction object is created, its drill type cannot be modified. Except for this drill type property, allother properties of the WebDrillAction object can be modified.

  • filterOnPageBy— It specifies whether drilling should be accompanied by filtering on the page by elements. It can be specified using setFilterOnPageBy(boolean filterOnPageBy). The corresponding get method is called getFilterOnPageBy().

On a WebDrillInstance, the following options are available for populating the drill actions:

  • Populate the WebDrillActions itself. This requires creating and loading the WebDrillActions collection. 

  • Use one of the default drill paths available for the report. The drill paths have the corresponding drill actions embedded in their definitions. In this case, the WebDrillInstance is populated by specifying the required drill path. The methods supported by WebDrillInstance for this task are getDrillPaths(), loadActionsFromDrillPath(int drillPathID), and loadActionsFromDrillPath(WebDrillPath obj). When loadActionsFromDrillPath(int drillPathID) is called after setting a Drill Template Unit ( setDrillTemplateUnit(int axis, int position)), a search is done on the corresponding template unit. If, however, no Drill Template Unit is set, the search is done only at the report level. If no drill path exists, an appropriate exception is thrown.

Note that drill path IDs are unique only within a given drill map. Hence it is possible to have more than one drill path with the same ID— one at the report level and others on the template units.