| Previous Contents Index Next |
| iPlanet Application Server 6.5 Java Foundation Class Reference |
Chapter 2 Classes
This chapter provides reference material on the classes in the iPlanet Application Server Foundation Class Library.The following classes are included in this chapter:
The AppLogic class is deprecated and is provided for backward compatibility only. AppLogics are not part of iPlanet Application Server's new application model, which is based on standards defined in the servlet, EJB, and JDBC specifications. The AppLogic class is provided so that existing AppLogics continue to be supported. However, new applications should avoid calling AppLogic methods whenever possible.
For information about replacing AppLogic functionality in existing applications, see the Migration Guide.
The AppLogic GXAppLogic class is the base class for all AppLogic code. It provides a suite of useful AppLogic-related helper methods and member variables. You can, for example, use methods in your derived AppLogic GXAppLogic class to create database connections, queries, transactions, and HTML output.
To derive a class from GXAppLogic, include gxapplogic.h and write a class declaration such as the following:
class HelloAppLogic : public GXAppLogic
In your derived class, override the Execute( ) method to implement the main task of the AppLogic object, as shown in the following example:
return Result("<html><body>Hello, world!<body></html>");
To use the AppLogic class, you must first import the com.kivasoft.applogic package at the beginning of your AppLogic file, as shown in the following example:
import com.kivasoft.applogic.*;
After you import the com.kivasoft.applogic package, you can create an instance of AppLogic and override the execute( ) method with AppLogic-specific code, as shown in the following example:
public class myAppLogic extends AppLogic {
/* Override execute() method with AppLogic code */
return result("Hello, world!\n");
Package Include File
com.kivasoft.applogic gxapplogic.h
Methods
Most methods of the AppLogic class are deprecated. Instead of calling these methods, we recommend using equivalent functionality as described with each AppLogic method.In some cases, you may want to call AppLogic methods to access iPlanet Application Server features that are not currently available through the Java standards. For example, you may want to take advantage of caching or distributed state trees. In the following table, boldface type indicates a method that may be useful in iPlanet Application Server 6.0 applications.
Example
The following example shows importing the com.kivasoft and Java packages, and overriding the execute( ) method with code that logs a series of messages:
Related Topics
Chapter 4, "Writing Server-Side Application Code," and Chapter 11, "Running and Debugging Applications," in Programmer's Guide.
Creates a new data connection object and opens a connection to a database or data source.
createDataConn( ) is deprecated. In standard-based applications, use the getConnection( ) method in the javax.sql.DataSource interface.
Syntax 1
Use this version for most database drivers.public IDataConn createDataConn(
int flags,
int driver,
String datasource,
String database,
String username,
String password)
Syntax 2
Use this version for database drivers requiring parameters not found in Syntax 1. Provides parameters through an IValList object instead. To use this syntax, you must first create an instance of the IValList interface and use setValString( ) to specify the connection parameter names and values.public IDataConn createDataConn(
int flags,
int driver,
IValList prop,
IContext context)HRESULT CreateDataConn(
DWORD flags,
DWORD driver,
IGXValList *props,
IGXContext *context,
IGXDataConn **ppConn);
flags. One or more optional flags used for connecting to the specified data source.
To try to use a cached connection, if one is available, specify GX_DA_CONN_FLAGS.GX_DA_CACHED. If no cached connections are currently available, a new one is created.
The AppLogic can pass one parameter from both mutually exclusive pairs, as shown in the following example:To always create a new connection (instead of using a cached connection), specify GX_DA_CONN_FLAGS.GX_DA_NEW.
To retry if a connection is not available, specify GX_DA_CONN_FLAGS.GX_DA_CONN_BLOCK.
To return a failure immediately after the first attempt if a connection is not available, specify GX_DA_CONN_FLAGS.GX_DA_CONN_NOBLOCK.
(GX_DA_CONN_FLAGS.GX_DA_CACHED | GX_DA_CONN_FLAGS.GX_DA_CONN_BLOCK)
Specify 0 (zero) to use the system's default settings: GX_DA_CONN_FLAGS.GX_DA_CACHED and GX_DA_CONN_FLAGS.GX_DA_CONN_BLOCK
driver. Specify one of the following static variables in the GX_DA_DAD_DRIVERS class:
If GX_DA_DRIVER_DEFAULT is specified, the iPlanet Application Server evaluates the drivers and their associated priorities set in the registry to determine the driver to use. Specify GX_DA_DRIVER_DEFAULT if your system uses ODBC and native drivers, and if you want the iPlanet Application Server to choose between an ODBC driver and a native driver at connection time.
datasource. Name of the data source to connect to. Used for databases that organize data into data source, database, and table objects and sub-objects. For example, a data source for Accounting might contain separate databases for GL, AP, and AR. Each database, such as Accounts Payable, might be a collection of individual tables, such as a vendor table, purchase order table, materials table, and so on. See your database server documentation for more information.
database. Name of the database to connect to. Used for database servers that organize data into databases and tables. See your database server documentation for more information.
username. Login user name that is valid for the specified database.
password. Login password that is valid for the specified user name and database.
props. IValListIGXValList of connection-specific information required to log in to the data source. Use the following keys for the connection parameters:
"DSN" for the data source name.
context. A pointer to the IContextIGXContext object, which provides access to iPlanet Application Server services. Specify nullNULL.
ppConn. A pointer to the created IGXDataConn object. When the AppLogic is finished using the object, call the Release( ) method to release the interface instance.
Usage
A data connection is a communication link or session with a database or other data source. Before interacting with a data source, an AppLogic must first establish a connection with it. Each connection is represented by a data connection object, which contains all the information needed to communicate with a database or data source, such as the name of the database, database driver, user name, password, and so on. A data connection object is an instance of the IGXDataConn interfaceIDataConn interface.Use createDataConn( )CreateDataConn( ) to set up a separate connection for each database or data source you want to access. AppLogic objects refer to the data connection object in their methods that perform subsequent operations on the database.
Call createDataConn( )CreateDataConn( ) before running any other database operations requiring a data connection object.
Your network and the database server must be correctly configured and running so that the AppLogic on your application server can log into the database management system with which it will communicate.
The data source name, database name, user name, and password must be valid for the database management system to which you want to connect.
The AppLogic must log in with sufficient access rights to perform all operations it attempts on the data source.
Tips
Before logging in to the database, the AppLogic should check the user's security level to verify sufficient access rights to perform intended operations on the database.
The Data Access Engine (DAE) manages database connections and related housekeeping tasks, such as shutdown and cleanup. While the DAE performs these tasks automatically and intermittently, an AppLogic can also explicitly close data connections using CloseConn( ) closeConn( ) in the IGXDataConn interfaceIDataConn interface.
Before using an ODBC connection, you must use the ODBC administration utility supplied with your database software to define and name a data source. For more information about how to do this, refer to your ODBC documentation.
To connect to a Sybase database, specify nullNULL for the datasource, and specify the database in the form of server:database_name. For example:
A connection object can only be used by one thread at a time. When you need to access a database, get the connection object and save it in a local variable. When you're done, close the connection. For example:
Return Value
IDataConn object representing the specified data connection, or null if a failure occurred. AppLogic uses the data connection object to uniquely identify this data connection in subsequent operations, such as queries and record insert, update, and delete operations.HRESULT, which is set to GXE_SUCCESS if the method succeeds.
Related Topics
IGXDataConn interface IDataConn interface,
IValList interfaceIGXValList interface
Chapter 5, "Working with Databases" in Programmer's Guide.createDataConnSet( )"> "About Database Connections" in Chapter 5, "Working with Databases" in Programmer's Guide.createDataConnSet( )
Creates a collection used to dynamically assign query name/data connection pairs before loading a query file.
createDataConnSet( ) is deprecated. In standard-based applications, use the JDBC API to provide similar functionality.
Syntax
public IDataConnSet createDataConnSet(
int flags)HRESULT CreateDataConnSet(
DWORD flags,
IGXDataConnSet **ppDataConnSet);
flags. Specify 0. Internal use only.
ppDataConnSet. Pointer to the created IGXDataConnSet object. When the AppLogic is finished using the object, call the Release( ) method to release the interface instance.
Usage
Use createDataConnSet( )CreateDataConnSet( ) only if you are loading a query file using loadHierQuery( )LoadHierQuery( ). To use a query file, an AppLogic first establishes a data connection with each database on which any queries will be run.Next, the AppLogic calls createDataConnSet( )CreateDataConnSet( ) to create an IDataConnSetIGXDataConnSet object, then populates this collection with query name/data connection pairs. Each query name in the collection matches a named query in the query file. IDataConnSet provides a method for adding query name/data connection pairs to the collection. In this way, AppLogic can use standardized queries and select and assign data connections dynamically at runtime.
Finally, the AppLogic calls loadHierQuery( )LoadHierQuery( ) to create the hierarchical query object.
Return Value
IDataConnSet object that can hold a collection of data connections, or null for failure (such as insufficient memory).HRESULT, which is set to GXE_SUCCESS if the method succeeds.
Related Topics
loadHierQuery( )LoadHierQuery( ),
IDataConnSet interfaceIGXDataConn interface"About Database Connections" in Chapter 5, "Working with Databases," in Programmer's Guide.
Creates a new query object used for building and running a hierarchical query.
createHierQuery( ) is deprecated. In standard-based applications, use the JDBC API to create join statements.
Syntax
public IHierQuery createHierQuery()HRESULT CreateHierQuery(
IGXHierQuery **pHQ);
pHQ. A pointer to the created IGXHierQuery object. When AppLogic is finished using the object, call the Release( ) method to release the interface instance.
Usage
Use createHierQuery( )CreateHierQuery( ) for nested output or for merging query results with a template using evalOutput( )EvalOutput( ) or evalTemplate( )EvalTemplate( ).A hierarchical query can be more complex than a flat query. A hierarchical query combines one or more flat queries which, when run on the database server, returns a result set with multiple nested levels of data. The number of nested levels is limited only by system resources.
The hierarchical query is not necessarily a single query. In fact, a hierarchical query is a collection of one or more flat queries arranged in a series of cascading parent-child, one-to-many relationships. The parent query obtains the outer level of information, or summary, and the child query obtains the inner level of information, or detail. The parent level of information determines the grouping of information in its child levels. The child query is run multiple times, once for each row in the parent query's result set.
Use createQuery( )CreateQuery( ) instead for simple, flat queries requiring tabular, non-nested output that is merged with HTML templates.
To use a hierarchical query, an AppLogic first creates each individual flat query and defines its selection criteria. Next, it creates the IHierQuery IGXHierQuery object with createHierQuery( )CreateHierQuery( ), then calls AddQuery( )addQuery( ) repeatedly to add a child query to a parent query for each level of detail in the hierarchical query.
Alternatively, an AppLogic can create a hierarchical query by loading a query file using loadHierQuery( )LoadHierQuery( ). With this technique, the iPlanet Application Server can cache query objects to service requests for identical queries more quickly.
Return Value
IHierQuery object representing a hierarchical query, or null for failure. An AppLogic module uses this object to uniquely identify this hierarchical query in subsequent operations, such as defining the query criteria, executing the query, retrieving query results, and processing templates.HRESULT, which is set to GXE_SUCCESS if the method succeeds.
Example 1
// Create the flat queryqry.setFields("loginName, Password, AccessLevel")
// Create the hierarchical query used for template processing
IHierQuery hqry = createHierQuery();
// Add the flat query object and data connection to hqry
hqry.addQuery(qry, conn, "USERS", "", "");
// Pass hierarchical query to evalTemplate() for reporting
if(evalTemplate("apps/template/userinfo.html", hqry)== GXE.SUCCESS)
return result("Failed to Generate HTML");
Example 2
// Create the flat queryqry.setFields("loginName, Password, AccessLevel")
// Create the hierarchical query
IHierQuery hqry = createHierQuery();
hqry.addQuery(qry, conn, "USERS", "", "");
// Execute the hierarchical query
IHierResultSet hrs = hqry.execute(0, 0, null);
if(hrs.getRowNumber("USERS")!=0)
// Create the hierarchical query
if(((hr=CreateHierQuery(&pHq))==GXE_SUCCESS)&&pHq) {
pHq->AddQuery(pQuery, pConn, "SelCusts", "", "");
Related Topics
addQuery( )AddQuery( ) in the IHierQuery interfaceIGXHierQuery interface,
createDataConn( )CreateDataConn( ),
createQuery( )CreateQuery( ),
execute( )Execute( ) in the IHierQuery interfaceIGXHierQuery interface,
IGXHierQuery interface IHierQuery interface,
IGXHierResultSet interface IHierResultSet interface""Caching AppLogic Results to Improve Performance" in Chapter 4, "Writing Server-Side Application Code," in Programmer's Guide.
Creates an electronic mailbox object used for communicating with a user's mailbox.
Syntax
public IMailbox createMailbox(
String pHost,
String pUser,
String pPassword,
String pUserAddr)HRESULT CreateMailbox(
LPSTR pHost,
LPSTR pUser,
LPSTR pPassword,
LPSTR pUserAddr,
IGXMailbox **ppMailbox);
pHost. Address of POP and SMTP server, such as mail.myOrg.com. If the POP and SMTP servers are running on different hosts, you must use two separate createMailbox( )CreateMailbox( ) calls.
pUser. Name of user's POP account, such as jdoe.
pPassword. Password for POP server.
pUserAddr. Return address for outgoing mail, such as john@myOrg.com. Usually the electronic mail address of the user sending the message.
ppMailbox. A pointer to the created IGXMailbox object. When the AppLogic is finished using the object, call the Release( ) method to release the interface instance.
Usage
Use createMailbox( )CreateMailbox( ) to set up a mail session for sending and receiving electronic mail messages.In the Internet electronic mail architecture, different servers are used for incoming and outgoing messages.
POP (post-office protocol) servers process incoming mail and forward messages to the recipient's mailbox.
SMTP (simple mail transport protocol) servers forward outgoing mail to the addressee's mail server.
Rules
The specified user account and password must be valid for the specified POP host name.
The user address must be valid for the specified SMTP server.
Tip
Once instantiated, use the methods in the IMailbox interfaceIGXMailBox interface to open and close a mailbox, as well as send and receive mail messages.
Return Value
IMailbox object representing a mailbox, or null for failure (such as an invalid parameter).HRESULT, which is set to GXE_SUCCESS if the method succeeds.
Related Topics
IMailbox interfaceIGXMailBox interface"Introduction to Email in Netscape Application Server Applications" in Chapter 10, "Integrating Applications with Email" in Programmer's Guide.
Creates a new query object used for building and running a flat query.
createQuery( ) is deprecated. In standard-based applications, use the createStatement( ) method in the java.sql.Connection interface.
Syntax
public IQuery createQuery()HRESULT CreateQuery(
IGXQuery **ppQuery);
ppQuery. A pointer to the created IGXQuery object. When AppLogic is finished using the object, call the Release( ) method to release the interface instance.
Usage
A flat query is the simplest type of query. It retrieves data in a tabular, non-hierarchical result set. Unlike a hierarchical query, a flat query returns a result set that is not divided into levels or groups.An AppLogic can also use createQuery( )CreateQuery( ) to create a query object to perform SELECT, INSERT, DELETE, or UPDATE operations on a database.
To query a database, the AppLogic first uses createQuery( )CreateQuery( ) to create the query object, then constructs the query selection criteria using methods in the IGXQuery interface IQuery interface, and finally runs the query on a database server. The AppLogic can process results using methods in the IGXResultSet interfaceIResultSet interface.
Alternatively, AppLogic can pass a SQL SELECT statement directly to the database server using SetSQL( )setSQL( ) in the IGXQuery interfaceIQuery interface.
To retrieve data with nested levels of information, use createHierQuery( )CreateHierQuery( ) instead.
Return Value
IQuery object representing a query, or null for failure. AppLogic uses this object to uniquely identify this query in subsequent operations, such as defining the query criteria, executing the query, retrieving query results, and processing templates.HRESULT, which is set to GXE_SUCCESS if the method succeeds.
Related Topics
createDataConn( ),
CreateDataConn( )createQuery( )CreateQuery( ),
IGXHierQuery interface IHierQuery interface,
IGXHierResultSet interface IHierResultSet interface,
ExecuteQuery( ) executeQuery( ) in the IGXDataConn interface IDataConn interface
Creates a new session object used for tracking a user session.
createSession( ) is deprecated. In standard-based applications, use the getSession( ) method in the interface javax.servlet.http.HttpSession, and set the boolean parameter to true.
Syntax
public ISession2 createSession(
int dwFlags,
int dwTimeout,
String pAppName,
String pSessionID,
ISessionIDGen pIDGen)HRESULT CreateSession(
DWORD dwFlags,
ULONG dwTimeout,
LPSTR pAppName,
LPSTR pSessionID,
IGXSessionIDGen *pIDGen,
IGXSession2 **ppSession);
dwFlags. Specify one of the following flags, or 0 to use the default system settings:
GXSESSION.GXSESSION_LOCAL to make the session visible to AppLogics in the local process only.
The default scope is distributed and the default timeout is 60 seconds from the time the session was last accessed.GXSESSION.GXSESSION_CLUSTER to make the session visible to all AppLogics within the cluster.
GXSESSION.GXSESSION_DISTRIB to make the session visible to all AppLogics on all iPlanet Application Servers.
GXSESSION.GXSESSION_TIMEOUT_ABSOLUTE to specify that the session expires at a specific date and time. Do not use this flag. It is currently unimplemented but reserved for future use.
GXSESSION.GXSESSION_TIMEOUT_CREATE to specify that the session expires n seconds from the time the session was created.
dwTimeout. Session timeout, in number of seconds, or zero for no timeout. The meaning of timeout depends on the timeout flag specified in dwFlags. A value of 0 means the session is deleted when the AppLogic calls destroySession( )DestroySession( ).
pAppName. Name of the application associated with the session. The application name enables the iPlanet Application Server to determine which AppLogics have access to the session data. Specify nullNULL to use the application name assigned to the AppLogic during kreg registration.
pSessionID. The session ID to use. Specify nullNULL to use the default ID generated by the system.
pIDGen. The session ID generation object used to generate session IDs. Specify null.NULL to use the default IGXSessionIDGen object, or specify a custom session ID generation object.
ppSession. A pointer to the created IGXSession2 object. When AppLogic is finished using the object, call the Release( ) method to release the interface instance.
Usage
Use createSession( )CreateSession( ) to create a new session between a user and your application. AppLogics use sessions to store information about each user's interaction with an application. For example, a login AppLogic might create a session object to store the user's login name and password. This session data is then available to other AppLogics in the application.
Rule
If you implement a custom session class, you must override createSession( )CreateSession( ).
Return Value
ISession2 object representing a user session, or null for failure.HRESULT, which is set to GXE_SUCCESS if the method succeeds.
Example
In the following code, getSession( )GetSession( ) checks if a session exists. If there isn't an existing session, createSession( )CreateSession( ) creates a new session.
ISession2 sess; sess = getSession(0, "Catalog", null); if (sess == null) { log("Could not get session, creating a new one"); sess = createSession(GXSESSION.GXSESSION_DISTRIB, 0, null, null, null);
hr = GetSession(0, "Catalog", NULL, &m_pSession); if (hr != GXE_SUCCESS) { Log("Could not get session, creating a new one"); hr = CreateSession(GXSESSION_DISTRIB, 0, NULL, NULL, NULL, &m_pSession);
Related Topics
getSession( )GetSession( ),
saveSession( )SaveSession( ),
Session2 classGXSession2 class,
ISession2 interfaceIGXSession2 interface"Starting a Session" in Chapter 8, "Managing Session and State Information" in Programmer's Guide.
"Writing Hierarchical Queries" in Chapter 6, "Querying a Database" in Programmer's Guide.
Creates a new transaction object used for transaction processing operations on a database.
createTrans( ) is deprecated. In standard-based applications, call setAutoCommit(FALSE), a method in the java.sql.Connection interface.
Syntax
public ITrans createTrans()HRESULT CreateTrans(
IGXTrans **ppTrans);
ppTrans. A pointer to the created IGXTrans object. When AppLogic is finished using the object, after a call to either Commit( ) or Rollback( ), call the Release( ) method to release the interface instance.
Usage
Transaction processing allows the AppLogic to define a series of operations that succeed or fail as a group. If all operations in the group succeed, then the system commits, or saves, all of the modifications from the operations. If any operation in the group fails for any reason, then the AppLogic can roll back, or abandon, any proposed changes to the target table(s).If your application requires transaction processing, use createTrans( )CreateTrans( ) to create a transaction object. Pass this transaction object to subsequent methods, such as AddRow( )addRow( ) or executeQuery( )ExecuteQuery( ), that make up a transaction.
Use this method in conjunction with AddRow( )addRow( ),UpdateRow( )updateRow( ), and DeleteRow( )deleteRow( ) methods in the IGXTable interfaceITable interface and executeQuery( )ExecuteQuery( ) in the IDataConn interfaceIGXDataConn interface.
To manage transaction processing operations, use createTrans( )CreateTrans( ) to create an instance of the IGXTrans interfaceITrans interface, then use Begin( )begin( ), Commit( )commit( ), and Rollback( )rollback( ) in the IGXTrans interfaceITrans interface to begin, commit, and rollback the transaction, respectively.
Return Value
ITrans object representing a transaction, or null for failure. AppLogic uses this object to uniquely identify this transaction in subsequent transaction processing operations, such as beginning, committing, or rolling back a transaction.HRESULT, which is set to GXE_SUCCESS if the method succeeds.
Related Topics
IGXTrans interfaceITrans interface
Chapter 5, "Working with Databases" in Programmer's Guide.deleteCache( )"> "Managing Database Transactions" in Chapter 5, "Working with Databases" in Programmer's Guide.deleteCache( )
Deletes the result cache for a specified AppLogic.
Syntax
public int deleteCache(
String guid)HRESULT DeleteCache(
LPSTR guid);
guid. The guid that identifies the AppLogic whose result cache to delete. Specify nullNULL to delete the current AppLogic's cache.
Usage
To free system resources, use deleteCache( )DeleteCache( ) to clear all results from an AppLogic's cache when the results are no longer needed. This method also stops further caching of results.To clear an AppLogic's result cache, but continue caching, use removeAllCachedResults( )RemoveAllCachedResults( ).
To clear a specific result from the cache, use removeCachedResult( )RemoveCachedResult( ).
Return Value
GXE.SUCCESS if the method succeeds.HRESULT, which is set to GXE_SUCCESS if the method succeeds.
int hr; String guid = valIn.getValString("applogic"); hr = deleteCache(guid); if (hr == GXE.SUCCESS) return result("Successfully deleted cache") else return result("Failed to delete cache");
Related Topics
removeAllCachedResults( )RemoveAllCachedResults( ),
removeCachedResult( )RemoveCachedResult( ),
setCacheCriteria( )SetCacheCriteria( )
Chapter 4, "Writing Server-Side Application Code" in Programmer's Guide.destroySession( ) "> "Caching AppLogic Results to Improve Performance" in Chapter 4, "Writing Server-Side Application Code" in Programmer's Guide.destroySession( )
destroySession( ) is deprecated. In standard-based applications, use the invalidate( ) method in the interface javax.servlet.http.HttpSession.
Syntax
public int destroySession(
ISessionIDGen pIDGen)HRESULT DestroySession(
IGXSessionIDGen *pIDGen);
pIDGen. The session ID generation object used to generate session IDs. Specify nullNULL to use the default IGXSessionIDGen object, or specify a custom session ID generation object.
Usage
To increase security and conserve system resources, use destroySession( )DestroySession( ) to delete a session between a user and the application when the session is no longer required. An AppLogic typically calls destroySession( )DestroySession( ) when the user logs out of an application.
Tip
If the AppLogic set a timeout value for the session when it was created, you need not delete the session explicitly with destroySession( )DestroySession( ). The session is deleted automatically when the timeout expires.
Return Value
GXE.SUCCESS if the method succeeds.HRESULT, which is set to GXE_SUCCESS if the method succeeds.
Related Topics
createSession( )CreateSession( ),
getSession( )GetSession( )
Chapter 8, "Managing Session and State Information" in Programmer's Guide.evalOutput( )"> "Removing a Session and Its Related Data" in Chapter 8, "Managing Session and State Information" in Programmer's Guide.evalOutput( )
Creates an output report by merging data with a report template file. Depending on the client—AppLogic or web browser—evalOutput( )EvalOutput( ) returns either a self-describing data stream or HTML output.
evalOutput( ) is deprecated. In standard-based applications, similar functionality can be achieved by using the interface javax.servlet.RequestDispatcher.
Syntax 1
Merges a template with data from a hierarchical query object.HRESULT EvalOutput(
LPSTR templatePath,
IGXHierQuery *query,
IGXTemplateMap *map,
IGXStream *stream,
IGXValList *props);
Syntax 2
Merges a template with data from an IGXTemplateData object or IGXHierResultSet object. IGXHierResultSet objects implement the IGXTemplateData interface.HRESULT EvalOutput(
LPSTR templatePath,
IGXTemplateData *data,
IGXTemplateMap *map,
IGXStream *stream,
IGXValList *props);
Syntax 1
Merges a template with data from a hierarchical query object.public int evalOutput(
String templatePath,
IHierQuery query,
ITemplateMap map,
IStream stream,
IValList props);
Syntax 2
Merges a template with data from an ITemplateData object or IHierResultSet object. IHierResultSet objects implement the ITemplateData interface.public int evalOutput(
String templatePath,
ITemplateData data,
ITemplateMap map,
IStream stream,
IValList props);
templatePath. Path to the template file used to create the report. At a minimum, specify the file name. Do not specify the filename extension; for example, specify "report" instead of "report.html". The evalOutput( )EvalOutput( ) method automatically uses the correct filename extension depending on the client type. Use a relative path whenever possible. The iPlanet Application Server first searches for the template using the specified path. If the template is not found, the iPlanet Application Server uses the configured TEMPLATE\PATH search path to find it. For more information on configuring the search path, see the Administration and Deployment Guide.
query. Pointer to the hierarchical Hierarchical query object from which evalOutput( )createTrans( )CreateTrans( ) derives the hierarchical result set to merge with the template. The Template Engine runs the query on the database server. To specify this parameter, the AppLogic must first create the specified hierarchical query, using createHierQuery( )CreateHierQuery( ) in the AppLogic classGXAppLogic class, and then define it using methods in the IGXHierQuery interfaceIHierQuery interface or calling loadHierQuery( )LoadHierQuery( ).
map. Pointer to the field Field map that links template fields to calculated values. Fields in the template are expressed with the cell type gx tags. Additionally, the map can be used to map source data with a non-matching field name but identically-formatted data. To specify this parameter, the AppLogic should instantiate the GXTemplateMapBasic classTemplateMapBasic class, add template / field mappings using Put( )put( ) in the IGXTemplateMap interfaceITemplateMap interface, then pass the populated IGXTemplateMapITemplateMap object to evalOutput( )EvalOutput( ) for template processing.
stream. Pointer to theThe output stream where results will be captured for subsequent retrieval and processing. Specify nullNULL to use the default stream, which sends results back to the client. To specify this parameter, an AppLogic creates a stream buffer object from IStreamBufferIGXStreamBuffer, which it passes to evalOutput( )EvalOutput( ). After evalOutput( )EvalOutput( ) returns, the AppLogic calls getStreamData( )GetStreamData( ) in the IStreamBufferIGSXtreamBuffer interface to retrieve the contents of the buffer as an array of byte values.
data. Pointer to the IGXTemplateData ITemplateData object containing data. This can be a hierarchical result set from executing a hierarchical query or it can be data programmatically organized in memory. To specify this data in memory, an AppLogic must first instantiate the GXTemplateDataBasic classTemplateDataBasic class (or implement your own version of the ITemplateData interfaceIGXTemplateData interface), populate the IGXTemplateDataITemplateData object with rows of hierarchical data, then pass it to evalOutput( )EvalOutput( ) for template processing.
Usage
Use evalOutput( )EvalOutput( ) in an AppLogic that returns output to different types of clients. The evalOutput( )EvalOutput( ) method detects the client type, selects the appropriate template file to merge with the data, and generates the appropriate output, as described in the following table:
Both the GXML and HTML template files contain embedded tags, called GX tags, that specify how the Template Engine merges dynamic data with the template to produce the output report. In addition, the HTML template file can contain graphics, static text, and other components, just like any HTML-formatted document.
The data that the Template Engine merges with the template can come from several sources. Most commonly, it comes from the result set of a hierarchical query. However, it can also come from an ITemplateDataIGXTemplateData object containing data organized hierarchically in memory.
If possible, write queries so that field names in the result set match the field names in the template. Otherwise, you must use an ITemplateMap IGXTemplateMap object to map field names.
To create an GXML file, you can convert an HTML template file with the khtml2gxml utility. This utility strips HTML tags from the template file and saves the file as a GXML file. The following is an example of how to run the utility from the command line:
- khtml2gxml mytemplate.html
Return Value
GXE.SUCCESS if the method succeeds.HRESULT, which is set to GXE_SUCCESS if the method succeeds.
Related Topics
evalTemplate( )EvalTemplate( ),
result( )Result( ),
IGXHierQuery interface IHierQuery interface,
GXTemplateDataBasic class TemplateDataBasic class and the IGXTemplateData interface ITemplateData interface,
GXTemplateMapBasic class TemplateMapBasic class and the IGXTemplateMap interface ITemplateMap interface
Chapter 4, "Writing Server-Side Application Code" in Programmer's Guide.evalTemplate( ) "> "Returning Results From an AppLogic Object" in Chapter 4, "Writing Server-Side Application Code" in Programmer's Guide.evalTemplate( )
Creates an output report by merging data with a report template file. The report is an HTML document that can be viewed using a Web browser.
evalTemplate( ) is deprecated. In standard-based applications, similar functionality can be achieved by using the interface javax.servlet.RequestDispatcher.
Syntax 1
Merges an HTML report template with data from a hierarchical query object.HRESULT EvalTemplate(
LPSTR path,
IGXHierQuery *query,
IGXTemplateMap *map,
IGXStream *stream,
IGXValList *props);
Syntax 2
Merges an HTML report template with data from an IGXTemplateData object or IGXHierResultSet object. IGXHierResultSet objects implement the IGXTemplateData interface.HRESULT EvalTemplate(
LPSTR path,
IGXTemplateData *data,
IGXTemplateMap *map,
IGXStream *stream,
IGXValList *props);
Syntax 1
Merges an HTML report template with data from a hierarchical query object.public int evalTemplate(
String path,
IHierQuery query)
Syntax 2
Merges an HTML report template with data from a hierarchical query object.public int evalTemplate(
String path,
IHierQuery query,
ITemplateMap map,
IStream stream)
Syntax 3
Merges an HTML report template with data from an ITemplateData object or IHierResultSet object. IHierResultSet objects implement the ITemplateData interface.public int evalTemplate(
String path,
ITemplateData data,
ITemplateMap map)
path. Path to the HTML template file used to create the report. At a minimum, specify the file name. Use a relative path whenever possible. The iPlanet Application Server first searches for the template using the specified path. If the template is not found, the iPlanet Application Server uses the configured TEMPLATE\PATH search path to find it. For more information on configuring the search path, see the Administration and Deployment Guide.
query. Pointer to the hierarchical Hierarchical query object from which evalTemplate( )EvalTemplate( ) derives the hierarchical result set to merge with the HTML template. The Template Engine runs the query on the database server. To specify this parameter, the AppLogic must first create the specified hierarchical query, using createHierQuery( )CreateHierQuery( ) in the AppLogic classGXAppLogic class, and then define it using methods in the IGXHierQuery interfaceIHierQuery interface or calling loadHierQuery( )LoadHierQuery( ).
map. Pointer to the field Field map that links template fields to calculated values. Fields in the template are expressed with the cell type gx tags. Additionally, the map can be used to map source data with a non-matching field name but identically-formatted data. To specify this parameter, the AppLogic should instantiate the GXTemplateMapBasic classTemplateMapBasic class, add template / field mappings using Put( )put( ) in the IGXTemplateMap interfaceITemplateMap interface, then pass the populated IGXTemplateMapITemplateMap object to evalTemplate( )EvalTemplate( ) for template processing.
stream. Pointer to theThe output stream where results will be captured for subsequent retrieval and processing. Specify nullNULL to use the default stream, which sends results back to the client. To specify this parameter, an AppLogic creates a stream buffer object from IStreamBufferIGXStreamBuffer, which it passes to evalOutput( )EvalOutput( ). After evalTemplate( )EvalTemplate( ) returns, the AppLogic calls getStreamData( )GetStreamData( ) in the IStreamBufferIGSXtreamBuffer interface to retrieve the contents of the buffer as an array of byte values.
data. Pointer to the IGXTemplateData ITemplateData object containing data. This can be a hierarchical result set from executing a hierarchical query or it can be data programmatically organized in memory. To specify this data in memory, an AppLogic must first instantiate the GXTemplateDataBasic classTemplateDataBasic class (or implement your own version of the ITemplateData interfaceIGXTemplateData interface), populate the IGXTemplateDataITemplateData object with rows of hierarchical data, then pass it to evalTemplate( )EvalTemplate( ) for template processing.
Usage
Use evalTemplate( )EvalTemplate( ) to create an HTML report by merging data with an HTML template file. An HTML template is an HTML document with the addition of special embedded tags, called GX tags, that specify how the Template Engine merges dynamic data with the template to produce the output report or HTML page. In addition to these dynamic links, a template can contain static text, graphics, and other components, just like any HTML-formatted document.The data that the Template Engine merges with the template can come from several sources. Most commonly, it comes from the result set of a hierarchical query. However, it can also come from an ITemplateDataIGXTemplateData object containing data organized hierarchically in memory.
If your AppLogic requires the flexibility of returning different output depending on the client—a Web browser or another AppLogic—use evalOutput( )EvalOutput( ) instead.
If possible, write queries so that field names in the result set match the field names in the template. Otherwise, you must use an ITemplateMap IGXTemplateMap object to map field names.
Return Value
GXE.SUCCESS if the method succeeds.HRESULT, which is set to GXE_SUCCESS if the method succeeds.
Related Topics
evalOutput( )EvalOutput( ),
IGXHierQuery interface IHierQuery interface,
GXTemplateDataBasic class TemplateDataBasic class and the IGXTemplateData interface ITemplateData interface,
GXTemplateMapBasic class TemplateMapBasic class and the IGXTemplateMap interface ITemplateMap interface
Chapter 4, "Writing Server-Side Application Code" in Programmer's Guide.execute( )"> "Returning Results From an AppLogic Object" in Chapter 4, "Writing Server-Side Application Code" in Programmer's Guide.execute( )
Performs the main task of an AppLogic, such as accessing a database, generating a report, or other operations. It should be overridden in your AppLogic subclass.
execute( ) is deprecated. In standard-based applications, use one of the request processing methods in the class javax.servlet.http.HttpServlet. For example, use doGet( ), doPost( ), or service( ).
Usage
iPlanet Application Server calls the AppLogic's execute( )Execute( ) method automatically whenever a request is received for an AppLogic, such as when a user submits a form or an information request.
Rule
By default, execute( )Execute( ) does nothing except return a value of zero (0). You should always write code to override this method in your AppLogic GXAppLogic derived class.In general, your AppLogic class will inherit from the AppLogic classGXAppLogic class and override the default behavior of the execute( )Execute( ) method, such as retrieving an orders report from a database.
The AppLogic can analyze the valInm_pValIn member variable for input arguments using methods in the IValList interfaceIGXValList interface.
The AppLogic can modify the valInm_pValIn member variable using methods in the IValList interfaceIGXValList interface.
Return Value
GXE.SUCCESS if the method succeeds.HRESULT, which is set to GXE_SUCCESS if the method succeeds.
Example
The following example overrides the execute( ) method to display "Hello world":import com.kivasoft.applogic.*;
public class HelloWorldAppLogic extends AppLogic {
// Simple code that overrides execute() method
return result("Hello world!");
In the following example, Execute( ) displays an HTML page:
if(EvalTemplate("GXApp/COnlineBank/templates/NewCust.html", (IGXHierQuery*)NULL, NULL, NULL, NULL)!=GXE_SUCCESS)
Result("<HTML><BODY>Unable to evaluate template.</BODY></HTML>");
Related Topics
result( )Result( ),
IValList interfaceIGXValList interface
"Performing the Main Task in an AppLogic Object" in Chapter 4, "Writing Server-Side Application Code" in Programmer's Guide.getAppEvent( ) "> "Performing the Main Task in an AppLogic Object" in Chapter 4, "Writing Server-Side Application Code" in Programmer's Guide.getAppEvent( )
Retrieves the application event object.
getAppEvent( )GetAppEvent( ) is deprecated. See New Usage section for more information.
Syntax
public IAppEvent getAppEvent()HRESULT GetAppEvent(
IGXAppEvent **ppAppEvent);
ppAppEvent. A pointer to the retrieved IGXAppEvent object. When the AppLogic is finished using the object, call the Release( ) method to release the interface instance.
New Usage
This method is deprecated and is provided for backward compatibility only.New applications should use the IAppEventMgr Interface and IAppEvent Interface (deprecated), along with the GetAppEventMgr( ) method in the com.kivasoft.dlm.GXContext class.
New applications should use the IGXAppEventMgr interface and IGXAppEventObj interface, along with the helper function GXContextGetAppEventMgr( ).
Old Usage
Use getAppEvent( )GetAppEvent( ) to retrieve an IAppEventIGXAppEvent object. Through the IAppEventIGXAppEvent interface, you can create and manage application events. An AppLogic uses application event objects to define events that are triggered at a specified time or times or when triggered explicitly.
Return Value
IAppEvent object, or null for failure.HRESULT, which is set to GXE_SUCCESS if the method succeeds.
Related Topics
IAppEvent interfaceIGXAppEvent interface,
registerEvent( )RegisterEvent( ) in the IAppEvent interfaceIGXAppEvent interface
Chapter 3, "Application Development Techniques" in Programmer's Guide.getSession( )"> "Using Events" in Chapter 3, "Application Development Techniques" in Programmer's Guide.getSession( )
Returns an existing user session.
getSession( ) is deprecated. In standard-based applications, use the getSession( ) method in the interface javax.servlet.http.HttpSession.
Syntax
public ISession2 getSession(
int dwFlags,
String appName,
ISessionIDGen pIDGen)HRESULT GetSession(
DWORD dwFlags,
LPSTR pAppName,
IGXSessionIDGen *pIDGen,
IGXSession2 **ppSession);
pAppName. Name of the application associated with the session. The application name enables the iPlanet Application Server to determine which AppLogics have access to the session data. Specify nullNULL to use the application name assigned to the AppLogic during kreg registration.
pIDGen. The session ID generation object used to generate session IDs. Specify null.NULL to use the default IGXSessionIDGen object, or specify a custom session ID generation object.
ppSession. A pointer to the created or retrieved IGXSession2 object. When the AppLogic is finished using the object, call the Release( ) method to release the interface instance.
Usage
Use getSession( )GetSession( ) to obtain an existing session. Use it also to determine if a user session exists before calling createSession( ) CreateSession( )to create one.
Rule
If you implement a custom session class, you must implement your own method to get a session, which in turn, can call the getSession( )GetSession( ) method.
Return Value
ISession2 object representing a user session, or null for failure.HRESULT, which is set to GXE_SUCCESS if the method succeeds.
Example 1
In the following code, getSession( )GetSession( ) checks if a session exists. If there isn't an existing session, createSession( )CreateSession( ) creates a new session.
ISession2 sess; sess = getSession(0, "Catalog", null); if (sess == null) { log("Could not get session, creating a new one"); sess = createSession(GXSESSION.GXSESSION_DISTRIB, 0, null, null, null);
hr = GetSession(0, "Catalog", NULL, &m_pSession); if (hr != GXE_SUCCESS) { Log("Could not get session, creating a new one"); hr = CreateSession(GXSESSION_DISTRIB, 0, NULL, NULL, NULL, &m_pSession);
Example 2
In the following code, getSession( )GetSession( ) gets an existing session, then checks if the user is authorized to perform a secured task:
Related Topics
createSession( )CreateSession( ),
loginSession( )LoginSession( ),
saveSession( )SaveSession( ),
GXSession2 class Session2 class,
IGXSession2 interface ISession2 interface
Chapter 8, "Managing Session and State Information" in Programmer's Guide.getStateTreeRoot( )"> "Using an Existing Session" in Chapter 8, "Managing Session and State Information" in Programmer's Guide.getStateTreeRoot( )
Returns an existing root node of a state tree or creates a new one.
Syntax
public IState2 getStateTreeRoot(
int dwFlags,
String pName)HRESULT GetStateTreeRoot(
DWORD dwFlags,
LPSTR pName,
IGXState2 **ppStateTree)
dwFlags. Specify one of the following flags or zero to use the default settings:
GXSTATE.GXSTATE_LOCAL to make the node visible to the local process only.
GXSTATE.GXSTATE_CLUSTER to make the node visible to all AppLogics within the cluster.
GXSTATE.GXSTATE_DISTRIB, the default, to make the node visible to all AppLogics on all servers.
pName. The name of the root node. If a node with this name doesn't already exist, a new node is created.
ppStateTree. A pointer to the created IGXState2 object. When the AppLogic is finished using the object, call the Release( ) method to release the interface instance.
Usage
Use getStateTreeRoot( )GetStateTreeRoot( ) to create a state tree. A state tree is a hierarchical data storage mechanism. It is used primarily for storing application data that needs to be distributed across server processes and clusters.
Return Value
IState2 object representing the root node, or null for failure.HRESULT, which is set to GXE_SUCCESS if the method succeeds.
Example
The following code shows how to create a state tree and a child node:
Related Topics
IState2 interfaceIGXState2 interface
Chapter 8, "Managing Session and State Information" in Programmer's Guide.isAuthorized( )"> "Using the State Layer" in Chapter 8, "Managing Session and State Information" in Programmer's Guide.isAuthorized( )
Checks a user's permission level to a specified action or AppLogic.
isAuthorized( ) is deprecated. As of the 2.1 servlet specification, there is no standard security model for servlets. However, iPlanet Application Server provides a security model. In servlets, use the equivalent isAuthorized( ) method, available from the HttpSession2 Interface in package com.iplanet.server.servlet.extension.
public int isAuthorized(
String pTarget,
String pPermission)HRESULT IsAuthorized(
LPSTR pTarget,
LPSTR pPermission,
DWORD *pResult);
Syntax 2
Contains several parameters that are placeholders for future functionality.public int isAuthorized(
String pDomain,
String pTarget,
String pPermission,
int method,
int flags,
ICred pCred,
IObject pEnv)HRESULT IsAuthorized(
LPSTR pDomain,
LPSTR pTarget,
LPSTR pPermission,
DWORD method,
DWORD flags,
IGXCred *pCred,
IGXObject *pEnv,
DWORD *pResult);
pDomain. The type of Access Control Lists (ACL). An ACL (created by the server administrator) defines the type of operations, such as Read or Write, that a user or group can perform. There are two types of ACLs: AppLogic and general. For this parameter, specify one of the following strings, which specifies the type of ACL to check for this user:
pTarget. The name of the ACL, if the ACL is a general type. If the ACL is an AppLogic ACL, specify the AppLogic name or GUID string.
pPermission. The type of permission, for example, "EXECUTE."
pResult. Pointer to the client-allocated variable that contains the returned permission status. The variable is set to one of the following enum constants:
The specified permission is unlisted or there is conflicting information.
Usage
Use isAuthorized( )IsAuthorized( ) in portions of the code where application security is enforced through Access Control Lists (ACL). This method lets an application check if a user has permission to execute an AppLogic or perform a particular action. The application can use the result of isAuthorized( )IsAuthorized( ) as a condition in an If statement. It can, for example, return a message to users who are denied access to an AppLogic.Application developers should obtain the list of registered ACLs, users and groups from the server administrator who created these items. ACLs are created through the Enterprise Administrator tool or through the kreg tool.
Rule
Before calling isAuthorized( )IsAuthorized( ), the application must create a session with createSession( ) CreateSession( )and a user must be logged in with loginSession( )LoginSession( ).
Return Value
One of the following:
The specified permission is unlisted or there is conflicting information.
HRESULT, which is set to GXE_SUCCESS if the method succeeds.
if (isAuthorized("MonthlyForecast", "READ") != GXACLPERMSTATUS.GXACL_ALLOWED) return result("<html><body>sorry no access</body></html>); else // run monthly forecast report
Related Topics
loginSession( )LoginSession( )
Chapter 9, "Writing Secure Applications" in Programmer's Guide.isCached( ) "> "Secure Sessions" in Chapter 9, "Writing Secure Applications" in Programmer's Guide.isCached( )
Returns true if AppLogic results are being saved in the result cache.
Syntax
public boolean isCached()
Usage
Call isCached( ) IsCached( ) to determine whether caching is enabled for the current AppLogic. You should, for example, call isCached( ) IsCached( ) before calling setCacheCriteria( )SetCacheCriteria( ) to avoid inadvertently overwriting the current contents of the result cache.
Return Value
A boolean BOOL true if caching is enabled, or a booleanBOOL false if not.
Related Topics
skipCache( )SkipCache( )
Chapter 4, "Writing Server-Side Application Code" in Programmer's Guide.loadHierQuery( )"> "Caching AppLogic Results to Improve Performance" in Chapter 4, "Writing Server-Side Application Code" in Programmer's Guide.loadHierQuery( )
Creates a hierarchical query by loading a query file containing one or more query names and associated data connections.
loadHierQuery( ) is deprecated. In standard-based applications, use the JDBC API to execute a join statement.
Syntax
public IHierQuery loadHierQuery(
String pFileName,
IDataConnSet pDataConnSet,
int flags,
IValList pParams)HRESULT LoadHierQuery
LPSTR pFileName,
IGXDataConnSet *pDataConnSet,
DWORD flags,
IGXValList *pParams,
IGXHierQuery **ppHierQuery);
pFileName. Name of the query (.GXQ) file, including the path. Use a relative path when possible.
A query file is an ASCII text file containing one or more SQL statements. You can create the file using any ASCII text editor. Use the following syntactical guidelines:
The file for a hierarchical query contains several SQL SELECT statements (compliant with ANSI SQL89) with the following additions:
In the query file, do not use any semicolons (;) or other vendor-specific SQL statement terminators.
pDataConnSet. Collection of query name/data connection pairs. The query names in the collection must match the named queries in the query file. The associated IDataConn object identifies the data connection for the query.
flags. Specify 0 (zero). Internal use only.
pParams. IValListIGXValList of query file parameters, or nullNULL. A collection of placeholders for the WHERE clause. A placeholder may be a name or a number. It is prefixed by a colon (:) character. The placeholders can be replaced by specifying replacement values in the ValList parameter.
ppHierQuery. Pointer to the created IGXHierQuery object. When the AppLogic is finished using the object, call the Release( ) method to release the interface instance.
Usage
Use loadHierQuery( )LoadHierQuery( ) to create a hierarchical query object. An AppLogic can retrieve standardized queries stored in a data file and, at runtime, can dynamically select and assign the data sources on which the query is run. You create the query file separately using the Query Designer or an ASCII text editor, ANSI 89 standard SQL SELECT statements, and specialized syntax. A query file can define both flat and hierarchical queries.To use a query file, the AppLogic first establishes a data connection with each database on which any queries will be run. Next, the AppLogic calls createDataConnSet( ) CreateDataConnSet( )in the AppLogic class to create an IDataConnSetIGXDataConnSet collection, then populates this collection with query name / data connection pairs. Each query name in the collection matches a named query in the query file.
IDataConnSetIGXDataConnSet provides a method for adding query name / data connection pairs to the collection. In this way, AppLogic can use standardized queries and assign data connections dynamically at runtime. Finally, the AppLogic calls loadHierQuery( )LoadHierQuery( ) to create the hierarchical query object.
AppLogic must first call createDataConnSet( ) CreateDataConnSet( )to create an IDataConnSetIGXDataConnSet, then add query name / data connection pairs using addConn( )AddConn( ) in the IDataConnSet interfaceIGXDataConnSet interface.
The query names in the collection must match the query names in the query file.
Return Value
IHierQuery object representing a hierarchical query, or null for failure (such as query file not found). The AppLogic uses this object to uniquely identify this hierarchical query in subsequent operations, such as defining the query criteria, executing the query, retrieving query results, and processing templates.HRESULT, which is set to GXE_SUCCESS if the method succeeds.
Example
The following example shows a query (GXQ) file and a section of an AppLogic that loads the hierarchical query file and creates an HTML report:
Related Topics
createDataConnSet( )CreateDataConnSet( ),
IDataConnSet interfaceIGXDataConnSet interface,
IHierQuery interfaceIGXHierQuery interface
Chapter 6, "Querying a Database" in Programmer's Guide.loadQuery( )"> "Working with Query Files" in Chapter 6, "Querying a Database" in Programmer's Guide.loadQuery( )
Creates a flat query by loading a query file.
loadQuery( ) is deprecated. Instead, use loadQuery( ) from the class com.kivasoft.util.SqlUtil.
Syntax
public IQuery loadQuery(
String pFileName,
String pQueryName,
int flags,
IValList pParams)HRESULT LoadQuery(
LPSTR pFileName,
LPSTR pQueryName,
DWORD flags,
IGXValList *pParams,
IGXQuery **ppQuery);
pFileName. Name of the query (.GXQ) file, including the path. Use a relative path when possible.
A query file is an ASCII text file containing one or more SQL statements. You can create the file using any ASCII text editor. Use the following syntactical guidelines:
The query file for a flat query contains a SQL SELECT statement (compliant with ANSI SQL89) preceded by the following line:
query queryName using (driverCode, DSN, UserName) is
In the query file, do not use any semicolons (;) or other vendor-specific SQL statement terminators. The SQL statement may contain placeholders in the WHERE clause.
- where queryName is the name of the flat query. Do not use any semicolons (;) in the query file.
pQueryName. Name of the query in the query file.
flags. Specify 0 (zero). Internal use only.
pParams. IValListIGXValList of query file parameters, or null. A collection of placeholders for the WHERE clause. A placeholder may be a name or a number. It is prefixed by a colon (:) character. The placeholders can be replaced by specifying replacement values in the IValListIGXValList parameter.
ppQuery. Pointer to the created IGXQuery object. When the AppLogic is finished using the object, call the Release( ) method to release the interface instance.
Usage
Use loadQuery( )LoadQuery( ) to create a flat query object by loading a query (.GXQ) file. An AppLogic can retrieve standardized queries stored in a data file and, at runtime, can dynamically select and assign the data source on which the query is run.You create the query file separately using the Query Designer or an ASCII text editor, ANSI 89 standard SQL SELECT statements, and special syntax.
To run the flat query, call executeQuery( )ExecuteQuery( ) in the IDataConn Interface (deprecated)IGXDataConn interface.
Return Value
IQuery object, or null for failure (such as query file not found).HRESULT, which is set to GXE_SUCCESS if the method succeeds.
Example
The following example shows a query (GXQ) file and a section of an AppLogic that loads and executes the query:
/* STATES */ query STATES using (ODBC, kstates, kuser) is select STATES.STATE as STATES_STATE from STATES where (STATES.REGION = ':REGION') order by STATES.STATE asc
Related Topics
IQuery Interface (deprecated)IGXQuery interface
Working with Query Files" in Chapter 6, "Querying a Database" in Programmer's Guide.log( ) "> "Working with Query Files" in Chapter 6, "Querying a Database" in Programmer's Guide.log( )
Writes a message to the server log.
log( ) is deprecated. In standard-based applications, use one of the log( ) methods available from the javax.servlet package. For example, refer to the GenericServlet class or the ServletContext interface.
Syntax 1
Logs a message (type = GXLOG.GXEVENTTYPE_INFORMATION and category = 0).
Syntax 2
Logs an event with a message, specifying the type and category of event.public int log(
int type,
int category,
String msg)HRESULT Log(
DWORD type,
DWORD category,
LPSTR msg);
type. Message type. Use one of the following variables:
GXLOG.GXEVENTTYPE_INFORMATION
category. User-defined message category. Do not use the range of values reserved for the iPlanet Application Server systems, which is 0 to 65535, inclusive.
Usage
Use log( )Log( ) for displaying or storing simple messages or for debugging. The output can be directed to the console, to a text file, or to a database table. To direct output, use the iPlanet Application Server Administrator. For more information, see the Administration and Deployment Guide.
Return Value
GXE.SUCCESS if the method succeeds.HRESULT, which is set to GXE_SUCCESS if the method succeeds.
hr = GetSession(0, "Catalog", NULL, &m_pSession); if (hr != GXE_SUCCESS) { Log("Could not get session; creating a new one"); hr = CreateSession(GXSESSION_DISTRIB, 0, NULL, NULL, NULL, &m_pSession);
Logs an authorized user into a session with a secured application.
loginSession( ) is deprecated. As of the 2.1 servlet specification, there is no standard security model for servlets. However, iPlanet Application Server provides a security model. In servlets, use the equivalent loginSession( ) method, available from the HttpSession2 Interface in package com.iplanet.server.servlet.extension.
public int loginSession(
String name,
String password)HRESULT LoginSession(
LPSTR pName,
LPSTR pPassword);
Syntax 2
Contains several parameters that are placeholders for future functionality.public int loginSession(
String pDomain,
int dwMethod,
int dwFlags,
String pName,
byte[] pAuthData,
int nAuthData)HRESULT LoginSession(
LPSTR pDomain,
DWORD dwMethod,
DWORD dwFlags,
LPSTR pName,
LPBYTE pAuthData,
ULONG nAuthData);
nAuthData. The size of the password.
Usage
Call loginSession( )LoginSession( ) after creating a user session with createSession( ) CreateSession( )or after retrieving a user session with getSession( )GetSession( ). loginSession( )LoginSession( ) checks the passed in login name and password against the user names and passwords stored in the iPlanet Application Server (the administrator sets up and manages this information) and logs the user into the session if the login name and password are valid.If login is successful, a security credential object is created and associated with the session. The server checks this security credential object each time it receives an AppLogic request, and verifies if the user has execute permission for the AppLogic.
Using loginSession( )LoginSession( ) in conjunction with isAuthorized( )IsAuthorized( ), an application can ensure that only authorized users can execute certain AppLogics or take certain actions.
Tip
The server administrator creates users and passwords and manages access to AppLogics and specified resources, such as sales or forecast reports. During the development and debugging phases, application developers can use the ldapmodifykreg tool to create users, groups, and ACLs in the LDIFGXR file. These tasks cannot be done programmatically.
Return Value
GXE.SUCCESS if the method succeeds.HRESULT, which is set to GXE_SUCCESS if the method succeeds.
Related Topics
isAuthorized( )IsAuthorized( ),
logoutSession( )LogoutSession( )
Chapter 9, "Writing Secure Applications" in Programmer's Guide.logoutSession( )"> "Secure Sessions" in Chapter 9, "Writing Secure Applications" in Programmer's Guide.logoutSession( )
Logs a user out of a session with a secured application.
logoutSession( ) is deprecated. As of the 2.1 servlet specification, there is no standard security model for servlets. However, iPlanet Application Server provides a security model. In servlets, use the equivalent isAuthorized( ) method, available from the HttpSession2 Interface in package com.iplanet.server.servlet.extension.
Syntax
public int logoutSession(
int dwFlags)HRESULT LogoutSession(
DWORD dwFlags);
Usage
If the AppLogic called loginSession( )LoginSession( ) to log into a session with a secured application, call logoutSession( )LogoutSession( ) when the user exits the application, or the secured portion of it.
Rule
Call getSession( ) GetSession( )before calling logoutSession( )LogoutSession( ).
Return Value
GXE.SUCCESS if the method succeeds.HRESULT, which is set to GXE_SUCCESS if the method succeeds.
Related Topics
getSession( )GetSession( ),
isAuthorized( )IsAuthorized( ),
loginSession( )LoginSession( )
Chapter 9, "Writing Secure Applications" in Programmer's Guide.newRequest( ) "> "Secure Sessions" in Chapter 9, "Writing Secure Applications" in Programmer's Guide.newRequest( )
Calls another AppLogic from within the current AppLogic.
Syntax 1
Passes in the ValIn and ValOut of the current AppLogic to the called AppLogic. If the called AppLogic streams results, the calling AppLogic streams the same results.public int newRequest(
String guidSTR)
Syntax 2
Passes in the specified valIn and valOut.public int newRequest(
String guidSTR,
IValList vIn,
IValList vOut)
Syntax 3
Use to explicitly specify the location of AppLogic execution.public int newRequest(
String guidSTR,
IObject vIn,
IObject vOut,
int host,
int port,
int flag)
Syntax 1
Passes in the specified IGXValList of input parameters and result values. The location of the AppLogic execution depends on partitioning and load balancing criteria.HRESULT NewRequest(
LPSTR guid,
IGXObject *vIn,
IGXObject *vOut,
DWORD flag);
Syntax 2
Same as Syntax 1, but explicitly specifies the location of AppLogic execution.HRESULT NewRequest(
LPSTR guid,
IGXObject *vIn,
IGXObject *vOut,
DWORD host,
DWORD port,
DWORD flag);
guidSTR guid. String GUID or name of the AppLogic to execute.
vIn. IValListIGXValList object containing input parameters to pass to the called AppLogic.
vOut. IValList IGXValList object containing result values of the called AppLogic.
host. IP address of the Internet host of the iPlanet Application Server where the AppLogic is to be executed. Specify 0 to execute the AppLogic locally.
port. Internet port of the iPlanet Application Server where the AppLogic is to be executed. Specify 0 to execute the AppLogic locally.
Usage
Use newRequest( )NewRequest( ) to call another AppLogic from within the current AppLogic. When it calls newRequest( )NewRequest( ), the AppLogic passes to the iPlanet Application Server the GUID or name of the AppLogic to execute and, optionally, any input and output parameters.iPlanet Application Server constructs a request using the parameters specified and processes it like any other request, by instantiating the AppLogic and passing in its parameters. The results from the called AppLogic module are returned to the calling AppLogic.
The AppLogic that newRequest( )NewRequest( ) invokes can do one of the following tasks:
Process application logic and return result values in the vOut parameter.
If the called AppLogic uses evalOutput( )EvalOutput( ) to stream results, evalOutput( )EvalOutput( ) returns HTML results by default. The current AppLogic can, however, specify that evalOutput( )EvalOutput( ) return a non-HTML data stream by setting the gx_client_type key to "ocl" in the input IValListIGXValList of newRequest( )NewRequest( ). For example:Process application logic and return the resulting data form (such as a report) by streaming the output or by calling result( )Result( ).
Process application logic and return result values in the vOut parameter as well as return the resulting data form (such as a report) by streaming the output or by calling result( )Result( ).
vallist.sSetValString("gx_client_type", "ocl");
Rule
The specified GUID string, input parameters, and output parameters must be valid for the specified AppLogic.The calling AppLogic can create new input and output IValLists" in Chapter 8, "Managing Session and State Information" in Programmer's Guide. so as to avoid changing its own input and output IValListsIGXValLists.
The AppLogic can call another AppLogic, passing its own input and output IValListsIGXValLists. In this case, the called AppLogic accesses the same stream destinations as the calling AppLogic.
Use newRequestAsync( )NewRequestAsync( ) instead of newRequest( )NewRequest( ) to execute asynchronous request.
Called AppLogics might reside on different servers, depending on partitioning and load balancing configurations, might be written in a different language, or might have cached results. The calling AppLogic can be unaware or independent of these conditions.
Using newRequest( )NewRequest( ), you can modularize parts of the application, build dynamic header/footer information and smart reporting templates, and hide complex or confidential business logic in secure submodules or even separate servers.
Use newRequest( )NewRequest( ) judiciously. Each invoked AppLogic uses a certain amount of communications and server resources.
Return Value
GXE.SUCCESS if the method succeeds.HRESULT, which is set to GXE_SUCCESS if the method succeeds.
Example 1
// Call specified AppLogic and pass parametersnewRequest("{E5CA1000-6EEE-11cf-96FD-0020AFED9A65}",
paramsToModule, paramsReturned);
Example 2
// Use DisplayBasket AppLogic to display the contentsif(newRequest("DisplayBasket", valIn, valOut)==0){
return result("Cannot execute DisplayBasket AppLogic");
Related Topics
GUID class,
IValList interface IGXValList interface"Passing Parameters to AppLogic From Code" in Chapter 4, "Writing Server-Side Application Code" in Programmer's Guide.
Calls another AppLogic from within the current AppLogic, and runs it asynchronously.
Syntax 1
Passes in the ValIn and ValOut of the AppLogic.public IOrder newRequestAsync(
String guidSTR)
Syntax 2
Passes in the specified valIn and valOut.public IOrder newRequestAsync(
String guidSTR,
IValList vIn,
IValList vOut)
Syntax 3
Use to explicitly specify the location of AppLogic execution.public IOrder newRequest(
String guidSTR,
IObject vIn,
IObject vOut,
int host,
int port,
int flag)
Syntax 1
Passes in the specified IGXValList of input parameters and result values. The location of the AppLogic execution depends on partitioning and load balancing criteria.HRESULT NewRequestAsync(
LPSTR guid,
IGXObject *vIn,
IGXObject *vOut,
DWORD flag,
IGXOrder **ppOrder);
Syntax 2
Same as Syntax 1, but explicitly specifies the location of AppLogic execution.HRESULT NewRequestAsync(
LPSTR guid,
IGXObject *vIn,
IGXObject *vOut,
DWORD host,
DWORD port,
DWORD flag
IGXOrder **ppOrder);
guidSTR guid. String GUID or name of the AppLogic to execute.
vIn. IValList IGXValList object containing input parameters to pass to the called AppLogic.
vOut. IValList evalOutput( ) EvalOutput( )object containing result values of the called AppLogic.
host. IP address of the Internet host of the iPlanet Application Server where the AppLogic is to be executed. Specify 0 to execute the AppLogic locally.
port. Internet port of the iPlanet Application Server where the AppLogic is to be executed. Specify 0 to execute the AppLogic locally.
ppOrder. Pointer to the returned IGXOrder object, which the AppLogic can use to obtain the status of the request. When the calling AppLogic is finished using the order object, call the Release( ) method to release the interface instance.
Usage
Use newRequestAsync( )NewRequestAsync( ) to call another AppLogic from within the current AppLogic, and run it asynchronously. Executing an AppLogic asynchronously is useful if the AppLogic performs a lengthy operation, or if the AppLogic acts as a monitor or remains persistent. For example, an asynchronous AppLogic may perform a lengthy database query to produce a complex result set that it sends an e-mail to a destination address. Another AppLogic module may run continuously and re-index HTML pages every 24 hours.When an AppLogic calls newRequestAsync( )NewRequestAsync( ), it passes to the iPlanet Application Server the GUID of the AppLogic module to execute and, optionally, any input and output parameters.
The iPlanet Application Server constructs a request using the parameters specified and processes it like any other request, by instantiating the AppLogic and passing in its parameters. The results from the called AppLogic module are returned to the calling AppLogic.
The AppLogic that newRequestAsync( )NewRequestAsync( ) invokes can do one of the following tasks:
Process application logic and return result values in the vOut parameter.
Process application logic and return the resulting data form (such as a report) by streaming the output or by calling result( )Result( ).
Process application logic and return result values in the vOut parameter as well as return the resulting data form (such as a report) by streaming the output or by calling result( )Result( ).
Rules
The specified AppLogic must be accessible to the iPlanet Application Server.
The specified GUID string, input parameters, and output parameters must be valid for the specified AppLogic module.
Tips
To get the current status of the request, use the getState( )GetState( ) method in the returned IOrderIGXOrder object.
The calling AppLogic can use GX.WaitForOrder( )GXWaitForOrder( ) to wait for one or multiple asynchronous requests to return.
The calling AppLogic can create new input and output IValListsIGXValLists so as to avoid changing its own input and output IValListsIGXValLists.
The AppLogic can call another AppLogic, passing its own input and output IValListsIGXValLists. In this case, the called AppLogic accesses the same stream destinations as the calling AppLogic. To prevent conflicts in streaming, the calling AppLogic can use GXWaitForOrder( )GX.WaitForOrder( ) to wait until the called AppLogic is finished.
Using newRequestAsync( )NewRequestAsync( ), you can modularize parts of the application, build dynamic header/footer information and smart reporting templates, and hide complex or confidential business logic in secure submodules or even separate servers.
Use newRequestAsync( )NewRequestAsync( ) judiciously. Each invoked AppLogic uses a certain amount of communications and server resources.
Return Value
IOrder object, or null for failure.HRESULT, which is set to GXE_SUCCESS if the method succeeds.
Related Topics
GUID class,
IOrder interfaceIGXOrder interface,
IValList interface IGXValList interface"Passing Parameters to AppLogic From Code" in Chapter 4, "Writing Server-Side Application Code" in Programmer's Guide.
Clears an AppLogic's result cache.
Syntax
public int removeAllCachedResults(
String guid)HRESULT RemoveAllCachedResults(
LPSTR guid);
guid. The guid that identifies the AppLogic whose result cache to clear. Specify nullNULL to clear the current AppLogic's cache.
Usage
To free system resources, use removeAllCachedResults( )RemoveAllCachedResults( ) to clear an AppLogic's result cache when the results are no longer needed. This method clears the cache, but does not disable caching.To clear an AppLogic's entire result cache and discontinue caching, use deleteCache( )DeleteCache( ).
To clear a specific result from the cache, use removeCachedResult( )RemoveCachedResult( ).
Return Value
GXE.SUCCESS if the method succeeds.HRESULT, which is set to GXE_SUCCESS if the method succeeds.
Related Topics
deleteCache( )DeleteCache( ),
removeCachedResult( )RemoveCachedResult( ),
setCacheCriteria( )SetCacheCriteria( )"Caching AppLogic Results to Improve Performance" in Chapter 4, "Writing Server-Side Application Code," in Programmer's Guide.
Clears a specific result from an AppLogic's result cache.
Syntax
public int removeCachedResult(
String guid,
IValList criteria)HRESULT RemoveCachedResult(
LPSTR guid
IGXValList *criteria);
guid. The guid that identifies the AppLogic whose cached result to clear. Specify nullNULL to clear the current AppLogic's cached result.
criteria. An IValListIGXValList object that contains the criteria for selecting the result to remove. In the IValListIGXValList object, set a specific value that matches the cache criteria passed to setCacheCriteria( )SetCacheCriteria( ). For example, if the cache criteria passed to setCacheCriteria( )SetCacheCriteria( ) was "Salary=40000-60000"), you can remove results where salary is 50000 by setting in the IValListIGXValList object a "Salary" key to a value of "50000".
Usage
Use removeCachedResult( )RemoveCachedResult( ) to clear a specific result from an AppLogic's cache when the result is no longer needed.To clear an AppLogic's entire result cache and discontinue caching, use deleteCache( )DeleteCache( ).
To clear an AppLogic's entire result cache, but continue caching, use removeAllCachedResults( )RemoveAllCachedResults( ).
Return Value
GXE.SUCCESS if the method succeeds.HRESULT, which is set to GXE_SUCCESS if the method succeeds.
Related Topics
deleteCache( )DeleteCache( ),
removeAllCachedResults( )RemoveAllCachedResults( ),
setCacheCriteria( )SetCacheCriteria( )"Caching AppLogic Results to Improve Performance" in Chapter 4, "Writing Server-Side Application Code," in Programmer's Guide.
Specifies the return value of an AppLogic.
result( ) is deprecated. In standard-based applications, use similar functionality as defined in the Servlet API. For example, refer to javax.servlet.ServletOutputStream or javax.servlet.http.HttpServletResponse.
Syntax
public int result(
String result)HRESULT Result(
LPSTR result);
result. Text representing the result value of the current AppLogic.
Usage
Use result( )Result( ) in conjunction with the execute( ) Execute( )method to define a return value for an AppLogic. In general, use result( )Result( ) in an AppLogic that services HTTP or HTML requests and returns a simple HTML string that does not require streaming.In the execute( ) Execute( ) method, the AppLogic can call result( )Result( ) in conjunction with the return statement to send data results directly back to the entity that called the AppLogic.
Rule
An AppLogic can stream results using streamResultHeader( ) StreamResultHeader( )or streamResult( ) StreamResult( ). If the AppLogic streams results, call result( ) Result( ) only after finishing streaming.To construct HTML output programmatically, use the Java StringBuffer class to efficiently build up an HTML result, which can then be efficiently converted to a string to be passed in as the input to result( ).
An AppLogic can cache results for reuse using setCacheCriteria( )SetCacheCriteria( ).
Alternatively, the AppLogic can return results using a template. The AppLogic can call evalOutput( ) EvalOutput( )to merge a dynamically created result set from a hierarchical query with a template to produce formatted results. The result from evalOutput( )EvalOutput( ) is streamed automatically.
Return Value
GXE.SUCCESS if the method succeeds.HRESULT, which is set to GXE_SUCCESS if the method succeeds.
if(EvalTemplate("GXApp/COnlineBank/templates/NewCust.html", (IGXHierQuery*)NULL, NULL, NULL, NULL)!=GXE_SUCCESS) Result("<HTML><BODY>Unable to evaluate template.</BODY></HTML>"); return GXE_SUCCESS;
Related Topics
execute( )Execute( ),
streamResult( )StreamResult( ),
streamResultHeader( )StreamResultHeader( )"Returning HTML Results" in Chapter 4, "Writing Server-Side Application Code," in Programmer's Guide.
saveSession( ) is deprecated. In standard-based applications, this method is unnecessary because the functionality is automatically provided.
Syntax
public int saveSession(
ISessionIDGen pIDGen)HRESULT SaveSession(
IGXSessionIDGen *pIDGen);
pIDGen. The session ID generation object used to generate session IDs. Specify null.NULL to use the default IGXSessionIDGen object, or specify a custom session ID generation object.
Usage
Use saveSession( ) SaveSession( ) to ensure that changes are saved in the distributed state storage area, which stores the session information for subsequent use if any other AppLogics are invoked within the same session.The saveSession( )SaveSession( ) method uses a cookie—if the Web browser supports cookies— to pass the session ID back and forth between the Web browser and iPlanet Application Server. It transfers only the session ID, not the session information itself, to provide better information security.
HRESULT, which is set to GXE_SUCCESS if the method succeeds.
Because saveSession( )SaveSession( ) uses streamResultHeader( ) StreamResultHeader( )to register the cookie, be sure to call saveSession( )SaveSession( ) before calling streamResult( )StreamResult( ), evalTemplate( )EvalTemplate( ), or any other HTTP body streaming methods.
The AppLogic needs to call the saveSession( )SaveSession( ) method in the AppLogicGXAppLogic class at least once to set a cookie. The saveSession( )SaveSession( ) method in the IGXSession2 interface only saves data to the distributed state store, whereas saveSession( )SaveSession( ) in the AppLogicGXAppLogic class saves data to the distributed state store and sets a cookie.
The AppLogic should call saveSession( ) SaveSession( ) to save changes after updating session data.
To improve performance, keep smaller amounts of information in the session.
Return Value
GXE.SUCCESS if the method succeeds.HRESULT, which is set to GXE_SUCCESS if the method succeeds.
Related Topics
createSession( )CreateSession( ),
getSession( )GetSession( ),
Session2 class GXSession2 class,
ISession2 interface IGXSession2 interface"Starting a Session" in Chapter 8, "Managing Session and State Information," in Programmer's Guide.
Stores AppLogic results, such as HTML, data values, and streamed data, in a result cache.
setCacheCriteria( ) is deprecated. In iPlanet Application Server 6.0 applications, this functionality is controlled using the setCacheCriteria property in the servletInfo.ntv file.
Syntax
public int setCacheCriteria(
int timeout,
int cachesize,
String criteria)HRESULT SetCacheCriteria(
ULONG timeout,
ULONG cachesize,
LPSTR criteria)
timeout. Number of seconds the AppLogic result remains in the result cache after the last access. To clear the result cache after a specified time from its creation, use the GXREPOSIT.GXREPOSIT_TIMEOUT_CREATE flag, as shown in the following example: sSetCacheCriteria(GXREPOSIT.GXREPOSIT_TIMEOUT_CREATE | 300, ...). In this example, the cache is cleared 300 seconds after it is created. Set timeout to zero to clear the result cache and disable caching for this AppLogic.
cachesize. Maximum number of results to be cached for the AppLogic at any time. The result cache stores distinct AppLogic output up to the cachesize limit. If the AppLogic generates another output to cache, the least accessed member of the cache is dropped. Setting cachesize to zero clears the result cache and disables caching for this AppLogic.
criteria. Criteria expression containing a string of comma-delimited descriptors. Each descriptor defines a match with one of the input parameters to the AppLogic. Use the following syntax:
Use ppSession. A pointer to the created or retrieved IGXSession2 object. When the AppLogic is finished using the object, call the Release( ) method to release the interface instance.
SetCacheCriteria( ) to specify caching for the results from an AppLogic. An AppLogic can cache any type of result. Caching improves performance for time-consuming operations such as queries and report generation.
When caching is enabled for an AppLogic, the iPlanet Application Server stores its input parameter values and its results in the cache so that, if the AppLogic is called again with the same parameters (matching the cache criteria), the iPlanet Application Server retrieves its results directly from the cache instead of running the AppLogic again. If the AppLogic is called with different parameters, the iPlanet Application Server runs the AppLogic again and saves its result in the cache as well.
Each AppLogic has only one cache but it can contain multiple sets of results if the AppLogic was run multiple times with different parameters for each call.
Do not use caching if real-time results are needed. For example, to ensure current data, caching is not recommended for query operations on highly volatile data.
Use skipCache( )SkipCache( ) to bypass result caching if an error occurred during AppLogic execution.
Use isCached( )IsCached( ) to test whether caching is currently enabled. Calling isCached( )IsCached( ) is important because it prevents calling setCacheCriteria( )SetCacheCriteria( ) too many times.
To change the caching criteria for AppLogic, call setCacheCriteria( ) again, this time specifying different caching criteria. Each subsequent call supersedes the previous call, discarding the current contents of the result cache, and its criteria remain in effect until the next setCacheCriteria( ) SetCacheCriteria( ) call, if applicable.
To stop caching results, call deleteCache( )DeleteCache( ). A subsequent call to setCacheCriteria( ) SetCacheCriteria( ) can reactivate caching.
Return Value
GXE.SUCCESS if the method succeeds.HRESULT, which is set to GXE_SUCCESS if the method succeeds.
Example 2
// Cache multiple results for up to 100 values of DepartmentsetCacheCriteria(3600,100,"Department");
SetCacheCriteria(3600,100,"Department");
Example 3
// Cache single result for given matching value of DepartmentsetCacheCriteria(3600,1,"Department=Operations");
SetCacheCriteria(3600,1,"Department=Operations");
Example 4
// Cache multiple results for two matching values of deptsetCacheCriteria(3600,2,"Department=Research | Engineering");
SetCacheCriteria(3600,2,"Department=Research | Engineering");
Example 5
// Cache one result for salary in a rangesetCacheCriteria(3600,1,"Salary=40000-60000");
SetCacheCriteria(3600,1,"Salary=40000-60000");
Example 6
// Cache two results for several parameters"Department=Sales,Salary=40000-60000");
"Department=Sales, Salary=40000-60000");
Related Topics
deleteCache( )DeleteCache( ),
removeAllCachedResults( )RemoveAllCachedResults( ),
removeCachedResult( )RemoveCachedResult( ),
isCached( )IsCached( ),
skipCache( )SkipCache( )"Caching AppLogic Results to Improve Performance" in Chapter 4, "Writing Server-Side Application Code," in Programmer's Guide.
setSessionVisibility( ) is deprecated. It provides functionality that does not apply to standard-based applications.
Syntax
public int setSessionVisibility(
String domain,
String path,
boolean isSecure)HRESULT SetSessionVisibility(
LPSTR domain,
LPSTR path,
BOOL isSecure)
domain. The domain in which the session is visible.
path. The path to which this session must be visible.
isSecure. If TRUE, the session is visible only to secure servers (HTTPS).
Usage
Because of the way cookies are used to identify sessions, iPlanet Application Server sessions are, by default, accessible only within the same URL name space where they were created. As a result, if you call only the saveSession( )SaveSession( ) method, then your session is not visible to any other domain or URL.However, if you call setSessionVisibility( )SetSessionVisibility( ) before calling saveSession( )SaveSession( ), you can control the visibility of the session. The setSessionVisibility( )SetSessionVisibility( ) method internally controls the attributes of the cookie used in transmitting the session ID.
You must be part of the domain to set the domain attribute. For example, if the domain is set to iplanet.com, then the session is visible to foo.iplanet.com, bar.iplanet.com, and so on. Domains must have at least two periods (.) in them. For example, .net is an invalid domain attribute.
By default, the session is visible only to the URL that created the session cookie. Use the path parameter to specify different URLs that will be visible. For example, the path /phoenix would match "/phoenixbird" and "/phoenix/bird.html". To make the entire server root visible, specify a path of "/", the most general value possible.
Both the domain and path parameters are null-terminated character strings. They are not modified within the setSessionVisibility( )SetSessionVisibility( ) method.
Rule
For the session visibility to take effect, you must invoke setSessionVisibility( )SetSessionVisibility( ) before a call to saveSession( )SaveSession( ). The saveSession( )SaveSession( ) method uses the visibility attributes set from setSessionVisibility( )SetSessionVisibility( ).
Return Value
GXE.SUCCESS if the method succeeds.HRESULT, which is set to GXE_SUCCESS if the method succeeds.
Related Topics
saveSession( )SaveSession( )
Sets a value that is passed to later AppLogic requests that are called by the same client. If the client is a browser, cookies are used to transfer variable values.
setVariable( ) is deprecated. In standard-based applications, use the addCookie( ) method in the interface javax.servlet.http.HttpServletResponse.
Syntax 1
public int setVariable(
String name,
String value)HRESULT SetVariable(
LPSTR name,
LPSTR value);
Syntax 2
public int setVariable(
String name,
String value,
int timeout,
String urlPath,
String urlDomain,
boolean secure)HRESULT SetVariable(
LPSTR name,
LPSTR value,
ULONG timeout,
LPSTR urlPath,
LPSTR urlDomain,
BOOL secure);
name. The name of the value to record for this browser session. The value will appear on any future AppLogic's input IValList IGXValList under this name.
value. The string value to record.
timeout. Number of seconds before the cookie expires. Applies to HTTP clients only.
urlPath. The subset of URLs in a domain for which the cookie is valid. Applies to HTTP clients only.
urlDomain. The domain for which the cookie is valid. Applies to HTTP clients only.
secure. If a cookie is marked secure, it will be sent only if the communications channel with the host is a secure one. Currently, this means that secure cookies will be sent only to HTTPS (HTTP over SSL) servers. Applies to HTTP clients only.
Usage
Use setVariable( )SetVariable( ) to store information specific to a client that you want to pass to other AppLogics invoked by the same client. The values set with setVariable( )SetVariable( ) are passed to the input IValList (valIn) IGXValList (m_pValIn) of the called AppLogics.In the case of an HTTP client, setVariable( )SetVariable( ) streams the variable out in an HTTP header. The HTTP header registers a cookie, which is the mechanism used to pass data back and forth between the browser and the iPlanet Application Server.
Rule
Because setVariable( )SetVariable( ) streams information in an HTTP header, call it before calling any HTTP body streaming methods, such as streamResult( )StreamResult( ), evalOutput( )EvalOutput( ), and evalTemplate( )EvalTemplate( ).
Tip
If your application requires more security, you should use iPlanet Application Server's session mechanism instead of cookies to maintain session information. With a iPlanet Application Server session, data is stored on the server and only a session ID is passed between the client and the server. For more information about the session mechanism, see ISession2 interfaceIGXSession2 interface.
Return Value
GXE.SUCCESS if the method succeeds.HRESULT, which is set to GXE_SUCCESS if the method succeeds.
Related Topics
"Using Cookies" in Chapter 3, "Application Development Techniques," in Programmer's Guide.
Skips result caching for the current AppLogic execution.
Usage
Use skipCache( ) SkipCache( ) to prevent results from the current request from being saved in the results cache if an error occurs during AppLogic execution.
Rule
For skipCache( ) SkipCache( ) to have any effect, you must first enable caching by calling setCacheCriteria( )SetCacheCriteria( ).
Return Value
GXE.SUCCESS if the method succeeds.
Related Topics
deleteCache( )DeleteCache( ),
removeAllCachedResults( )RemoveAllCachedResults( ),
removeCachedResult( )RemoveCachedResult( ),
isCached( )IsCached( ),
setCacheCriteria( )SetCacheCriteria( ),
IValList interface IGXValList interface"Caching AppLogic Results to Improve Performance" in Chapter 4, "Writing Server-Side Application Code," in Programmer's Guide.
streamResult( ) is deprecated. In standard-based applications, use similar functionality as defined in the Servlet API. For example, refer to javax.servlet.ServletOutputStream or javax.servlet.http.HttpServletResponse.
Syntax
public synchronized int streamResult(
String res)HRESULT StreamResult(
LPSTR res);
res. The body data to stream. If returning HTML body data, you can use HTML formatting following HTTP body conventions. See your HTTP documentation for more information.
Usage
Use streamResult( )StreamResult( ) to stream data as soon as it is available. With streaming, an AppLogic can make the first portion of the data available for use immediately, even if the remainder of the stream has not yet been processed. This is especially useful with large volumes of data, such as a query that takes a while for the database server to process completely. An AppLogic can process and display those rows in the result set that have been returned. Without streaming, AppLogic must prepare the entire result first before returning any data.The streamResult( )StreamResult( ) method is typically used to stream HTTP body content. Before calling streamResult( )StreamResult( ), the AppLogic must call streamResultHeader( )StreamResultHeader( ) to return the HTTP header data first. The HTTP protocol separates data streams into header and body data, and specifies that the header data and body data are returned in that order. For details about HTTP header and body data, see your HTTP documentation.
Alternatively, use evalTemplate( )EvalTemplate( ) to stream HTTP body output. It merges data with an HTML template. As soon as a segment of the output page is finished, evalTemplate( )EvalTemplate( ) streams it out to the Web browser.
An AppLogic can call streamResultHeader( )StreamResultHeader( ) and streamResult( )StreamResult( ) repeatedly to stream more results.
To stream binary data, use streamResultBinary( )StreamResultBinary( ).
Return Value
GXE.SUCCESS if the method succeeds.HRESULT, which is set to GXE_SUCCESS if the method succeeds.
Related Topics
streamResultBinary( )StreamResultBinary( ),
streamResultHeader( )StreamResultHeader( )"Streaming Results" in Chapter 4, "Writing Server-Side Application Code," in Programmer's Guide.
Streams binary data, such as a GIF file.
streamResultBinary( ) is deprecated. In standard-based applications, use similar functionality as defined in the Servlet API. For example, refer to javax.servlet.ServletOutputStream or javax.servlet.http.HttpServletResponse.
Syntax
public synchronized int streamResultBinary(
byte[] buf,
int offset,
int length)HRESULT StreamResultBinary(
LPBYTE buf,
ULONG offset,
ULONG length);
buf. The array from which binary data is streamed.
offset. Index in the array. The starting position in the array to start streaming binary body data.
length. Number of bytes to stream from the array, starting at the specified offset position.
Usage
Use streamResultBinary( )StreamResultBinary( ) to stream binary data as soon as it is available. With streaming, an AppLogic can make the first portion of the data available for use immediately, even if the remainder of the stream has not yet been processed. This is especially useful with large volumes of data, such as a query that takes a while for the database server to process completely. An AppLogic can process and display those rows in the result set that have been returned. Without streaming, AppLogic must prepare the entire result first before returning any data.The streamResultBinary( )StreamResultBinary( ) method is used to stream HTTP body data of binary type, such as an image (GIF) file. Before calling streamResultBinary( )StreamResultBinary( ), the AppLogic should call streamResultHeader( )StreamResultHeader( ) to return the HTTP header data first. The HTTP protocol separates data streams into header and body data, and specifies that the header data and body data are returned in that order. For details about HTTP header and body data, see your HTTP documentation.
Alternatively, use evalTemplate( )EvalTemplate( ) to stream HTTP body output. It merges data with an HTML template. As soon as a segment of the output page is finished, evalTemplate( )EvalTemplate( ) streams it out to the waiting Web browser.
To stream non-binary data, use streamResult( )StreamResult( ).
Return Value
GXE.SUCCESS if the method succeeds.HRESULT, which is set to GXE_SUCCESS if the method succeeds.
Related Topics
streamResult( )StreamResult( ),
streamResultHeader( )StreamResultHeader( )"Streaming Results" in Chapter 4, "Writing Server-Side Application Code," in Programmer's Guide.
streamResultHeader( ) is deprecated. In standard-based applications, use similar functionality as defined in the Servlet API. For example, refer to javax.servlet.ServletOutputStream or javax.servlet.http.HttpServletResponse.
Syntax
public synchronized int streamResultHeader(
String hdr)HRESULT StreamResultHeader(
LPSTR hdr)
hdr. The header data to stream. If returning HTTP header data, use the HTTP header conventions, such as the following:
See your HTTP documentation for more information.
Usage
Use streamResultHeader( )StreamResultHeader( ) to return header data before streaming body data. With streaming, an AppLogic can make the first portion of the data available for use immediately, even if the remainder of the stream has not yet been processed. This is especially useful with large volumes of data, such as a query that takes a while for the database server to process completely. An AppLogic can process and display those rows in the result set that have been returned. Without streaming, AppLogic must prepare the entire result first before returning any data.The streamResultHeader( )StreamResultHeader( ) method is typically used in conjunction with streamResult( )StreamResult( ) to stream HTTP data. Before calling streamResult( )StreamResult( ), the AppLogic should call streamResultHeader( )StreamResultHeader( ) to return the HTTP header data first. The HTTP protocol separates data streams into header and body data, and specifies that the header data and body data are returned in that order. For details about HTTP header and body data, see your HTTP documentation.
Return Value
GXE.SUCCESS if the method succeeds.HRESULT, which is set to GXE_SUCCESS if the method succeeds.
Related Topics
streamResult( )StreamResult( ),
streamResultBinary( )StreamResultBinary( )"Streaming Results" in Chapter 4, "Writing Server-Side Application Code," in Programmer's Guide.
The BaseUtils class provides a set of convenience methods similar to those in the GX class. The methods of this class apply to user-written AppLogics.
Although anyone developing a iPlanet Application Server application can use BaseUtils, this class is typically used in components generated by iPlanet Application Builder.
Package
com.iplanet.server.servlet.extension
Constructor
public BaseUtils( )
convertITemplateDataToResultSet( )
Creates a ResultSet wrapper for an ITemplateData object.
Syntax
public static ResultSet convertITemplateDataToResultSet(
String groupName,
ITemplateData templateData)
groupName. The group name of the specified ITemplateData.
templateData. The ITemplateData to be wrapped.
Usage
The convertITemplateDataToResultSet( ) method takes an ITemplateData object and wraps it so that it conforms to the specifications of a JDBC ResultSet object.
Rules
Hierarchical ITemplateData objects are not supported, so do not specify one as a parameter.
Return Value
A ResultSet object.
Creates a RowSet object that conforms to the IListRowSet interface.
Syntax
public static IListRowSet createListRowSet(
HttpServletRequest request,
HttpServletResponse response,
String listName)
response. The response object.
listName. The name of the RowSet to pass in.
Usage
The createListRowSet( ) method creates a RowSet object that conforms to the IListRowSet interface. IListRowSet objects are useful for dynamically populating a pop-up list. The listName parameter is used to add the RowSet name as an attribute of the specified request.
Return Value
An IListRowSet object.
Related Topics
IListRowSet interface
Syntax
public static final MethodHash createMethodHash()
Usage
Method hashes are used to cache method lookups but are hidden from the user. createMethodHash( ) allows for the construction of method hashes. This construction is necessary when subclasses of DBRowSet are created.
Related Topics
getStaticMethodCache( ) in the DBRowSet class
Creates a string from an IBuffer object.
Syntax
public static final String createStringFromBuffer(
IBuffer buff)
buff. IBuffer object containing the value to convert.
Usage
This method creates a String from an IBuffer object. Use createStringFromBuffer( ) instead of the toString( ) method of the Util class. Unlike toString( ), the createStringFromBuffer( ) method accounts for null terminators. Ignoring null terminators in an IBuffer object causes incorrect Strings.
Tip
createStringFromBuffer( ) does not perform character conversion. You may want to write your own method if character conversion is important.
Return Value
String representing the data in an IBuffer object.
Example
ITemplateMap map = (ITemplateMap) request.getAttribute("GX_MAP");buff = map.get("foo",null,null);
Related Topics
Util class,
IBuffer interface
Converts each occurrence of one single quote to two successive single quotes.
Syntax
public static final String doubleQuote(
String input)
input. The input string whose single quotes are to be affected.
Usage
Use doubleQuote( ) for input bindings to queries. Suppose there is a query that takes one input parameter, NameInput:If the name is O'Reilly, then the following query would be loaded:
Normally, an attempt to execute this query results in a syntax error. The correct query should be as follows:
To produce this query, any single quotes in the input binding for NameInput must be doubled up. The doubleQuote( ) method performs this doubling up.
Return Value
The converted string.
Related Topics
DBRowSet class, GX class
A convenience method for streaming a JSP file.
Syntax
public static void includeJSP(
HttpServletRequest request,
HttpServletResponse response,
String name) throws ServletException, IOException
response. The response object.
name. The name of the JSP or servlet to include.
Usage
The includeJSP( ) method provides a shortcut for streaming a JSP file (or a servlet file). This method also sets the response object's ContentType to "text/html". If an error occurs when including the file, a ServletException is thrown.
Initializes RowSet objects specified in a servlet's configuration file.
Syntax
public static int initRowSets(
HttpServletRequest request,
HttpServletResponse response)
response. The response object.
Usage
Use the initRowSets( ) method to instantiate and initialize all RowSet objects from the metadata in a servlet's configuration file. The initRowSets( ) method also stores the RowSets into the specified request object.A servlet's configuration file has a "RowSets" entry under the ServletData key. The "RowSets" entry identifies each RowSet that the application designer knew about at design-time.
For each RowSet, the initRowSets( ) method first checks the value of the autoCreate variable. If autoCreate is set to true or is not set, then initRowSets( ) instantiates the RowSet identified by the className variable.
The initRowSets( ) method next initializes each RowSet in either of two ways:
If the RowSet is an instance of IRowSet2, then initRowSets( ) initializes the RowSet by calling the setName( ), setRequest( ), setResponse( ) and initMetaInfo( ) methods of the IRowSet2 interface.
If the RowSet is not an instance of IRowSet2, then the properties in the metadata are assumed to be settable on the RowSet by a call to its setProperty( ) method. The initRowSets( ) method will look up the setProperty( ) method and call it if it's available.
When RowSets are instantiated, the null constructor is used. If a null constructor is not available, the server takes the first constructor defined for that class and calls it with null parameters.
The initRowSets( ) method also creates a new DefaultTemplateMap and adds it into the request object. The DefaultTemplateMap is added as an attribute under the name GX_MAP.
Rule
Do not call initRowSets( ) from an EJB. No provision yet exists for instantiating RowSets from an EJB.
Return Value
Return codes defined in the IServletErrorHandler interface: SUCCESS if the method succeeds; otherwise, FAIL_DONT_STREAM_ERROR or FAIL_STREAM_ERROR.
Related Topics
IRowSet2 interface, IServletErrorHandler interface, DefaultTemplateMap class
Calls the log( ) method in the AppLogic class and logs an error to the error output.
Syntax 1
Logs a message (type = GXLOG.GXEVENTTYPE_INFORMATION and category = 0).public static int log(
HttpServletRequest request,
String message)
Syntax 2
Logs an exception instead of a message:public static int log(
HttpServletRequest request,
String message, // message is currently unused
Throwable t)
Syntax 3
Logs an event with a message, specifying the type and category of event:public static int log(
HttpServletRequest request,
int type,
int category,
String message)
message. The message text to log.
request. The request object that contains the pointer to the AppLogic.
t. The Throwable that caused the problem.
type. The type of message to log. Use one of the following variables:
GXLOG.GXEVENTTYPE_INFORMATION
category. User-defined message category. Do not use the range of values reserved for the iPlanet Application Server systems, which is 0 to 65535, inclusive.
Usage
Use log( ) as a convenience method for calling the AppLogic's log( ) method and logging an error to the error output.In Syntax 2, the request's streamError( ) method is called with a null response object. The IServletErrorHandler object is responsible for converting the exception to a string and then calling:
log(HttpServletRequest request, String message)
which is the log( ) method defined by Syntax 1.
Return Value
GXE.SUCCESS if the method succeeds.
Related Topics
log( ) in the AppLogic class,
IServletErrorHandler interface
When you generate JSPs with iPlanet Application Builder (iAB), the resulting JSPs use declarative tags, which support a result-set-oriented view of data rather than a bean-oriented view. To support standard RowSet objects in iAB-generated JSPs, iPlanet Application Server provides the DBRowSet class.
DBRowSet is a declarative-tag-aware extension to the iASRowSet class. Use the methods of DBRowSet in any JSP you have generated with iPlanet Application Builder. iPlanet Application Builder programmers can extend DBRowSet to display formatted, columnar data in a JSP.
DBRowSet can either load queries from a query file or use queries set up by the user. When results (and/or result sets) are requested, the Statement is executed to produce the requested values. After the data is exhausted, the isLast( ) method returns true and the next( ) method returns false.
DBRowSet replaces the DBDataSet and DBStoredProcedure classes from iPlanet Application Builder 6.0.
Package
com.iplanet.server.servlet.extension
Constructors
Syntax 1
Use this syntax for the null constructor:public DBRowSet() throws SQLException
Syntax 2
Use the following constructor to allocate a new DBRowSet with a given name and the name of the file from which queries will be loaded.public DBRowSet(
HttpServletRequest request,
HttpServletResponse response,
String name,
String filename) throws SQLException
Syntax 3
Use the following constructor to allocate a new DBRowSet with a given name, the name of the file from which queries will be loaded later, and the name of the connection against which this query will be executed.public DBRowSet(
HttpServletRequest request,
HttpServletResponse response,
String name,
String filename,
String connectionName) throws SQLException
Syntax 4
Use this constructor like the previous one, but specify a query name as well.public DBRowSet(
HttpServletRequest request,
HttpServletResponse response,
String name,
String filename,
String connectionName,
String queryName) throws SQLException
response. The response object.
filename . The name of the query file from which the queries will be loaded.
connectionName. The default name of the connection to use.
queryName. The name of the query to load from the query file.
SQLException. This exception will be thrown by all constructors whenever the initMetaInfo( ) method throws SQLException.
Methods
This section is divided into four parts:
Methods That Auto-Execute
Methods That Auto-Execute
The following methods override the corresponding iASRowSet method and execute the RowSet if and only if the RowSet is not already executing. For more information, see either the iPlanet-specific iASRowSet class or the javax.sql.RowSet interface. In particular, see the RowSet execute( ) method or the DBRowSet isExecuted( ) method.
Note:
The String-parameter version of getString( ) attempts to resolve references to method invocations as well as references to the database columns.
Methods That Auto-Initialize
The following methods override the corresponding iASRowSet method and initialize the RowSet if and only if the RowSet is not already initialized. For more information, see the iPlanet-specific iASRowSet class or the standard RowSet interface. In addition, see the DBRowSet methods init( ) and isInitialized( ).
Methods That Take a Name Instead of an Index
Queries created with iPlanet Application Builder identify their parameters by name. But JDBC uses query parameters that are identified by an index.DBRowSet therefore provides a group of "set" methods that have counterparts in the RowSet interface. The only difference is that the DBRowSet method expects a String (for the parameter name), where the corresponding RowSet method expects an integer (for the parameter index). This group of "set" methods is listed below:
In order for your servlets to set parameters on the RowSets, you must translate parameter names to parameter indexes. There are two ways to do this:
Call any of the set methods listed above, supplying the parameter name as the String value. Each of the listed set methods will in turn call getLoadParameter( ), which returns the index associated with the named query parameter.
For more information about the previous set methods, see the corresponding methods in the standard javax.sql.RowSet interface.Call the getLoadParameter( ) method directly, supplying the parameter name to convert to a parameter index. Then call the standard RowSet version of the set methods listed above, supplying the parameter index that was previously returned by getLoadParameter( ).
Other Methods
The remaining DBRowSet methods are described here, with the DBRowSet class. These methods are summarized in the following table:
Sets a parameter to a particular String value, prior to loading the query.
Syntax
public int bindLoadValue(
String destVariable,
String value)
destVariable. The name of the variable to set.
value. The value to set for the variable.
Usage
Use the bindLoadValue( ) method to set parameters when a query is loaded—before the query is executed. In other words, call bindLoadValue( ) before init( ) is called.Sometimes, it is better to set a parameter at load time rather than at run time. In particular, sometimes you need to replace a parameter to make a SQL statement conform to standard SQL syntax. For example, the following SQL code is nonstandard:
If you set the whereClause parameter at load time, this SQL will comply with standard syntax because the parameter is substituted before the command is set on the RowSet.
Return Value
GXE.SUCCESS if the method succeeds.
Clears the list of parameters.
Syntax
public void clearParameters() throws SQLException
Usage
Use clearParameters( ) to clear the list of parameters that were set by the developer.In general, it is unnecessary to call clearParameters( ) because (typically) you don't re-execute your RowSet.
This method overrides the clearParameters( ) method on the iASRowSet. The iASRowSet, in turn, implements the clearParameters( ) method in javax.sql.RowSet.
Note that clearParameters( ) does not set the RowSet to be uninitialized. As a result, all information that maps parameter names to parameter indexes is lost. To preserve the parameter mapping information, first call the setInitialized( ) method to set the RowSet to be uninitialized. Then call init( ) again to reload the query (and thus the parameter information).
Retrieves the value required by the FetchSize hidden field for iAB's "VCR" support.
Syntax
public String getFetchSize(
iASString max)
max. The maximum number to retrieve for the next iteration.
Usage
The FetchSize hidden field supports a "VCR-like" display of records in a window. This type of display is useful when you want to get the next or previous set of records from a query that returns many pages worth of records. For example, the window might contain buttons for displaying the next, previous, first, or last page of data.
Example
The getFetchSize( ) method is invoked from the template engine using a gx-callback such as the following:%gx type=cell id=RowSet.getFetchSize(#max)%%/gx%
Return Value
A String representing the value required by FetchSize.
Related Topics
iASString class
Gets the parameter index for a particular parameter in the query.
Syntax
public int getLoadParameter(
String paramName)
paramName. The name of the parameter whose index is to be retrieved.
Usage
Use this method when setting parameters. In iAB, parameters are stored by name, but standard RowSets use parameter indexes. The DBRowSet class provides a group of "set" methods that automatically call getLoadParameter( ) to retrieve the index. For more information, see the section "Methods That Take a Name Instead of an Index."After you load the query to define the name-index pairs, you can explicitly call getLoadParameter( ) to retrieve the indices.
If the query is not already loaded (in other words, if the RowSet is not already initialized), then getLoadParameter( ) initializes the RowSet.
Return Value
An integer index associated with a paramater name.
Syntax
public String getName()
Usage
Use this method to get the name for the RowSet. This is the name that is used to store the RowSet into the attribute list of the Request object.
Retrieves one record number beyond the last one that has been printed out.
Syntax
public String getNextRowNumber(
iASString unused)
Usage
This method is useful for populating hidden values for supporting VCR-style display (for example, buttons that display next or previous values).
Example
The getNextRowNumber( ) method is invoked from the template engine, using a gx-callback such as this:%gx type=cell id=RowSet.getNextRowNumber()%%/gx%
Related Topics
getRowNumber( )
Gets the name of the file that was used (or will be used) to load queries.
Syntax
public String getQueryFile()
Usage
Use this method to get the file name that was previously set using setQueryFile( ) or set in the constructor.
Related Topics
setQueryFile( ), getQueryName( )
Gets the name of the query to be loaded from the query file.
Syntax
public String getQueryName()
Usage
Use this method to get the name of the query to be loaded from the query file.
Related Topics
setQueryName( ), getQueryFile( )
Retrieves the last record number that has been displayed.
Syntax
public String getRowNumber(
iASString groupName)
Usage
This method is useful for populating table outputs with a row number for each row.
Example
The getRowNumber( ) method is invoked from the template engine, using a gx-callback such as this:%gx type=cell id=RowSet.getRowNumber()%%/gx%
Related Topics
getNextRowNumber( )
Retrieves the method cache for a particular class.
Syntax
public MethodHash getStaticMethodCache()
Usage
In order for RowSet subclasses to be efficiently garbage-collected, each RowSet subclass must override this method to return a different MethodHash. In this way, each class caches only the methods defined in this class or its superclasses without dangling references to the methods of other classes.
Return Value
A MethodHash object.
Related Topics
createMethodCache( ) in the BaseUtils class
Overloads the getString(String) method to use a iASString instead.
Syntax
public String getString(
iASString colName) throws SQLException
colName. The name of the column, as a iASString.
The javax.sql.RowSet interface has a getString( ) method that takes a String parameter. The getString(iASString) version intercepts the getString(String) version, allowing you to specify a iASString instead.
A SQLException is thrown, as is done in the getString(String) form of the method.
Related Topics
javax.sql.RowSet interface
Usage
The init( ) method is called implicitly during the execute( ) call.
Related Topics
execute( ), initMetaInfo( )
Initializes the RowSet to match specific metadata.
Syntax
public boolean initMetaInfo(
OrderedHash metaData) throws SQLException
metaData. An OrderedHash of properties. The RowSet will be initialized with these properties.
Usage
The initMetaInfo( ) is used to initialize a RowSet. This method is called by BaseUtils.initRowSets( ) when the RowSet is created.The metaData parameter specifies the properties stored in a method in the NTV list. The properties specify the query file name, the query name, the connection name, and the input bindings for the query parameters. In this way, the RowSet is initialized so as to match the properties stored in the NTV-list method.
If any subclasses have cached metadata that differs from this RowSet's metadata, then the subclasses should override the method in the NTV list.
Return Value
Returns false if the initialization fails for some reason.
Evaluates a field specification in an HTML template.
Syntax
public String isEqualToExpression(
iASString expression)
expression. The expression to evaluate.
Usage
This method is similar to isEqualToValue( ). Both methods are intended to be called from the template engine, with the expression containing one equal sign (=) and the lefthand value being a full field specification. In isEqualToValue( ) the righthand value is a constant, whereas in isEqualToExpression( ), the righthand value is another field specification.The isEqualtoValue( ) method lets you write more standard if statements in an HTML template. The isEqualToExpression( ) method is useful for filling a popup list.
Example
The following code fragment creates a data set as a list:
To display this list on a web page, you might create an HTML template containing the following code:
<OPTION VALUE="%gx type=cell id=myList.value% %/gx%"
id=myList.isEqualToExpression(
myList.value=myList.ListSelection)%SELECTED
%gx type=cell id=myList.label%%/gx%
Return Value
Returns null if the expression is true, or "" if the expression is false.
Related Topics
isEqualToValue( ),
MemRowSet class
Evaluates a field specification in an HTML template.
Syntax
public String isEqualToExpression(
iASString expression)
expression. The expression to evaluate.
Usage
This method is similar to isEqualToExpression( ). Both methods are intended to be called from the template engine, with the expression containing one equal sign (=) and the lefthand value being a full field specification. In isEqualToValue( ) the righthand value is a constant, whereas in isEqualToExpression( ), the righthand value is another field specification.The isEqualtoValue( ) method lets you write more standard if statements in an HTML template. The isEqualToExpression( ) method is useful for filling a popup list.
For example, you can use isEqualToValue( ) to determine whether a checkbox should be "CHECKED" or not.
Example
<gx type=cell id=isEqualToValue(DataSet.field_name=ALLMINE)>
Return Value
Returns null if the expression is true, or "" if the expression is false.
Related Topics
isEqualToExpression( )
Determines whether the RowSet is being executed.
Syntax
public boolean isExecuted()
Usage
Use isExecuted( ) to determine whether the RowSet is being executed.
Return Value
Returns true if the RowSet is being executed; otherwise, returns false.
Determines whether the RowSet is initialized.
Syntax
public boolean isInitialized()
Usage
Use isInitialized( ) to determine whether the RowSet is initialized.
Return Value
Returns true if the RowSet is initialized; otherwise, returns false.
Related Topics
setInitialized( ), init( ), initMetaInfo( )
Returns null if the current record is the last fetchable record; otherwise, it returns the null string.
Syntax
public String isLastFetchableRecord(
iASString unused)
unused. Not used. The default query name is always used.
Usage
This method lets you write JavaScript code that, for example, changes the name of the Next button to be Refresh. In this way, users don't get a blank row when they press the ">" (Next) button at the end of a record set.
Return Value
Returns null if the current record is the last fetchable record; otherwise, it returns the null string.
Example
This method is invoked from the template engine using a gx-callback such as the following:
<%gx type=cell id=RowSet.isLastFetchableRecord()%> <SCRIPT> datasetFetchCommandNext.name = "datasetFetchCommandRefresh" </SCRIPT> <%/gx%>
Sets whether the RowSet is being executed.
Syntax
public void setExecuted(
boolean executed)
executed. The state indicating whether the RowSet is executing or not.
Usage
Use setExecuted( ) to specify the state of RowSet execution. Specify true to indicate that the RowSet is being executed, and specify false otherwise. You can also use isExecuted( ) to determine whether the RowSet is being executed.
Sets whether the RowSet is initialized.
Syntax
public void setInitialized(
boolean initialized)
initialized. The state indicating whether the RowSet is initialized.
Usage
Use setInitialized( ) to specify the initialization state. Specify true to indicate that the RowSet is initialized, which means that the init( ) method has been called. Otherwise, specify false . You can also use isInitialized( ) to determine whether the RowSet is initialized.
Related Topics
isInitialized( ), init( ), initMetaInfo( )
Syntax
public void setName(
String name)
Usage
Use this method to set the name for the RowSet. You can also set the name using the constructor.Note that this method also sets the query name—to the same name. If you don't want this to happen, then call setQueryName( ) to reset the query name.
Sets the name of the file that was used or will be used to load queries.
Syntax
public int setQueryFile(
String filename)
filename. The name of the file that contains the queries for this RowSet.
Usage
Use setQueryFile( ) to specify the file for loading queries. You can use getQueryFile( ) to retrieve the file name.
Rule
setQueryFile( ) must be called on an uninitialized RowSet.
Return Value
-1 if called on an initialized RowSet.
Related Topics
getQueryFile( ), setQueryName( )
Resets the DBRowSet to access only the given query.
Syntax
public int setQueryName(
String query)
query. The name of the query that the DBRowSet should load.
Usage
Use setQueryName( ) to reset the DBRowSet to access the specified query. Call setQueryName( ) before executing the DBRowSet.
Return Value
-1 if called on an executed DBRowSet.
Related Topics
getQueryName( ), setQueryFile( )
Sets the request object in which the RowSet will run.
Syntax
public void setRequest(
HttpServletRequest request)
request. The HttpServletRequest object.
Usage
This method is called during construction. The HttpServletRequest is useful when implementing isEqualToExpression( ), where other RowSets may be required.
Sets the response object in which the RowSet will run.
Syntax
public void setResponse(
HttpServletResponse response)
response. The HttpServletResponse object.
Usage
Use setResponse( ) to set the response object in which the RowSet will run.
The DefaultHttpSession class is a proxy class for a javax.servlet.http.HttpSession object. When you create subclasses of DefaultHttpSession, these subclasses enable their session objects to conform to the JavaBeans specification (for instance, individual property-getters and property-setters). Both the DefaultHttpSession and user-derived subclasses must have a constructor that takes one argument, the HttpSession.iAB
To retrieve the instance of DefaultHttpSession, you must first ensure that you have correctly configured the SessionInfo section of the application's appInfo.ntv file. In particular, you must set the httpSessionBeanClass attribute to identify the class that acts as proxy for the HttpSession. Assuming that httpSessionBeanClass is set correctly, you can now cast the request to HttpServletRequest2 and call that interface's getHttpSessionBean( ) method.
Note that DefaultHttpSession implements HttpSession. If you want an HttpSession2 object, you must extend the DefaultHttpSession2 class instead.
Although anyone developing a iPlanet Application Server application can use DefaultHttpSession, this class is typically used in components generated by iPlanet Application Builder.
Package
com.iplanet.server.servlet.extension
Constructor
The following constructor is required:public DefaultHttpSession(
HttpSession baseSession)Use the baseSession parameter to pass in the HttpSession that will serve as the target for all delegated HttpSession methods.
Methods
Most of the methods in the DefaultHttpSession class are delegated from a corresponding method in the HttpSession interface. The following DefaultHttpSession methods are delegated:
For more information on the previous methods, see the interface javax.servlet.http.HttpSession.
DefaultHttpSession contains the following additional methods:
Returns the delegated implementor of the HttpSession methods.
Related Topics
getHttpSessionBean( ) in the HttpServletRequest2 interface,
DefaultHttpSession2 class
Returns the delegated implementor of the HttpSession methods.
Syntax
public HttpSession getHttpSession()
Return Value
An HttpSession object.
Related Topics
setHttpSession( )
Returns a String value from an HttpSession object.
Syntax
public String getString(
String name)
name. The name of the string whose value is to be returned.
Usage
The getString( ) method is almost identical to the getValue( ) method. The only difference is that getValue( ) returns an Object value, whereas getString( ) returns a String value.
Related Topics
getValue( ) method in the HttpSession interface, from the Java Servlet API.
Sets the delegated implementor of all HttpSession methods.
Syntax
public void setHttpSession(
HttpSession baseSession)
baseSession. The HttpSession object that is delegated as the implementor of all HttpSession methods.
Usage
Use setHttpSession( ) to define the proxy object that implements HttpSession methods. Use getHttpSession( ) to retrieve the object.
Related Topics
getHttpSession( )
The DefaultHttpSession2 class is a proxy class for an HttpSession2 object. HttpSession2 is an interface of the iPlanet Application Server API, in the package com.iplanet.server.servlet.extension.
When you create subclasses of DefaultHttpSession2, these subclasses enable their session objects to conform to the JavaBeans specification (for instance, individual property-getters and property-setters). Both the DefaultHttpSession2 and user-derived subclasses must have a constructor that takes one argument, the HttpSession. This HttpSession must also be an HttpSession2 object.
In other words, the application must use iPlanet Application Server sessions that implement both HttpSession and HttpSession2. To configure applications to use iPlanet Application Server sessions, set the appropriate session property in the appInfo.ntv file.
To retrieve the instance of DefaultHttpSession2, you must first ensure that you have correctly configured the SessionInfo section of the application's appInfo.ntv file. In particular, you must set the httpSessionBeanClass attribute to identify the class that acts as proxy for the HttpSession2. Assuming that httpSessionBeanClass is set correctly, you can now cast the request to HttpServletRequest2 and call that interface's getHttpSessionBean( ) method.
Note that DefaultHttpSession2 implements HttpSession2. If you want an HttpSession object, you must extend the DefaultHttpSession class instead.
Although anyone developing a iPlanet Application Server application can use DefaultHttpSession2, this class is typically used in components generated by iPlanet Application Builder.
Package
com.iplanet.server.servlet.extension
Constructor
The following constructor is required:public DefaultHttpSession2(
HttpSession baseSession)Use the baseSession parameter to pass in the Object that will serve as the target for all delegated HttpSession2 and HttpSession methods.
Methods
Most of the methods in the DefaultHttpSession2 class are delegated from a corresponding method in the interface com.iplanet.server.servlet.extension.HttpSession2. The following DefaultHttpSession2 methods are delegated:
For more information on the previous methods, see the HttpSession2 interface in this guide.
DefaultHttpSession2 contains the following additional methods:
Returns the delegated implementor of the HttpSession2 methods.
Overrides the invalidate( ) method of DefaultHttpSession to clear out the pointer to the session delegate.
Related Topics
getHttpSessionBean( ) in the HttpServletRequest2 interface,
DefaultHttpSession class
Returns the delegated implementor of the HttpSession2 methods.
Syntax
public HttpSession2 getHttpSession2()
Return Value
An HttpSession2 object.
Related Topics
setHttpSession2( )
Overrides the invalidate( ) method of DefaultHttpSession to clear out the pointer to the session delegate.
Syntax
public void invalidate()
Usage
The invalidate( ) method overrides the DefaultHttpSession invalidate( ) method, which in turn is a delegated HttpSession method. Use invalidate( ) to clear out the pointer to the session delegate.
Related Topics
invalidate( ) method in the javax.servlet.http.HttpSession interface
Sets the delegated implementor of all HttpSession2 methods.
Syntax
public void setHttpSession2(
HttpSession2 baseSession2)
baseSession2. The HttpSession2 object that is delegated as the implementor of all HttpSession2 methods.
Usage
Use setHttpSession2( ) to set the HttpSession2 object that acts as the delegated implementor of all HttpSession2 methods. Use getHttpSession2( ) to retrieve the object that was set.The setHttpSession2( ) method calls setHttpSession( ) if the passed-in baseSession2 parameter is also an HttpSession object.
Related Topics
getHttpSession2( )
The DefaultHttpSession2 class is a proxy class for an HttpSession2 object. HttpSession2 is an interface of the iPlanet Application Server API, in the package com.iplanet.server.servlet.extension.
When you create subclasses of DefaultHttpSession2, these subclasses enable their session objects to conform to the JavaBeans specification (for instance, individual property-getters and property-setters). Both the DefaultHttpSession2 and user-derived subclasses must have a constructor that takes one argument, the HttpSession. This HttpSession must also be an HttpSession2 object.
In other words, the application must use iPlanet Application Server sessions that implement both HttpSession and HttpSession2. To configure applications to use iPlanet Application Server sessions, set the appropriate session property in the appInfo.ntv file.
To retrieve the instance of DefaultHttpSession2, you must first ensure that you have correctly configured the SessionInfo section of the application's appInfo.ntv file. In particular, you must set the httpSessionBeanClass attribute to identify the class that acts as proxy for the HttpSession2. Assuming that httpSessionBeanClass is set correctly, you can now cast the request to HttpServletRequest2 and call that interface's getHttpSessionBean( ) method.
Note that DefaultHttpSession2 implements HttpSession2. If you want an HttpSession object, you must extend the DefaultHttpSession class instead.
Although anyone developing a iPlanet Application Server application can use DefaultHttpSession2, this class is typically used in components generated by iPlanet Application Builder.
Package
com.iplanet.server.servlet.extension
Constructor
The following constructor is required:public DefaultHttpSession2(
HttpSession baseSession)Use the baseSession parameter to pass in the Object that will serve as the target for all delegated HttpSession2 and HttpSession methods.
Methods
Most of the methods in the DefaultHttpSession2 class are delegated from a corresponding method in the interface com.iplanet.server.servlet.extension.HttpSession2. The following DefaultHttpSession2 methods are delegated:
For more information on the previous methods, see the HttpSession2 interface in this guide.
DefaultHttpSession2 contains the following additional methods:
Returns the delegated implementor of the HttpSession2 methods.
Overrides the invalidate( ) method of DefaultHttpSession to clear out the pointer to the session delegate.
Related Topics
getHttpSessionBean( ) in the HttpServletRequest2 interface,
DefaultHttpSession class
Returns the delegated implementor of the HttpSession2 methods.
Syntax
public HttpSession2 getHttpSession2()
Return Value
An HttpSession2 object.
Related Topics
setHttpSession2( )
Overrides the invalidate( ) method of DefaultHttpSession to clear out the pointer to the session delegate.
Syntax
public void invalidate()
Usage
The invalidate( ) method overrides the DefaultHttpSession invalidate( ) method, which in turn is a delegated HttpSession method. Use invalidate( ) to clear out the pointer to the session delegate.
Related Topics
invalidate( ) method in the javax.servlet.http.HttpSession interface
Sets the delegated implementor of all HttpSession2 methods.
Syntax
public void setHttpSession2(
HttpSession2 baseSession2)
baseSession2. The HttpSession2 object that is delegated as the implementor of all HttpSession2 methods.
Usage
Use setHttpSession2( ) to set the HttpSession2 object that acts as the delegated implementor of all HttpSession2 methods. Use getHttpSession2( ) to retrieve the object that was set.The setHttpSession2( ) method calls setHttpSession( ) if the passed-in baseSession2 parameter is also an HttpSession object.
Related Topics
getHttpSession2( )
The GUID class is not necessary in the new application model. This class is deprecated and is provided for backward compatiblity only.
The GUID class represents a Globally Unique Identifier, or GUID, which uniquely identifies each application component under iPlanet Application Server. This class provides methods for creating, specifying, and testing GUIDs within application components.
A GUID is a 128-bit hexadecimal number in the following printed format:
{XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX}
Each X is a hexadecimal digit, and the braces and hyphens are required.
GUIDs provide a simple layer of security for your applications because they are not easily human-readable, as in the following example:
{E8128C30-6BF8-11cf-96FC-0020AFED9A65}
When calling an application component from a web page or from another application component, you must specify a GUID, usually in a string printed format, as shown in the examples in this section. When an application component is called, a request message notifies iPlanet Application Server, which then runs the component.
You must assign and register a unique GUID for each application component you create. For more information about registering GUIDs, see the Programmer's Guide.
To instantiate the GUID class, use the Java new keyword, as shown in the following example:
Syntax 1
This version, the default constructor method, creates a null GUID containing all zeros.
Syntax 2
This version creates a GUID from a String representation.public GUID(String guidString)
guidString. String representing the GUID, using hexadecimal numbers, in the following format:
{XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX}
Return Value
A GUID object containing either all zeros (null) or a 128-bit hexadecimal number, or null for failure (such as the input string or values are not in the correct format).
Related Topics
isNull( ), reset( )
Determines whether the GUID object is null (all zeros).
Syntax
public boolean isNull()
Usage
Use isNull( ) after calling GUID( ) to determine whether the GUID was created successfully. A null GUID object has the following format:{00000000-0000-0000-0000-000000000000}
Return Value
A Boolean true if the specified GUID is null, or false if not.
if (!guid.isNull()) { return guid; }
Related Topics
GUID( ), reset( )
Resets the GUID object to null (all zeros). A null GUID object has the following format:
{00000000-0000-0000-0000-000000000000}
// Reset a GUID to null guid.reset(); // At this point, guid.isNull() returns true
Related Topics
GUID( ), isNull( )
The GX class is deprecated and is provided for backward compatibility only. New applications developed according to the servlet-JSP programming model do not need the functionality provided by the GX class.
The GX class is a utility class for general operations, such as creating a memory buffer or an IValList object. Like the Math and System classes in the Java Class Library, the GX class provides a suite of static methods that can be used anywhere regardless of whether an instance of the class exists or not.
You call the methods in the GX class by using the following convention: GX.method. The following example shows how you call CreateBuffer( ), a method in the GX class:
Creates a new IBuffer object, which represents a block of memory.
Syntax
public static IBuffer CreateBuffer()
Usage
Use CreateBuffer( ) to create IBuffer objects to pass as input arguments to methods, such as put( ) in the TemplateMapBasic class. After you create the IBuffer object, use methods in the IBuffer interface to allocate the memory buffer and to assign a value to it.
Tip
If the buffer is to contain a string, use CreateBufferFromString( ) instead. This method creates the IBuffer object and assigns a string value to it.
Return Value
IBuffer object, or null for failure.
Related Topics
IBuffer Interface (deprecated)
Creates a new IBuffer object, which represents a block of memory, and assigns a string value to it.
Syntax
public static IBuffer CreateBufferFromString(
String str)
str. The string to assign to the memory buffer.
Usage
Use CreateBufferFromString( ) to create an IBuffer object that contains a string value. The put( ) method in the TemplateMapBasic class, for example, takes an IBuffer object and a string value as an input argument.
Return Value
IBuffer object, or null for failure.
String str = "StateName"; IBuffer buff; buff = GX.CreateBufferFromString(str); ... ITemplateMap tmplmap; tmplmap.put("$STATES", buff);
Related Topics
IBuffer Interface (deprecated)
Deprecated. This method is retained for backward compatibility only.
Creates a new IStream object, which represents a buffer for capturing streamed output during template processing.
Syntax
public IStream CreateStreamBuffer(
IStream stream)
stream. Specify null to create a simple stream buffer. Specify another stream buffer to chain two stream buffers.
Usage
Use CreateStreamBuffer( ) to create a stream buffer to pass to evalOutput( ) or evalTemplate( ). The evalOutput( ) and evalTemplate( ) methods merge a template with data from the ITemplateData object and stream the output to the buffer. Use a stream buffer if, for example, your AppLogic needs to manipulate the data before sending it to another AppLogic.
Tip
The IStream object implements the IStreamBuffer interface. To manipulate data in a stream buffer, use the getStreamData( ) method in the IStreamBuffer Interface (deprecated).
Return Value
IStream object, or null for failure.
Related Topics
evalOutput( ) and evalTemplate( ) in the AppLogic class (deprecated)IStreamBuffer Interface (deprecated)
Deprecated. This method is retained for backward compatibility only.
Creates a new ITemplateData object, which represents a hierarchical source of data.
Syntax
public static ITemplateData CreateTemplateDataBasic(
String str)
str. The name of the TemplateDataBasic object.
Usage
Use CreateTemplateDataBasic( ) to create a hierarchical source of data to pass to evalOutput( ) or evalTemplate( ). The evalOutput( ) and evalTemplate( ) methods merge a template with data from the ITemplateData object and stream an output report.
Tip
CreateTemplateDataBasic( ) returns an ITemplateData object. If the AppLogic needs to call a method in the TemplateDataBasic class, cast the ITemplateData object to the TemplateDataBasic class, as shown in the following example:td = (TemplateDataBasic)GX.CreateTemplateDataBasic("td");
Return Value
ITemplateData object, or null for failure.
Example
In the following code snippet, two TemplateDataBasic objects are created to store the results from a query to avoid running the same query twice. The two TemplateDataBasic objects are then combined into one and passed to evalTemplate( ) for processing.
Related Topics
evalOutput( ) and evalTemplate( ) in the AppLogic class (deprecated)ITemplateData Interface (deprecated)
TemplateDataBasic class (deprecated)
Deprecated. This method is retained for backward compatibility only.
Creates a new ITemplateMap object, which represents a mapping between a template field specification and dynamic data used for template processing.
Syntax
public static ITemplateMap CreateTemplateMapBasic()
Usage
Use CreateTemplateMapBasic( ) to create a template map object to pass to evalOutput( ) or evalTemplate( ). A template map object is used to link template fields to calculated values or to source data with a non-matching field name but identically-formatted data.
Tip
CreateTemplateMapBasic( ) returns an ITemplateMap object. If the AppLogic needs to call a method in the TemplateMapBasic class, cast to TemplateMapBasic, as shown in the following example:tmplmap = (TemplateMapBasic) GX.CreateTemplateMapBasic();
Return Value
ITemplateMap object, or null for failure.
Related Topics
evalOutput( ) and evalTemplate( ) in the AppLogic class (deprecated)ITemplateMap Interface (deprecated)
TemplateMapBasic class (deprecated)
Creates a new IValList object, which represents a collection of values.
Syntax
public static IValList CreateValList()
Usage
Use CreateValList( ) to create IValList objects to pass as input arguments to methods, such as execute( ) in the IPreparedQuery interface. After creating the IValList object, use methods in the IValList interface to set values in the IValList.
Return Value
IValList object, or null for failure.
IValList params; params = GX.CreateValList(); params.setValString(":Make", "Acura") params.setValString(":Model", "Integra") ... resultset = pqry.execute(0, params, null, null);
Related Topics
IValList interface
Deprecated. This method is retained for backward compatibility only.
Processes the results in an AppLogic's output IValList (vOut) and returns an ITile object from which the caller can extract data.
Syntax
public static ITile ProcessOutput(
IContext context,
int flags,
IValList list)
context. The IContext object, which gives the AppLogic access to iPlanet Application Server services. Pass in the AppLogic's context member variable.
flags. Specify 0. Internal use only.
list. The output IValList that contains the results returned by a called AppLogic.
Usage
Use ProcessOutput( ) to process non-HTML results that are returned in the following situation:
A client (AppLogic or OCL client application) calls an AppLogic with newRequest( ).
ProcessOutput( ) returns the processed data as an ITile object. Data in the ITile object is organized like a hierarchical result set. The client can use methods in the ITile interface to loop through the result set and retrieve values.Through newRequest( ), the client passes input and output IValLists to the called AppLogic. If the client is an AppLogic, it should specify the value "ocl" for the gx_client_type key in the input IValList. The "ocl" value is assigned automatically for OCL clients.
The called AppLogic processes the request and returns results in the output IValList.
Return Value
ITile object, or null for failure.
Related Topics
newRequest( ) in the AppLogic class (deprecated)
Releases an object from memory.
Syntax
public static int Release(
Object obj)
Usage
Use Release( ) to free an object from memory when it is no longer needed. Although Java automatically detects and frees objects that are no longer being used, the Java garbage collector generally runs only at set garbage collection intervals; unused objects might not be freed immediately. Release( ) gives your application more control over object deallocation and system resource usage.
Return Value
GXE.SUCCESS if the method succeeds.
Example
GX.Release(resultset);
Deprecated. This method is retained for backward compatibility only.
Waits for asynchronous operations, such as database queries, to be completed.
Syntax
public static int WaitForOrder(
IOrder orders[],
IObject context,
int timeout);
orders. An array of IOrder objects. Each element in the array corresponds to an asynchronous operation.
context. The context object, which is a member variable of the AppLogic class.
timeout. Maximum number of seconds to wait before expiring, if none of the asynchronous queries is finished. Specify 0 to wait forever.
Usage
Use WaitForOrder( ) to wait for one or more asynchronous operations, such as asynchronous database queries, to return the completed results from the database server on which they are submitted. Asynchronous queries that were started with executeQuery( ) in the IDataConn interface might return result sets that are not finished yet. An AppLogic, however, must wait for the result set to be finished before using it.WaitForOrder( ) waits until one of the following conditions occurs:
The status of the IOrder object associated with one of the queries changes to GXORDER_STATE.GX_STATE_DONE.
Return Value
The index in the orders array of the IOrder that is now completed. WaitForOrder( ) returns a negative number if an error or timeout occurred.
Related Topics
IOrder Interface (deprecated)
GXContext is a utility class that enables developers to access iPlanet Application Server services. Most methods of this class are used primarily in the method stubs of Java extensions. For more information about using GXContext while creating extensions, see the Developer's Guide that accompanies your version of iPlanet Extension Builder, a separately available product.
In rare situations, EJB and servlet developers may want to call the methods of GXContext, thereby allowing iPlanet Application Server 6.0 applications to include additional iPlanet Application Server features that are not currently supported in the EJB or servlet specifications. For example, the CreateMailbox( ) method supports electronic messaging.
In addition to using GXContext methods, servlet developers can access iPlanet Application Server features in other ways. Servlet developers can use the methods of two iPlanet Application Server-specific interfaces—HttpSession2 or HttpServletRequest2—as well as the methods of AppLogic, a deprecated class.
You call the methods in the GXContext class by using the following convention:
All of the methods on the GXContext class require the caller to supply an instance of com.kivasoft.IContext. There are many ways in which the context may be obtained, depending on the type of the calling component. Refer to the following examples.
Examples
The following examples describe different ways to obtain a context.
Example 1
From an AppLogic, an instance of this context is available as a member variable context within the superclass com.kivasoft.applogic.Applogic. The following code is used from within an AppLogic method:com.kivasoft.IContext kivaContext;
Example 2
From a servlet, the standard servlet context can be cast to IServerContext, and from there, a com.kivasoft.IContext instance can be obtained. The servlet code would look like this:ServletContext ctx = getServletContext();
com.iplanet.server.IServerContext sc;
// legal cast within iPlanet Application Server
sc = (com.iplanet.server.IServerContext) ctx;
com.kivasoft.IContext kivaContext = sc.getContext();
Example 3
As an alternative to Example 2, a caller can access the underlying AppLogic instance from a servlet and obtain the context there, as described in Example 1 for AppLogics. The servlet code would look like this:req2 = (HttpServletRequest2) req; // legal cast within iPlanet Application Server
AppLogic al = req2.getAppLogic();
com.kivasoft.IContext kivaContext;
Example 4
From a bean, the standard javax.ejb.SessionContext or javax.ejb.EntityContext can be cast to an IServerContext, and from there, a com.kivasoft.IContext instance can be obtained. In a bean, the code would look like this:javax.ejb.SessionContext m_ctx;
com.iplanet.server.IServerContext sc;
// legal cast within iPlanet Application Server
sc = (com.iplanet.server.IServerContext) m_ctx;
com.kivasoft.IContext kivaContext;
kivaContext = sc.getContext();
Example 5
From a Java extension, an instance of the context is supplied to the init( ) method of your extension, as shown by the following code:public int init(IObject obj) {
com.kivasoft.IContext kivaContext = (com.kivasoft.IContext) obj;
Related Topics
com.kivasoft.applogic.AppLogic class (deprecated),
com.iplanet.server.ICallerContext Interface,
com.kivasoft.IContext Interface,
com.iplanet.server.IServerContext Interface,
com.iplanet.server.servlet.extension.HttpSession2 Interface,
com.iplanet.server.servlet.extension.HttpServletRequest2 Interface
Creates an electronic mailbox object used for communicating with a user's mailbox.
Syntax
public static IMailbox CreateMailbox(
IContext context,
String pHost,
String pUser,
String pPassword,
String pUserAddr)
context. An IContext object, which provides access to iPlanet Application Server services. For information on obtaining a context, see "Examples."
pHost. Address of POP and SMTP server, such as mail.myOrg.com. If the POP and SMTP servers are running on different hosts, you must use two separate CreateMailbox( ) calls.
pUser. Name of user's POP account, such as jdoe.
pPassword. Password for POP server.
pUserAddr. Return address for outgoing mail, such as john@myOrg.com. Usually the electronic mail address of the user sending the message.
Usage
Use CreateMailbox( ) to set up a mail session for sending and receiving electronic mail messages.In the Internet electronic mail architecture, different servers are used for incoming and outgoing messages.
POP (post-office protocol) servers process incoming mail and forward messages to the recipient's mailbox.
SMTP (simple mail transport protocol) servers forward outgoing mail to the addressee's mail server.
Rules
The specified user account and password must be valid for the specified POP host name.
The user address must be valid for the specified SMTP server.
Tip
Once instantiated, use the methods in the IMailbox interface to open and close a mailbox, as well as send and receive mail messages.
Note
In a future release of iPlanet Application Server, this method may be replaced by the JavaMail( ) method.
Return Value
IMailbox object representing a mailbox, or null for failure (such as an invalid parameter).
Syntax
public static int DestroySession(
IContext context,
String pAppName
String pSessionID
ISessionIDGen pIDGen)
context. An IContext object, which provides access to iPlanet Application Server services. For information on obtaining a context, see "Examples."
pAppName. Name of the application associated with the session. The application name enables the iPlanet Application Server to determine which calling code has access to the session data.
pSessionID. The session ID to use.
pIDGen. The session ID generation object used to generate session IDs. Specify null.
Usage
To increase security and conserve system resources, use DestroySession( ) to delete a session between a user and the application when the session is no longer required. A caller typically calls DestroySession( ) when the user logs out of an application.
Tip
If the caller set a timeout value for the session when it was created, you need not delete the session explicitly with DestroySession( ). The session is deleted automatically when the timeout expires.
Return Value
GXE.SUCCESS if the method succeeds.
Related Topics
CreateSession( )
Retrieves the object for managing application events.
Syntax
public static IAppEventMgr GetAppEventMgr(
IContext context)
context. An IContext object, which provides access to iPlanet Application Server services. For information on obtaining a context, see "Examples."
Usage
Use GetAppEventMgr( ) to retrieve an IAppEventMgr object. Through the IAppEventMgr interface, you can create and manage application events. Application event objects define events that are triggered at a specified time or triggered explicitly.
Return Value
IAppEventMgr object, or null for failure.
Related Topics
IAppEventMgr Interface
Retrieves an object from the context.
Syntax
public static Object GetObject(
IContext context,
String contextName)
context. An IContext object, which provides access to iPlanet Application Server services. For information on obtaining a context, see "Examples."
contextName. The name of the object in the context. If an object with this name does not exist, null is returned.
Usage
Call GetObject( ) to retrieve a service. For example, call GetObject( ) from an application component in order to access the services of another loaded application component.
Return Value
The returned object, or null for failure.
Example
IModuleData modData=GXContext.GetObject(context,
Retrieves a session other than the current one.
Syntax
public static ISession2 GetSession(
IContext context,
int dwFlags,
String pAppName,
String pSessionID,
ISessionIDGen pIDGen)
context. An IContext object, which provides access to iPlanet Application Server services. For information on obtaining a context, see "Examples."
pAppName. Name of the application associated with the specified session ID.
pSessionID. The ID of the session you want to retrieve.
pIDGen. The session ID generation object used to generate session IDs. Specify null.
Usage
Call GetSession( ) to retrieve a session other than the current one. For example, you may want to invalidate another session based on some timeout criteria. An application can use GetSession( ) to exert greater control over session management.
Return Value
ISession2 object representing a user session, or null for failure.
Returns the number of sessions in a iPlanet Application Server cluster.
Syntax
public static int GetSessionCount(
IContext context,
int dwFlags,
String appName)
context. An IContext object, which provides access to iPlanet Application Server services. For information on obtaining a context, see "Examples."
appName. Name of the application in which sessions are being counted.
Usage
Call this method to obtain the number of existing sessions for a given application. If you want your application to limit the number of active sessions, you can call GetSessionCount( ) before creating a new session.
Return Value
The number of sessions.
Returns an existing root node of a state tree or creates a new one.
Syntax
public static IState2 GetStateTreeRoot(
IContext context,
int dwFlags,
String pName)
context. An IContext object, which provides access to iPlanet Application Server services. For information on obtaining a context, see "Examples."
dwFlags. Specify one of the following flags or zero to use the default settings.
GXSTATE.GXSTATE_LOCAL to make the node visible to the local process only.
GXSTATE.GXSTATE_CLUSTER to make the node visible within the cluster.
GXSTATE.GXSTATE_DISTRIB, the default, to make the node visible on all servers.
pName. The name of the root node. If a node with this name doesn't already exist, a new node is created.
Usage
Use GetStateTreeRoot( ) to create a state tree. A state tree is a hierarchical data storage mechanism. It is used primarily for storing application data that needs to be distributed across server processes and clusters.
Return Value
IState2 object representing the root node, or null for failure.
Example
The following code shows how to create a state tree and a child node.
Writes a message to the server log.
Syntax
Logs an event with a message, specifying the type and category of event.public static int Log(
IContext context,
int type,
int category,
String msg)
context. An IContext object, which provides access to iPlanet Application Server services. For information on obtaining a context, see "Examples."
type. Message type. Use one of the following variables:
GXLOG.GXEVENTTYPE_INFORMATION
category. User-defined message category. Do not use the range of values reserved for the iPlanet systems, which is 0 to 65535, inclusive.
Usage
Use Log( ) for displaying or storing simple messages or for debugging. The output can be directed to the console, to a text file, or to a database table. To direct output, use the iPlanet Application Server Administrator. For more information, see the Administration and Deployment Guide.
Return Value
GXE.SUCCESS if the method succeeds.
Example
Log(m_Context, GXLOG.GXEVENTTYPE_ERROR", -1,"Cannot find table: "+"Shipping");
Syntax 1
Passes in the specified valIn and valOut.public static int NewRequest(
IContext context,
String guidSTR,
IValList vIn,
IValList vOut,
int flags)
Syntax 2
Use to explicitly specify the location of AppLogic execution.public static int NewRequest(
IContext context,
String guidSTR,
IObject vIn,
IObject vOut,
int host,
int port)
Syntax 3
Use to explicitly specify the location of AppLogic execution.public static int NewRequest(
IContext context,
String guidSTR,
IObject vIn,
IObject vOut,
int host,
int port,
int flags)
context. An IContext object, which provides access to iPlanet Application Server services. For information on obtaining a context, see "Examples."
guidSTR . String GUID or name of the AppLogic to execute.
vIn. IValList object containing input parameters to pass to the called AppLogic.
vOut. IValList object containing result values of the called AppLogic.
host. IP address of the Internet host of the iPlanet Application Server where the AppLogic is to be executed. Specify 0 to execute the AppLogic locally.
port. Internet port of the iPlanet Application Server where the AppLogic is to be executed. Specify 0 to execute the AppLogic locally.
Usage
Use NewRequest( ) to call an AppLogic. When you call NewRequest( ), the caller passes to iPlanet Application Server the GUID or name of the AppLogic to execute and, optionally, any input and output parameters.iPlanet Application Server constructs a request using the parameters specified. iPlanet Application Server then processes the request like any other request, by instantiating the AppLogic and passing in its parameters. The results from the called AppLogic module are returned to the caller.
The AppLogic that NewRequest( ) invokes can do one of the following tasks:
Process application logic and return result values in the vOut parameter.
If the called AppLogic uses evalOutput( ) to stream results, evalOutput( ) returns HTML results by default. The caller can, however, specify that evalOutput( ) return a non-HTML data stream by setting the gx_client_type key to "ocl" in the input IValList of NewRequest( ). For example:Process application logic and return the resulting data form (such as a report) by streaming the output or by calling result( ).
Process application logic and return result values in the vOut parameter as well as return the resulting data form (such as a report) by streaming the output or by calling result( ).
vallist.setValString("gx_client_type", "ocl");
Rule
The specified GUID string, input parameters, and output parameters must be valid for the specified AppLogic.The calling code can create new input and output IValLists so as to avoid changing its own input and output IValLists.
Use NewRequestAsync( ) instead of NewRequest( ) to execute an asynchronous request.
Called AppLogics might reside on different servers, depending on partitioning and load balancing configurations, might be written in a different language, or might have cached results. The calling code can be unaware or independent of these conditions.
Using NewRequest( ), you can modularize parts of the application, build dynamic header/footer information and smart reporting templates, and hide complex or confidential business logic in secure submodules or even separate servers.
Use NewRequest( ) judiciously. Each invoked AppLogic uses a certain amount of communications and server resources.
Return Value
GXE.SUCCESS if the method succeeds.
Example 1
Calls another AppLogic and runs it asynchronously.
Syntax 1
Passes in the specified valIn and valOut.public static IOrder NewRequestAsync(
IContext context,
String guidSTR,
IValList vIn,
IValList vOut,
int flags)
Syntax 2
Use to explicitly specify the location of AppLogic execution.public static IOrder NewRequestAsync(
IContext context,
String guidSTR,
IObject vIn,
IObject vOut,
int host,
int port)
Syntax 3
Use to explicitly specify the location of AppLogic execution.public static IOrder NewRequestAsync(
IContext context,
String guidSTR,
IObject vIn,
IObject vOut,
int host,
int port,
int flags)
context. An IContext object, which provides access to iPlanet Application Server services. For information on obtaining a context, see "Examples."
guidSTR . String GUID or name of the AppLogic to execute.
vIn. IValList object containing input parameters to pass to the called AppLogic.
vOut. IValList object containing result values of the called AppLogic.
host. IP address of the Internet host of the iPlanet Application Server where the AppLogic is to be executed. Specify 0 to execute the AppLogic locally.
port. Internet port of the iPlanet Application Server where the AppLogic is to be executed. Specify 0 to execute the AppLogic locally.
Usage
Use NewRequestAsync( ) to call another AppLogic and run it asynchronously. Executing an AppLogic asynchronously is useful if the AppLogic performs a lengthy operation, or if the AppLogic acts as a monitor or remains persistent. For example, an asynchronous AppLogic may perform a lengthy database query to produce a complex result set that it e-mails to a destination address. Another AppLogic module may run continuously and re-index HTML pages every 24 hours.When NewRequestAsync( ) is called, the caller passes to iPlanet Application Server the GUID of the AppLogic module to execute and, optionally, any input and output parameters.
The iPlanet Application Server constructs a request using the parameters specified and processes it like any other request, by instantiating the AppLogic and passing in its parameters. The results from the called AppLogic module are returned to the calling code.
The AppLogic that NewRequestAsync( ) invokes can do one of the following tasks:
Process application logic and return result values in the vOut parameter.
Process application logic and return the resulting data form (such as a report) by streaming the output or by calling result( ).
Process application logic and return result values in the vOut parameter as well as return the resulting data form (such as a report) by streaming the output or by calling result( ).
Rules
The specified AppLogic must be accessible to the iPlanet Application Server.
The specified GUID string, input parameters, and output parameters must be valid for the specified AppLogic module.
Tips
To get the current status of the request, use the getState( ) method in the returned IOrder object.
The calling code can use GX.WaitForOrder( ) to wait for multiple asynchronous requests to return.
Using NewRequestAsync( ), you can modularize parts of the application, build dynamic header/footer information and smart reporting templates, and hide complex or confidential business logic in secure submodules or even separate servers.
Use NewRequestAsync( ) judiciously. Each invoked AppLogic uses a certain amount of communications and server resources.
Return Value
IOrder object, or null for failure.
GXVAL is deprecated and is provided for backward compatibility only. New Java applications should use the standard servlet-JSP programming model.
For information about replacing GXVAL functionality in existing applications, see the Migration Guide.
The GXVAL class represents a single value of a particular data type. Parameters that are passed to an AppLogic, or results that are retrieved from an AppLogic, are contained in an IValList object that contains one or more GXVAL objects.
Typically, you do not need to use the GXVAL class directly. Generally, you use the getVal***( ) and setVal***( ) suite of methods in the IValList interface to access values in an IValList object. Using the getVal***( ) and setVal***( ) methods in IValList, you can access values of type integer, string, and BLOB in an IValList object. To access more types, such as float or double, use the GXVAL class.
The following example shows how you create a GXVAL object of type double:
To create a GXVAL object of a different type, change the GXVALTYPE_ENUM value and the accessor method.
The following table lists the accessor methods and corresponding GXVAL types.
MemRowSet is a subclass of DBRowSet that implements the IListRowSet interface. MemRowSet provides hooks to the in-memory TemplateDataBasic class of iPlanet Application Server. Specifically, MemRowSet wraps the TemplateDataBasic class, adding support for callback methods. For example, a tag such as the following:
<gx type=cell id=Jack.callMe(Boisenberry)>
would call the method callMe( ) on the rowset named Jack.
Although anyone developing a iPlanet Application Server application can use MemRowSet, this class is typically used in components generated by iPlanet Application Builder.
MemRowSet replaces the DataSet class from iAB 6.0.
Package
com.iplanet.server.servlet.extension
Constructor
The MemRowSet class has two constructors. The first one, the null constructor, is required:public MemRowSet() throws SQLException
The second one is a convenience constructor:
public MemRowSet(
HttpServletRequest request,
HttpServletResponse response,
String name,
ITemplateData dataSource) throws SQLExceptionIn addition to the request and response objects, the dataSource parameter is the ITemplateData object to use to store data. The name parameter is the MemRowSet name and must correspond with the dataSource's groupName.
Both constructors throw SQLException if it occurs.
Methods
MemRowSet has dozens of methods. Most of them override a corresponding method from one of the following sources:
iASRowSet class, from package com.iplanet.server.jdbc.
The MemRowSet methods are overridden to prevent undesirable behavior. In most cases, a developer should not call the overridden methods, because calling them has no meaning. You might unintentionally call one of these methods on a RowSet object if the RowSet is implemented by MemRowSet, which does not represent a query.DBRowSet class, from package com.iplanet.server.servlet.extension.
The methods of MemRowSet are listed in the following table. For methods that override a correspondingly named method, only a summary is provided. For new methods of MemRowSet, additional description is also provided after the table. New methods are marked in boldface type.
Adds a new item into a MemRowSet that is being used as an IListRowSet.
Syntax
public void addListItem(
String label,
String value)
label. The name of the item as it appears in the list.
value. The value assigned to the label.
Usage
When working with an IListRowSet, use addListItem( ) with setListSelection( ) to create a selection list or a group of radio buttons.
Example
The following code fragment creates a data set as a list:
To display this list on a web page, you might create an HTML template containing the following code:
Related Topics
setListSelection( )
Adds data as a separate row into the data source.
Usage
Use addRow( ) to add a new row to a data set. The values of the row must have been previously added using addValue( ); otherwise, no row is added.
The previous code, along with an HTML template containing the following:
<gx type=cell id=tryMe.col1></gx> <gx type=cell id=tryMe.col2><%gx>
Return Value
Unused. Always 0.
Related Topics
addValue( ), addListItem( )
Queues a value for later addition into the data source.
Syntax
public int addValue(
String name,
String value)
name. The column name of the value.
value. The value to add to the data source.
Usage
In-memory data sources start out without any data. Use a series of addValue( ) and addRow( ) calls to populate a data source with values.Note that data is not actually added to the data source until addRow() is called.
Example
See addRow( ) for an example.
Return Value
Unused. Always 0.
Gets the list selection of the MemRowSet that is being used as an IListRowSet.
Syntax
public String getListSelection(
String value)
value. The value to add to the data source.
Usage
Use getListSelection( ) to obtain the list selection previously set by a call to setListSelection( ).
Return Value
A String representing the list selection.
Related Topics
setListSelection( )
Gets the data source of the RowSet.
Syntax
public ITemplateData getTemplateData()
Usage
Use getTemplateData( ) to obtain the ITemplateData that serves as the data source of the RowSet. This ITemplateData object was created in either of two ways:
Return Value
An ITemplateData representing the data source.
Related Topics
setTemplateData( )
Sets the list selection on the MemRowSet that is being used as an IListRowSet.
Syntax
public void setListSelection(
String value)
value. The value to be set for the list selection.
Usage
When working with an IListRowSet, use addListItem( ) with setListSelection( ) to create a selection list or a group of radio buttons. Use getListSelection( ) to obtain the list selection previously set by a call to setListSelection( ).
Example
See addListItem( ) for an example.
Related Topics
addListItem( ), getListSelection( )
Sets the data source to the provided TemplateDataBasic.
Creates an ITemplateData object on a data set.
Syntax
public void setTemplateData(
ITemplateData td)
td. The name of the ITemplateData object to create.
Usage
After you call setTemplateData( ) with a specified ITemplateData object, data requests such as calls to getString( ) and next( ) will be routed through the passed-in ITemplateData. Therefore, if you already have an ITemplateData (for example, from an extension), you can wrap a data set around it by creating a MemRowSet and calling setTemplateData( ) on the MemRowSet to pass in the ITemplateData.Furthermore, if the ITemplateData is also a TemplateDataBasic, then calls to addRow( ) and setHint( ) will succeed. However, if the ITemplateData is not a TemplateDataBasic, calls to add a row or set the hint will fail, returning a value of -1.
Related Topics
getTemplateData( )
A RowSet is an object that encapsulates a set of rows retrieved from a database or other tabular data store, such as a spreadsheet. To implement a RowSet, your code must import javax.sql, and implement the RowSet interface. RowSet extends the java.sql.ResultSet interface, permitting it to act as a JavaBeans component.
Because a RowSet is a JavaBean, you can implement events and event listeners for the RowSet, and you can set properties on the RowSet. Furthermore, because RowSet is an extension of ResultSet, you can iterate through a RowSet just as you would iterate through a result set.
You fill a RowSet by calling the RowSet.execute( ) method. The execute( ) method uses property values to determine the data source and retrieve data. The properties you decide to set and examine depend on the implementation of RowSet you invoke.
Package
com.iplanetiplanet.server.jdbc
Constructors
In a iPlanet Application Server application, you can create a RowSet in either of two ways:
You can create iPlanet Application Server-dependent code by calling new on the iASRowSet class:
iASRowSet rs = new iASRowSet();
You can create iPlanet Application Server-independent code. To do so, call new on the InitialContext class. Then, using this InitialContext, look up the class that implements the RowSet interface:
InitialContext ctx = new InitialContext();
RowSet rs = (javax.sql.RowSet) ctx.lookup("javax.sql.RowSet");
- The ctx.lookup( ) call returns an instance of the class that is bound to the implementation of javax.sql.RowSet. In this case, the class that is bound is iASRowSet.
Methods
This section provides details about what iASRowSet implements.iASRowSet is a class that extends ResultSet, so the iASRowSet methods are inherited from the ResultSet object.
In addition, iASRowSet does the following:
implements, in whole or in part, these four standard interfaces:
implements many methods available in CachedRowSet, a class provided by Sun.
implements loadQuery( ), a method of the SqlUtil class in the com.kivasoft.util package.
RowSet interface
The RowSet interface is fully supported except as noted in the following table:
RowSetReader interface
iASRowSet provides a full implementation of the RowSetReader interface. As an alternative to one of the RowSetReader methods, you can use the setReaderMethod( ) from the CachedRowSet class. The argument of setReaderMethod( ) must nonetheless implement the RowSetReader interface.
RowSetWriter interface
Although iASRowSet is read-only, it implements the RowSetWriter interface for future use. The only method of RowSetWriter, writeData( ), throws SQLException when called, indicating that this method is not supported.
RowSetInternal interface
This internal interface is called by a method of the RowSetReader interface to retrieve information about the RowSet. RowSetInternal has a single method, getOriginalRow( ), which returns the entire result set instead of a single row.
CachedRowSet class
Sun provides a rowset class named CachedRowSet, which is an implementation of the RowSet interface. CachedRowSet lets you retrieve data from a data source, then detach from the data source while you examine (and modify) the data. A cached rowset keeps track of not only the original data retrieved, but also any data changes your application made. If the application trys to update the original data source, the rowset is reconnected to the data source, and only those rows that have changed are merged back into the database.iASRowSet implements many of the methods in the CachedRowSet class because they're useful. However, iASRowSet does not implement all the methods. Unimplemented methods throw SQLException if called. The following CachedRowSet methods throw SQLException because iASRowSet is read-only:
acceptChanges( )
The toCollection( ) method throws SQLException because collections are a JDK 1.2 feature.
SqlUtil class
The SqlUtil class is part of the iPlanet Application Server Foundation Class Library. This class contains loadQuery( ), a method that supports rowsets. The loadQuery( ) method can be used on the RowSet interface in place of the setCommand( ) method.import com.kivasoft.util.SqlUtil;
SqlUtil.loadQuery(rowset, pathname, queryname, params);
This version of loadQuery( ) reads the queryname from the file specified by pathname. The method then replaces parameters according to params (an IValList object) and sets the query command as the RowSet query command.
Related Topics
RowSet, RowSetInternal, RowSetReader, or RowSetWriter interfaces in the javax.sql package,
java.sql.ResultSet interface,
com.kivasoft.util.SqlUtil class
The iASString class shadows the java.lang.String class.
Strings are constant. However, iASStrings are not. Their value can be changed, and they provide a simple method to change which part of a String to operate on. In this way, you can section off parts of a String without the overhead of creating a new String. In addition, iASString conforms to the method signatures provided for the String class.
Although anyone developing a iPlanet Application Server application can use iASString, this class is typically used in components generated by iPlanet Application Builder.
Package
com.iplanet.server.servlet.extension
Constructors
The following constructors are available:
Methods
iASString and String are almost identical. Every instance method on java.lang.String has a corresponding, functionally identical method on iASString. Every instance method on String that takes a String as a parameter is overloaded in iASString to take a String or a iASString.The following additional methods are in iASString but not in String.
Resets the value of this iASString to shadow the specified String.
Compares this iASString to the specified parameter.
Syntax 1
public boolean equals(
Object anObject)
Syntax 2
public boolean equals(
String val)
Syntax 3
public boolean equals(
iASString string)
Usage
The equals( ) method compares this iASString to the specified parameter, either an Object, a String, or an iASString.This method returns true if the parameter is not null and if it meets the following conditions:
When specified as an Object (Syntax 1), the parameter must be either:
The equals( ) method allows the compiler to bind to this method when the class of the object is known. This binding allows for removal of the code to check the class of the incoming object.
a String object that represents the same sequence of characters as this object
When specified as String (Syntax 2), the parameter must be a String object that represents the same sequence of characters as this objectan iASString that shadows a substring of a String representing the same sequence of characters as this object
When specified as an iASString (Syntax 3), the parameter must be an iASString that shadows a substring of a String representing the same sequence of characters as this object
Return Value
Returns true if the previous conditions are met; otherwise, returns false.
Modifies this iASString to point to a substring of shadow.
Syntax
public void makeSubstring(
int beginIndex)
Syntax
public void makeSubstring(
int beginIndex,
int endIndex)
beginIndex. The beginning index. If the iASString is already pointing at a substring, then this index can be negative, indicating that the beginning of the substring will occur earlier. If beginIndex is out of range, this method throws StringIndexOutOfBoundsException.
endIndex. The ending index, excluding itself.
Usage
Use makeSubstring( ) to modify this iASString to point at a substring of shadow. The substring begins at the specified index, which is the offset from the current substring being shadowed by the iASString.If no endIndex is specified, the substring extends to the end of the currently shadowed substring. If endIndex is specified, the substring extends to the character located at endIndex - 1 of the newly shadowed substring.
Resets the value of this iASString to shadow the specified String.
Syntax
public void setValue(
String val)
Usage
Use setValue( ) to reset the value of this iASString to shadow the specified String.
iASStringBuffer is a subclass of Object that resembles the java.lang.StringBuffer class (an object that manages a mutable string). Unlike java.lang.StringBuffer, none of iASStringBuffer's methods are synchronized, so performance is significantly increased.
iASStringBuffer also has additional methods that allow it to be more easily modified than the standard StringBuffer. Unfortunately, it is slower than StringBuffer when converting to a string.
Although anyone developing a iPlanet Application Server application can use iASStringBuffer, this class is typically used in components generated by iPlanet Application Builder.
iASStringBuffer replaces the FastStringBuffer class from iAB 6.0.
Package
com.iplanet.server.servlet.extension
Constructors
The following constructors are available:
Appends a character or string to the iASStringBuffer.
Syntax 1
public void append(
char aChar)
Syntax 2
public void append(
char str[])
Syntax 3
public void append(
String aString)
Syntax 4
public void append(
char str[],
int offset,
int length)
aChar. The character to append.
aString. The string to append.
str. The characters to append.
offset. The index of the first character to append. If the offset is invalid, this method throws StringIndexOutOfBoundsException
length. The number of characters to append.
Usage
The first three forms of append( ) let you append a character or a string to the iASStringBuffer. In the last form of this method, characters in the specified character array, str, are appended in order, starting at the specified offset. The length of the iASStringBuffer increases by the specified length.This method returns the modified iASStringBuffer.
Returns the iASStringBuffer's character array.
Syntax
public char[] charArray()
Usage
Use this method whenever you need to access the character array. However, do not modify this array yourself.For example, suppose you want to draw the contents of the iASStringBuffer. You can do this by passing the array to the graphic's drawString( ) method that takes a character array, rather than converting the StringBuffer to a String.
Tip
You may want to call trimToSize() first; otherwise, some characters in the array will be out of the "valid" range for the StringBuffer.
Returns the character at the specified index.
Syntax
public char charAt(
int index)
index. The position of the character.
Usage
If the index is invalid, this method throws StringIndexOutOfBoundsException.
Makes sure that the StringBuffer has enough space to contain "newCapacity" characters.
Syntax
public void ensureCapacity(
int newCapacity)
Compares the contents of this iASStringBuffer with the contents of another iASStringBuffer.
Syntax
public boolean equals(
iASStringBuffer value)
Usage
Specify a value to compare.
Copies characters from the iASStringBuffer to the specified destination array.
Syntax
public void getChars(
int srcBegin,
int srcEnd,
char dst[],
int dstBegin)
srcBegin. The offset in the source iASStringBuffer at which copying begins.
srcEnd. The offset in the source iASStringBuffer at which copying ends.
dst. The destination array, to which data is copied.
dstBegin. The offset at which copying into the destination array begins.
Usage
Use getChars( ) to copy characters to an array. The first character to be copied is at the index srcBegin, and the last character to be copied is at srcEnd - 1. The total number of characters to be copied is srcEnd - srcBegin.These characters are copied into a subarray of the specified destination array, dst. This subarray begins at the index dstBegin and ends at the following index:
dstBegin + (srcEnd - srcBegin) - 1
If any index is invalid, this method throws StringIndexOutOfBoundsException.
Returns the index of the first occurrence of the specified character in the iASStringBuffer.
Syntax 1
public int indexOf(
char aChar,
int offset)
Syntax 2
public int indexOf(
char aChar
aChar. The character whose position you are looking for.
offset. The starting position for searching in the iASStringBuffer.
Usage
You can use indexOf( ) in two forms. The first form starts at the specified offset in iASStringBuffer and returns the index of the specified character's first occurrence. If the offset is invalid, this method throws StringIndexOutOfBoundsException.The second form is similar, except that is starts at the beginning of the iASStringBuffer and is equivalent to the following code:
Inserts a character or string into the iASStringBuffer.
Syntax 1
public void insert(
int index,
char aChar)
Syntax 2
public void insert(
int index,
String aString)
Syntax 3
public void insert(
int offset,
char str[])
index. The position in the iASStringBuffer.
aChar. The character to insert.
aString. The string to insert.
offset. The starting position for searching in the iASStringBuffer.
str. The character array to insert.
Usage
The first two forms of the insert( ) method insert either a character or a string at the specified index.If the index equals or exceeds the number of characters in the buffer, then this method appends the item. If the index is invalid, this method throws StringIndexOutOfBoundsException.
In the last form of this method, characters in the specified character array, str, are appended in order, starting at the specified offset. The length of the iASStringBuffer increases by the length of the argument.
This method returns the modified iASStringBuffer.
Returns the number of characters in the iASStringBuffer.
Moves the tail of the string, by removing characters.
Syntax
public void moveChars(
int fromIndex,
int toIndex)
fromIndex. Position of the first character to move. The affected characters range from this position to the end of the iASStringBuffer.
toIndex. Position to move the affected characters.
Usage
If characters are moved to an index within the existing string, the previous characters are overwritten by the move.
Removes the character at the specified index.
Syntax
public void removeCharAt(
int index)
index. The index of the character to remove.
Usage
If the index is invalid, this method throws StringIndexOutOfBoundsException.
Replaces the given range with a string, or removes the given range.
Syntax
public void replace(
int begin,
int end,
String value)
begin. The index of the beginning of the range.
end. The index of the end of the range.
value. The string that replaces the range. If null, the range is removed.
Usage
Use replace( ) to remove or replace characters in a iASStringBuffer. If either of the range indexes is invalid, this method throws StringIndexOutOfBoundsException.
Sets the value of a character at the specified index.
Syntax
public void setCharAt(
int index,
char ch)
index. The position of the character to set.
ch. The value to set the character to.
Usage
If the index is invalid, this method throws StringIndexOutOfBoundsException.
Truncates the iASStringBuffer to the specified number of characters.
Syntax
public void setLength(
int length)
length. Number of characters to remain in the truncated iASStringBuffer. If the specified length is invalid, this method does nothing.
Sets the contents of the iASStringBuffer to the characters in the specified string.
Syntax
public void setStringValue(
String aString)
aString. The string to use as the new contents of iASStringBuffer.
Determines whether a tab or space exists at the specified index.
Syntax
public boolean tabOrSpaceAt(
int index)
index. The position in the iASStringBuffer.
Usage
The tabOrSpaceAt( ) method returns true if the specified index contains a tab or a space; otherwise, this method returns false. If the index is invalid, this method throws StringIndexOutOfBoundsException.
Returns the String for the iASStringBuffer's contents.
Syntax
public String toString()
Usage
This method overrides toString( ) in the Object class.
Truncates the internal character array to match the size of the contained string.
Syntax
public void trimToSize()
Usage
Use trimToSize( ) when more space than necessary is allocated to the iASStringBuffer, and you want to free this space for other uses.
Same as the trimToSize( ) method.
Syntax
public void truncateToLength(
int aLength)
The Session2 class is deprecated and is provided for backward compatibility only. New applications should use the methods provided by the standard javax.servlet.http.HttpSession interface. In addition, iPlanet Application Server provides the HttpSession2 interface, an extension to HttpSession that supports applications that must call AppLogics.
The Session2 GXSession2 class is designed to help you implement a custom session class if your application requires additional session functionality. To create a custom session class, subclass the Session2 GXSession2 class, then define new methods. Your subclass can, for example, define accessor methods to read and write information specific to your session. An online shopping application, for example, might require specialized methods, such as AddItemToCart( ), to track shopping items per user session.
When you subclass the Session2GXSession2 class, you must do the following:
Override the createSession( )CreateSession( ) and getSession( )GetSession( ) methods in the AppLogicGXAppLogic class. In these methods, you can invoke the base AppLogicGXAppLogic methods to obtain an ISession2IGXSession2 object, and construct your own session class by passing in this object, as shown in the following example:
Because the Session2GXSession2 class delegates the implementation of methods in the ISession2IGXSession2 interface to the object passed to its constructor, you don't have to implement every method of that interface in your subclass. You need only define the methods you want to add.
ISession2 s = super.createSession(flags, timeout, appname, sessionid, idgen); if (s!= null) sess = new MySession(s); return s; Pass in the ISession2IGXSession2 interface in the subclass constructor, as shown in the following example:
public class MySession extends Session2
public MySession(ISession2 sess)
Package Include File
com.kivasoft.session gxapplogic.h
Related Topics
ISession2 Interface (deprecated)IGXSession2 interface"Using Custom Sessions" in Chapter 8, "Managing Session and State Information" in Programmer's Guide.
The SqlUtil class contains helper methods for two main purposes:
to load queries from query files (.gxq files)
At present, this class contains only one helper method, loadQuery( ). This method has six syntax variants.Although anyone developing a iPlanet Application Server application can use SqlUtil, this class is typically used in components generated by iPlanet Application Builder.
Lower end set of characters that are considered part of a variable name, in addition to a-zA-Z0-9.
Upper end set of characters that are considered part of a variable name, in addition to a-zA-Z0-9.
Constructor
SqlUtil extends the Object class and should never be instantiated. The SqlUtil constructor is as follows:
Examples
Example 1
The following code shows how you might use a SELECT query:
Example 2
The following code shows how you might use an UPDATE query:
Related Topics
com.iplanet.server.jdbc.iAS6.0RowSet class,
java.sql.Connection interface,
java.sql.PreparedStatement interface,
javax.sql.RowSet interface
Syntax 1
Use any of the following three variants to initialize a RowSet, given a SELECT query.static public boolean loadQuery(
RowSet rs,
String filepath,
String queryname,
IValList params)
Syntax 2
static public boolean loadQuery(
RowSet rs,
String query,
IValList params)
Syntax 3
static public boolean loadQuery(
RowSet rs,
Reader r,
String queryname,
IValList params)
Syntax 4
Use any of the following three variants to generate a PreparedStatement, given an INSERT, UPDATE, or DELETE query.static public PreparedStatement loadQuery(
Connection conn,
String filepath,
String queryname,
IValList params)
Syntax 5
static public PreparedStatement loadQuery(
Connection conn,
String query,
IValList params)
Syntax 6
static public PreparedStatement loadQuery(
Connection conn,
Reader r,
String queryname,
IValList params)
rs. Specifies the rowset on which the query will act. The rowset handed in must have its Connection initialized; otherwise the loadQuery( ) call will fail.
filepath. The full pathname of the query file (.gxq file).
queryname. For Syntax 3 (using a RowSet), the name of the SELECT query in the query file. For Syntax 6 (using a Connection), the name of the INSERT, UPDATE, or DELETE query in the query file.
query. For Syntax 2 (using a RowSet), the SELECT query. For Syntax 5 (using a Connection), the INSERT, UPDATE, or DELETE query.
params. A list of parameter-value pairs that will be permanently replaced in the SELECT query.
r. A reader that points to the contents of a query file (.gxq file).
conn. Connection information needed to generate a PreparedStatement.
Usage
Use loadQuery( ) either to initialize a RowSet given a SELECT query, or to generate a PreparedStatement given an INSERT, UPDATE, or DELETE query. This method performs the following:
removes comments of the form /* (slash-asterisk).
replaces any parameters it finds in the SQL statement with values that match the passed-in parameter list.
replaces parameters it finds in the SQL statement with ? (question mark) for values it cannot find in the parameter list.
converts SQL statements to database-specific SQL for constructs such as left joins, right joins, or outer joins.
Return Value
The boolean syntax returns true if no errors were encountered or returns false for failure. The PreparedStatement syntax has the following return values: if no errors are encountered, loadQuery( ) returns the PreparedStatement object that references the query; otherwise, the method returns null for failure.
TemplateDataBasic class (deprecated)
TemplateDataBasic is deprecated and is provided for backward compatibility only. New Java applications should use the standard servlet-JSP programming model, where similar functionality is provided through interfaces such as java.sql.ResultSet and javax.sql.RowSet.
For information about replacing TemplateDataBasic functionality in existing applications, see the Migration Guide.
The TemplateDataBasicGXTemplateDataBasic class represents a memory-based, hierarchical source of data used for HTML template processing. It implements the ITemplateData Interface (deprecated)IGXTemplateData interface, and provides methods for creating and managing this hierarchical data.
The most common sources of data used for template processing are result sets obtained from queries on supported relational database management systems. However, an AppLogic might need to obtain data from non-RDBMS sources. For example, an AppLogic might display a list of numbers generated from a formula, or it might display a list of processors available on the server machine and their CPU loads. To display such information, the AppLogic can create an instance of the TemplateDataBasicGXTemplateDataBasic class, populate that instance with rows of hierarchical data, and then pass the TemplateDataBasicGXTemplateDataBasic object to the Template Engine for processing by calling evalTemplate( )EvalTemplate( ) or evalOutput( )EvalOutput( ) in the AppLogic class (deprecated)GXAppLogic class.
Alternatively, to provide application-specific special processing and to hook into the template generation process, AppLogic can subclass the TemplateDataBasicGXTemplateDataBasic class and override the member methods in the ITemplateData Interface (deprecated)IGXTemplateData interface.
An AppLogic can create a flat or hierarchical data structure.
For a flat data structure, create the data structure using TemplateDataBasic( )GXTemplateDataBasic( ), then call rowAppend( )RowAppend( ) for each row of data to be added, specifying the column name and data in each row.
The number of nesting levels is limited only by system resources. One parent row can contain many joined child instances, in which case the AppLogic calls the parent's groupAppend( )GroupAppend( ) more than once after calling the parent's rowAppend( )RowAppend( ).For a hierarchical data structure, proceed in the following sequence:
Create the parent TemplateDataBasic( )GXTemplateDataBasic( ) instance.
Create the child TemplateDataBasic( )GXTemplateDataBasic( ) instance.
Add one or more rows to the child data structure using rowAppend( )RowAppend( ) on the child instance.
Define the start of a new parent row by using rowAppend( )RowAppend( ) on the parent instance.
Join the child data structure to the parent data structure using the parent's groupAppend( )GroupAppend( ).
Repeat steps 2 through 5 for each subsequent group of data.
To create a template data source, use the GX.CreateTemplateDataBasic( ) method, as shown in the following example:
TemplateDataBasic data = GX.CreateTemplateDataBasic("data");
Package Include File
com.kivasoft.applogicgxtmplbasic.h
Links the specified child group to the current parent group.
Appends a new row of data to the current template data object or group.
Creates an empty template data object with the specified name.
Implements
ITemplateData Interface (deprecated)IGXTemplateData interface
Related Topics
evalTemplate( )EvalTemplate( ) and evalOutput( )EvalOutput( ) in the AppLogic class (deprecated)GXAppLogic classITemplateData Interface (deprecated)IGXTemplateData interface
"Constructing a Hierarchical Result Set with GXTemplateDataBasic" in Chapter 7, "Working with Templates" in Programmer's Guide.
Links the specified child group to the current parent group.
Syntax
public int groupAppend(
TemplateDataBasic childName)HRESULT GroupAppend(
GXTemplateDataBasic *pChild);
childName pChild. Name of Pointer to the child TemplateDataBasicGXTemplateDataBasic object to link. When AppLogic is finished using the object, call the Release( ) method to release the interface instance.
Usage
Use groupAppend( )GroupAppend( ) to define the hierarchical relationship from a parent row to child TemplateDataBasicGXTemplateDataBasic objects.Call groupAppend( )GroupAppend( ) only after calling rowAppend( )RowAppend( ). The child instance is associated with the last row from the last call to rowAppend( )RowAppend( ) on the parent.
The AppLogic must first create the parent and child objects using new TemplateDataBasic( )GXTemplateDataBasic( ), then populate the child object with rows of data using rowAppend( )RowAppend( ).
Tip
Use groupAppend( )GroupAppend( ) for hierarchical data objects only.
Return Value
GXE.SUCCESS if the method succeeds.HRESULT, which is set to GXE_SUCCESS if the method succeeds.
Related Topics
evalTemplate( )EvalTemplate( ) and evalOutput( )EvalOutput( ) in the AppLogic class (deprecated)GXAppLogic classITemplateData Interface (deprecated)IGXTemplateData interface
"Constructing a Hierarchical Result Set with GXTemplateDataBasic" in Chapter 7, "Working with Templates" in Programmer's Guide.
Appends a new row of data to the current template data object or group.
Syntax
public int rowAppend(
String rowString)HRESULT RowAppend(
LPSTR szRow);
rowString szRow. String containing a series of column name and value pairs, separated by semi-colons, using the following format:
"column1=value1[;column2=value2[...]]"
The columns must be identical for each rowAppend( )RowAppend( ) call within the same TemplateDataBasicGXTemplateDataBasic object.
Usage
Use rowAppend( )RowAppend( ) to populate the template data object with rows of data.
Rule
AppLogic must first create the template data object using TemplateDataBasic( )GXTemplateDataBasic( ).
Tip
Add rows in the sequence in which you want the Template Engine to process them. The template data object is processed in physical order only. AppLogic can only append rows to the data object. It cannot subsequently insert, delete, or sort records in the template data object.
Return Value
GXE.SUCCESS if the method succeeds.HRESULT, which is set to GXE_SUCCESS if the method succeeds.
Related Topics
evalTemplate( )EvalTemplate( ) and evalOutput( )EvalOutput( ) in the AppLogic class (deprecated)GXAppLogic classITemplateData Interface (deprecated)IGXTemplateData interface
"Constructing a Hierarchical Result Set with GXTemplateDataBasic" in Chapter 7, "Working with Templates" in Programmer's Guide.
Creates an empty template data object with the specified name.
Syntax
public TemplateDataBasic(
String dataObjectName)HRESULT GXTemplateDataBasic(
LPSTR pName);
dataObjectName pName. Name of the parent or child data object referred to in the template.
Usage
Use new TemplateDataBasic( )GXTemplateDataBasic( ) to create parent and child data objects.
Rule
The specified data object name must be unique within this template data object.Use rowAppend( )RowAppend( ) to populate this data object with rows of data.
For hierarchical template data objects, use groupAppend( )GroupAppend( ) to define the hierarchy among TemplateDataBasicGXTemplateDataBasic objects.
The specified data object name must be unique within the hierarchical result set.
Create parent and child groups in the sequence in which you want the Template Engine to process them. The template data object is processed in physical order only.
Return Value
An empty TemplateDataBasic object, or null for failure.HRESULT, which is set to GXE_SUCCESS if the method succeeds.
Related Topics
evalTemplate( )EvalTemplate( ) and evalOutput( )EvalOutput( ) in the AppLogic class (deprecated)GXAppLogic classITemplateData Interface (deprecated)IGXTemplateData interface
"Constructing a Hierarchical Result Set with GXTemplateDataBasic" in Chapter 7, "Working with Templates" in Programmer's Guide.
TemplateMapBasic class (deprecated)
TemplateMapBasic is deprecated and is provided for backward compatibility only. New Java applications should use the standard servlet-JSP programming model.
For information about replacing TemplateMapBasic functionality in existing applications, see the Migration Guide.
The TemplateMapBasic classGXTemplateMapBasic class represents an object that contains one or more mappings between fields in an HTML template and the data used to replace those fields. It provides a method for defining these mappings before processing the template using evalTemplate( )EvalTemplate( ) or evalOutput( )EvalOutput( ) in the AppLogic class (deprecated)GXAppLogic class.
Fields in the HTML template are defined using special GX markup tags. The data, which the Template Engine uses to replace those fields dynamically at runtime, can come from any of the following sources: a calculated value, a column in a result set, a field in an ITemplateData IGXTemplateData template data object, or a field from a map object.
Before calling evalTemplate( )EvalTemplate( ) or evalOutput( )EvalOutput( ) in the AppLogic classGXAppLogic class, an AppLogic uses the put( )Put( ) or putString( ) method in the TemplateMapBasicGXTemplateMapBasic class to link the field name in the GX markup tag with a precomputed value or a named column or field in the data source. After defining the mappings, the AppLogic passes the populated ITemplateMapBasic IGXTemplateMapBasic object as the mapmap parameter in evalTemplate( )EvalTemplate( ) or evalOutput( )EvalOutput( ). The Template Engine uses these mappings during template processing to dynamically transfer data values from the data source to the HTML output report.
Mapping allows the AppLogic to use the same template for multiple data sources with different column names, for a data source whose schema changes over time, or for memory-based data sources defined using a TemplateDataBasic TemplateDataBasic object.
To create a template map, use the GXCreateTemplateMapBasic( ) method, as shown in the following example:
TemplateMapBasic map = GX.CreateTemplateMapBasic();
While it is not necessary, you may derive a class from GXTemplateMapBasic, by writing a class declaration such as the following:
class MyTemplateMapBasic : public TemplateMapBasic
To provide application-specific special processing, the AppLogic can subclass TemplateMapBasic GXTemplateMapBasic and override its getString( )Get( ) method in the IGXTemplateMap interface to hook into the Template Engine generation process. For example, AppLogic can intercept and filter data from a database before the Template Engine processes it.
Package Include File
com.kivasoft.applogicgxtmplbasic.h
Resolves the id attribute specified in a GX markup tag in the template being processed by the Template Engine. This method is called by the get( ) method in the ITemplateMap interface.
Maps the value assigned to the id attribute in the HTML template to another value. This method takes an IBuffer object (that contains a string expression) for the replacement value argument.
Maps the value assigned to the id attribute in the HTML template to another value. This method takes a string argument for the replacement value.
Implements
ITemplateMap Interface (deprecated) IGXTemplateMap interface
Example
Related Topics
evalTemplate( )EvalTemplate( ) and evalOutput( )EvalOutput( ) in the AppLogic class (deprecated)GXAppLogic class,
TemplateDataBasic class (deprecated)GXTemplateDataBasic class,
ITemplateData Interface (deprecated)IGXTemplateData interface,
ITemplateMap Interface (deprecated)IGXTemplateMap interface"TagAttributes" in Chapter 7, "Working with Templates" in Programmer's Guide.
Resolves the id attribute specified in a GX markup tag in the template being processed by the Template Engine. This method is called by the Template Engine.
Syntax
public String getString(
String szExpr,
IObject pData,
IObject pMark)
szExpr. In the current GX markup tag in the HTML template being processed, the name of the field, or placeholder, assigned to the id attribute. Must be an identical match (case-sensitive).
Usage
GX markup tags are used in an HTML template to identify where dynamic data appears in the output report. In the GX markup tags, the id attribute specifies any of the following items: the name of a flat query within a hierarchical query, a field in the hierarchical result set or TemplateDataBasic object, or an HTML template. The type of item specified in the id attribute depends on the type attribute that is specified in the same GX markup tag.To provide application-specific special processing, an AppLogic can subclass the TemplateMapBasic class (deprecated) and override getString( ) to manipulate the Template Engine generation process. For example, an AppLogic can intercept and filter data from a database before the Template Engine processes it.
Rule
An AppLogic should use getString( ) only to override it after subclassing the TemplateMapBasic class (deprecated).
Return Value
A string that contains the value of the id mapping, or null for failure.
Example
The following code shows how getString( ) in a custom template map class is overridden to recalculate the current time each time it is encountered in a template:
Maps the value assigned to the id attribute in the HTML template to another value. This method takes an IBuffer object that contains a string expression for the replacement value.
Syntax
public int put(
String szExpr,
IBuffer pBuff)HRESULT Put(
LPSTR szKey,
IGXBuffer *pBuff);
szExpr szKey. In the GX markup tag in the HTML template, the name of the field, or placeholder, assigned to the id attribute. Must be an identical match (case-sensitive).
pBuff. Pointer to the IGXBufferIBuffer object that contains the String expression to substitute for the specified template field name, such as:
Calculated value, such as a number or date.
Name of the column in the hierarchical result set that the Template Engine uses to process the template. In your template, the column name must begin with a "$" character.
Name of a field in the TemplateDataBasicGXTemplateDataBasic object that the Template Engine uses to process the template. In your template, the field name must begin with a "$" character.
Usage
Use put( )Put( ) to add template field/data source pairs to the template map before calling evalTemplate( )EvalTemplate( ) or evalOutput( )EvalOutput( ) in the AppLogic classGXAppLogic class.
Rule
Use the GXCreateBuffer( ) function to create the IGXBuffer object. Thereafter, use methods in the IGXBuffer interface to manipulate the memory block.To create an IBuffer object that contains the string expression to pass to put( ), use GX.CreateBufferFromString( ). Alternatively, use putString( ) to pass a string directly.
The AppLogic can place the Put( ) method call inside a loop to construct the field map iteratively. For example, the AppLogic could use this technique to populate a map from a file, line by line.The AppLogic can place the put( ) method call inside a loop to construct the field map iteratively. For example, the AppLogic could use this technique to populate a map from a file, line by line.
Return Value
GXE.SUCCESS if the method succeeds.HRESULT, which is set to GXE_SUCCESS if the method succeeds.
Related Topics
evalTemplate( )EvalTemplate( ) and evalOutput( )EvalOutput( ) in the AppLogic class (deprecated)GXAppLogic class,
TemplateDataBasic class (deprecated) GXTemplateDataBasic class,
ITemplateData Interface (deprecated) IGXTemplateData interface,
ITemplateMap Interface (deprecated) IGXTemplateMap interface"TagAttributes" in Chapter 7, "Working with Templates" in Programmer's Guide.
Maps the value assigned to the id attribute in the HTML template to another value. This method takes a string argument for the replacement value.
Syntax
public int putString(
String szExpr,
String szData)
szExpr. In the GX markup tag in the HTML template, the name of the field, or placeholder, assigned to the id attribute. Must be an identical match (case-sensitive).
szData. The String expression to substitute for the specified template field name, such as:
Calculated value, such as a number or date. Use the string.valueOf( ) methods to convert calculated values to a string.
Name of the column in the hierarchical result set that the Template Engine uses to process the template. In your template, the column name must begin with a "$" character.
Name of a field in the TemplateDataBasic object that the Template Engine uses to process the template. In your template, the field name must begin with a "$" character.
Usage
Use putString( ) to add template field/data source pairs to the template map before calling evalTemplate( ) or evalOutput( ) in the AppLogic class.
Tip
The AppLogic can place the putString( ) method call inside a loop to construct the field map iteratively. For example, the AppLogic could use this technique to populate a map from a file, line by line.
Return Value
GXE.SUCCESS if the method succeeds.
Related Topics
evalTemplate( ) and evalOutput( ) in the AppLogic class (deprecated)TemplateDataBasic class (deprecated)
ITemplateData Interface (deprecated)
ITemplateMap Interface (deprecated)
The Util class is deprecated and is provided for backward compatibility only. New applications developed using standard JDBC calls do not need the functionality provided by the Util class.
The Util class is a utility class that contains static methods for converting Java Date objects to iPlanet Application Server date/time formats and IBuffer values to string. Like the methods in the Math and System classes in the Java Class Library, the methods in the Util class can be used anywhere regardless of whether an instance of the class exists or not.
You call the methods in the Util class by using the following convention: Util.method. The following example shows how you call toString( ), a method in the Util class, to convert data in a returned IBuffer object to a string value:
groupbyString = Util.toString(qry.getGroupBy());
Converts a Java Date object and returns a string containing the date value in the iPlanet Application Server date format.
Syntax
public static String dateToDate(
Date date)
date. Date object containing the date value to convert. The specified date must be a Java Date object.
Usage
Use dateToDate( ) when working with dates and operations in the Data Access Engine (DAE).
Tip
See the java.util.Date class for additional options for obtaining and formatting date and time values.
Return Value
String representing the date portion of the Date object, or null for failure.
Example 1
Date startDate=new Date(String.valueOf(month)+"/1/"+year);Date endDate=new Date(String.valueOf(month)+"/"+numDays+"/"+year+" 23:59:59");
log(month+"/"+numDays+"/"+year);
log(startDate.toString()+" "+dateToDate(startDate));
log(endDate.toString()+" "+dateToDate(endDate));
Example 2
// Get and display date portion of current date as a string.todaysDate=dateToDate(new date());
System.out.println("Today, in iPlanet Application Server format, is " + todaysDate + ".");
Related Topics
dateToTime( )
Converts a Java Date object and returns a string containing the time value in the iPlanet Application Server time format.
Syntax
public static String dateToTime(
Date date)
date. Date object containing the time value to convert. The specified date must be a Java Date object.
Usage
Use dateToTime( ) when working with time and operations in the Data Access Engine (DAE).
Return Value
String representing the time portion of the Date object, or null for failure.
Tip
See the java.util.Date class for additional options for obtaining and formatting date and time values.
Example 1
Date startDate=new Date(String.valueOf(month)+"/1/"+year);Date endDate=new Date(String.valueOf(month)+"/"+numDays+"/"+year+" 23:59:59");
log(month+"/"+numDays+"/"+year);
log(startTime.toString()+" "+dateToTime(startDate));
log(endTime.toString()+" "+dateToTime(endDate));
Example 2
// Get and display time portion of current date as a string.timeRightNow=dateToTime(new date());
System.out.println("Time right now, in iPlanet Application Server format, is " + todaysDate + ".");
Related Topics
dateToDate( )
Converts a Java Date object and returns a string containing the date and time value in the iPlanet Application Server time stamp format.
Syntax
public static String dateToTimeStamp(
Date date)
date. Date object containing the value to convert. The specified date must be a Java Date object.
Usage
Use dateToTimeStamp( ) when working with dates and times, as well as operations in the Data Access Engine (DAE).
Tip
See the java.util.Date class for additional options for obtaining and formatting date and time values.
Return Value
String representing the date and time portions of a date.
Example 1
Date startDate=new Date(String.valueOf(month)+"/1/"+year);Date endDate=new Date(String.valueOf(month)+"/"+numDays+"/"+year+" 23:59:59");
log(month+"/"+numDays+"/"+year);
log(startTime.toString()+" "+dateToTimeStamp(startDate));
log(endTime.toString()+" "+dateToTimeStamp(endDate));
Example 2
// Get and display time portion of current date as a string.dateTimeRightNow=dateToTimeStamp(new date());
System.out.println("Date and time right now, in iPlanet Application Server format, is " + dateTimeRightNow + ".");
Related Topics
dateToDate( )
Converts data in an IBuffer object to a string value.
Syntax
public static String toString(
IBuffer buffer)
buffer. IBuffer object containing the value to convert.
Usage
Use toString( ) to convert the IBuffer objects returned by the get**( ) methods in the IQuery Interface (deprecated) to string values.
Return Value
String representing the data in an IBuffer object.
Related Topics
IBuffer Interface (deprecated)
Previous Contents Index Next
Copyright © 2002 Sun Microsystems, Inc. All rights reserved.
Last Updated March 10, 2002