Programmer's Guide



Contents


Preface

Purpose
Audience
Prerequisites
Organization

Chapter 1    Starting Your Development Project

Making basic application design choices
Clients
Business logic
Data access
Server configuration
Setting up your development environment
Development tools
Code management
Database platform
Standards and conventions
Tips for a successful project and application
Project tips
Design tips
Coding tips

Part I    Core Programming

Chapter 2    Coding Java for SilverStream Applications

Using Java
Java platform support
About the core language
About APIs
Resources for learning Java
Using the Java APIs
Java API support
Using the SilverStream API
SilverStream API packages
SilverStream API terminology
SilverStream API reference documentation
Coding in the SilverStream development environment
SilverStream API support
How you'll work
Coding in external development environments
SilverStream API support
Setup requirements
How you'll work

Chapter 3    Using SilverStream Expressions

JDBC and SilverStream
About expressions in SilverStream
Expression building blocks
Types of expressions
The SilverStream Expression Builder
About queries
The WHERE clause
The ORDER BY clause
Summary of operators
Summary of built-in functions

Chapter 4    Using Utility Classes, JAR Files, and JavaBeans

About Java utility classes
Importing a utility object created externally
Using utility classes
Utility objects, ClassLoaders, and session management
Using JAR files in SilverStream
Using JAR files to enhance performance
Using JavaBeans in SilverStream
Importing a third-party JavaBean
Specifying JavaBeans in a Manifest file
Using a JavaBean in your application
Creating your own JavaBean

Chapter 5    Using XML in SilverStream

SilverStream XML support
Using XML with EJBs
Using XML with SilverCmd
Resources for learning about XML

Part II    Accessing Data

Chapter 6    Data Access Basics

About the data access architecture
Data abstraction model
Data caching
SilverStream data sets
SilverStream Enterprise Data Connectors
SilverStream data cache implementation
Data flow
Updating data
Updating data from different databases
Ensuring data concurrency
About the AgiRowCursor data model
About Hierarchical AgiRowCursors
Working with the data cache
Controlling how data is loaded to a form or page
Data binding
How data binding works
Design time data binding
Programmatic data binding

Chapter 7    Advanced Data Access

Writing your own AgiRowCursor
Prerequisites for writing an AgiRowCursor
SilverStream API support
About the AgiRowCursor interface
Producing events
Accessing database connection pools
About database access permissions
Accessing connections
Releasing the connection

Chapter 8    Using Data Source Business Objects

About data providers
About data source objects
How the DSO works
Creating a DSO
Importing a DSO created externally
Using an executeSQL DSO
Defining the executeSQL DSO
Example code for the DSO invokeQuery event
Calling a stored procedure
Using a SetResultSet DSO
About the java.sql.ResultSet interface
Defining the java.sql.ResultSet DSO
Example code for instantiating the ResultSet object
Using a pass-through DSO
Creating a pass-through DSO
Creating a pass-through DSO programmatically
About the setDataSource DSO
Using a setDataSource DSO to access data
Data access flow
Implementing AgiDataSource
Implementing AgiBandDescriptor
Using a setDataSource DSO to update data
Data update flow
Subclassing AgoDataUpdateRequest
Subclassing AgoDataUpdateRow
Implementing AgiTransactionHandle
Implementing AgiDataUpdateRequest directly

Part III    Developing HTML Clients

Chapter 9    Page Basics

About SilverStream pages
Background concepts
The page event model
Supported standards
Absolute positioning
Framesets
JavaScript
DHTML
Programmable page objects
Design requirements
Dynamic behavior
Browser requirements
Page state maintenance
Built-in controls
Controls within other controls
Complex control combinations
Helper instance variables
URLs and pages
Default database URL and default server URL
Debugging and testing pages
Using the SilverStream Debugger
Testing tips

Chapter 10    Programming Pages

Choosing a page programming model
Understanding Web programming models
Maintaining page state
Writing code on events
Handling page transitions in multi-page applications
Creating a page
Selecting the static page layout
Selecting from the data-bound page layouts
Creating a frameset
Adding data to pages
Validating user input
Passing data between pages
Working with page controls
Setting page control properties
Making objects programmable
Setting text in label controls
Specifying data typing and formatting for text fields
Using HTML data controls
Adding images
Creating links to e-mail
Including Java forms and views in a page
Working with subpages
Calling subpage methods from the parent page
Calling parent page methods from the subpage
Broadcasting events between subpages
Navigating between pages
Using an invisible tab control to create a multi-page look
Invoking a business object
Handling page exceptions
Writing custom methods
Adding helper classes
Customizing pages for users

Chapter 11    Advanced Page Topics

Adding applets
Adding ActiveX objects
Adding plug-ins
Specifying additional HTML
Setting tags and attributes
Changing the edit mode
Formatting text
Using style sheets
Changing text properties programmatically
Adding JavaScript to a page
SilverStream support for JavaScript
Writing JavaScript functions in SilverStream
Accessing SilverStream elements from JavaScript
Using JavaScript to bring up dialogs and perform special tasks
Controlling browser history
Transferring files
Uploading files
Downloading files
Implementing interfaces on a page
Using custom page controls
Creating a brand new control
Inheriting from a built-in control
Adding persistent properties to a custom control
Defining the design-time appearance of a custom control
Installing a custom control
Binding custom controls to data
Posting data from a page to a servlet
Defining servlet page controls
Understanding dynamic name assignment
Handling international characters in older browsers
Importing static HTML into SilverStream

Chapter 12    Using HTML-Based Views

About HTML data views
View components
The HTML data view and data
Working with data views, pages, and data
Updating the database
Using data view methods
Adding editable controls bound to data
Adding editable controls not bound to data
Row-level formatting
Alternating row colors
Adding data-driven formatting
Manipulating unbound controls
Grouping records by value
Including additional rows by inserting raw HTML
Creating reusable objects for row formatting

Chapter 13    Using JavaServer Pages

About JSP integration
JSP Basics
SilverStream support for JSP
Compiling JSP files
Example 1: Specifying a JSP file as input
Example 2: Specifying an XML file as input
Deploying JSP JARs to SilverStream
Writing the input XML file
Running DeployJSP
Using a batch file to deploy the JAR file
JSP runtime considerations
How URLs are processed
Dispatching requests within a JAR
Dispatching requests to a JAR from a page or business object

Part IV    Developing Java Clients

Chapter 14    Form Basics

About forms
The Form API
Form properties
Form methods
Form events
Forms and data
Working with data from multiple tables
Controls and data
Forms and data validation
Where and how to check for valid data
How control-level validation is performed
How form-level validation is performed
Responding to good and bad values with AgoValidationException
Displaying validation messages to the user
Compiling, debugging, and testing forms
Testing and running forms

Chapter 15    Programming Forms

Adding your own methods
Working with Swing and AWT controls
Swing and AWT
Converting existing applications to Swing
Working with Swing controls
Using child forms
Child forms and data
Communicating between parent and child forms
Working with subforms
Subforms and program design
Working with dialog boxes
Displaying a dialog box
Closing a modal dialog box
Working with message boxes
Return values
Creating your own message box
Navigating pages
Customizing forms for users

Chapter 16    Advanced Form Topics

Working with Java menus
About MenuBars
About popup menus
About java.awt.Menu and java.awt.MenuItem objects
Menu restrictions
Strategies for building menus
Defining MenuBars
Creating a MenuBar
Creating Menu objects
Adding MenuItems to a Menu
Adding Menus to the MenuBar
Adding the MenuBar to the window's Frame
Responding to menu selections
Defining PopupMenus
Creating a PopupMenu
Adding MenuItems to a PopupMenu
Adding a PopupMenu to the form
Displaying a PopupMenu to the user
Responding to menu selections on a PopupMenu
Using Swing menus
File attachments and local disk access
Binding a file attachment to a database table
Programming file attachments
Forms and asynchronous processing
Using AgcTimer
Using threads
Controlling the appearance of your form
Controlling the layout of the form
Taking advantage of pluggable look and feel
Instantiating SilverStream form controls
Handling events for controls instantiated at runtime
Extending SilverStream form controls
Providing context-sensitive help for forms
Specifying help information
Default help processing
Custom help processing
How the help manager processes help

Chapter 17    Using Java-based Views

About Java-based view controls
View components
Choosing a view control
Creating dynamic views
Creating AgoViewFormats
Creating AgoBandFormats
Creating columns
Appending columns to bands
Appending bands to view formats
Instantiating an AgcView
Views and data
Static views and data
Dynamic views and data
Navigating and manipulating data
Getting data from an AgoTreeDataManager
Manipulating view formats at runtime
Obtaining the object to change
Modifying runtime attributes

Chapter 18    Writing External Java Clients

Designing your client
Client types
Client requirements
Client features
Communication protocols
Accessing the server from your client
Initializing the SilverStream runtime environment
Connecting to a SilverStream server
Using your server session
Closing your server session
Developing the features for your client
Accessing data
Calling EJBs
Invoking business objects
Administering the server
Deploying your client
Installing the runtime environment
Installing your files
Installing SilverStream files
Setting the classpath

Part V    Developing Enterprise JavaBeans

Chapter 19    Using EJBs with SilverStream Applications

SilverStream EJB support
Integrated tools for designing, customizing, assembling, and administering EJBs
Load balancing
Naming service
Remote access
Security
Transaction support
Writing EJB applications
Writing portable beans
Using SilverStream extensions
Designing EJB applications

Chapter 20    Writing Session Beans

About session beans
Session beans and transactions
Session beans and data
Developing a session bean
Session bean development cycle
Session bean deployment cycle
Writing a session bean class
Writing the remote interface
Writing the home interface

Chapter 21    Writing Entity Beans

About entity beans
Entity bean persistence models
Entity bean lifecycle
Entity beans and transactions
Developing entity beans
Writing the primary key class
Writing the entity bean class
Writing the remote interface
Writing the home interface
Extending container-managed persistence

Chapter 22    Understanding Deployment Descriptors

About deployment descriptors
Defining the bean's structural information
Defining the bean's application assembly information
Application assembly entries
SilverStream tools for creating deployment descriptors
Creating a single EJB JAR from multiple EJB JARs
Converting EJB 1.0 deployment descriptors to EJB 1.1 format

Chapter 23    Deploying EJBs

About deployment
Enabling the EJB JAR
Mapping security roles
Specifying JNDI names for an EJB
Mapping entity beans to a data source
Mapping entity bean fields
Specifying the methods that do not modify fields
Delaying instantiation
Specifying Finder methods
Subclassing beans
SilverStream's EJB Deployment tools
Deploying an EJB JAR
Using the SilverStream IDE
Using SilverCmd
Exporting a SilverStream EJB JAR file

Chapter 24    Calling EJBs

Supported EJB clients
Setting up the client environment
Accessing EJBs
Accessing the server
Finding EJBHomes and instantiating beans
Calling remote methods
Closing the session

Part VI    Developing Triggered Business Objects

Chapter 25    Triggered Object Basics

About triggered business objects
Business objects and threads of execution
Creating triggered business objects
Using the Business Object Designer
About the new business object
Importing triggered objects created outside of SilverStream
About event objects
Example of an event object
More about event objects
Business object life cycle
Saving and publishing server-lifetime objects
Object life-cycle and threads
Session persistence
Triggered objects and data
Specifying the dataset
Populating AgaData
About the AgaData
Triggered objects and security
Business objects, class loaders, and JAR files
About class loaders
Deserializing business objects
About the AgiDataRunner interface

Chapter 26    Using Server, Cluster, and Scheduled Business Objects

About server triggered business objects
Server error events
ServerStarted and serverStopped events
UserLogin and UserLogout events
Troubleshooting server listeners
About clustered triggered business objects
How cluster events fire
Listener behavior in clustered environments
About scheduled triggered business objects
Scheduled events and the AgoScheduledEvent object
Managing scheduled listeners in a cluster

Chapter 27    Using Mail Business Objects

SilverStream e-mail support
About sending and receiving mail
About the SMTP and MIME standards
About MIME
About the SMTP and MIME standards
About MIME
About POP3
How the mail system works
Mail system components
Mail system data flow
Creating a mail-triggered business object
Creating a mail business object
Importing a mail triggered object created externally
Working with received messages
Obtaining the message from the AgoMailEvent object
Accessing the message body
Notes about mail listeners
Sending e-mail
About the SilverStream AgoMailSend
Composing an e-mail message
Constructing a message that contains MIME parts

Chapter 28    Using Table-Modified Business Objects

About table-modified business objects
Uses of table listeners
Table listeners and external table modifiers
Creating a table listener
How table listeners work
Table listener events
Table event objects
Getting data from event objects
About the AgaRowData object
Accessing additional datasets
Getting other information from event objects
Table listeners and database transactions
Aborting a transaction
Using table listeners to modify the database
Working with versioned tables
Working with automatically versioned tables
Working with manually versioned tables

Chapter 29    Using Invoked Business Objects

About invoked business objects
Creating an invoked listener
Invoked listeners and synchronization
Using invoked listeners in SilverStream
Calling the invoked listener
About the calling objects
Returning data to the caller
Examples of using invoked business objects
Invoking listeners from non-SilverStream Java clients
Invoking listeners from external Java clients
Calling an invoked listener on a remote server

Chapter 30    Using Servlet Business Objects

About servlets
About the servlet business object
Creating a servlet object
How servlets work
Servlet methods
Servlet processing summary
Associating URLs with servlets
Specifying URLs using the Business Object Designer
Specifying URLs programmatically
Programming servlets
About request headers
About response headers
SilverStream servlet extensions
Servlet coding example

Part VII    Extending Your Applications

Chapter 31    Using CORBA Objects

About CORBA
SilverStream CORBA support
Writing CORBA applications in SilverStream
Creating a CORBA IDL file
Writing a CORBA implementation class
Writing the SilverStream triggered business object
Writing CORBA clients

Chapter 32    Using COM Objects

About COM integration
COM Basics
SilverStream support for COM
Working with ComGen
Example 1: Listing available type libraries
Example 2: Generating Java source files for a type library
Writing Java code to access a COM object
Coding basics
Example 1: Making a simple function call
Example 2: Using the Variant class
Migrating from JActiveX to ComGen

Chapter 33    Accessing DLLs Directly

About DLL integration
DLL Basics
SilverStream support for DLL access
Writing Java code to access a DLL
Coding basics
Example 1: Making a simple function call
Example 2: Calling a function with parameters

Part VIII    Deploying Your Applications

Chapter 34    Deploying and Distributing Applications

Publishing to a production database
Basics of publishing
Publishing SilverStream objects
Publishing database tables
Considerations when publishing
Deploying Enterprise JavaBeans
Deploying Enterprise Data Connectors
Setting up SilverJRunner clients
Installing SilverJRunner
Starting SilverJRunner
Using startup options
Setting up HTML clients that use forms or views
Setting up external Java clients
Configuring security
Tuning performance





Copyright © 2000, SilverStream Software, Inc. All rights reserved.