IDE
Programming
Guide
release 4.0
May 1999 MN07-C-00-400-00
Notice
No part of this publication may be copied, photocopied, reproduced, transmitted, transcribed, or reduced to any electronic medium or machine-readable form without the prior written consent of HAHT Software, Inc. Information in this document is subject to change without notice. Names and information used in examples are fictitious.
U.S. GOVERNMENT RESTRICTED RIGHTS. It is acknowledged that the Software and the Documentation were developed at private expense, that no part is in the public domain, and that the Software and Documentation are Commercial Computer Software provided with RESTRICTED RIGHTS under Federal Acquisition Regulations and agency supplements to them. Use, duplication, or disclosure by the U.S. Government is subject to restrictions as set forth in subparagraph (c)(1)(ii) of The Rights in Technical Data and Computer Software clause at DFAR 252.227-7013 et. seq. or subparagraph (c)(1) and (2) of the Commercial Computer Software—96 Restricted Rights at FAR 52.227-19, as applicable. Contractor is HAHT Software, Inc., 4200 Six Forks Road, Raleigh, NC 27609. Rights are reserved under copyright laws of the United States with respect to unpublished portions of the Software.
Trademarks
HAHT, HAHT Software, HAHTsite, e-Scenario, and “e-nable your enterprise” are trademarks or U.S. registered trademarks of HAHT Software, Inc.
Portions Copyright© 1992-1996 Summit Software Company.
This product includes software developed by the Apache Group for use in the Apache HTTP server project (http://www.apache.org/).
Any other corporate names, product names, tradenames, trademarks, service marks, or service names owned or registered by any other company and mentioned herein are the property of their respective companies. Specifications subject to change without notice.
HAHT Software, Inc. 4200 Six Forks Road Raleigh, NC 27609 USA
(919) 786-5100 (888) 438-4248 (in the USA) (919) 786-5200 (Technical Support)
C on t en t s
About This Book
Who is this book for? . . . xvii
Conventions . . . xvii
Other HAHTsite documentation . . . xviii
Other HAHTsite products . . . xix
HAHT Software’s commitment to you . . . xix
1 Introduction Overview . . . 2
HAHTsite Server Object Model . . . 3
The project package . . . 3
The datamanager package . . . 4
The form package . . . 4
The access package . . . 5
The corba package . . . 5
Data-management API . . . 5
ActiveX Data Objects classes . . . 6
Relationship between ADO and SOM classes . . . 6
Data management in HAHTtalk Basic projects . . . 7
Client-side scripting . . . 8
CORBA capabilities . . . 9
Access to COM/DCOM objects. . . 9
HAHTsite Server Object Model . . . 13
External logic . . . 13
In-line code . . . 13
Invoking an expression or a method from a dialog box . . . 15
Adding code in Server-side Code view . . . 17
What’s in a Java page? . . . 18
Editing HahtApplication.java and HahtSession.java . . . 25
Adding Java files to a project . . . 26
Naming conventions for Java projects . . . 30
Naming conventions for dynamic pages . . . 30
Calling a dynamic page from Java . . . 30
Event handling in a Java project . . . 31
Editing and compiling Java code . . . 37
Using the code editor . . . 37
Compiling a Java application . . . 38
Finding compile-time errors . . . 39
Debugging a Java application . . . 39
Working with application directories . . . 39
Java options . . . 41
Changing the Java file type . . . 41
Overriding Java compiler options . . . 42
Overriding options for JAR, CAB, and ZIP files . . . 43
3 Working with HAHTtalk Basic Projects What’s in this chapter . . . 46
Adding server-side code to a HAHTtalk Basic project . . . 46
HAHTsite Server Object Model . . . 47
External logic . . . 47
In-line code . . . 48
Invoking an expression or a subroutine from a dialog box . . . 50
Adding code in Server-side Code view . . . 52
What’s in a HAHTtalk Basic page? . . . 53
Adding HAHTtalk Basic files to a project . . . 60
Naming conventions for HAHTtalk Basic projects . . . 62
Project and external includes . . . 63
Declaring public variables with Globals.hbs . . . 64
Precompiler directives . . . .64
Calling dynamic pages from HAHTtalk Basic . . . 65
Event handling in a HAHTtalk Basic project . . . 66
Editing and compiling HAHTtalk Basic code . . . 67
Using the code editor . . . 67
Compiling a HAHTtalk Basic application . . . 69
Finding compile-time errors . . . 69
Debugging a HAHTtalk Basic application . . . 70
Working with application directories . . . 70
Comparing HAHTtalk Basic and Visual Basic . . . 72
HAHTtalk Basic data types . . . 72
Subroutines and functions . . . 73
File I/O . . . 73
Error handling . . . 73
Code page properties . . . 73
4 Calling Server-side Java from HAHTtalk Basic Introduction . . . 76
Using Java objects with HAHTtalk Basic . . . 76
CreateJavaObject . . . 77
GetJavaClass . . . 78
CreateTypedJavaNull . . . 78
Differences between HAHTtalk Basic and Java . . . 79
Java is strongly typed . . . 79
Parameter passing . . . 80
Java is case sensitive . . . 80
Locating objects . . . 80
5 HAHTsite Server Object Model
Introduction . . . 89
Built-in objects . . . 90
Getting references to the built-in objects. . . 91
From a Java project . . . 91
From a HAHTtalk Basic project . . . 96
The Application object . . . 97
Application object methods . . . 97
Application object variables . . . 98
Multiple processes and application-level variables . . . 99
Retrieving Application object properties . . . 100
Summary of Application object methods . . . 102
The Session object. . . 107
Session state . . . 107
Session timeout . . . 108
Event handling . . . 108
Creating a dynamic URL . . . 109
Creating a static URL . . . 113
Identification methods . . . 113
Summary of Session object methods . . . 114
The Request object . . . 117
Retrieving field values . . . 117
Retrieving cookie values . . . 121
Retrieving attachments . . . 122
Retrieving environment variables . . . 122
Summary of Request object methods . . . 123
The Response object . . . 126
Writing headers . . . 126
Setting cookies . . . 127
Writing the HTML output . . . 129
Summary of Response object methods . . . 130
6 Forms-Related Programming What’s in this chapter . . . 134
Writing the subroutine . . . 138
Associating the subroutine with a form . . . 139
Attaching a file to a form . . . 140
Adding a File Upload control to a page . . . 141
Working with a file attachment . . . 142
Custom Form Handler widgets. . . 145
Writing the form-handler function . . . 145
Creating the custom form-handler widget . . . 152
7 Form Fields Programming What’s in this chapter . . . 156
Setting form-field properties. . . 156
Examples of setting form-field properties . . . 156
Setting and getting form-field properties . . . 161
FormField properties . . . 163
Button properties . . . 165
Checkbox properties . . . 167
Combo properties . . . 168
FileUpload properties . . . 168
ListElement and Listbox classes . . . 169
Radiobutton properties . . . 175
StaticText properties . . . 176
TextArea properties . . . 178
Textbox properties . . . 178
Calculating form-field values . . . 180
Calling user code from a button. . . 183
Code associated with a button versus code associated with a form . . . 183
Configuring a button to call user code . . . 184
8 Data-Agent Programming Data agents and command handlers . . . 188
Getting a reference to a data agent’s connection . . . 198
Dealing with recordsets . . . 198
Getting parameters to stored procedures . . . 202
Refreshing a data agent’s data . . . 203
Sorting records . . . 204
Filtering records . . . 205
Handling errors . . . 210
Enabling tracing . . . 210
The structure of a command handler. . . 212
Modifying a command handler . . . 216
Where to add code to a command handler . . . 216
Examples of adding code to a command handler . . . 217
Changing the flow of control in a command handler . . . 225
Example of changing the flow of control . . . 227
9 Programming with the Connection Manager The DMConnectionManager class . . . 230
Opening a connection . . . 230
Opening a shared connection . . . 231
Opening a private connection . . . 232
Closing a connection . . . 232
Connections in HAHTtalk Basic projects . . . 233
10 Working with Client-side Scripts Introduction to client-side scripts . . . 236
Types of client-side scripts . . . 238
Choosing a scripting language . . . 238
Client-side scripts and the HTML editor . . . 240
Browsing the object model . . . 241
Configuring the Client Scripts view . . . 242
Writing in-line scripts. . . 243
Writing script functions . . . 244
About event handlers . . . 247
Scripting event handlers . . . 247
Browser compatibility issues . . . 249
The browser object model . . . 250
Strategies for handling browser incompatibilities . . . 250
About Dynamic HTML . . . 252
Moving objects using DTHML . . . 252
Why use Netscape Layers for positioning? . . . 253
JavaScript example for browser-independent DHTML . . . 255
Scripts with server-side expressions . . . 257
11 Using HtmlOut Routines or the HtmlOut Class Creating HTML at runtime . . . 260
The HAHTtalk Basic HtmlOut library. . . 260
Using the HAHTtalk Basic HtmlOut library . . . 261
HAHTtalk Basic example . . . 262
The HtmlOut Java class . . . 264
Java example . . . 265
12 Access Control What is access control?. . . 270
Granting privileges: the basics . . . 271
Controlling access to a page . . . 271
Controlling access to part of a page . . . 274
Displaying a custom error page . . . 275
Granting privileges to logged-in users . . . 276
Authenticating users with the Login widget . . . 277
Authenticating users with the Authentication interface . . . 286
Server Object Model methods . . . 296
Session class . . . 297
Privileges class . . . 298
Application class . . . 298
Authentication interface . . . 299
UserProfile interface . . . 299
13 Connecting to COM Objects Introduction . . . 302
Calling DLLs . . . 302
Declaring a DLL in HAHTtalk Basic . . . 302
Example DLL declarations . . . 303
Mapping HAHTtalk Basic types to DLL data types . . . 304
Using COM objects with HAHTtalk Basic . . . 305
The CreateObject function . . . 305
A COM Server example. . . 306
Background . . . 307
HAHTMem methods . . . 307
14 HAHTsite CORBA Capabilities Overview . . . 310
What is CORBA? . . . 310
What does HAHTsite/CORBA interoperation mean? . . . 310
Using CORBA with the HAHTsite IDE . . . 311
Handling CORBA projects . . . 311
Setting options for CORBA . . . 312
HAHTsite as a CORBA client . . . 315
Example: Building a HAHTsite CORBA client . . . 316
HAHTsite as a traditional CORBA server . . . 318
Example: Using CORBA to hold HAHTsite global state . . . 319
CORBA and the HAHTsite Server Object Model . . . 321
Using the HAHTsite Server Object Model in a HAHTsite CORBA server . . . 321
Accessing the HAHTsite Server Object Model from a CORBA client
. . . 322
Client/server communication . . . 325
Example: Using CORBA in a session initiated via HTTP . . . 325
Example: Initiating a HAHTsite application session with CORBA . 327 Other Information . . . 328
Interoperability with other ORBS . . . 328
Using CORBA with HAHTtalk Basic . . . 329
VisiBroker installation and configuration . . . 329
VisiBroker SmartAgent and the CORBA Naming Service . . . 329
VisiBroker GateKeeper . . . 329
References . . . 330
15 Debugging Server-side Code Introduction . . . 332
Requirements for debugging . . . 332
A special case: debugging HAHTtalk Basic stand-alone programs . 333 Starting a debugging session . . . 333
Debugging a code page . . . 336
Executing code in the debugger . . . 336
Single-stepping . . . 337
Procedure-stepping . . . 338
Using breakpoints . . . 338
The debug windows . . . 340
Debug output panel . . . 341
Variable window . . . 341
Watch window . . . 343
Call Stack window . . . 344
Threads window . . . 345
Pseudo-methods . . . 352
B HAHTsite 3.x Data Management Introduction . . . 356
DataSets and data agents . . . 356
Accessing and changing DataSet properties at runtime . . . 356
DataSet control functions . . . 357
Writing user-defined DataSet functions . . . 358
Accessing and changing form-control properties at runtime . . . 358
Connection-manager functions . . . 359
C Code Examples Calling a subroutine as a form action . . . 362
Modifying a command handler . . . 370
Writing a custom authentication class. . . 373
D ADO Primer What’s in this appendix . . . 376
Connections . . . 376
Opening a connection . . . 376
Executing a command against a connection . . . 378
Closing a connection . . . 379
Recordsets . . . 380
Creating a recordset . . . 380
Iterating through the records in a recordset . . . 381
Finding a specific record in a recordset . . . 382
Reading a record . . . 382
Updating a record . . . 383
Inserting a record . . . 383
Deleting a record . . . 384
Closing a recordset . . . 385
E ADO Extensions What’s in this appendix . . . 388
Extensions to the Java interface . . . 388
ADO tracing in Java projects . . . 388
Additional appendChunk methods . . . 390
The Variant data type . . . 390
Extensions to the HAHTtalk Basic interface. . . 391
ADO tracing in HAHTtalk Basic projects . . . 391
Abo u t T h is Bo o k
The HAHTsite IDE Programming Guide explains how to extend your HAHTsite® applications programmatically. Chapter 1, “Introduction,” gives you an overview of the programming capabilities available within HAHTsite. If you’re developing a Java application, continue with Chapter 2, “Working with Java Projects.” If you’re developing a HAHTtalk Basic application, look at the corresponding chapter, Chapter 3, “Working with HAHTtalk Basic Projects.” Then read Chapter 5, “HAHTsite Server Object Model,” which describes the programming model that underlies a HAHTsite application, including the Application, Session, Page, Request, and Response objects. This chapter, and all the chapters that follow, contain both HAHTtalk Basic and Java examples. However, the functionality is the same, regardless of which language you use. The table below lists each chapter in the HAHTsite IDE Programming Guide, along with its contents.
Chapter/Appendix Contents
Chapter 1, “Introduction” A high-level introduction to the IDE’s Server Object Model, data management model, and COM, CORBA, and client-scripting capabilities. Chapter 2, “Working with Java
Projects”
Information for developers who are adding server-side code to a Java project.
Chapter 3, “Working with HAHTtalk Basic Projects”
Information for developers who are adding server-side code to a HAHTtalk Basic project. Chapter 4, “Calling Server-side
Java from HAHTtalk Basic”
How to call Java from a HAHTtalk Basic project.
Chapter 5, “HAHTsite Server Object Model”
Explanation of the built-in objects in HAHTsite’s Server Object Model.
Chapter 6, “Forms-Related Programming”
Customizing your application’s form-handling capabilities. For HAHTtalk Basic projects, adding a custom form handler.
Chapter 8, “Data-Agent Programming”
Calling data-agent methods at runtime; customizing HAHTsite’s command handlers. Chapter 9, “Programming with
the Connection Manager”
Opening and closing shared and private connections using the DMConnectionManager class.
Chapter 10, “Working with Client-side Scripts”
Adding JavaScript or VBScript to your application.
Chapter 11, “Using HtmlOut Routines or the HtmlOut Class”
Using HAHTsite functions/methods to create HTML at runtime.
Chapter 12, “Access Control” Controlling access to HAHTsite project items by assigning a set of required privileges to the items.
Chapter 13, “Connecting to COM Objects”
Accessing DLLs and COM/DCOM objects from HAHTsite applications.
Chapter 14, “HAHTsite CORBA Capabilities”
Building HAHTsite applications that are CORBA clients or servers.
Chapter 15, “Debugging Server-side Code”
Using HAHTsite’s remote debugger to inspect code running on the Application Server. Appendix A, “HAHTsite 3.x
WebApp Methods and Properties”
How WebApp properties and methods (from HAHTsite 3.x) relate to objects in the Server Object Model.
Appendix B, “HAHTsite 3.x Data Management”
How programming database applications differs between HAHTsite 3.x and HAHTsite 4.0. Appendix C, “Code Examples” A set of sample functions/methods that
supplement those in the text.
Appendix D, “ADO Primer” How to perform basic operations using ADO connections and recordsets.
Appendix E, “ADO Extensions” The few ways in which HAHTsite’s ADO implementation differs from the standard.
Who is this book for?
This book is written for use by HAHTsite programmers. It assumes that you: • know how to use the HAHTsite IDE to create Web applications.
• have an understanding of how the HAHTsite IDE creates Web applications, how HAHTsite applications are structured, and how applications interact with the HAHTsite Application Server.
• know how to use either the Visual Basic or Java programming language. • are familiar with HTML.
Prerequisites
In order to build a Java project that contains dynamic pages, or a HAHTtalk Basic project that calls server-side Java, you must have a Java compiler installed (not included with the HAHTsite software). See the ReadMe file for information on downloading a Java compiler.
Conventions
This book uses several conventions, which are described here.
HAHTsite installation directory
The directory into which you install the HAHTsite IDE is called the HAHTsite installation directory. This book uses the variable HAHTsiteInstallDir as a placeholder for the HAHTsite installation directory — for example,
C:\HAHTsite. When you see this variable, you should replace it with the name of the HAHTsite installation directory on your system.
Continuation characters in sample code
Some lines of sample code are too long to fit on one line. For HAHTtalk Basic code, this book uses the line-continuation character (“_”) at the end of a line.
Screen images
The HAHTsite IDE/IP runs on Windows 95, Windows 98, and Windows NT. Depending on which operating system you are using, the “look” of the screens might be slightly different from what you see in this book. However, the screens’ contents are the same.
Other HAHTsite documentation
The HAHTsite IDE includes this additional documentation: • HAHTsite IDE and IP User’s Guide
• HAHTsite IDE and IP Installation Guide
• HAHTsite Widget Programming Guide
“Getting Started”
The HAHTsite IDE/IP also includes an introduction to HAHTsite, lessons in using HAHTsite, and sample (HAHT_Intro) projects in Java and HAHTtalk Basic. Choose Getting Started from the Help menu.
Online documentation
In addition to the printed books, you can use the IDE/IP’s online help system. As well as context-sensitive help for each of the dialogs, the online help system includes:
• Overview information about the IDE/IP.
• Step-by-step instructions on how to use the IDE/IP’s features.
• Reference pages for the HAHTtalk Basic language, HAHTsite’s Server Object Model, and the SQL Assistant.
• Information about using HAHTtalk Basic’s Dialog Editor (used in building widgets).
HAHTsite OLE Interface Guide
The HAHTsite IDE provides an OLE interface that you can access from your custom widgets. The OLE objects and methods are described in the HAHTsite OLE Interface Guide, which you can access from the IDE’s Help menu. The
HAHTsite OLE Interface Guide is an HTML document.
The HAHTsite OLE Interface Guide is also installed as a HAHTsite project (in
HAHTsiteInstallDir\sdk\oleapi). This enables you to add comments to the guide or to copy the guide’s examples into the HAHTsite IDE and test them.
Other HAHTsite products
In addition to the IDE and the IP, the HAHTsite family of products includes the HAHTsite Application Server, which works with any Web server to execute HAHTsite applications. The Application Server runs on the Windows NT, HP/UX, Solaris, and AIX operating systems. It executes application logic, enables complete access to multiple data sources, maintains session information, and dynamically generates HTML pages.
HAHT Software’s commitment to you
We want you to be completely satisfied with your HAHT Software products. If you have questions about HAHTsite, the HAHTsite IDE, the HAHTsite IP, or the HAHTsite Application Server, you can contact HAHT Software in the following ways:
Telephone
• (919) 786-5200 Technical Support (Voice)
• (919) 786-5252 Technical Support (FAX)
• info@haht.com General Information
• sales@haht.com Sales
• support@haht.com Support
World Wide Web
1
Introduction
Overview ... 2 HAHTsite Server Object Model... 3 The project package ... 3 The datamanager package ... 4 The form package ... 4 The access package ... 5 The corba package ... 5 Data-management API... 5 ActiveX Data Objects classes ... 6 Relationship between ADO and SOM classes ... 6 Data management in HAHTtalk Basic projects ... 7 Client-side scripting... 8 CORBA capabilities ... 9 Access to COM/DCOM objects ... 9 Remote debugging ... 10
Overview
Using HAHTsite’s Integrated Development Environment (IDE), you can create many Web applications without writing any code. You describe your
application’s requirements using the IDE’s graphical user interface, and HAHTsite’s code generator creates the code for your application.
Of course, code generators can’t account for every contingency. Therefore, HAHTsite makes it easy for you to add your own code to this generated code as needed. In HAHTsite, you can add such code using either Java or HAHTtalk Basic (which is syntax compatible with Visual Basic). A Java virtual machine (either Microsoft or Sun) and a Basic virtual machine are embedded in the Application Server for the execution of code written in these languages. Being able to add Java or HAHTtalk Basic code to HAHTsite pages is useful in itself, but the real power of this language support lies in the fact that you can use these languages to call a tremendous amount of existing code. For instance, from either Java or HAHTtalk Basic, your Web application can call other code in DLLs, UNIX shared libraries, Java classes, or practically anything else that has a callable API. Of particular importance are the Java packages and Basic libraries supplied with HAHTsite.
First, HAHTsite includes a set of Java packages that make up what is called its Server Object Model. The classes in these packages can be called from both Java and HAHTtalk Basic projects and enable you to:
• obtain information about the Application Server, about your application and individual user sessions, and about the data being passed back and forth between the Application Server and the Web server
• establish connections with relational and nonrelational data sources and to manage the ActiveX Data Objects (ADO) recordsets obtained via those connections
• control the form fields in your application’s forms • provide access control for the pages in your application • make your application a CORBA server
HAHTsite also includes a Java package and a Basic library that enable you to use the ActiveX Data Objects API for data management.
HAHTsite Server Object Model
The classes in the HAHTsite Server Object Model (SOM) are implemented in Java. At runtime, Java projects access SOM objects as real Java objects, and can subclass SOM classes and override SOM methods. You can also access the SOM from HAHTtalk Basic projects using HAHTtalk Basic syntax. However, some limitations apply; for example, SOM objects cannot be subclassed in a HAHTtalk Basic project. The classes in the SOM give you many capabilities, including the ability to examine requests sent from a Web browser, to manage data sources, and to protect information from unauthorized access.
The principal packages in the SOM are: • com.haht.project
• com.haht.project.datamanager • com.haht.project.form
• com.haht.access • com.haht.corba
The project package
The project package contains a number of built-in objects, which are available in every HAHTsite application. These objects are similar to the built-in objects in Microsoft’s Active Server Pages. They let you control the data passed to and from a Web browser client and to get information about the application, the Web server, and the Application Server.
When you run a HAHTsite application, each instance of a dynamic page is a Page object. You can also create dynamic pages programmatically, by
implementing the HAHTPage interface in a Java project, or by implementing a Basic subroutine that generates HTML in a HAHTtalk Basic project. In addition to Page objects, each HAHTsite application contains these built-in objects: • The Server object contains methods for storing variables that may be
shared among multiple applications (as long as they are running in the same process on the Application Server).
• The Application object has information about the current application, as well as event handlers that are triggered when an application or session
• The Request object’s methods retrieve data the client browser sends to the Web server — for example, form data or cookies.
• The Response object’s methods generate HTML that the Web server sends to the browser.
For further information about the project package, see Chapter 5, “HAHTsite Server Object Model.”
The datamanager package
The most important classes in the datamanager package are: • DataAgent
• DMConnectionManager
The DataAgent class represents an ADO recordset and enables you perform a variety of actions against that recordset. For example, you can use this class’s methods to set the command that returns the recordset, to perform an action such as updating a record, or to get or set the value of a field in the recordset’s current record.
The DMConnectionManager class includes methods for opening ADO connections to relational or nonrelational data sources. These connections can be shared by two or more data agents within a session to lessen the amount of time your application spends establishing connections. Or they can be private so that you can perform transactions on the connection.
The DataAgent and DMConnectionManager classes are discussed in detail in Chapter 8, “Data-Agent Programming” and Chapter 9, “Programming with the Connection Manager,” respectively.
The form package
The form package contains classes that represent the different types of form fields that you can place in a form, such as text boxes, combo boxes, and submit buttons. The methods of these classes enable you to perform tasks such as:
• setting a form field’s value • setting a text box’s width
• setting the selected status of a list-box element
Basically, all the form-field attributes that you can set in the IDE, you can also set at runtime.
For further information about the form package, see Chapter 7, “Form Fields Programming.”
The access package
The access package includes classes that enable you to control access to HAHTsite pages. A Privileges class provides a container for a set of user-defined privileges, and each session contains a Privileges object. In addition, HAHTsite pages have associated with them a set of privileges. At runtime, the Application Server determines whether a session has access to a particular page in an application by comparing the privileges in the session’s Privileges object with the page’s privileges. The session can access a page only if all of that page’s required privileges are contained in its Privileges object.
This package also contains classes that enable you to: • authenticate a user login
• retrieve a set of privileges from a repository by user name
Chapter 12, “Access Control,” provides a complete explanation of how to use the classes in this package.
The corba package
The corba package enables you to create a HAHTsite application that plays the role of a CORBA server. Using the CORBA interface, clients can create sessions and invoke Java object methods. This CORBA interface enables applets running in a browser to communicate directly with the Application Server, bypassing the Web server. It also enables other CORBA applications in the corporate IT infrastructure to invoke services from the HAHTsite Application Server.
A HAHTsite application can also function as a CORBA client. For further information about creating CORBA clients and servers, see Chapter 14, “HAHTsite CORBA Capabilities.”
HAHTtalk Basic projects use the Basic classes. You can find documentation for both interfaces on Microsoft’s Web site (http://msdn.microsoft.com/isapi/ msdnlib.idc?theURL=/library/sdkdoc/dasdk/mdwe7i0f.htm).
The ADO interface has the benefit of being well known and widely used by developers and, thus, is preferable to yet another proprietary data-access model. In addition, ADO is not tied to SQL, but allows access to both relational and nonrelational data sources.
ActiveX Data Objects classes
As mentioned earlier, HAHTsite’s ADO interfaces are based on those of Microsoft ADO 2.0. If you’re familiar with ADO programming, you know that the principal classes in the ADO object model are:
• Connection • Command • Recordset
The Connection class represents a connection to a data source. An object of this type enables you to open and close a connection to a data source, to execute a command that returns a recordset from the data source, and to manage transactions on the connection.
A Command object represents a command that queries a data source and returns a recordset. This command may be a SQL statement or some other textual command, the name of a database table, or the name of a stored procedure. A Recordset object contains the records returned over a connection following the execution of a query. Using a Recordset’s methods, you can navigate the records in the recordset, add a new row to the recordset or delete an existing record, update a record, and so on.
For information on how these ADO classes relate to the Server Object Model’s DataAgent and DMConnectionManager classes, see “Relationship between ADO and SOM classes” on page 6.
Relationship between ADO and SOM classes
As you’ve probably noticed, there’s some overlap between the ADO object model and the Server Object Model’s DMConnectionManager and DataAgent classes. You can use either — or a combination of both — for your
data-management programming.
Basically, the classes in the Server Object Model (SOM) provide a layer on top of the ADO classes that makes programming easier. The DMConnectionManager
class enables you to create an ADO connection, and the DataAgent class not only represents an ADO recordset, but knows about the connection and the command used to retrieve that recordset. If you use the IDE to create
connections to data sources and to create data agents, HAHTsite calls methods of the DMConnectionManager class and the DataAgent class in its generated code. So some of your data-management programming can be as simple as describing your requirements in the IDE.
For situations where you need to perform tasks that aren’t supported by the IDE, you can supplement the IDE’s generated code with your own code that uses the DMConnectionManager and DataAgent classes, or you can use the ADO interface directly.
Data management in HAHTtalk Basic projects
In HAHTtalk Basic projects, you have two options when it comes to ADO programming. You can create Basic objects by making calls like this:
Dim myConn As New ADODB.Connection myConn.open "..."
Or you can create Java objects by using the classes defined in the package com.haht.ado, like this:
Dim myConn As Object
myConn = CreateJavaObject("com.haht.ado.Connection" ...) myConn.open "..."
Although both approaches are perfectly acceptable, the assumption is that Basic programmers will prefer to use Basic objects (the first approach). If you do use the Basic library for your ADO programming, make sure you understand that a Basic object and its Java counterpart are not type compatible. That is, a Basic recordset and a Java recordset do not have the same data type. Therefore, the following code will result in a type-mismatch error:
Dim myRS As ADODB.Recordset .
. .
functions that give you much of the functionality of the
DMConnectionManager class. (These functions are discussed in Appendix E, “ADO Extensions.”) However, to work with data agents, you must work with Java objects.
Client-side scripting
Most code in a HAHTsite application is executed by the Application Server; however, HAHTsite also provides support for writing client-side scripts to be executed in the user’s browser. You can write these scripts in either JavaScript or VBScript.
To help you develop scripts more easily, the HAHTsite IDE provides a Client Scripts view of each HTML page. In this view, you see a tree representation of the Document Object Model for the page. By navigating this tree, you can select specific objects that you want to associate event handlers with. For instance, you can navigate to a text box in a form and select the text box’s onChange event. You can then use a script editor window to write a script that will be executed when this event occurs.
The Document Object Model window also displays properties of the currently selected object and methods that may be applied to that object. If you drag one of these properties from the Document Object Model window to the editing window, HAHTsite constructs the appropriate reference, including correct capitalization and syntax. This drag-and-drop feature makes it easier to write client scripts.
One other point. The task of writing client scripts and Dynamic HTML is complicated by variations in the Document Object Models in different browsers and different browser revisions. In general, the Document Object Model has become much more sophisticated and robust in later browser revisions, but pages that use the new browser features do not work in older browsers. The HAHTsite client-script editor enables you to view a particular Document Object Model. Thus, if you select the Internet Explorer 3.0 Document Object Model, HAHTsite will not display the new events and scriptable objects introduced in later versions of Internet Explorer and Netscape Navigator. This feature makes it easy to write scripts that work when the browser revision of your end users varies.
For additional information about using JavaScript and VBScript in your applications, see Chapter 10, “Working with Client-side Scripts.”
CORBA capabilities
The software bundled with HAHTsite includes Inprise (formerly Visigenic) VisiBroker for Java, a suite of tools for building distributed-object applications. HAHTsite applications written using the HAHTsite Server Object Model can incorporate calls to the VisiBroker interfaces and thereby act as standard CORBA objects. Using CORBA’s built-in capabilities, they can communicate with and become part of an enterprise built of distributed CORBA objects. Information from remote CORBA systems, such as mainframes, can be obtained by these CORBA-enhanced HAHTsite applications. This data can then be used in any manner within the HAHTsite application, providing a flexible, complete method to present enterprise information on the Web. In addition, there are several extensions to the HAHTsite Server Object Model that provide CORBA interfaces, allowing CORBA systems to operate directly on some HAHTsite server objects. This level of integration allows an external, non-HAHTsite application to connect as a CORBA client to a CORBA-enabled HAHTsite application acting as a CORBA server. Such a client can initiate and control a HAHTsite session, making use of session capabilities such as
automatic timeout.
CORBA can also provide a Java applet running in a browser the ability to communicate with a HAHTsite application without the overhead of the HTTP protocol. For applets requiring substantial or very dynamic data from the server, this can be very beneficial.
Access to COM/DCOM objects
In a Microsoft environment, HAHTsite also provides full access to
COM/DCOM objects. This access is native and does not depend on bridges from CORBA or other distributed object systems. From HAHTtalk Basic code, COM/DCOM servers are instantiated using the standard CreateObject call. Both in-process and out-of-process servers are supported. From Java code, COM/DCOM objects can be accessed via Java wrapper classes created using tools provided with the Microsoft SDK for Java. HAHTsite’s ability to naturally and directly access COM/DCOM objects makes it easy to interface your
Remote debugging
HAHTsite supports remote debugging of both Java and HAHTtalk Basic code running in the Application Server (but not both in the same debug session). The Java and HAHTtalk Basic debuggers share the same IDE interface and have equivalent function except that Java code must be published with the debug option so that debug symbols are included. (HAHTtalk Basic code can be debugged without the debug option.)
Debugging HAHTsite applications is discussed in detail in Chapter 15, “Debugging Server-side Code.”
2
Working with Java
Projects
What’s in this chapter ... 12 Adding server-side code to a Java project... 12 In-line code ... 13 Invoking an expression or a method from a dialog box ... 15 Adding code in Server-side Code view ... 17 What’s in a Java page?... 18 Editing HahtApplication.java and HahtSession.java ... 25 Adding Java files to a project ... 26 Naming conventions for Java projects ... 30 Calling a dynamic page from Java... 30 Event handling in a Java project ... 31 Editing and compiling Java code ... 37 Using the code editor ... 37 Compiling a Java application... 38 Finding compile-time errors... 39 Debugging a Java application... 39 Working with application directories ... 39
What’s in this chapter
The first half of this chapter explains how to add server-side code — that is, code that runs on the Application Server — to a Java project. The second half of the chapter explains the mechanics of working with the code editor and compiling the code.
Later chapters in this book give detailed explanations, with examples, of ways you can extend your HAHTsite application programmatically. For complete information about specific Java classes and methods, refer to the online help for the Server Object Model.
In addition, if you are interested in further customizing your application with client-side scripts and applets, then be sure to look at Chapter 10, “Working with Client-side Scripts,” and the HAHTsite IDE and IP User’s Guide, Chapter 20, “Applets and Multimedia Objects.”
Note - The examples throughout this book assume the appropriate import statements and invoke Java methods without qualifying them with the full package name — for example, they call Haht.getRequest() instead of
com.haht.Haht.getRequest(). HAHTsite’s generated code uses the full qualification, to eliminate the possibility that a HAHTsite class might have the same name as another (non-HAHTsite) package you have imported. You may wish to do the same.
Adding server-side code to a Java project
With Java, you can easily extend the functionality of your HAHTsite Web applications beyond what you can do with HTML or CGI programs. In a HAHTsite Java project, you can use Java in these ways:
1 You can add in-line code to a page, intermixed with other HAHTsite elements such as text, pictures, and forms. The code can be a simple expression, a single line, or a complete block of code. See “In-line code” on page 13.
2 You can insert expressions and method calls in many of the dialogs in the IDE — for example, a text box can be initialized with the value of an expression, and a form’s action can be a call to a Java method. See “Invoking an expression or a method from a dialog box” on page 15.
3 You can insert code in predefined places within the Java source for a page, using the HTML editor’s Server-side Code view. See “Adding code in Server-side Code view” on page 17.
4 You can modify or add to the source code for the HahtApplication and HahtSession classes. See “Editing HahtApplication.java and
HahtSession.java” on page 25.
5 You can create or import separate Java source files, with classes and methods that can be shared by all of the pages in an project and that can be reused in other projects. In addition, you can import Java class files as well as JAR, CAB, and ZIP files. See “Adding Java files to a project” on page 26.
HAHTsite Server Object Model
Much of this book describes classes and methods in HAHTsite’s Server Object Model, which controls the structure of a HAHTsite Web application. With the Server Object Model, you can perform tasks such as reading data passed on the URL, writing HTML data, and controlling session timeout, as well as managing data source connections, setting form field values, and controlling access to dynamic pages.
The Server Object Model is implemented in Java. However, it is equally accessible from HAHTtalk Basic projects, and the online help for the Server Object Model shows both the Java and HAHTtalk Basic syntax to call each method.
External logic
From your Java code, you also have access to Java classes outside the project and to capabilities such as CORBA, COM objects, and native methods. For more information, see Chapter 13, “Connecting to COM Objects” and Chapter 14, “HAHTsite CORBA Capabilities.”
In-line code
The ability to intermix Java code with other elements (such as text, pictures, widgets, and form elements) gives you a powerful tool for dynamically
• to create “internationalized” pages that contain text in different languages from which a user can select
• to retrieve values passed on the URL from a calling page • to override the value of a form field at runtime
In-line code is typically used for short expressions and statements. To
maintain the WYSIWYG look of your pages, you’ll probably want to minimize the amount of code that you place directly onto a page. You can do this by creating classes and methods in a project’s source pages and calling them from your Web pages. With this approach, you can also share classes and methods among the project’s Web pages.
In this example, a data agent (represented by the icon at the top of the page) populates a form with fields from a database. However, between the data agent and the form, note the code that disables the Next button if we’ve reached end of file.
Besides adding entire lines of code, you can also add expressions. An expression can include variables, constants, operators, and methods, as long as it resolves to a single value. Here are two examples:
a * b / c
aRequest.getURLField("txtCity")
To add a Java expression to an HTML page
1 On the page, click where you want the expression to appear. 2 Click the Server-side Expression button .
3 Type the expression.
4 By default, expressions are displayed in red in the editor, although you can change this setting using Tools > Options.
To add a statement to an HTML page
1 On the page, click where you want the statement to appear. 2 Click the Server-side Statement button .
3 Type one or more statements.
4 By default, statements are displayed in blue in the HTML editor. To convert existing text to an expression or statement
1 Select the text you want to convert.
2 Click either the Server-side Expression button or the Server-side Statement button . Or choose Edit > Character, click the Script tab, and then select the type of expression or statement you want to create.
To format the output of an expression or statement
You can format the output of a Java expression or statement, just as you can format text that you type directly on the page.
1 Select the paragraph or characters you want to affect.
2 To modify the paragraph properties, choose Edit > Paragraph... or make a selection from the Paragraph Styles toolbar.
3 To modify the character properties, choose Edit > Character.... or make a selection from the Character Styles toolbar. (If you modify the font color, the new color will be displayed in the browser, but not in the IDE.)
Invoking an expression or a method from a dialog box
The second way you can customize your project is through dialog boxes. FromDialog box expressions
To substitute an expression for a field name or constant, prefix the expression with “==”. For example, in the properties for a link, you could define the query string to contain the entry point name of the current page:
callingPage=/*==getName()*/
On the destination page, you could retrieve the information this way: aRequest.getURLField("callingPage")
which would return packagename.class.method, like this: JavaExample.HsLinkStart.run
Notice in the example the use of "/*" and "*/" bracketing the expression. You must use this construction when you want to use an expression in a
name/value attribute pair, or when it appears in the middle of a script. However, if you simply want to set an attribute to the value of an expression, you can use ==expression.
Dialog box method calls
In addition to using expressions, you can call user-defined methods from several property sheets in the IDE, such as the Form Properties dialog and the Link Properties dialog. For example:
• A Java method can generate the binary data to display a picture, an image map, or a multimedia object.
• It can be the destination for a dynamic link (the value of an HREF attribute tag).
• It can be the default action that takes place when the user submits a form, or the action tied to one of the form’s buttons.
Obviously, the content of your Java method will be determined primarily by what you want it to do, and the HAHTsite IDE and IP User’s Guide explains any restrictions on calling a method or subroutine in the documentation for each set of properties. However, if the effect is to display a page, the class should implement the HAHTPage interface, including the run method:
void run (Request aRequest, Response aResponse)
The run method and its arguments are described later in this chapter; see “What’s in a Java page?” on page 18.
Adding code in Server-side Code view
The third way to customize your project is to add code directly to the server-side code for a page. When you include a dynamic page in a build or publish operation, the IDE generates a new Java source file for that page, extending the com.haht.project.Page class. When you add in-line code to the page, it’s inserted in the Java source, in the run method for that page. However, you may want to make other additions to the code for a page — for example, you might want to add an import statement, add some initialization code to the run method, or call your own exception handler. The HTML editor’s Server-side Code view lets you view the source code for a page, and lets you make additions, in predefined places, that will be preserved when the page is regenerated. (Note - you cannot change the generated source code; you can only add to it.)
3 Here are some points to note:
• The white areas mark places where you can insert code.
• The grayed-out areas mark generated source code, which is read-only. • If you make changes in Server-side Code view, and then return to
Normal view or HTML tags view, you will see your changes reflected.
• If the Server-side Code view button is disabled, be sure that you have
saved the page.
For more information on this process, see the note that follows. Behind the scenes: How does Server-side Code view work?
To keep from overwriting your additions, the IDE must keep your code separate from the code it generates. When you add code in Server-side Code view, your code is translated into HTML tags and kept in the project’s HTML file for this page. If you look at the page in HTML tags view, you will see sections like this:
<SCRIPT
language="hahtjava-statement"><!--out.print(aRequest.getURLField("txtName"));--></SCRIPT> When you build or publish the project, the code for the dynamic page is generated from the HTML file.
What’s in a Java page?
For each dynamic page, the IDE generates a file (Hspagename.java) that defines a class Hspagename as a subclass of Page. The source code for each dynamic page has these contents:
• A package statement • Import statements
• Class declaration and constructor • A run method
• An exception handler • A form handler
• Places to add classes and methods
The following sections explain each of these topics, using as an example the Java source for a page that simply displays the current date.
A package statement
The package name is the name of the project.
For more information about package names, see “Naming conventions for Java projects” on page 30.
Import statements
Each page source file imports several packages, including the HAHTsite packages for the Server Object Model and for data management. You can add your own import statements using the HTML editor’s Server-side Code view.
Class declaration and constructor
Each page has a constructor, called once per page per session to create the page object. If the page contains form fields, they are initialized here. You can also add custom code to the constructor.
package ExamplProj;
//////////////////////////////////////////////////////////////// // IMPORTS
//////////////////////////////////////////////////////////////// import com.haht.*;
import com.haht.project.*; import com.haht.io.*;
import com.haht.project.form.*;
import com.haht.project.datamanager.*; import com.haht.ado.Abstract.*;
import java.io.*; import java.util.*; // custom imports
import com.haht.access.*; import java.text.*;
The constructor also gets references to both the Application object and the Session object — references you can use anywhere in a dynamic page. These references are very useful in accessing application-level and session-level variables.
A run method
Each page has a run method, with two arguments: the Request object and the Response object. The run method emits any header lines — for example,
Content-type: text/html
Note that you can override the content-type header by another call to the Response object’s setContentType method. See “Adding content information to a header line” on page 127.
After emitting header lines, the run method then sets up the basic structure of the page, which would look like this in HTML:
<HTML>
<HEAD>...</HEAD> <BODY>...</BODY> </HTML>
public class HsShowDate extends com.haht.project.Page // Specify implements declarations here.
{ /**
* Default constructor for HsShowDate *
**/
public HsShowDate () {
hahtApplication = (HahtApplication) Haht.getApplication(); hahtSession = (HahtSession) Haht.getSession();
...
// Custom constructor code.
When you add in-line code to a page, it’s normally added here, between the <BODY> and </BODY> tags. (Some code — such as setting a cookie — must be output with the HTTP headers. HAHTsite automatically handles this code correctly. See “Writing headers” on page 126.)
Notice the marked sections where you can add local variables, initialization code, and custom HTTP response headers (two places). You can also edit any in-line code. In this example, the page contains two lines of in-line code, to set the date.
/**
* Runs the page, producing HTML. *
* @param aRequest - HTTP request for this page * @param aResponse - HTTP response for this page *
**/
public void run(com.haht.project.Request aRequest, com.haht.project.Response aResponse) {
HtmlWriter out;
// user-defined run() local variables
try {
// Initialize variables. out = aResponse.getWriter();
// Custom initialization code executes before HTML // tags are generated.
// Output HTTP response headers. // Custom HTTP Response Headers.
aResponse.setContentType("text/html"); out.print("\r\n");
References to the Request and Response objects
The run method, seen in the example above, has two arguments:
• the Request object (aRequest), whose methods get information from the Web browser — for example, methods to read data passed in a form field or on the URL.
• the Response object (aResponse), whose methods send information to the Web server — for example, HTML output and cookies.
The Request and Response objects are built in to your HAHTsite application, along with the Application and Session objects. Both these object references (aRequest and aResponse) will be useful in your in-line code. For example, to read a value passed in a form or on the URL, you would call
aRequest.getURLField. // Generate HTML.
out.print("<HTML>\r\n"); out.print("<HEAD>\r\n");
out.print(" <META name=\"Generator\" content=\"HAHTsite 4.0\">\r\n");
out.print(" <TITLE>ShowDate</TITLE>\r\n"); out.print("</HEAD>\r\n");
out.print("<BODY>\r\n"); out.print(" <P>"); Date d = new Date(); out.print(d);
out.print("</P>\r\n");
out.print(" <P> </P>\r\n"); out.print("</BODY>\r\n");
out.print("</HTML>");
// All HTML has been generated. Put cleanup code here.
} // try
catch (java.lang.Throwable t) {
handleException(t, "HsShowDate", aRequest, aResponse); } // catch
Note - For information about using the variables and methods of the Application and Session objects, see “Calling a dynamic page from Java” on page 30. For general information on the HAHTsite Server Object Model’s built-in objects, see “Built-in objects” on page 90.
A reference for writing HTML output
The run method also gets a reference to the default HtmlWriter. To write HTML output programmatically, you can use statements like this:
out.print(d);
Of course, you can also intermix text and in-line code on a page. In the Java source, the text turns into out.print statements.
An exception handler
The run method of every dynamic page calls a general-purpose exception handler, handleException, to catch runtime errors and print an error message similar to this.
You can override this method or add other exception handlers to your code. A form handler
The Java source for each dynamic page contains a form handler that adapts to the contents of the page. At runtime, when a user submits a form, the form handler determines which button was clicked and calls the appropriate command handler.
Because this page doesn’t contain a form, it has no command handlers. If it did, you would see additional places in which you can customize the command handlers by writing your own event-handling code. For more information, see Chapter 8, “Data-Agent Programming.”
Places to add classes and methods
In Server-side Code view, you will see a number of marked sections where you can add classes, methods, and variables:
• public, protected, and private methods • static initializer code
• nested classes
• public, protected, and private member variables /**
* Entry point that is called via URL when a form is * submitted from this page.
*
* @param aRequest - HTTP request for this page * @param aResponse - HTTP response for this page *
**/
public void mapFormToCmd
(com.haht.project.Request aRequest, com.haht.project.Response aResponse) {
boolean bCmdHandlerCalled = false; if (! bCmdHandlerCalled)
{
getErrors().add("Received form command did not invoke a command-handler", "form-handler");
run (aRequest, aResponse); }
}
// user-defined public methods
// protected methods
Editing HahtApplication.java and HahtSession.java
In addition to one or more Page subclasses, your HAHTsite application includes a HahtApplication class and a HahtSession class, which you can see in your project window.// private methods
// user-defined private methods
// static initializer code static
{
// Initialization code for user-defined static variables.
}
// nested classes
// user-defined nested classes
// public member variables // user-defined public variables
// protected member variables
protected HahtApplication hahtApplication; protected HahtSession hahtSession;
// user-defined protected variables
// private member variables // user-defined private variables
You can open these files in the code editor and add variables and methods to these classes. You can use HahtApplication to cache variables that may be shared by multiple sessions. Use HahtSession to store variables that apply across page boundaries.
A session recordset is a particularly powerful use of the HahtSession object. You can update a recordset on one page and use it to populate a form on another, without reaccessing the database.
Both HahtApplication and HahtSession contain event handlers that you can edit; see “Event handling in a Java project” on page 31.
For more information about these files, see “Built-in objects” on page 90. Note - Do not call Server Object Model methods from the
constructors in HahtApplication and HahtSession. The Server Object Model must be initialized first. Instead, edit the onStart and onEnd methods.
Adding Java files to a project
The final way to add server-side Java to your project is by creating a Java source file or by importing a Java source file, class file, or JAR, CAB, or ZIP file, to be used by any of a project’s dynamic pages.
In a Java project, all Java files should be stored in the Packages folder. You can use the same package name as the page files (that is, the project name), or you can create additional packages and store the Java files in subfolders under Packages.
Note - If you (1) omit the package statement in a Java source page and (2) reference one of its classes from an HTML page, some compilers will generate a “class not found” compiler error. To avoid this problem, put all your source code in packages and use the appropriate package import statements. To add a new Java source page
1 Choose File > New > Java Source... The New Java Source dialog appears.
2 Select the type of Java code you want to create:
Type Description
Applet Source for a Java applet
Common Java source that may be used in both server-side code and applets
Server-side Java Source for Java code that will run on the server Servlet Source for a Java servlet — a Web server plug-in that
To import a Java source, class, JAR, CAB, or ZIP file
In addition to creating new source files in your project, you can import existing Java files, including:
1 In the project window, select the folder in which you want to store the imported file. For server-side Java, files must be stored in the Packages folder. (Applets, on the other hand, are stored in the Web folder.) 2 Choose File > Import File.... The Import Files dialog appears.
Type Description Extension
Java source Java source code .java
Class file Compiled Java code .class
JAR file Java archive file, which can contain multiple files (class files, images, etc.)
.jar
Java CAB file Collection of Java class files in Microsoft’s Java Cabinet format
.cab
Java ZIP file Collection of Java class files in ZIP format, typically uncompressed
3 Type or browse for one or more filenames.
4 Choose Copy Files or Create Shortcuts. If you want to maintain one central version of a file but use it in several projects, you may want to create a shortcut.
5 In the combo box marked Import Java files as, select the type of Java code you are importing — server-side, applet, servlet, or common.
6 Click OK to complete the import.
For more information about imported files, including information about source control, consult the HAHTsite IDE and IP User’s Guide, Chapter 3, “Managing Projects.”
To save a source code page
1 Select File > Save. The Save Code Page As dialog appears.
2 Type in a page name, or accept the default name. The suffix must be “.java”.
3 To save the code page inside the project, browse within the Project Items window for the folder name you want.
4 If the project is in source control, you will see an additional checkbox: Add to source control. Check this box to add this file to the source control system.
5 Click OK to save your changes.
To save a source code page outside the project
To be called from within the project, a source code page must be saved inside the project. However, you can also save it to a file outside the project. 1 Select File > Save. The Save Code Page As dialog appears.
2 Click the Save to File... button. The Save As dialog appears. 3 Browse for a folder location and enter a filename.
Naming conventions for Java projects
HAHTsite uses certain naming conventions for Java projects. In a HAHTsite Java project, project names become package names.
• Project names must be unique within a site.
• Any valid filename can be used as a project name, with one exception: Java keywords cannot be used as project names (you’ll get an error when you create the project).
• When the IDE generates the package name, it turns any non-alphanumeric characters (including spaces) to underscores (_).
Naming conventions for dynamic pages
When the IDE generates the Java code for a dynamic page, the page becomes a Java class.
• All the dynamic pages in a project are placed in the same package, regardless of the directory structure you may have set up within the project. This means that page names must be unique to the entire project, since class names must be unique within a package. (Note: you can have source pages in different packages; this rule applies only to dynamic pages.)
• The IDE prepends “Hs" to the page name, so that a page named Welcome would become the class HsWelcome.
• Any valid filename can be used as a page name. When it generates the class name, the IDE converts non-alphanumeric characters (anything other than A-Z, a-z, and 0-9) to underscores. For example, Page 1.html, Page_1.html, and Page$1.html would all resolve to the class HsPage_1.
Calling a dynamic page from Java
When a user browses a dynamic page for the first time, HAHTsite instantiates the page object and invokes its run method. If the user returns to the same page, rather than instantiating the page again, HAHTsite uses a reference to that page.
You can do the same thing in your application, when you call a dynamic page programmatically. In a Java application, you instantiate a dynamic page by calling the Session object’s returnHAHTPageObject method and passing it the
fully-qualified page name (that is, packagename.classname). If the page hasn’t already been instantiated, returnHAHTPageObject instantiates the page object and returns a reference to it; otherwise, it simply returns the object reference. (If for some reason, you want a new instance of the page, then you can use new rather than returnHAHTPageObject.) You call a dynamic page by invoking its run method.
This code instantiates a dynamic page called MyNewPage, in a project called ExampleProj:
HAHTPage MyNewPage = hahtSession.returnHAHTPageObject ("ExampleProj.HsMyNewPage");
To call its run method, you would use this code: MyNewPage.run(aRequest, aResponse);
Event handling in a Java project
If you look at the code for HahtApplication.java and HahtSession.java, you’ll see several methods that are triggered when an application or a session starts or ends. In a Java project, you can add your own code to these six methods:
Application method
Description
onStart Called right after a new application is created, but before any pages are run.
onEnd Called just before an application is destroyed.
onSessionStart Called when a new session is created, but before any pages are run. (Called for each session. This method is called before the Session object’s onStart method.)
onSessionEnd Called just before a session is destroyed. (Called for each session. This method is called after the Session object’s onEnd method.)
When are these methods useful? In the Session object’s onStart method, you could populate a session recordset for use by subsequent pages in the session — for example, you might want to read in the values of a database table (a catalog, say) that’s used by several different pages. In the onEnd method, you might want to save the session state, so that you can restore it later if the user returns to the application.
If onStart fails, the Application Server calls onEnd and terminates the application or session without running any pages. There are two ways for onStart to fail:
• You can throw a runtime exception, such as this: throw new RuntimeException("Failed in onStart");
In this case, the Application Server calls onEnd, generates a runtime error message, and terminates the session.
• You can edit the onStart method to produce a custom diagnostic page. Generally, after producing a diagnostic page, you want to prevent any further running of the session and any further error output from the Application Server, so you should also call the Session object’s abandon method, which calls onEnd and terminates the session.
The onEnd methods are passed an ApplicationEvent or SessionEvent object. By calling this object’s getReason method, you can determine the reason for the event. For a session ending, the available reasons are:
Session method Description
onStart Called when a new session is created, but before any pages are run. (Called once, for the current session.)
onEnd Called just before a session is destroyed. (Called once, for the current session.) Note: onEnd is called even if onStart fails.
Java
Response aResponse = Haht.getResponse(); aResponse.setContentType("text/html"); aResponse.endHeaders();
aResponse.write("Exiting the session <br>"); aResponse.write("Failed in onStart <br>"); // Abandon the session
