DECISION
WORKS JAVA API
User Manual
Contents
Using the Decision Works JAVA API
DnD in JAVA its use in the JAVA API
The mouse cursor workaround in the JAVA API
This document is intended to be a guide for using the DecisionWorks JAVA API. It first describes how to use the API, followed by background information on the architecture of the package.
The JAVA API was developed to enable developers to connect to a DecisionWorks Server. It provides controls and dialogs that will work with such a server to display OLAP reports.
Please note that the JAVA API is only an additional API for use with a DecisionWorks Server. It therefore does not provide all of the functionality that is provided by the main API.
This document requires some knowledge of OLAP from the reader. The terms CUBE, DIMENSION, MEMBER and ACROSS, PAGE, DOWN should be known to understand the document. As this is a JAVA API, the reader should be familiar with JAVA to understand the examples given in this document.
The Decision Works JAVA API is designed to work in both applications and applets. The difference between the two is that applets require an additional step. In an applet, you must initialise "JRunningContext" function. This is necessary for user interface decisions in some components. Things won't fail immediately if you miss this step, but they may look wrong.
Due to a bug in the JDK [SUN2000] (v1.3.0 and before), drag and drop might not work in an applet. For a workaround please refer to Appendix 1.3.
For each control you wish to add to your application,
The control will need a panel for constructing, and a parent reference. You should give the appropriate panel to the control, as well as a reference to the visible component that is its parent. The control will then place itself into the panel.
If you want to enable the controls DragnDrop ability, you must call the controls "enableDnD()" method. This method requires a JOLAPDnDManager object. If you want more than one control to participate in the DnD operations with that control, you must give them all the same JOLAPDnDManager object.
The last method you must call in order to start working with the control is "setDataView()". This method, which takes an OLAPDataView as a parameter, initialises the control with data. Chapter 2.4 explains how to get an OLAPDataView.
Example
|
//must be initialised
once in an applet //not necessary in an
application (default) JRunningContext.getRunningContext().initContext(this); //create a spreadsheet
in jPanel1 cSpreadSheet = new JOLAPSpreadSheet(jPanel1, this); //create a new DnD
manager cDnDManager = new JOLAPDnDManager(); //enable DnD for
spreadsheet cSpreadSheet.enableDnD(cDnDManager); //init spreadsheet with
a dataview cSpreadSheet.setDataView(cDataView); |
Dialogs are stand-alone parts of the Decision Works JAVA API. All modal dialogs will have a method "doModal()" which displays the dialog and returns an ID for the action that was used to close the dialog.
Currently all dialogs (except the JOLAPConnectionWizard) are not designed to be called from somewhere else other than the controls. This is because they require some knowledge of how to use them properly. All dialogs, except the JOLAPConnectionWizard, will need an OLAPDataView object. This is used to select data from the OLAPDataView to display, as well as apply changes (if appropriate).
Some dialogs also require a Vector of JOLAPDimension. It must be assured that the Vector only contains JOLAPDimension objects, otherwise the application will crash.
Example:
|
//getting
all dimensions from data view //Warning: This is NOT an array of JOLAPDimension Object[] cDimensions = (Object[])cDataView.getDimensions(); //transform dimensions
and store them into vector array for (iIndex = 0; iIndex < java.lang.reflect.Array.getLength(cDimensions); iIndex ++) {
//adding cDimensionsVector.add( cDataView.getDimensionFromArray( (Object[])cDimensions[iIndex]) ); } //build hierarchy
selector dialog JOLAPHierarchySelectorDialog cHierarchySelector = new JOLAPHierarchySelectorDialog(getParent(), cDataView, DimensionsVector); //show dialog if (cHierarchySelector.doModal() == JOLAPHierarchySelectorDialog.HS_BUTTON_OK_ID) { //do something on OK } |
You can obtain an OLAPDataView two ways.
–
OR –
TRACKServer = ...
TRACKPort = ...
PROVIDER = ...
DSN = ...
UID = ...
PWD = ...
CUBE = ...
In the case that something is not correct an exception is returned.
Example:
|
//creating
the OLAPDataView object directly cDataView = new OLAPDataView("TRACKServer=localhost;" + "TRACKPort=20000;" + "PROVIDER=Essbase;" + "DSN=tosca;" + "UID=user;" + "PWD=password;" + "CUBE=Sample Cube"); //using the
JOLAPConnectionWizard to obtain a data view JOLAPConnectionWizard cWizard = new JOLAPConnectionWizard(this); if (cWizard.doModal() == JOLAPConnectionWizard.WIZ_FINISH_BUTTON) { //get data view cDataView = cWizard.getDataView(); } |
The central class to retrieve data from the server is OLAPDataView [OLAPDataPack]. All controls and dialogues have a reference to an object of this class. Whenever a control or dialog triggers a change in the data view, all other controls and dialogs that use the same data view will be updated automatically (if this was requested).
Every control and every dialog that wishes to retrieve data from the data view automatically whenever the view changes, must register itself as a ChangeListener with the OLAPDataView. The OLAPDataView will then notify each registered ChangeListener whenever the data changes.
Most methods of the OLAPDataView will throw JOLAPException errors in the case that something went wrong. Developers that wish to use the OLAPDataView directly must catch these errors.
The JAVA API comes with two different controls to display data from a dataview. These are
As controls, these classes do not have their own frame. Instead they will place themselves into a given panel, which in turn is part of a frame. In order to display data they must be initialised with an OLAPDataView.
The JAVA API also comes along with a set of dialogs that operate on a given OLAPDataView. These dialogs are
This dialog enables you to connect to a DecisionWorks Server and a data source. To create an OLAPDataView a connection string is necessary, this is created by this dialog. Therefore the wizard will take you through 3 steps that let you define the server, the data source, the actual cube you wish to use, which dimensions from that cube you wish to use, and which members in these dimensions you wish to use. It is a very powerful dialog, which assists you in defining your report.
You can also define your own connection strings and use them instead of the wizard to create an OLAPDataView. Please refer to chapter 2.4 for more detailed instructions. If you do choose to do it this way, you will also need to select some dimensions and members. Remember that both controls won't display anything without selected dimensions across and down.
This dialog lets you choose the dimensions want to have in your report across, down or paged. By default, all dimensions are in page. Simply drag the dimensions from one direction into the one where you want them.
This dialog lets you choose single members in a given dimension. This is useful if you are interested in one single member in a dimension. Select the member you want from the tree on the left side, and drag it into the table on the right side. Drag the other way to remove selected members.
|
Note:
Removing all members from a dimension in the table will result in the dimension set to page. This is not shown in the dialog. |
This is a simple dialog that allows you to search for a member in a given dimension. This is useful if your dimension consists of lots of members and you want to find one of them without having to search the tree manually. Once you have found the desired member you can then drag it from the dialog into a table on the JOLAPSpreadSheet or the JOLAPHierarchySelectorDialog. (This depends on, where you have created the JOLAPMember dialog. Please refer to the following topic on Drag& Drop). This is a non-modal dialog (currently the only one).
In general, all controls and dialogs support Drag&Drop (DnD). For technical reasons the JAVA API uses a modified mechanism to enable DnD, (see Appendix 1). In general terms a JOLAPDnDManager object is required to be shared between all controls that participate in DnD. You can create sets of controls, each set sharing one JOLAPDnDManager. The result would be that you can drag and drop from and to controls inside one group, but you cannot drag from a set of controls in group A to a set of controls in group B.
Dialogs will have their own JOLAPDnDManager if they support DnD. Because most dialogs are modal (except JOLAPFindMember) they cannot participate in DnD with other controls. The JOLAPFindMemberDialog however is a non-modal dialog. Therefore it can participate in DnD operations with controls. If it does, it requires the JOLAPDnDManager that is used with that control. If this dialog is created from inside the JOLAPHierarchySelector, it will only be able to drag into this dialog, if you create the JOLAPFindMember dialog from the context menu of a control, the FindMember dialog will participate in that control’s DnDManager.
|
Reference |
Description |
SUN2000
|
http://developer.java.sun.com/developer/bugParade/bugs/4225247.html |
OLAPDataPack
|
\\Tosca\issue\Documentation\Objects3.5.1\OLAP\OLAPDataPack.doc |
DnD in JAVA its use in the JAVA API
Drag and Drop (DnD) is implemented in JAVA using 4 different objects. First, there is a DragGestureRecognizer object, which checks if the user wants to initiate a DnD operation. Once it notices this, it creates a Transferable object. This will contain the data that is supposed to be transferred and some other status bits.
Each object that wishes to be a starting point of a DnD operation must have a DragSource listener object. Each object that wishes to be a target of a DnD operation must have a DropTarget listener.
When the DragGestureRecognizer notices a drag, it will inform the DragSource listener that a Drag has started. Once this is done, each DropTarget Listener will be informed whenever the drag enters, is over, or exits the area of each DropTarget Listener. These messages will also go to the DragSource Listener.
The data flow happens only from the source to the target. There is currently no way information can flow "back", from the drop target to the drag source. Technically this is required because the drop target cannot set the mouse cursor, and the drag source has no idea where the mouse cursor is at any given moment. The standard requirement is that the mouse cursor changes depending on the area where the mouse cursor is over the drop target. Currrently there is no standard way of getting this done.
The mouse cursor workaround in the JAVA API
The workaround that has been developed to enable the application to change the mouse cursor depending on the area where the mouse is over the drop target, is quite tricky and could be a bit confusing. This workaround will stop all DnD interactions with other applications. Interestingly enough, you can drag from the controls into other applications, such as MS-Word.
The workaround relies on a shared object between the drag source and each drop target. This object, because it is shared, will allow the information to flow "back" — the drop target writes into it, and the drag source can read out of it. This object also holds a reference to the drag object and the drop target object itself, as well as a reference to the data that should be transferred. The original Transferable only solves to kick off the drag, and contains a simple status string. (This is the one you will get when dragging into MS-Word).
All initialising of this shared object as well as the set up of the drag source listener and drop target listener is managed in the JOLAPDnDManager class. A component that wishes to take part in a DnD operation needs to register itself with the JOLAPDnDManager (method registerComponent()). To do this, the component must implement the JOLAPDnDComponent interface. Once this is done, the component can be a valid source and a valid target for a DnD operation with components that where registered using the same JOLAPDnDManager.
To make things easier a set of DnD enabled base classes was developed. These classes (JOLAPDnDTree, JOLAPDnDTable, JOLAPDnDViewPort) are all prepared to be used with the JOLAPDnDManager. To easily build a DnDTable, a DnDTree, or a DnDViewPort, simply extend these classes and overwrite the methods from the JOLAPDnDComponent interface you desire.
Currently you must use these classes in order to build new DnD enabled components. This is because the DragGestureRecogniser has to know which kind of DnD control is the source to correctly initialise the data. In the future this method may be generalised.
Due to a bug in the JDK [SUN2000] the DnD will not work in an applet if you create the layout of your applet in the usual way. The workaround of this problem is shown in the code fragment below.
|
public class MainApplet extends Applet implements Runnable { //Construct the applet public MainApplet() {} //Initialize the applet public void init() { //do all STATIC init
here. //do NOT init DnD here! } //this starts the applet public void start() { //To enable DnD,
creation of the DnD components must be delayed. Thread dndThread = new Thread(this); dndThread.start(); } public void run() { try { //send the thread to sleep to givet the applet some
time Thread.sleep(1000); } catch (InterruptedException ex) {} //now init your DnD
enabled components } } |