HYPERION® APPLICATION BUILDER FOR .NET RELEASE 11.1.1
DEVELOPER’S GUIDE
Application Builder for .NET Developer’s Guide, 11.1.1 Copyright © 2004,2008, Oracle and/or its affiliates. All rights reserved. Authors: EPM Information Development Team This software and related documentation are provided under a license agreement containing restrictions on use and disclosure and are protected by intellectual property laws. Except as expressly permitted in your license agreement or allowed by law, you may not use, copy, reproduce, translate, broadcast, modify, license, transmit, distribute, exhibit, perform, publish or display any part, in any form, or by any means. Reverse engineering, disassembly, or decompilation of this software, unless required by law for interoperability, is prohibited. The information contained herein is subject to change without notice and is not warranted to be error-free. If you find any errors, please report them to us in writing. If this software or related documentation is delivered to the U.S. Government or anyone licensing it on behalf of the U.S. Government, the following notice is applicable: U.S. GOVERNMENT RIGHTS: Programs, software, databases, and related documentation and technical data delivered to U.S. Government customers are "commercial computer software" or "commercial technical data" pursuant to the applicable Federal Acquisition Regulation and agency-specific supplemental regulations. As such, the use, duplication, disclosure, modification, and adaptation shall be subject to the restrictions and license terms set forth in the applicable Government contract, and, to the extent applicable by the terms of the Government contract, the additional rights set forth in FAR 52.227-19, Commercial Computer Software License (December 2007). Oracle USA, Inc., 500 Oracle Parkway, Redwood City, CA 94065. This software is developed for general use in a variety of information management applications. It is not developed or intended for use in any inherently dangerous applications, including applications which may create a risk of personal injury. If you use this software in dangerous applications, then you shall be responsible to take all appropriate fail-safe, backup, redundancy and other measures to ensure the safe use of this software. Oracle Corporation and its affiliates disclaim any liability for any damages caused by use of this software in dangerous applications. This software and documentation may provide access to or information on content, products and services from third parties. Oracle Corporation and its affiliates are not responsible for and expressly disclaim all warranties of any kind with respect to third party content, products and services. Oracle Corporation and its affiliates will not be responsible for any loss, costs, or damages incurred due to your access to or use of third party content, products or services.
Contents
Chapter 1. Getting Started with Application Builder for .NET . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 Setting Up the Development Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 Programming Environment Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 About Embedded Java Application Programming Interface . . . . . . . . . . . . . . . . . . . . . . . . 9 Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 Enabling Embedded JAPI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 Managing the Embedded JAPI Feature . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 Running the Embedded JAPI Utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 Chapter 2. Creating OLAP Aware Web Application with Application Builder for .NET . . . . . . . . . . . . . . . . . . . . 13 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 Creating a Basic ASP.NET Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 Setting Up Dependencies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 Creating a Sample Application using List box, Drop-Down List, and Data Grid . . . . . . 14 Creating a Sample Application using Grid Adapter OWC11, List Box, and Drop-down List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 Chapter 3. Creating OLAP Aware Windows Application with Application Builder for .NET . . . . . . . . . . . . . . . . . 31 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 Creating a Basic Windows Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 Setting Up Dependencies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32 Creating a Sample Application using List Box, Combo Box, Tree View, and Data Grid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32 Creating a Sample Application using Grid Adapter OWC11, List Box, Combo Box, and Tree View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41 Chapter 4. Programming with Base Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51 EssOperations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52 EssConnection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
Contents
iii
EssDomain . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53 EssProperties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54 Chapter 5. Programming with Dialog Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55 SignOnDialog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55 MemberSelectionDialog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56 EssTreeview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56 Chapter 6. Application Builder for .NET ASP.Net Components Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59 Data Server Component . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59 Web Grid Adapters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61 Grid Adapter Generic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61 Grid Adapter OWC11 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61 Web Metadata Adapters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62 Drop-Down List Adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62 List Box Adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63 TreeviewAdapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64 Chapter 7. Application Builder for .NET Windows Components Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . 67 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67 ComboBoxAdapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67 DataServer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68 GridAdapterOWC11 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69 ListBoxAdapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70 TreeViewAdapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71 Appendix A. Application Builder for .NET APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73 Hyperion.Objects.Essbase.Common . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74 Hyperion.Objects.Essbase.Common.Grid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75 Hyperion.Objects.Essbase.Common.Transports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76 Hyperion.Objects.Essbase.Common.Grid.OWC11 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76 Hyperion.Objects.Essbase.Components.Design . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77 Hyperion.Objects.Essbase.Components.Metadata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77 Hyperion.Objects.Essbase.Components.Web.Design . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79 Hyperion.Objects.Essbase.Components.Web . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79 Hyperion.Objects.Essbase.Components.Windows.Design . . . . . . . . . . . . . . . . . . . . . . . . 80 Hyperion.Objects.Essbase.Components.Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
iv
Contents
Hyperion.Objects.Essbase.Windows.Forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82 Appendix B. Migrating Application Builder for .NET Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85 Comparing the Components of Application Builder for .NET Release 9.2 with Application Builder for .NET Release 11.1.1.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85 Migrating to Application Builder for .NET Release 11.1.1 . . . . . . . . . . . . . . . . . . . . . . . . 88 Drag-Drop Option . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88 Run time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92 Appendix C. Performance Tuning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93 Performance Tuning to Retrieve Records . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93 Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
Contents
v
vi
Contents
Getting Started with Application Builder for .NET
1 In This Chapter
Overview ............................................................................................................................. 7 Setting Up the Development Environment........................................................................................ 8 Programming Environment Requirements ........................................................................................ 8 About Embedded Java Application Programming Interface ..................................................................... 9 Enabling Embedded JAPI..........................................................................................................10 Managing the Embedded JAPI Feature ..........................................................................................10 Running the Embedded JAPI Utility ..............................................................................................11
This chapter introduces Oracle's Hyperion® Application Builder for .NET. It describes how to create a basic application within the .NET environment that will access Oracle Essbase data.
Overview Application Builder for .NET provides a comprehensive set of OLAP-aware classes for data navigation, selection, reporting, and visualization to assist you in building custom analytical applications. These controls provide you with the tools to quickly create and deploy applications in stand-alone, client-server, Web, or distributed processing environments. Application Builder for .NET is a component of the Oracle Enterprise Performance Management system that provides an application development workbench for companies wanting to use the Microsoft .NET Framework to create tailored business performance management solutions. Application Builder for .NET includes the following key features: ●
Drag and Drop components for creating OLAP aware applications for Web and Windows using MS Visual Studio.Net
●
.NET Framework compatibility
●
Web Service -based architecture (SOAP)
Application Builder for .NET provides the following functionality: ●
Base classes. These classes contain basic OLAP functionality and encapsulate functionality necessary to connect to and perform operations on Essbase applications and databases.
●
Dialog components. These classes encapsulate the functionality of Essbase dialog boxes, including the sign-on and member selection dialog boxes.
Overview
7
●
Grid classes: These classes encapsulate functionality enabling data grid controls to display Essbase data.
●
Application Builder for .NET Drag and Drop OLAP aware components utilize the functionality listed preceding and bind the Microsoft .Net application controls to Essbase. These components use this technique to expose all Essbase functionality to enable creation of OLAP aware Web based and Desktop applications utilizing the Microsoft .Net framework.
Setting Up the Development Environment To develop Application Builder for .NET applications within Visual Studio for .NET, perform the following steps: ●
Install and configure Microsoft Visual Studio for .NET.
●
Install Application Builder for .NET and note which directory contains theApplication Builder for .NET assemblies.
●
If you are developing an ASP .NET (Active Server Pages) application, install or ensure access to an instance of Microsoft Internet Information Server (IIS).
●
If you are developing applications using Microsoft Office Web Components (OWC11), you may need to add Microsoft Office Primary Interop Assemblies and install additional assemblies available from www.microsoft.com.
●
Install or ensure access to an Essbase server and application. This guide assumes that you will be using the Sample application and Basic database installed with Essbase.
●
Ensure that the Application Builder for .NET .WAR file has been applied to your Web application server. For information on how to deploy the .WAR file, see the Oracle Hyperion Enterprise Performance Management System Installation and Configuration Guide.
●
Ensure that Oracle Hyperion Provider Services™ is running, and that your application server can access it.
Programming Environment Requirements The examples and graphics in the Application Builder for .NET Release 11.1.1.0 Developer's Guide are built in Microsoft Visual Studio .NET 2003, using Microsoft Visual Basic for .NET and Microsoft C# for .NET. ●
Microsoft VB.NET
●
C#.NET 2003
Any design-time work that involves actual data from the database requires an active connection to an Essbase server. Design work such as layout and inter-object communication can be done without a live connection.
8
Getting Started with Application Builder for .NET
About Embedded Java Application Programming Interface The Embedded Java Application Programming Interface (JAPI) feature is a simple deployment of the JAPI solution. Enabling this feature will provide the Application Builder for .NET applications to establish connection with the Essbase servers even when Provider Services is not installed, see Figure. The connection protocol between the Application Builder for .NET applications and the Essbase servers is TCP/IP or HTTPS.
Figure 1
Embedded JAPI Connectivity
The embedded JAPI deployment for Application Builder for .NET includes .jar files and property files. When you enable the embedded JAPI feature, the Application Programming Interface (API) client will include these .jar files and property files in the Application Builder for .NET application.
Prerequisites Some of the current Java API customers may require only Java API functionality, and will not require a full installation of the Provider Services product with the extended functionality such as Clustering, High Availability, Connection Pooling, and XMLA provider. Complete these prerequisites to enable this feature: ●
%APS_HOME% should contain both \bin and \data folders
●
%APS_HOME%\bin should contain essbase.properties file
●
Update the Habnet.properties file. In \HABNET_HOME\products\Essbase\habnet\Server\lib\, In Habnet.properties file include value EDSUrl=Embedded.
About Embedded Java Application Programming Interface
9
●
From Essbase server installation location: HABNET_HOME\products\Essbase\habnet \server\lib copy the Essbase.properties file to %APS_HOME%\bin.
Enabling Embedded JAPI The embedded JAPI feature is available when you install this release of Application Builder for .NET. However, to enable this feature, you must do some updates to the Habnet.properties file. With this feature update to the Application Builder for .NET release, to establish connection between Application Builder for .NET applications and Essbase has a option of using either Provider Services or embedded JAPI depending on the requirement. This utility is run based on the following assumptions: ●
The password information of the Essbase servers are read without any encryption.
●
The user ID and password information is used for authentication and this utility will update only the server name information in the domain.db file.
●
The utility will read the environment variables APS_HOME and HABNET_HOME to get the location information of the files domain.db and essbase_servers.xml.
➤ To enable the embedded JAPI utility: 1 In the Habnet.properties file, for EDSUrl provide the value Embedded. 2 Save and close the Habnet.properties file.
➤ To revert to Provider Services: 1 In the Habnet.properties file, for EDSUrl provide the value EDSUrl = http://:/aps/JAPI.
2 Save and close the Habnet.properties file.
Managing the Embedded JAPI Feature This feature offers a utility that gathers the Essbase server information (server name, user ID, and password) from the XML template file essbase_servers.xml and updates the domain.db file. The user has a privilege to add the server information in essbase_servers.xml to "add","delete" and "None" actions to update the domain.db file. The essbase_servers.xml file must include these server information:
