DataWindow, Java Edition
Features
The DataWindow, Java Edition is a set of JavaBeans components
and associated classes for use in Java applications. It implements
all the features of the PowerBuilder DataWindow except rich text,
graphs, and OLE.
The DataWindow, Java Edition supports data retrieval with
retrieval arguments and data update. You can use edit styles, display
formats, and validation rules.
Most of the PowerBuilder methods for manipulating the DataWindow
are available, including Modify for changing DataWindow object properties.
The DataWindow, Java Edition does not support or generate JavaScript.
Several functions that involve the system clipboard are not available.
JavaBeans components
The DataWindow includes these components:
- DataWindow JavaBeans component The complete DataWindow, which supports data retrieval and
management, layout and display of data, and user interaction and
data update capabilities. - DataStore JavaBeans component A DataWindow with data retrieval and update but no onscreen
data display and user interaction. It can be used to manage data
and share data with other components without displaying the data–for
example, in a server application or as a data source for other DataWindow
components. It can also provide an alternative data layout for printing
data.
Native and Swing DataWindow controls
There are two versions of the DataWindow JavaBeans component:
- A native component (DataWindowControl)
- A lightweight Swing component (JDataWindowControl)
They are both available on the DataWindow component palette.
Both have the same methods and events. If your application uses
Swing components, use the JDataWindowControl instead of DataWindowControl.
The DataWindow classes are in PowerJ35javalibDataWindow.jar,
which is a subdirectory of the install directory (the default install
directory is drive:Program FilesSybase).
Development environment and documentation
When you install PowerJ, the Setup program installs all the
classes necessary for using DataWindow components.
The components appear on the Database tab of the component
palette. You can insert them on a form and write code to connect
to databases and retrieve, manipulate, and update data.
The DataWindow is integrated into the PowerJ Help system,
and you can use the PowerJ Reference Card to examine the properties,
methods, and events of the DataWindow.
The DataWindow Reference
provides full
documentation for properties, methods, and events of the JavaBeans
components and additional Java classes.
DataWindow objects
The DataWindow and DataStore JavaBeans components use a DataWindow object,
which determines what data is retrieved and how it is displayed.
The DataWindow component can also display Powersoft reports (PSRs),
which do not need to retrieve data.
A DataWindow object for the JavaBeans components can have
any presentation style except RichText, Graph, or OLE. If the DataWindow
object includes graph or OLE controls, they are ignored.
You create DataWindow objects in DataWindow Builder. You can
also use the PowerBuilder DataWindow painter, if PowerBuilder is
installed.
DataWindow objects are stored in PowerBuilder libraries (PBLs).
Before deploying, you can convert a PBL to a PowerBuilder dynamic
library (PBD), which provides runtime versions of the DataWindow
objects.
In the DataWindow component, you use a URL or a file path
to point to the library. A URL can be relative or absolute, using
any supported protocol–for example, http, ftp, or file.
For more information, see “DataWindow objects for the DataWindow JavaBeans component”.
Database connections
The DataWindow components use JDBC for database connectivity.
Users can connect to any data source to which they have access,
including databases and middle-tier servers on the Internet.
For more information, see “Database connections”.
Coding
The DataWindow and DataStore JavaBeans components support
most of the functionality found in the PowerBuilder DataWindow.
For more information, see “Coding for the DataWindow
JavaBeans component”.
Deployment
After you create your applet or application target, you can
create a collection target in PowerJ that includes your project
and the DataWindow JAR file.
For more information, see “Deploying the application”.
DataWindow objects for the DataWindow JavaBeans component
The DataWindow and DataStore JavaBeans components require either:
- A DataWindow
object stored in a PowerBuilder library - A Powersoft report (PSR) that was saved previously
with data - A DataWindow object exported to an SRD file
Properties for the component identify the library and DataWindow
object you want to use.
This section describes considerations for:
- Defining
DataWindow objects - Building libraries
- Identifying the DataWindow object or Powersoft report
(PSR) by setting properties
What the DataWindow object can include
You can define DataWindow objects in DataWindow Builder or
PowerBuilder. The DataWindow, Java Edition supports most DataWindow presentation styles;
it does not support RichText, Graph, or OLE. If you include an OLE
or graph control in another presentation style, it is ignored.
You can use all edit styles, including DropDownDataWindow.
Properties can have conditional expressions, and computed fields
can use any of the functions available to DataWindows used in PowerBuilder.
Managing DataWindow objects in PowerBuilder libraries
About libraries
The DataWindow and DataStore JavaBeans components use DataWindow objects that are stored in PowerBuilder
libraries (PBLs) or PowerBuilder dynamic libraries (PBDs).
The library of DataWindow objects must be delivered with your
application or stored on an accessible server. For an applet, the
library is accessed via HTTP and downloaded by the Web browser and
stored in a temporary cache. For a client application, the library
can be installed on the user’s computer or stored on a
server.
If you do not want your DataWindow object source code to be
available to the user, you should convert a PBL to a PBD before
deploying it. This also compresses the library, making downloading
more efficient.
Supported DataWindow versions The DataWindow and DataStore JavaBeans components work with PowerBuilder
Version 6 and later libraries.
If you have libraries from older versions, you can migrate
them to the current version with either DataWindow Builder or PowerBuilder.
Grouping DataWindow objects into libraries
When the PBL or PBD is downloaded from a Web server, you should
make sure your library includes only those objects that your application
needs. You can create a single library that includes all the DataWindow
objects used in your application. If the library is to be downloaded,
you might consider creating separate libraries for DataWindow objects
that are used in different parts of the application so that users
are not forced to download objects that they do not need.
Using other resources in the DataWindow object
A DataWindow object can use external resources such as bitmaps
or cursors. You can use a PowerBuilder resource file (PBR) when
you build a PBD to include these resources in the library. You can
also store these resources on the server or install them on the
user’s computer.
A DataWindow object can use other DataWindow objects. Make
sure these objects are included in the library.
Specifying a DataWindow object for the component
To identify the DataWindow object you want to display in the
component, you can specify values for two properties:
- SourceFileName
- DataWindowObject
Specify the values on the DataWindow Source page of the property
sheet for the DataWindow component.
Library in stream format You can also make the library available as an input stream.
For more information, see setSourceStream in the DataWindow
Reference
.
About SourceFileName
The value for SourceFileName is the name of the library that
contains the DataWindow object for the component. It can be a URL
or a file path. These examples illustrate some typical variations:
| Source | Example | ||
|---|---|---|---|
| Absolute URL |
|
||
| Relative URL or file path |
|
||
| Absolute file path |
|
In the property sheet, when you use the Browse button to look
for the library, you browse the file system, not URLs. After the
full path is inserted in the field, you will probably need to edit
it so that it is valid when your application is deployed.
PowerJ projects If you keep the library in the target folder and deploy it
in the same directory as the class files, SourceFileName can be
a relative path that is valid in both your design and deployment
environments.
Changing SourceFileName during execution You can change the value of SourceFileName in your code by
calling setSourceFileName. If you do, you also have to specify a
value for DataWindowObject that is valid in the new library. If
you have set up the component to require an explicit call to use
a transaction object, you also need to call SetTransObject or SetTrans
again.
About DataWindowObject
The value for DataWindowObject is the name of a DataWindow
object that is in the library specified in SourceFileName.
In PowerJ, if the library is accessible in the development
environment, the property sheet displays a dropdown list of the
DataWindow objects contained in the library.
Displaying Powersoft reports To display a PSR file instead of a DataWindow object, specify
its URL as the value for SourceFileName and specify nothing for
DataWindowObject.
Database connections
Database connections are handled using a PowerJ transaction
object. The JavaBeans component can use a transaction object you
create, or it can create its own to establish a connection using
parameters you specify. You determine which method to use on the
Database tab page in the property sheet for the component.
You can use internal transaction properties for specifying
a connection, or you can make the connection with a separate PowerJ
transaction object. When you use a separate transaction object,
you can control when SQL commit and rollback statements occur, and
you can use the same connection for multiple DataWindow components.
Coding for the DataWindow JavaBeans component
In general, you can use the same methods as in a PowerBuilder
application. However, there are a few differences:
- Some
methods are not supported, including methods that use the system clipboard
and methods for manipulating graphs, rich text, and OLE. - PowerBuilder has several date and time data types;
but in Java, these all map to the Date object. - PowerBuilder enumerated data type values are implemented
as fields. You can specify the field name or the associated numeric
value.
For reference information
The fields, properties, methods, events, and DataWindow object
properties and expression functions are documented in the DataWindow
Reference
.
To see a list of the properties, methods, and events for the
JavaBeans components, look at the PowerJ Reference Card.
Setting event return codes
Action codes for events are specified using the setActionCode
method, rather than by specifying a return value.
For example, the return code of the onItemError event allows
you to determine what happens when user-entered data fails a validation
rule. By specifying a return code of 3, you cause the DataWindow
component to reject the data but allow focus to change. This statement
would be the last line of the onItemError event script:
|
1 |
This.SetActionCode(3); |
Data binding
The DataWindow JavaBeans component implements the powersoft.powerj.db.DataSource
interface, which allows you to bind data-aware components to the
DataWindow, just as you can bind those components to a PowerJ Query
object.
For more information, see the Query object in the PowerJ documentation.
Deploying the application
After you create your applet or application (which is a PowerJ
target), you define a PowerJ collection target to bring together
the application target and supporting pieces. The collection target
builds a JAR file that includes everything.
You can include the DataWindow JAR file in the target, or
you can rely on PowerJ to examine the references in the application
and include the DataWindow classes, as necessary.
Depending on how you have used JDBC for database connectivity,
you may need to include JDBC classes in the collection. For more
information about when this is necessary, see the PowerJ
Programmer’s Guide
.
The library of DataWindow objects is not included in the JAR
file and must be deployed separately. The URL or file path you use
in the application for the SourceFileName property determines where
the library will be on the deployment server or user’s
computer.