Previous     Contents     Index     Next     
iPlanet Application Server 6.5 SP1, Enterprise Edition Java Foundation Class Reference Guide
Updated: November 25, 2002

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:



AppLogic class (deprecated)

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.



GXAppLogic class

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:

#include <gxapplogic.h>

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:

STDMETHODIMP

HelloAppLogic::Execute()

{

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 {

public int execute() {

/* Override execute() method with AppLogic code */

return result("Hello, world!\n");

}

}


Package Include File

com.kivasoft.applogic gxapplogic.h


VariablesMembers


Table 2.1

Variable

Description

contextm_pContext  

A pointer to theIContext IGXContext object, which provides access to iPlanet Application Server services. Some objects require services from IContextIGXContext.  

m_pStream  

A pointer to the IGXStream object containing the AppLogic output stream. The EvalOutput( ) and EvalTemplate( ) methods merge the contents of dynamic data with a template file to send to the output stream. If the client of the request is a Web browser, the streamed data is HTML output.  

valIn

m_pValIn  

IValList A pointer to the IGXValList object containing input parameters and other information. During the execute( ) Execute( ) method, an AppLogic can access items in the IValList IGXValList to retrieve the arguments passed into the request.  

valOut

m_pValOut  

IValList A pointer to the IGXValList object containing output parameters. During the execute( ) Execute( ) method, the AppLogic can add or update items in the IValList IGXValList to specify output values for the request.  


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.


Table 2.2

Method

Description

createDataConn( )CreateDataConn( )  

Creates a new data connection object and opens a connection to a database or data source.  

createDataConnSet( )CreateDataConnSet( )  

Creates a collection used to dynamically assign query name/data connection pairs before loading a query file.  

createHierQuery( )CreateHierQuery( )  

Creates a new query object used for building and running a hierarchical query.  

createMailbox( )Creates an electronic mailbox object used for communicating with a user's mailbox.  

Creates an electronic mailbox object used for communicating with a user through email.  

createQuery( )CreateQuery( )  

Creates a new query object used for building and running a flat query.  

createSession( )CreateSession( )  

Creates a new session object used for tracking a user session.

 

createTrans( )CreateTrans( )  

Creates a new transaction object used for transaction processing operations on a database.  

deleteCache( )DeleteCache( )  

Deletes the result cache for a specified AppLogic.  

destroySession( )Deletes a user session.  

Deletes a user session.  

evalOutput( )EvalOutput( )  

Creates an output report by merging data with a report template file.  

evalTemplate( )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.  

execute( )Execute( )  

Performs the main task of an AppLogic object, such as accessing a database, generating a report, or other operations. Should be overridden or implemented.  

getAppEvent( )GetAppEvent( )  

Retrieves the application event object.  

getSession( )GetSession( )  

Returns an existing user session.  

getStateTreeRoot( )Returns an existing root node of a state tree or creates a new one.  

Returns an existing root node of a state tree or creates a new one.  

isAuthorized( )IsAuthorized( )  

Checks a user's permission level to a specified action or AppLogic.  

isCached( )IsCached( )  

Returns true if AppLogic results are being saved in the result cache.  

loadHierQuery( )LoadHierQuery( )  

Creates a hierarchical query by loading a query file and one or more query names with associated data connections.  

log( )Writes a message to the server log.  

Writes a message to the server log.  

loginSession( )LoginSession( )  

Logs an authorized user into a session with a secured application.  

logoutSession( )LogoutSession( )  

Logs a user out of a session with a secured application.  

newRequest( )Calls an AppLogic.  

Calls another AppLogic from within the current AppLogic.  

newRequestAsync( )Calls another AppLogic and runs it asynchronously.  

Calls another AppLogic from within the current AppLogic, and runs it asynchronously.  

removeAllCachedResults( )RemoveAllCachedResults( )  

Clears an AppLogic's result cache.  

removeCachedResult( )RemoveCachedResult( )  

Clears specific results from an AppLogic's result cache.  

result( )Result( )  

Specifies the return value of an AppLogic.  

saveSession( )SaveSession( )  

Saves changes to a session.  

setCacheCriteria( )SetCacheCriteria( )  

Stores AppLogic results, such as HTML, data values, and streamed results, in a result cache.  

setSessionVisibility( )SetSessionVisibility( )  

Sets the session visibility.  

setVariable( )SetVariable( )  

Sets a value that is passed to later AppLogic requests that are called by the same client session.  

skipCache( )SkipCache( )  

Skips result caching for the current AppLogic execution.  

streamResult( )StreamResult( )  

Streams output results as a string.  

streamResultBinary( )StreamResultBinary( )  

Streams output binary data, such as a GIF file.  

streamResultHeader( )StreamResultHeader( )  

Streams output header data.  


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:


import java.lang.*;
import com.kivasoft.*;
import com.kivasoft.types.*;
import com,kivasoft.util.*;
import com.kivasoft.applogic.*;

public class mySimpleAppLogic extends AppLogic {
public int execute() {
log("The execute method got called.");
log("I can do anything I want here, such as");
log("run queries, generate reports, update tables,");
log("and log messages like this one.");
return GXE.SUCCESS;
}
}


Related Topics


createDataConn( )


CreateDataConn( )

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.

  • 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.
The AppLogic can pass one parameter from both mutually exclusive pairs, as shown in the following example:

(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:




GX_DA_DRIVER_ODBC

GX_DA_DRIVER_SYBASE_CTLIB

GX_DA_DRIVER_MICROSOFT_JET  

GX_DA_DRIVER_MICROSOFT_SQL  

GX_DA_DRIVER_INFORMIX_SQLNET  

GX_DA_DRIVER_INFORMIX_CLI  

GX_DA_DRIVER_INFORMIX_CORBA  

GX_DA_DRIVER_DB2_CLI  

GX_DA_DRIVER_ORACLE_OCI  

GX_DA_DRIVER_DEFAULT  

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.

  • "DB" for the database name.

  • "USER" for the user name.

  • "PSWD" for the password.

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.


Rules

  • 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: devds003:dnet00a

  • 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: Connection conn = DataSource.getConnection();

    // code for database access

    conn.close();


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.


Example


// Method to open a connection to a database
protected com.kivasoft.IDataConn getOBDataConn()
{
String username = "kdemo";
String password = "kdemo";
IDataConn newDataConn = createDataConn(0,
GX_DA_DAD_DRIVERS.GX_DA_DRIVER_ODBC,
/* Datasource name. */ "ksample",
/* Database name. */ "",
/* userName. */ username,
/* password. */ password);

if (newDataConn == null)
{
log("ERROR: Could not create database connection");
}
return newDataConn;
}


// Method to open a connection to a database
STDMETHODIMP
OBBaseAppLogic::GetOBDataConn(IGXDataConn **ppConn)
{
HRESULT hr=GXE_SUCCESS;

// Create a vallist for the connection parameters
IGXValList *pList=GXCreateValList();
if(pList) {
// Set up the connection parameters
GXSetValListString(pList, "DSN", OB_DSN);
GXSetValListString(pList, "DB", "");
GXSetValListString(pList, "USER", OB_USER);
GXSetValListString(pList, "PSWD", OB_PASSWORD);

// Attempt to create the connection
hr = CreateDataConn(0, GX_DA_DRIVER_DEFAULT, pList, m_pContext,
         ppConn);

// Release pList when it's no longer needed
pList->Release();
}
return hr;
}


Related Topics
IGXDataConn interface IDataConn interface,
IValList interfaceIGXValList interface


createDataConnSet( )


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.


Example


IDataConnSet connSet;
connSet = createDataConnSet(0);
// Specify query / db connection pairs
connSet.addConn("employee", conn_empDB);
connSet.addConn("sales", conn_salesDB);
IHierQuery hqry;
// Load the GXQ file with the db connection set
hqry = loadHierQuery("employeeReport.gxq",connSet, 0, null);

// Run the report
evalTemplate("employeeReport.html", hqry);


Related Topics
loadHierQuery( )LoadHierQuery( ),
IDataConnSet interfaceIGXDataConn interface

About Database Connections


createHierQuery( )


CreateHierQuery( )

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.


Tips

  • 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 query

IQuery qry = createQuery();

qry.setTables("CTLusers");

qry.setFields("loginName, Password, AccessLevel")

qry.setOrderBy("LoginName);

// 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("");

else

return result("Failed to Generate HTML");

}


Example 2
// Create the flat query

IQuery qry = createQuery();

qry.setTables("CTLusers");

qry.setFields("loginName, Password, AccessLevel")

qry.setWhere("UserId > 100");

// Create the hierarchical query

IHierQuery hqry = createHierQuery();

hqry.addQuery(qry, conn, "USERS", "", "");

// Execute the hierarchical query

IHierResultSet hrs = hqry.execute(0, 0, null);

// Process rows in result set

if(hrs.getRowNumber("USERS")!=0)

. . .

// Create the hierarchical query

IGXHierQuery *pHq=NULL;

if(((hr=CreateHierQuery(&pHq))==GXE_SUCCESS)&&pHq) {

// Add a query

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"createMailbox( )"> "Caching AppLogic Results to Improve Performance"createMailbox( )


CreateMailbox( )

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


createQuery( )


CreateQuery( )

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.


Tips

  • 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.


Example


// Create the flat query object
IQuery qry = createQuery();
// Set up the query
qry.setTables("CTLcust");
qry.setFields("CustomerID, Customer");
qry.setWhere("Customer"+"='"+String.valueOf(custId)+"'");

// Execute the query
IResultSet rs = conn.executeQuery(0, qry, null, null);

// Check for a result set with rows
if((rs!=null)&&(rs.getRowNumber()>0))
return result("Sorry, this user ("+
firstName+" "+lastName+") already exists");
// Otherwise, process the result set . . .


// Create a query to insert data into a table
IGXQuery *pUserQuery=NULL;

if(((hr=CreateQuery(&pUserQuery))==GXE_SUCCESS)&&pUserQuery) {
pUserQuery->SetSQL("INSERT INTO OBUser(userName, password, userType,
   eMail) VALUES (:userName, :password, :userType, :eMail)");


Related Topics
createDataConn( ),
CreateDataConn( )

createQuery( )CreateQuery( ),
IGXHierQuery interface IHierQuery interface,
IGXHierResultSet interface IHierResultSet interface,
ExecuteQuery( ) executeQuery( ) in the IGXDataConn interface IDataConn interface


createSession( )


CreateSession( )

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.

  • 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.
The default scope is distributed and the default timeout is 60 seconds from the time the session was last accessed.

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

Writing Hierarchical Queries


createTrans( )


CreateTrans( )

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.


Tips

  • 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.


Example


// Create and begin a transaction
ITrans trx = createTrans();
trx.begin();

// 1) Process the credit card
if(!processCreditCard(cusId, card, number, expirationDate, trx)) {
trx.rollback();
return result("Could not process the credit card information"); }

// 2) Process the invoice record
InfoHolder info=new InfoHolder();
if(!makeInvoiceRecord(cusId, number, trx, info)) {
trx.rollback();
return result("Could not create the invoice record"); };

// 3) Process products on the invoice
if(!makeInvoiceEntries(info.invoiceId, trx)) {
trx.rollback();
return result("Can't create product records"); };

// 4) Process optional shipping information
if(shippingInfo && !makeShippingRecord(info.invoiceId, trx, addr1, addr2, city, state, zip)) {
trx.rollback();
return result("Could not create the shipping information record"); };

// 5) Process the inventory for each purchased product
if(!reduceProductInventory(trx)) {
// Problem occurred - abandon everything
trx.rollback();
   return result("Could not reduce inventory");
}

// No problem occurred - save everything
trx.commit(0);
// Return success message / report


// Create a transaction for several insert operations
IGXTrans *pTx=NULL;

if(((hr=CreateTrans(&pTx))==GXE_SUCCESS)&&pTx) {
// Begin the transaction
pTx->Begin();
IGXResultSet *pRset=NULL;

// Update User
if(((hr=pUserPQuery->Execute(0, pUserValList, pTx, NULL,
   &pRset))==GXE_SUCCESS)&&pRset) {

// The result set is not needed; release it
pRset->Release();

// Update Customer
if(((hr=pCustPQuery->Execute(0, pCustValList, pTx, NULL,
         &pRset))==GXE_SUCCESS)&&pRset) {

// All updates succeeded. Commit the transaction
pTx->Commit(0, NULL);
GXSetValListString(m_pValIn, "ssn", m_pSsn);
GXSetValListString(m_pValIn, "OUTPUTMESSAGE", "Successfully
          updated customer record");

if(NewRequest("AppLogic CShowCustPage", m_pValIn, m_pValOut,
          0)!=GXE_SUCCESS)
HandleOBSystemError("Could not chain to CShowCustPage
             applogic");
}
else {
pTx->Rollback();
HandleOBSystemError("Could not insert checking account record
          for new customer");
}
}
else {
pTx->Rollback();
HandleOBSystemError("Could not insert checking account record for
       new customer");
}
pTx->Release();
}
else
HandleOBSystemError("Could not start transaction");


Related Topics
IGXTrans interfaceITrans interface


deleteCache( )


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.


Tips

  • 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.


Example


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");


HRESULT hr;
LPSTR guid;

guid = GXGetValListString(m_pValIn, "applogic");

hr = DeleteCache(guid);

if (hr == GXE_SUCCESS)
sprintf(msg, "Successfully deleted cache");
else
sprintf(msg, "Failed to delete cache");


Related Topics
removeAllCachedResults( )RemoveAllCachedResults( ),
removeCachedResult( )RemoveCachedResult( ),
setCacheCriteria( )SetCacheCriteria( )


destroySession( )


DestroySession( )

Deletes a user session.

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( )


evalOutput( )


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.

props. Specify nullNULL.


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:


Table 2.3

Client

Template File Used by evalOutput( )EvalOutput( )

Output Returned by evalOutput( )EvalOutput( )

Web browser  

HTML  

HTML page  

AppLogic that passed to its newRequest( )NewRequest( ) call the following key and value in the input IValListIGXValList parameter:

key: gx_client_type

value: "ocl"  

GXML  

Self-describing data stream, which contains the names of the fields in the result set and their values.  

AppLogic that does not specify a client type explicitly, or that passed to its newRequest( )NewRequest( ) call the following key and value in the input IValListIGXValList parameter:

key: gx_client_type

value: "http"  

HTML  

HTML page  

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.


Tips

  • 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.


Example


// Create a hierarchical query used for template processing
IHierQuery hqry = createHierQuery();

// Add a flat query object and data connection to hqry
hqry.addQuery(qry, conn, "USERS", "", "");

// Pass hierarchical query to evalOutput() for reporting
if(evalOutput("apps/template/userinfo", hqry)== GXE.SUCCESS)
return result("");
else
return result("Failed to Generate HTML");
}


IGXHierQuery *pHq=NULL;

if(((hr=CreateHierQuery(&pHq))==GXE_SUCCESS)&&pHq) {
// Add a query that has already been defined
pHq->AddQuery(pQuery, pConn, "SelCusts", "", "");

// Pass the hierarchical query to EvalOutput()
if(EvalOutput("apps/template/customer", pHq, NULL, NULL,
   NULL)!=GXE_SUCCESS)
Result("<HTML><BODY>Unable to evaluate template.</BODY></HTML>");


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


evalTemplate( )


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.

props. Specify NULL.


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.


Tips

  • 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.


Example


// Create the flat query
IQuery qry = createQuery();
qry.setTables("CTLusers");
qry.setFields("loginName, Password, AccessLevel");
qry.setOrderBy("LoginName");

// 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("");
else
return result("Failed to Generate HTML");
}


// Create a flat query
IGXQuery *pQuery=NULL;
pQuery->SetTables("OBCustomer, OBAccount");
pQuery->SetFields("lastName, firstName, userName, ssn");
pQuery->SetWhere(whereClause);
pQuery->SetOrderBy("lastName, firstName");

// Create the hier query used for template processing
IGXHierQuery *pHq=NULL;

if(((hr=CreateHierQuery(&pHq))==GXE_SUCCESS)&&pHq) {
// Add a query
pHq->AddQuery(pQuery, pConn, "SelCusts", "", "");

// Pass the hierarchical query to EvalTemplate()
if(EvalTemplate("Customer.html", pHq, NULL, NULL, NULL)!=GXE_SUCCESS)
Result("<HTML><BODY>Unable to evaluate template.</BODY></HTML>");


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


execute( )


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( ).


Syntax
public int execute()

HRESULT Execute()


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.


Tips

  • 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":

package gxApp.sample

import java.lang.*;

import com.kivasoft.*;

import com.kivasoft.types.*;

import com,kivasoft.util.*;

import com.kivasoft.applogic.*;

public class HelloWorldAppLogic extends AppLogic {

public int execute() {

// Simple code that overrides execute() method

return result("Hello world!");

}

}

In the following example, Execute( ) displays an HTML page:

OBShowNewCustPage::Execute()

{

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
result( )Result( ),
IValList interfaceIGXValList interface


getAppEvent( )


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


getSession( )


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);

dwFlags. Specify 0 (zero).

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.

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:


public class ProductRestock extends AppLogic
{
public int execute()
{
try {
ISession2 mySess;
mySess = getSession(0, null, null);
if (mySess == null) {
log("missing session");
return evalOutput("kivaapp/shop/please_login",
(ITemplateData) null,
(ITemplateMap) null, null, null);
}
// Check to see if the current role is authorized
// to update inventory.
//
if (isAuthorized("Shop_Inventory", "WRITE") !=
               GXACLPERMSTATUS.GXACL_ALLOWED)
{
log("unauthorized access: Shop_Inventory");
return evalOutput("kivaapp/shop/no_access",
(ITemplateData) null,
(ITemplateMap) null, null, null);
}
// Record the inventory restock transaction.


Related Topics
createSession( )CreateSession( ),
loginSession( )LoginSession( ),
saveSession( )SaveSession( ),
GXSession2 class Session2 class,
IGXSession2 interface ISession2 interface


getStateTreeRoot( )


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:


IState2 tree = getStateTreeRoot(GXSTATE.GXSTATE_DISTRIB, "Grammy");

if (tree!=null)
{
IState2 child = tree.getStateChild("Best Female Vocal");
if (child == null)
{
child = tree.createStateChild("Best Female Vocal", 0,
GXSTATE.GXSTATE_DISTRIB);


HRESULT hr;

hr = GetStateTreeRoot(GXSTATE_DISTRIB, "Grammy", &m_pStateRoot);

if (hr == NOERROR && m_pStateRoot)
{
IGXState2 *pState = NOERROR;
hr = m_pStateRoot->GetStateChild("Best Female Vocal",
&pState);
if (hr != NOERROR || !pState)
{
hr = m_pStateRoot->CreateStateChild("Best Female Vocal",
0, GXSTATE_DISTRIB, &pState);


Related Topics
IState2 interfaceIGXState2 interface


isAuthorized( )


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.


Syntax 1
Use in most cases.

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:

"kiva:acl,logic"

"kiva:acl,general"

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."

method. Specify 0.

flags. Specify 0.

pCred. Specify nullNULL.

pEnv. Specify nullNULL.

pResult. Pointer to the client-allocated variable that contains the returned permission status. The variable is set to one of the following enum constants:





Constant

Description

GXACL_ALLOWED  

The specified permission is granted to the user.  

GXACL_NOTALLOWED  

The specified permission is not granted to the user.  

GXACL_DONTKNOW  

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:


Table 2.5

Value

Description

GXACLPERMSTATUS.GXACL_ALLOWED  

The specified permission is granted to the user.  

GXACLPERMSTATUS.GXACL_NOTALLOWED  

The specified permission is not granted to the user.  

GXACLPERMSTATUS.GXACL_DONTKNOW  

The specified permission is unlisted or there is conflicting information.  

HRESULT, which is set to GXE_SUCCESS if the method succeeds.


Example


if (isAuthorized("MonthlyForecast", "READ") != GXACLPERMSTATUS.GXACL_ALLOWED)
return result("<html><body>sorry no access</body></html>);
else
// run monthly forecast report


DWORD auth_result = 0;

if (IsAuthorized("Shop_Inventory", "WRITE", &auth_result) != NOERROR || auth_result != (DWORD) GXACL_ALLOWED)
{
Log("Unauthorized access: Shop_Inventory");

EvalOutput("kivaapp/shop/unauthorized_access",
(IGXTemplateData *) NULL,
(IGXTemplateMap *) NULL, NULL, NULL);
}
else
// Update inventory


Related Topics
loginSession( )LoginSession( )


isCached( )


IsCached( )

Returns true if AppLogic results are being saved in the result cache.


Syntax
public boolean isCached()

BOOL 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.


Example


// Determine whether AppLogic is cached
// before setting cache criteria
if(!isCached()) {
log("Setting agent cache criteria");
if(setCacheCriteria(60, 3, "category")!=0)
log("Could not set agent cache criteria");
else
log("Succeeded in setting agent cache criteria");
}
else
log("Not setting agent cache criteria");


Related Topics
skipCache( )SkipCache( )


loadHierQuery( )


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:

    • Each query is preceded by the following line: query queryName using (driverCode, DSN, UserName) is

    • For a child query, append the following line after the SQL SELECT statement: join currentQueryName to parent parentName where

      currentQueryName.table.column = parentName.colorAlias

  • 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.


Rules

  • 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:

Query file:


/* 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

/* DETAILS */
query DETAILS using (ODBC, kdetails, kuser) is
select COUNTIES.COUNTYNAM as COUNTIES_COUNTYNAM,
COUNTIES.POP as COUNTIES_POP,
COUNTIES.STATE as COUNTIES_STATE
from COUNTIES
order by COUNTIES.COUNTYNAM asc

join DETAILS to parent STATES
where DETAILS.COUNTIES.STATE = 'STATES.STATES_STATE'

AppLogic code snippet:


IDataConnSet connSet;
connSet = createDataConnSet(0);

// Create database connections
IDataConn conn_detailDB = createDataConn(0, GX_DA_DAD_DRIVERS.GX_DA_DRIVER_DEFAULT, "kdetails", "", "kuser", "kpassword");

IDataConn conn_statesDB = createDataConn(0, GX_DA_DAD_DRIVERS.GX_DA_DRIVER_ODBC, "kstates", "", "kuser", "kpassword");

// Specify query / db connection pairs
connSet.addConn("DETAILS", conn_detailDB);
connSet.addConn("STATES", conn_statesDB);

// Create IValList that contains the REGION parameter
// value to pass to the hierarchical query
IValList param = GX.CreateValList();
param.setValString("REGION", "WEST");

IHierQuery hqry;
// Load the GXQ file with the db connection set and
// parameter value
hqry = loadHierQuery("state.gxq", connSet, 0, param);

// Run the report
evalTemplate("state.html", hqry);


IGXDataConnSet *connSet = NULL;
HRESULT hr;
hr = CreateDataConnSet(0, &connSet);
if (hr == GXE_SUCCESS)
{
// Create database connections
IGXDataConn *conn_detailDB = NULL;
IGXDataConn *conn_statesDB = NULL;

IGXValList *pList=GXCreateValList();
pList->SetValString("DSN", "kdetails");
pList->SetValString("DB", "");
pList->SetValString("USER", "kuser");
pList->SetValString("PSWD", "kpassword");

// Create first connection
hr = CreateDataConn(0, GX_DA_DRIVER_DEFAULT, pList,
NULL, &conn_detailDB);
if (hr == GXE_SUCCESS)
{
pList->SetValString("DSN", "dstates");
pList->SetValString("DB", "");
pList->SetValString("USER", "kuser");
pList->SetValString("PSWD", "kpassword");

// Create second connection
hr = CreateDataConn(0, GX_DA_DRIVER_DEFAULT, pList,
NULL, &conn_statesDB);
pList->Release();

if (hr == GXE_SUCCESS)
{
// Specify query / db connection pairs
connSet->AddConn("DETAILS", conn_detailDB);
connSet->AddConn("STATES", conn_statesDB);

// Create IGXValList that contains the
// REGION parameter value to pass to the
// hierarchical query
IGXValList param = GXCreateValList();
param->SetValString("REGION", "WEST");

IGXHierQuery *hqry;
// Load the GXQ file with the db connection set
// and parameter value

hr = LoadHierQuery("state.gxq", connSet, 0,
param, &hqry);

if (hr == GXE_SUCCESS)
{
// Run the report
EvalOutput("state", hqry, NULL,
NULL, NULL);
}
else
....


Related Topics
createDataConnSet( )CreateDataConnSet( ),
IDataConnSet interfaceIGXDataConnSet interface,
IHierQuery interfaceIGXHierQuery interface


loadQuery( )


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: /* optional comments */

    query queryName using (driverCode, DSN, UserName) is

    where queryName is the name of the flat query. Do not use any semicolons (;) in the query file.

  • 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.

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:

Query file:


/* 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

AppLogic code snippet:


// Create database connection
IDataConn conn = createDataConn(0, GX_DA_DAD_DRIVERS.GX_DA_DRIVER_DEFAULT, "kstates", "", "kuser", "kpassword");

// Create IValList that contains the REGION parameter
// value to pass to the query
IValList param = GX.CreateValList();
param.setValString("REGION", "WEST");

IQuery qry;
// Load the query file with the parameter value
qry = loadQuery("state.gxq", "STATES", 0, param);

// Execute the query
IResultSet rs = conn.executeQuery(
GX_DA_EXECUTEQUERY_FLAGS.GX_DA_RS_BUFFERING, qry, null, null);


HRESULT hr;

// Create database connection
IGXDataConn *conn = NULL;

IGXValList *pList=GXCreateValList();
pList->SetValString("DSN", "kstates");
pList->SetValString("DB", "");
pList->SetValString("USER", "kuser");
pList->SetValString("PSWD", "kpassword");

hr = CreateDataConn(0, GX_DA_DRIVER_DEFAULT, pList,
NULL, &conn);
if (hr == GXE_SUCCESS)
{
// Create IGXValList that contains the REGION
// parameter value to pass to the
// hierarchical query
IGXValList param = GXCreateValList();
param->SetValString("REGION", "WEST");

IGXQuery *qry;

// Load the GXQ file with the parameter value
hr = LoadQuery("state.gxq", "STATES", 0,
param, &qry);

// Execute the query
IGXResultSet *rs = NULL;
hr = conn->ExecuteQuery(GX_DA_RS_BUFERRING, qry, NULL,
NULL, &rs);


Related Topics
IQuery Interface (deprecated)IGXQuery interface


log( )


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).

public int log(
   String msg)

HRESULT Log(
   LPSTR msg);


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);

msg. Message text to log.

type. Message type. Use one of the following variables:

  • GXLOG.GXEVENTTYPE_INFORMATION

  • GXLOG.GXEVENTTYPE_ERROR

  • GXLOG.GXEVENTTYPE_SYSTEM

  • GXLOG.GXEVENTTYPE_WARNING

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.


Example 1
// Log a message
log("This is the message text saved to the log");
Example 2
// Log messages that include String variables
log(firstName+lastName+password+" "+String.valueOf(cusId));
log(GXLOG.GXEVENTTYPE_ERROR", -1, Cannot find table: "+"Shipping");


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);


loginSession( )


LoginSession( )

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.


Syntax 1
Use in most cases.

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);

name. The login user name.

password. The user password.

pDomain. Specify nullNULL.

dwMethod. Specify 0.

dwFlags. Specify 0.

pName. The login user name.

pAuthData. The user password.

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.


Example


public class Welcome extends AppLogic
{
public int execute()
{
try {

// Check user login
if (valIn.getValString("NAME") == null ||
valIn.getValString("PASSWORD") == null) {
log("missing login NAME/PASSWORD");
return evalOutput("kivaapp/shop/login_again",
(ITemplateData) null,
(ITemplateMap) null, null, null);
}
// If login succeeds, create a session
ISession2 mySess;
mySess = getSession(0, null, null);
if (mySess == null) {
mySess=createSession(0, 60000, null, null, null);
log("created session: " + String.valueOf(mySess != null));
} else
log("got session");

// Now, look up user NAME/PASSWORD in database
// and see what role the user has. The database
// should have a user table which tracks all the
// users of the online shop application.
//
String role;
role = /* Database lookup here. */ "Shop_Customer";

// Call loginSession() to set up the session with
// that role. Future requests to AppLogics in this
// session will now operate under the right role.
//
loginSession(role, "");
saveSession(null);

// Check to see if the current role is authorized
// against some of the more advanced operations,
// and choose the appropriate main menu page to
// return to the user.
//
if (isAuthorized("Shop_Inventory", "READ") ==
             GXACLPERMSTATUS.GXACL_ALLOWED ||
isAuthorized("Shop_Daily_Forecast", "READ") ==
             GXACLPERMSTATUS.GXACL_ALLOWED ||
isAuthorized("Shop_Weekly_Forecast", "READ") ==
             GXACLPERMSTATUS.GXACL_ALLOWED)
return evalOutput("mainmenu_advanced",
(ITemplateData) null,
(ITemplateMap) null, null, null);
return evalOutput("kivaapp/shop/mainmenu_regular",
(ITemplateData) null,
(ITemplateMap) null, null, null);
} finally {
}
}
}


STDMETHODIMP
ShopWelcome::Execute()
{
char buffer[256];
buffer[0] = '\0';

// Verify user login
if (m_pValIn->GetValString("NAME", buffer, sizeof(buffer)) != NOERROR
   ||
m_pValIn->GetValString("PASSWORD", buffer, sizeof(buffer)) !=
   NOERROR)
{
Log("missing login NAME/PASSWORD");
return EvalOutput("kivaapp/shop/please_login_again",
(IGXTemplateData *) NULL,
(IGXTemplateMap *) NULL, NULL, NULL);
}
// If login is successful, create a session
IGXSession2 *mySess = NULL;
HRESULT hr;
hr = GetSession(0, NULL, NULL, &mySess);
if (hr != NOERROR ||
!mySess)
{
hr=CreateSession(0, 60000, NULL, NULL, NULL, &mySess);
if (hr == NOERROR)
Log("created session: success");
else
Log("created session: fail");
} else
Log("got session");

// Now, look up user NAME/PASSWORD in database
// and see what role the user has. The database
// should have a user table which tracks all the
// users of the online shop application.
//
LPSTR role;
role = /* Database lookup here. */ "Shop_Customer";

// Call LoginSession() to set up the session with that
// role. Future requests to AppLogics in this session
// will now operate under the right role.
//
LoginSession(role, "");
SaveSession(NULL);

if (mySess)
mySess->Release();

// Check to see if the current role is authorized
// against some of the more advanced operations, and
// choose the appropriate main menu page to return to
// the user.
DWORD auth_result = 0;

if ((IsAuthorized("Shop_Inventory", "READ", &auth_result) == NOERROR
   &&
auth_result == (DWORD) GXACL_ALLOWED) ||
(IsAuthorized("Shop_Daily_Forecast", "READ", &auth_result) ==
   NOERROR &&
auth_result == (DWORD) GXACL_ALLOWED) ||
(IsAuthorized("Shop_Weekly_Forecast", "READ", &auth_result) ==
   NOERROR &&
auth_result == (DWORD) GXACL_ALLOWED))
return EvalOutput("kivaapp/shop/mainmenu_advanced",
(IGXTemplateData *) NULL,
(IGXTemplateMap *) NULL, NULL, NULL);
return EvalOutput("kivaapp/shop/mainmenu_regular",
(IGXTemplateData *) NULL,
(IGXTemplateMap *) NULL, NULL, NULL);
}


Related Topics
isAuthorized( )IsAuthorized( ),
logoutSession( )LogoutSession( )


logoutSession( )


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);

dwFlags. Specify 0.


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( )


newRequest( )


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.

flag. Specify zero.


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.

  • 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( ).
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:

vallist.sSetValString("gx_client_type", "ocl");


Rule
The specified GUID string, input parameters, and output parameters must be valid for the specified AppLogic.


Tips

  • The calling AppLogic can create new input and output IValLists 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 parameters

newRequest("{E5CA1000-6EEE-11cf-96FD-0020AFED9A65}",

paramsToModule, paramsReturned);


Example 2
// Use DisplayBasket AppLogic to display the contents

if(newRequest("DisplayBasket", valIn, valOut)==0){

return 0;

}

else

return result("Cannot execute DisplayBasket AppLogic");


Related Topics
GUID class,
IValList interface IGXValList interface


newRequestAsync( )


NewRequestAsync( )

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.

flag. Specify 0.

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.


Example


IGXOrder *pOrder;
ULONG nOrder;
HRESULT hr, ReqResult;

if (NewRequestAsync(asyncGUIDStr, m_pValIn,
m_pValOut, 0, &pOrder) == GXE_SUCCESS)
{
Log("Successfully invoked async AppLogic\n");

// wait for async applogic to finish (max 100 seconds)
hr = GXWaitForOrder(&pOrder, 1, &nOrder, m_pContext, 100);
if (hr != NOERROR)
{
return Result("Error in executing async request:
   order wait returned an error");
}
else
{
pOrder->GetState(NULL, &ReqResult, NULL);
if (ReqResult != NOERROR)
return Result("Error in executing async request");
}
}
else
{
Log("Failed to invoke async AppLogic\n");
}


Orders[] = new IOrder[1];
int nOrder;

Orders[0] = newRequestAsync(asyncGUIDStr, valIn, valOut);
if (Orders[0] != null)
{
log("Successfully invoked async AppLogic\n");

// wait for async applogic to finish (max 100 seconds)
nOrder = GX.WaitForOrder(Orders, context, 100);
if (nOrder >= 0)
{
return result("Error in executing async request:
          order wait returned an error");
}
else
{
getStateIOrder state = Orders[0].getState();
if (state == null || state.pdwState != GXE.SUCCESS)
return result("Error in executing async
             request");
}
}
else
{
log("Failed to invoke async AppLogic\n");
}


Related Topics
GUID class,
IOrder interfaceIGXOrder interface,
IValList interface IGXValList interface


removeAllCachedResults( )


RemoveAllCachedResults( )

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.


Tips

  • 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.


Example


int hr;
String guid = valIn.getValString("applogic");

hr = removeAllCachedResults(guid);
if (hr == GXE.SUCCESS)
return result("Successfully cleared cached results")
else
return result("Failed to clear cached results");


HRESULT hr;
LPSTR guid;

guid = GXGetValListString(m_pValIn, "applogic");

hr = RemoveAllCachedResults(guid);

if (hr == GXE_SUCCESS)
sprintf(msg, "Successfully cleared cached results");
else
sprintf(msg, "Failed to clear cached results");


Related Topics
deleteCache( )DeleteCache( ),
removeCachedResult( )RemoveCachedResult( ),
setCacheCriteria( )SetCacheCriteria( )


"Caching AppLogic Results to Improve Performance"removeCachedResult( )"> "Caching AppLogic Results to Improve Performance"removeCachedResult( )


RemoveCachedResult( )

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.


Tips

  • 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.


Example


int hr;
String guid = valIn.getValString("applogic");

IValList resultList = GX.CreateValList();
resultList.setValString("Salary", "50000");

hr = removeCachedResult(guid, resultList);

if (hr == GXE.SUCCESS)
return result("Successfully deleted specified result")
else
return result("Failed to delete specified result");


HRESULT hr;
LPSTR guid;
guid = GXGetValListString(m_pValIn, "applogic");

resultList = GXCreateValList();
hr = resultList->SetValString("Salary", "50000");

hr = RemovedCachedResult(guid, resultList);

if (hr == GXE_SUCCESS)
sprintf(msg, "Successfully deleted specified result");
else
sprintf(msg, "Failed to delete specified result");


Related Topics
deleteCache( )DeleteCache( ),
removeAllCachedResults( )RemoveAllCachedResults( ),
setCacheCriteria( )SetCacheCriteria( )

"Caching AppLogic Results to Improve Performance"


result( )


Result( )

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.


Tips

  • 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.


Example 1
// Return a simple HTML string
public class HelloWorld extends AppLogic {
public int execute() {
return result("Hello, world!\n");
}
}
Example 2
// Dynamically create the return string
public int execute() {
String resultStr;
String text;
text = valIn.getValString("Incoming Text");
if (text == null)
resultStr = "No input text.";
else if (text.indexOf('-') >= 0)
resultStr = "Input text has a hyphen.";
else
resultStr = "Input text has no hyphen.";
resultStr = "<HTML>" + resultStr + "</HTML>";
return result(resultStr);
}


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"


saveSession( )


SaveSession( )

Saves changes to a session.

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.


Tip

  • 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"


setCacheCriteria( )


SetCacheCriteria( )

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:


Table 2.6

Syntax

Description

arg  

Test succeeds for any value of arg in the input parameter list. For example:

setCacheCriteriaSetCacheCriteria(3600,1,"EmployeeCode");  

arg=v  

Test whether arg matches v (a string or numeric expression). For example:

"stock=NSCP"

Assign an asterisk (*) to the argument to cache a new set of results every time the AppLogic module runs with a different value. For example:

setCacheCriteriaSetCacheCriteria(3600,1,"EmployeeCode=*");  

arg=v1|v2  

Test whether arg matches any values in the list (v1, v2, and so on). For example:

"dept=sales|marketing|support"  

arg=n1-n2  

Test whether arg is a number that falls within the range. For example:

"salary=40000-60000"  


Usage
Use 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.


Tips

  • 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 1


// Verify AppLogic caching before setting cache criteria
if(!isCached()) {
log("Set criteria to save output from 3 deptcodes");
if(setCacheCriteria(60, 3, "deptcode")!=0)
log("Could not set criteria");
else
log("Succeeded in setting criteria");
}
else
log("Not Setting Criteria");


// Verify AppLogic caching before setting cache criteria
if(!IsCached()) {
Log ("Set criteria to save output from 3 deptcodes");
if(SetCacheCriteria(60, 3, "deptcode")!=GXE_SUCCESS)
Log("Could not set criteria");
else
Log("Succeeded in setting criteria");
}
else
Log("Not setting Criteria");


Example 2
// Cache multiple results for up to 100 values of Department

setCacheCriteria(3600,100,"Department");

SetCacheCriteria(3600,100,"Department");


Example 3
// Cache single result for given matching value of Department

setCacheCriteria(3600,1,"Department=Operations");

SetCacheCriteria(3600,1,"Department=Operations");


Example 4
// Cache multiple results for two matching values of dept

setCacheCriteria(3600,2,"Department=Research | Engineering");

SetCacheCriteria(3600,2,"Department=Research | Engineering");


Example 5
// Cache one result for salary in a range

setCacheCriteria(3600,1,"Salary=40000-60000");

SetCacheCriteria(3600,1,"Salary=40000-60000");


Example 6
// Cache two results for several parameters

setCacheCriteria(3600, 2,

"Department=Sales,Salary=40000-60000");

SetCacheCriteria(3600,2,

"Department=Sales, Salary=40000-60000");


Related Topics
deleteCache( )DeleteCache( ),
removeAllCachedResults( )RemoveAllCachedResults( ),
removeCachedResult( )RemoveCachedResult( ),
isCached( )IsCached( ),
skipCache( )SkipCache( )


"Caching AppLogic Results to Improve Performance"setSessionVisibility( )"> "Caching AppLogic Results to Improve Performance"setSessionVisibility( )


SetSessionVisibility( )

Sets the session visibility.

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( )


setVariable( )


SetVariable( )

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"


skipCache( )


SkipCache( )

Skips result caching for the current AppLogic execution.


Syntax
public int skipCache()

HRESULT SkipCache()


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.


Example


// Skip result caching if an error occurs
// during AppLogic execution
public class produceReport extends AppLogic {
public int execute() {
if (isCached == false)
// Set up results cache
setCacheCriteria(3600, 1, "");
String result;
if (. . . Input arguments are not valid . . .) {
result = "Please enter your employee id...";

// We don't want the above error prompt to be
// put into the result cache, so we must
// call skipCache.
skipCache();
else {
result = [. . . Generate report . . .];
}
return result(result);
}
}


Related Topics
deleteCache( )DeleteCache( ),
removeAllCachedResults( )RemoveAllCachedResults( ),
removeCachedResult( )RemoveCachedResult( ),
isCached( )IsCached( ),
setCacheCriteria( )SetCacheCriteria( ),
IValList interface IGXValList interface

"Caching AppLogic Results to Improve Performance"


streamResult( )


StreamResult( )

Streams results as a string.

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.


Tips

  • 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.


Example 1
// Stream header and body, passing the header and body data
// as variables.
streamResultHeader(headerVariable);
streamResult(bodyVariable);
Example 2
// Stream header or body in several parts, using several
// method calls, starting with the header
streamResultHeader(startHeader);
streamResultHeader(finishHeader);
streamResult(bodyStart);
streamResult(bodyMiddle);
streamResult(bodyEnd);


Related Topics
streamResultBinary( )StreamResultBinary( ),
streamResultHeader( )StreamResultHeader( )

"Streaming Results"


streamResultBinary( )


StreamResultBinary( )

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.


Tips

  • 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"


streamResultHeader( )


StreamResultHeader( )

Streams header data.

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:

"Content-Type: text/html"

"Location: <redirect url>"

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.


Example 1

// Stream header and body, passing the header and body data
// as variables.
StreamResultHeader(headerVariable);
StreamResult(bodyVariable);

Example 2

// Stream header or body in several parts, using several
// method calls, starting with the header
StreamResultHeader(startHeader);
StreamResultHeader(finishHeader);
StreamResult(bodyStart);
StreamResult(bodyMiddle);
StreamResult(bodyEnd);


Related Topics
streamResult( )StreamResult( ),
streamResultBinary( )StreamResultBinary( )

"Streaming Results"



BaseUtils class

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( )


Methods


Table 2.7

Method

Description

convertITemplateDataToResultSet( )  

Creates a ResultSet wrapper for an ITemplateData object.  

createListRowSet( )  

Creates a RowSet object that conforms to the IListRowSet interface.  

createMethodHash( )  

Creates a method hash.  

createStringFromBuffer( )  

Creates a string from an IBuffer object.  

doubleQuote( )  

Converts each occurrence of one single quote to two successive single quotes.  

includeJSP( )  

A convenience method for streaming a JSP file.  

initRowSets( )  

Initializes RowSet objects specified in a servlet's configuration file.  

log( )  

Calls the log( ) method in the AppLogic class and logs an error to the error output.  


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.


createListRowSet( )

Creates a RowSet object that conforms to the IListRowSet interface.


Syntax
public static IListRowSet createListRowSet(
   HttpServletRequest request,
   HttpServletResponse response,
   String listName)

request. The request object.

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


createMethodHash( )

Creates a method hash.


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.


Return Value
A method hash.


Related Topics
getStaticMethodCache( ) in the DBRowSet class


createStringFromBuffer( )

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");

IBuffer buff;

buff = map.get("foo",null,null);


Related Topics
Util class,
IBuffer interface


doubleQuote( )

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:

select *

from emp

where (ename = ':NameInput')

If the name is O'Reilly, then the following query would be loaded:

select *

from emp

where (ename ='O'Reilly')

Normally, an attempt to execute this query results in a syntax error. The correct query should be as follows:

select *

from emp

where (ename ='O''Reilly')

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.


Example


// Create a DBRowSet from a query in a query file for output.
DBRowSet ds = new DBRowSet(this, "main", "query_filename.gxq",
   "connection_name");

bindLoadValue("NameInput",
   BaseUtils.doubleQuote(request.getParameter("NameInput")));
ds.setQueryName("query_name");
request.setAttribute(ds.getName(),ds); // Ready for output!


Related Topics
DBRowSet class, GX class


includeJSP( )

A convenience method for streaming a JSP file.


Syntax
public static void includeJSP(
   HttpServletRequest request,
   HttpServletResponse response,
   String name) throws ServletException, IOException

request. The request object.

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.


initRowSets( )

Initializes RowSet objects specified in a servlet's configuration file.


Syntax
public static int initRowSets(
   HttpServletRequest request,
   HttpServletResponse response)

request. The request object.

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


log( )

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

  • GXLOG.GXEVENTTYPE_ERROR

  • GXLOG.GXEVENTTYPE_SYSTEM

  • GXLOG.GXEVENTTYPE_WARNING

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



DBRowSet class

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

request. The request object.

response. The response object.

name. The name of the RowSet.

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
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.




absolute( )  

getBytes( )  

getShort( )  

afterLast( )  

getCharacterStream( )  

getString( ) — see note below  

beforeFirst( )  

getClob( )  

getTime( )  

first( )  

getDate( )  

getTimeStamp( )  

getArray( )  

getDouble( )  

isLast( )  

getAsciiStream( )  

getFloat( )  

last( )  

getBigDecimal( )  

getInputFormat( )  

moveToCurrentRow( )  

getBinaryStream( )  

getInt( )  

moveToInsertRow( )  

getBlob( )  

getLong( )  

next( )  

getBoolean( )  

getObject( )  

previous( )  

getByte( )  

getRef( )  

relative( )  


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( ).

  • execute( )

  • getCommand( )

  • getStatement( )

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:




setArray( )  

setByte( )  

setDouble( )  

setObject( )  

setAsciiStream( )  

setBytes( )  

setFloat( )  

setRef( )  

setBigDecimal( )  

setCharacterStream( )  

setInt( )  

setShort( )  

setBinaryStream( )  

setClob( )  

setLong( )  

setString( )  

setBlob( )  

setCommand( )  

setName( )  

setTime( )  

setBoolean( )  

setDate( )  

setNull( )  

setTimestamp( )  

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.

  • 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( ).
For more information about the previous set methods, see the corresponding methods in the standard javax.sql.RowSet interface.


Other Methods
The remaining DBRowSet methods are described here, with the DBRowSet class. These methods are summarized in the following table:


Table 2.8

Method  

Description  

bindLoadValue( )  

Sets a parameter to a particular String value, prior to loading the query.  

clearParameters( )  

Clears the list of parameters.  

getFetchSize( )  

Retrieves the value required by the FetchSize hidden field for iAB's "VCR" support.  

getLoadParameter( )  

Gets the parameter index for a particular parameter in the query.  

getName( )  

Gets the name for the RowSet.  

getNextRowNumber( )  

Retrieves one record number beyond the last one that has been printed out.  

getQueryFile( )  

Gets the name of the file that was used (or will be used) to load queries.  

getQueryName( )  

Gets the name of the query to be loaded from the query file.  

getRowNumber( )  

Retrieves the last record number that has been displayed.  

getStaticMethodCache( )  

Retrieves the method cache for a particular class.  

getString( )  

Overloads the getString(String) method to use a iASString instead.  

init( )  

Loads the query.  

initMetaInfo( )  

Initializes the RowSet to match specific metadata.  

isEqualToExpression( )  

Evaluates a field specification in an HTML template.  

isEqualToValue( )  

Evaluates a field specification in an HTML template.  

isExecuted( )  

Determines whether the RowSet is being executed.  

isInitialized( )  

Determines whether the RowSet is initialized.  

isLastFetchableRecord( )  

Returns null if the current record is the last fetchable record; otherwise, it returns the null string.  

setExecuted( )  

Sets whether the RowSet is being executed.  

setInitialized( )  

Sets whether the RowSet is initialized.  

setName( )  

Sets the name for the RowSet.  

setQueryFile( )  

Sets the name of the file that was used or will be used to load queries.  

setQueryName( )  

Resets the DBRowSet to access only the given query.  

setRequest( )  

Sets the request object in which the RowSet will run.  

setResponse( )  

Sets the response object in which the RowSet will run.  


bindLoadValue( )

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:

select * from emp

where :whereClause

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.


clearParameters( )

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).


getFetchSize( )

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


getLoadParameter( )

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.


getName( )

Gets the name for the RowSet.


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.


Related Topics
setName( )


getNextRowNumber( )

Retrieves one record number beyond the last one that has been printed out.


Syntax
public String getNextRowNumber(
   iASString unused)

unused. Not used.


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%


Return Value
A String.


Related Topics
getRowNumber( )


getQueryFile( )

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.


Return Value
A String.


Related Topics
setQueryFile( ), getQueryName( )


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.


Return Value
A String.


Related Topics
setQueryName( ), getQueryFile( )


getRowNumber( )

Retrieves the last record number that has been displayed.


Syntax
public String getRowNumber(
   iASString groupName)

groupName. Not used.


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%


Return Value
A String.


Related Topics
getNextRowNumber( )


getStaticMethodCache( )

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


getString( )

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.


Return Value
A String.


Related Topics
javax.sql.RowSet interface


init( )

Loads the query.


Syntax
public void init()


Usage
The init( ) method is called implicitly during the execute( ) call.


Related Topics
execute( ), initMetaInfo( )


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.


isEqualToExpression( )

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:


MemRowSet ds = new MemRowSet();
ds.setRequest(request);
ds.setResponse(response);
ds.setName("myList");

ds.addListItem("Star Trek", "1");
ds.addListItem("Babylon 5", "2");
ds.addListItem("Red Dwarf", "3");
ds.addListItem("Crusade", "4");
ds.setListSelection("2"); // Babylon 5 is the default selection
request.setAttribute(ds.getName(), ds);

To display this list on a web page, you might create an HTML template containing the following code:

<SELECT NAME="TVShow">

%gx type=tile id=myList%

<OPTION VALUE="%gx type=cell id=myList.value% %/gx%"

%gx

type=cell

id=myList.isEqualToExpression(

   myList.value=myList.ListSelection)%SELECTED

%/gx%

>

%gx type=cell id=myList.label%%/gx%

%/gx%

</SELECT>


Return Value
Returns null if the expression is true, or "" if the expression is false.


Related Topics
isEqualToValue( ),
MemRowSet class


isEqualToValue( )

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)>

   HTML specific to ALLMINE

</gx>


Return Value
Returns null if the expression is true, or "" if the expression is false.


Related Topics
isEqualToExpression( )


isExecuted( )

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.


Related Topics
setExecuted( )


isInitialized( )

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( )


isLastFetchableRecord( )

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%>


setExecuted( )

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.


Related Topics
isExecuted( )


setInitialized( )

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( )


setName( )

Sets the name for the RowSet.


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.


setQueryFile( )

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( )


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( )


setRequest( )

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.


setResponse( )

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.



DefaultHttpSession class

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:

  • getCreationTime( )

  • getValueNames( )

  • getId( )

  • invalidate( )

  • getLastAccessedTime( )

  • isNew( )

  • getMaxInactiveInterval( )

  • putValue( )

  • getSessionContext( )

  • removeValue( )

  • getValue( )

  • setMaxInactiveInterval( )

For more information on the previous methods, see the interface javax.servlet.http.HttpSession.

DefaultHttpSession contains the following additional methods:




Method

Description

getHttpSession( )  

Returns the delegated implementor of the HttpSession methods.  

getString( )  

Returns a String value from an HttpSession object.  

setHttpSession( )  

Sets the delegated implementor of all HttpSession methods.  


Related Topics

getHttpSessionBean( ) in the HttpServletRequest2 interface,
DefaultHttpSession2 class


getHttpSession( )

Returns the delegated implementor of the HttpSession methods.


Syntax
public HttpSession getHttpSession()


Return Value
An HttpSession object.


Related Topics
setHttpSession( )


getString( )

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.


Return Value
A String.


Related Topics
getValue( ) method in the HttpSession interface, from the Java Servlet API.


setHttpSession( )

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( )



DefaultHttpSession2 class

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:

  • getBytes( )

  • isAuthorized( )

  • putBytes( )

  • getInt( )

  • loginSession( )

  • putInt( )

  • getString( )

  • logoutSession( )

  • putString( )

For more information on the previous methods, see the HttpSession2 interface in this guide.

DefaultHttpSession2 contains the following additional methods:




Method

Description

getHttpSession( )  

Returns the delegated implementor of the HttpSession2 methods.  

getString( )  

Overrides the invalidate( ) method of DefaultHttpSession to clear out the pointer to the session delegate.  

setHttpSession( )  

Sets the delegated implementor of all HttpSession2 methods.  


Related Topics

getHttpSessionBean( ) in the HttpServletRequest2 interface,
DefaultHttpSession class


getHttpSession2( )

Returns the delegated implementor of the HttpSession2 methods.


Syntax
public HttpSession2 getHttpSession2()


Return Value
An HttpSession2 object.


Related Topics
setHttpSession2( )


invalidate( )

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


setHttpSession2( )

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( )



DefaultHttpSession2 class

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:

  • getBytes( )

  • isAuthorized( )

  • putBytes( )

  • getInt( )

  • loginSession( )

  • putInt( )

  • getString( )

  • logoutSession( )

  • putString( )

For more information on the previous methods, see the HttpSession2 interface in this guide.

DefaultHttpSession2 contains the following additional methods:




Method

Description

getHttpSession( )  

Returns the delegated implementor of the HttpSession2 methods.  

getString( )  

Overrides the invalidate( ) method of DefaultHttpSession to clear out the pointer to the session delegate.  

setHttpSession( )  

Sets the delegated implementor of all HttpSession2 methods.  


Related Topics

getHttpSessionBean( ) in the HttpServletRequest2 interface,
DefaultHttpSession class


getHttpSession2( )

Returns the delegated implementor of the HttpSession2 methods.


Syntax
public HttpSession2 getHttpSession2()


Return Value
An HttpSession2 object.


Related Topics
setHttpSession2( )


invalidate( )

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


setHttpSession2( )

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( )



GUID class (deprecated)

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:

GUID myGUID;

myGUID = new GUID();


Package

com.kivasoft.types


Methods


Table 2.12

Method

Description

GUID( )  

Creates a GUID object.  

isNull( )  

Determines whether the GUID object is null (all zeros).  

reset( )  

Resets the GUID object to null (all zeros).  


Extends

Object.


Example


String str;
// Create a unique GUID string
str = runprogram("kguidgen", null, null, null);
if (str != null) {
//example: str = "{E8128C30-6BF8-11cf-96FC-0020AFED9A65}";
GUID guid;
guid = new GUID(str);
if (!guid.isNull()) {
return guid;
}
}
return null;
}


GUID( )

Creates a GUID object.


Syntax 1
This version, the default constructor method, creates a null GUID containing all zeros.

public guid()


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).


Example


String str;
// Create a unique GUID string
str = runprogram("kguidgen", null, null, null);
if (str != null) {
// example: str = "{E8128C30-6BF8-11cf-96FC-0020AFED9A65}";
GUID guid;
guid = new GUID(str);
if (!guid.isNull()) {
return guid;
}
}
return null;
}


Related Topics
isNull( ), reset( )


isNull( )

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.


Example


if (!guid.isNull()) {
return guid;
}


Related Topics
GUID( ), reset( )


reset( )

Resets the GUID object to null (all zeros). A null GUID object has the following format:

{00000000-0000-0000-0000-000000000000}


Syntax
public void reset()


Example


// Reset a GUID to null
guid.reset();
// At this point, guid.isNull() returns true


Related Topics
GUID( ), isNull( )



GX class (deprecated)

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:

IBuffer buff;

buff = GX.CreateBuffer();


Package

com.kivasoft.util


Methods


Table 2.13

Method

Description

CreateBuffer( )  

Creates a new IBuffer object, which represents a block of memory.  

CreateBufferFromString( )  

Creates a new IBuffer object, which represents a block of memory, and assigns a string value to it.  

CreateStreamBuffer( )  

Creates a new IStreamBuffer object, which represents a buffer for capturing streamed output during template processing.  

CreateTemplateDataBasic( )  

Creates a new ITemplateData object, which represents a hierarchical source of data.  

CreateTemplateMapBasic( )  

Creates a new ITemplateMap object, which represents a mapping between a template field specification and dynamic data used for template processing.  

CreateValList( )  

Creates a new IValList object, which represents a collection of values.  

ProcessOutput( )  

Processes the results in an AppLogic's output IValList (vOut) and returns an ITile object from which the caller can extract data.  

Release( )  

Releases an object from memory.  

WaitForOrder( )  

Waits for asynchronous operations, such as database queries, to be completed.  


CreateBuffer( )

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)


CreateBufferFromString( )

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.


Example


String str = "StateName";
IBuffer buff;
buff = GX.CreateBufferFromString(str);
...
ITemplateMap tmplmap;
tmplmap.put("$STATES", buff);


Related Topics
IBuffer Interface (deprecated)


CreateStreamBuffer( )

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)


CreateTemplateDataBasic( )

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:

TemplateDataBasic td;

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.


// Create the TemplateDataBasic objects.
// CreateTemplateDataBasic() returns an ITemplateData
// object, which is cast to TemplateDataBasic
TemplateDataBasic acctsTempDB = (TemplateDataBasic)GX.CreateTemplateDataBasic("CustAccts");
TemplateDataBasic acctsTempDB2 = (TemplateDataBasic)GX.CreateTemplateDataBasic("CustAccts2");

String acctDesc;
String acctNum;

// Get the indices of columns in the result set
int acctDescCol = rs.getColumnOrdinal("OBAcctType_acctDesc");
int acctNumCol = rs.getColumnOrdinal("OBAcct_acctNum");

// Loop through the result set and add rows to the
// TemplateDataBasic objects
do
{
acctDesc = rs.getValueString(acctDescCol);
acctNum = rs.getValueString(acctNumCol);

String newRowString = "acctDesc=" + acctDesc + ";" +
"acctNum=" + acctNum;

log(newRowString);
acctsTempDB.rowAppend(newRowString);
acctsTempDB2.rowAppend(newRowString);
} while (rs.fetchNext() == 0);

//Create a dummy parent to contain the two template objects
TemplateDataBasic parentTempDB = (TemplateDataBasic)GX.CreateTemplateDataBasic("Parent");
parentTempDB.rowAppend("Dummy=dummy");// one dummy row
parentTempDB.groupAppend(acctsTempDB);
parentTempDB.groupAppend(acctsTempDB2);

// Merge the template data results with a template
if (evalTemplate("GXApp/OnlineBank/templates/Transfer.html", parentTempDB, null) != 0)
{
return handleOBSystemError("Unable to handle template");
}
return (result(null));


Related Topics
evalOutput( ) and evalTemplate( ) in the AppLogic class (deprecated)

ITemplateData Interface (deprecated)

TemplateDataBasic class (deprecated)


CreateTemplateMapBasic( )

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:

TemplateMapBasic tmplmap;

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)


CreateValList( )

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.


Example


IValList params;
params = GX.CreateValList();
params.setValString(":Make", "Acura")
params.setValString(":Model", "Integra")
...
resultset = pqry.execute(0, params, null, null);


Related Topics
IValList interface


ProcessOutput( )

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:

  1. A client (AppLogic or OCL client application) calls an AppLogic with newRequest( ).

  2. 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.

  3. The called AppLogic processes the request and returns results in the output IValList.
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.


Return Value
ITile object, or null for failure.


Example


// Call an AppLogic
hr = newRequest(guid, vIn, vOut, 0);
if (hr == GXE.SUCCESS)
{
// Get the root tile from the output vallist
ITile roottile = GX.ProcessOutput(null, 0, vOut);
if (roottile != null)
{
String sval;
ITile ptile;

//Iterate over all products and print their names
ptile = roottile.getTileChild("PRODUCTS");
hr = GXE.SUCCESS;
System.out.println("Products:");
while (ptile != null && hr != GXE.FAIL)
{
sval = ptile.getTileValue("PRODUCTS.ProdName");
System.out.println(" " + sval);

hr = ptile.moveTileNextRecord();
}


Related Topics
newRequest( ) in the AppLogic class (deprecated)

ITile Interface (deprecated)


Release( )

Releases an object from memory.


Syntax
public static int Release(
   Object obj)

obj. The object to release.


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);


WaitForOrder( )

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.

  • The specified timeout limit has been exceeded.

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.


Example


class MyAppLogic extends AppLogic
execute(){
...
IOrder orders[] = new orders[5];
// fill array with order objects

int done_index = GX.WaitForOrder(orders, this.context,
timeout);
if (done_index >= 0)
System.out.println("order finished:" +
orders[done_index]);
else
System.out.println("error or timeout occurred");


Related Topics
IOrder Interface (deprecated)



GXContext class

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:

GXContext.method

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;

kivaContext = this.context;


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:

HttpServletRequest req;

HttpServletRequest2 req2;

req2 = (HttpServletRequest2) req; // legal cast within iPlanet Application Server

AppLogic al = req2.getAppLogic();

com.kivasoft.IContext kivaContext;

kivaContext = al.context;


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;

.

.

.


Package

com.kivasoft.dlm


Methods


Table 0.5

Method

Description

createMailbox( )  

Creates an electronic mailbox object used for communicating with a user's mailbox.  

destroySession( )  

Deletes a user session.  

GetAppEventMgr( )  

Retrieves the object for managing application events.  

GetObject( )  

Retrieves an object from the context.  

GetSession( )  

Retrieves a session other than the current one.  

GetSessionCount( )  

Returns the number of sessions in a iPlanet Application Server cluster.  

getStateTreeRoot( )  

Returns an existing root node of a state tree or creates a new one.  

log( )  

Writes a message to the server log.  

newRequest( )  

Calls an AppLogic.  

newRequestAsync( )  

Calls another AppLogic and runs it asynchronously.  


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


CreateMailbox( )

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).


DestroySession( )

Deletes a user session.


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( )


GetAppEventMgr( )

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


GetObject( )

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,

"com.kivasoft.IModuleData");


GetSession( )

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."

dwFlags. Specify 0 (zero).

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.


GetSessionCount( )

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."

dwFlags. Unused.

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.


GetStateTreeRoot( )

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.


IState2 tree = GetStateTreeRoot(m_Context,
GXSTATE.GXSTATE_DISTRIB,
"Grammy");

if (tree!=null)
{
IState2 child = tree.getStateChild("Best Female Vocal");
if (child == null)
{
child = tree.createStateChild("Best Female Vocal", 0,
GXSTATE.GXSTATE_DISTRIB);


Log( )

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

  • GXLOG.GXEVENTTYPE_ERROR

  • GXLOG.GXEVENTTYPE_SYSTEM

  • GXLOG.GXEVENTTYPE_WARNING

category. User-defined message category. Do not use the range of values reserved for the iPlanet systems, which is 0 to 65535, inclusive.

msg. Message text to log.


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");


NewRequest( )

Calls an AppLogic.


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.

flags. Specify zero.


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.

  • 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( ).
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:

vallist.setValString("gx_client_type", "ocl");


Rule
The specified GUID string, input parameters, and output parameters must be valid for the specified AppLogic.


Tips

  • 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

// Call specified AppLogic and pass parameters
NewRequest(m_Context,
"{E5CA1000-6EEE-11cf-96FD-0020AFED9A65}",
paramsToModule, paramsReturned,0);
Example 2
// Use DisplayBasket AppLogic to display the contents
if(NewRequest(m_Context, "DisplayBasket",
valIn, valOut,0)==0){
return 0;
}
else
return result("Cannot execute DisplayBasket AppLogic");


NewRequestAsync( )

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.

flags. Specify 0.


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.


Example


IOrder Orders[1];
ULONG nOrder;
HRESULT hr, ReqResult;

Orders[0] = NewRequestAsync(m_Context, asyncGUIDStr, valIn,
valOut, 0);
if (Orders[0] != null)
{
Log(m_Context, "Successfully invoked async AppLogic\n");

// wait for async applogic to finish (max 100 seconds)
hr = waitForOrder(Orders, context, 100);
if (hr != GXE.SUCCESS)
{
return result("Error in executing async request:
            order wait returned an error");
}
else
{
getStateIOrder state = Orders[0].getState();
if (state == null || state.pdwState != GXE.SUCCESS)
return result("Error in executing async request");
}
}
else
{
Log(m_Context,
GXLOG.GXLOG.GXEVENTTYPE_WARNING,
-1,
"Failed to invoke async AppLogic\n");
}



GXVAL class (deprecated)

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:


import com.kivasoft.types.*;
GXVAL v;
v = new GXVAL();
// Set the member variable vt to the double type
v.vt = GXVALTYPE_ENUM.GXVT_R8;
// Call the accessor method for the double type. The member
// variable u holds the value and has accessor methods.
v.u.dblVal(123.45);

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.


Table 2.14

Java type

Accessor method

GXVAL type

char  

cVal( )  

GXVT_I1  

int  

iVal( )  

GXVT_I2  

int  

lVal( )  

GXVT_I4  

float  

fltVal( )  

GXVT_R4  

double  

dblVal( )  

GXVT_R8  

boolean  

boolVal( )  

GXVT_BOOL  

char  

bVal( )  

GXVT_UI1  

int  

uiVal( )  

GXVT_UI2  

int  

ulVal( )  

GXVT_UI4  

java.lang.string  

pstrVal( )  

GXVT_LPSTR  

byte[ ]  

pbyteVal( )  

GXVT_BLOB  

int  

pvoidVal( )  

GXVT_VOID  


Package

com.kivasoft.types


Example


import com.kivasoft.types.*;

IValList vallist = GX.CreateValList();
GXVAL x = new GXVAL();
x.vt = GXVALTYPE_ENUM.GXVT_R8;
x.u.dblVal(123.45);
vallist.setVal("test", x);

GXVAL y;
y = vallist.getVal("test");
if (y.vt == GXVALTYPE_ENUM.GXVT_R8 && y.u.dblVal() == 123.45){
//success
}



MemRowSet class

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 SQLException

In 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.

  • DBRowSet class, from package com.iplanet.server.servlet.extension.

  • RowSet interface, from package javax.sql.

  • ResultSet interface, from package java.sql.
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.

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.





Method

New Behavior of Overridden Method

absolute( )  

See separate description below table.  

addListItem( )  

New method. Adds a new item into a MemRowSet that is being used as an IListRowSet. See separate description below table.  

addRow( )  

New method. Adds data as a separate row into the data source. See separate description below table.  

addValue( )  

New method. Queues a value for later addition into the data source. See separate description below table.  

afterLast( )  

Can never be called. Always throws SQLException.  

beforeFirst( )  

Can never be called. Always throws SQLException.  

cancelRowUpdates( )  

Does nothing.  

clearWarnings( )  

Does nothing.  

close( )  

Removes the reference to the ITemplateData object.  

deleteRow( )  

Can never be called. Always throws SQLException.  

execute( )  

Sets MemRowSet to the "executing" status.  

findColumn( )  

Returns -1. Columns are not indexed for MemRowSets.  

first( )  

Can never be called. Always throws SQLException.  

getArray( )  

Returns null.  

getAsciiStream( )  

Returns null.  

getBigDecimal( )  

Returns null.  

getBinaryStream( )  

Returns null.  

getBlob( )  

Returns null.  

getBoolean( )  

Returns false.  

getByte( )  

Returns -1.  

getBytes( )  

Returns null.  

getCharacterStream( )  

Returns null.  

getClob( )  

Returns null.  

getCommand( )  

Returns null.  

getConcurrency( )  

Returns -1.  

getCursorName( )  

Returns null.  

getDate( )  

Returns null.  

getDouble( )  

Returns -1.  

getFetchDirection( )  

Returns -1.  

getFetchSize( )  

Rreturns -1.  

getFloat( )  

Returns -1.  

getInt( )  

Returns -1.  

getListSelection( )  

New method. Gets the list selection of the MemRowSet that is being used as an IListRowSet. See separate description below table.  

getLoadParameter( )  

Returns 0.  

getLong( )  

Returns -1.  

getMetaData( )  

Returns a class that can use ITemplateData objects.  

getObject( )  

With a String parameter, returns the value returned by getString( ); with an int parameter, returns null.  

getQueryName( )  

Returns null.  

getRef( )  

Returns null.  

getRow( )  

Returns the row number whose contents can currently be examined.  

getShort( )  

Returns -1.  

getStatement( )  

Returns null.  

getStaticMethodCache( )  

Retrieves the method cache for a particular class.  

getString( )  

With a String parameter, returns the value returned by its superclass; this form is not overridden. With an int parameter, returns null.  

getString( )  

With a iASString parameter, either returns the list selection or redirects to the underlying ITemplateData data source.  

getTemplateData( )  

New method. Gets the data source of the RowSet. See separate description below table.  

getTime( )  

Returns null.  

getTimeStamp( )  

Returns null.  

getType( )  

Returns -1.  

getUnicodeStream( )  

Returns null.  

insertRow( )  

Can never be called. Always throws SQLException.  

isAfterLast( )  

Delegates to the ITemplateData data source. If the RowSet hasn't been accessed, this method returns the value of isEmpty( ) on the ITemplateData. Otherwise, this method returns false.  

isBeforeFirst( )  

Returns the value of the ITemplateData's isEmpty( ).  

isFirst( )  

Returns true.  

isLast( )  

Returns false.  

last( )  

Must never be called. Always throws SQLException.  

moveToCurrentRow( )  

Does nothing.  

moveToInsertRow( )  

Does nothing.  

next( )  

Called by the template engine to return the next row.  

previous( )  

Can never be called. Always throws SQLException.  

refreshRow( )  

Does nothing.  

relative( )  

Does nothing.  

rowDeleted( )  

Returns false.  

rowInserted( )  

Returns false.  

rowUpdated( )  

Returns false.  

setCommand( )  

Stubs out uninteresting DBRowSet functionality.  

setFetchDirection( )  

Does nothing.  

setFetchSize( )  

Does nothing.  

setListSelection( )  

New method. Sets the list selection on the MemRowSet that is being used as an IListRowSet. See separate description below table.  

setName( )  

Does nothing.  

setQueryName( )  

Stubs out uninteresting DBRowSet functionality.  

setTemplateData( )  

New method. Sets the data source to the provided TemplateDataBasic. See separate description below table.  

setupQuery( )  

Stubs out uninteresting DBRowSet functionality.  

updateAsciiStream( )  

Does nothing.  

updateBigDecimal( )  

Does nothing.  

updateBinaryStream( )  

Does nothing.  

updateBoolean( )  

Does nothing.  

updateByte( )  

Does nothing.  

updateBytes( )  

Does nothing.  

updateCharacterStream( )  

Does nothing.  

updateDate( )  

Does nothing.  

updateDouble( )  

Does nothing.  

updateFloat( )  

Does nothing.  

updateInt( )  

Does nothing.  

updateLong( )  

Does nothing.  

updateNull( )  

Does nothing.  

updateObject( )  

Does nothing.  

updateShort( )  

Does nothing.  

updateString( )  

Does nothing.  

updateTime( )  

Does nothing.  

updateTimestamp( )  

Does nothing.  

wasNull( )  

Returns false.  


addListItem( )

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:


MemRowSet ds = new MemRowSet();
ds.setRequest(req);
ds.setResponse(res);
ds.setName("myList");
ds.addListItem("Star Trek", "1");
ds.addListItem("Babylon 5", "2");
ds.addListItem("Red Dwarf", "3");
ds.addListItem("Crusade", "4");
ds.setListSelection("2"); // Babylon 5 is the default selection
req.setAttribute(ds.getName(),ds);

To display this list on a web page, you might create an HTML template containing the following code:


<SELECT NAME="TVShow">
%gx type=tile id=myList%
<OPTION VALUE="%gx type=cell id=myList.value% %/gx%"
%gx
type=cell
id=myList.isEqualToExpression(
   myList.value=myList.ListSelection)%SELECTED
%/gx%
>

%gx type=cell id=myList.label%%/gx%
%/gx%
</SELECT>


Related Topics
setListSelection( )


addRow( )

Adds data as a separate row into the data source.


Syntax
public int addRow()


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.


Example


MemRowSet ds = new MemRowSet();
ds.setRequest(req);
ds.setResponse(res);
ds.setName("tryMe");
ds.addValue("col1", "Hello");
ds.addValue("col2", "World");
ds.addRow();
ds.addValue("col1", "GoodBye");
ds.addValue("col2", "World");
ds.addRow();
req.setAttribute(ds.getName(),ds);

The previous code, along with an HTML template containing the following:

<gx type=tile id=tryMe>

<gx type=cell id=tryMe.col1></gx> <gx type=cell id=tryMe.col2><%gx>

<BR>

</gx>

would produce:

Hello World

Goodbye World


Return Value
Unused. Always 0.


Related Topics
addValue( ), addListItem( )


addValue( )

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.


Related Topics
addRow( )


getListSelection( )

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( )


getTemplateData( )

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:

  • implicitly, as a result of calling addRow( ).

  • by calling setTemplateData( ).

Return Value
An ITemplateData representing the data source.


Related Topics
setTemplateData( )


setListSelection( )

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( )


setTemplateData( )

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( )



iAS6.0RowSet class

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:

    • javax.sql.RowSet

    • javax.sql.RowSetReader

    • javax.sql.RowSetWriter

    • javax.sql.RowSetInternal

  • 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:


Table 0.7

Method

Argument

Action

Reason

setReadOnly( )  

false  

throws SQLException  

iASRowSet is already read-only.  

setType()  

TYPE_SCROLL_ SENSITIVE  

throws SQLException  

Argument is not supported.  

setConcurrency( )  

CONCUR_ UPDATABLE  

throws SQLException  

iASRowSet is read-only.  

addRowSetListener( )  

any  

None  

Not supported.  

removeRowSetListener( )  

any  

None  

Not supported.  

setNull( )  

any type name  

ignores argument  

Not supported.  

setTypeMap( )  

java.util.Map  

None  

Map is a JDK 1.2 feature, so is not supported.  


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( )

  • cancelRowDelete( )

  • cancelRowInsert( )

  • getShowDeleted( )

  • restoreOriginal( )

  • setShowDeleted( )

  • setWriter( )
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.

For example:

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



iASString 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:


Table 0.8

Constructor

Type of iASString Created

public iASString()  

Allocates a new iASString containing no characters. Using this constructor is not recommended.  

public iASString(

String value)  

Allocates a new iASString that shadows the passed-in String. The iASString will be identical to the shadow string, except that it is changeable.  

public iASString(

iASString value)  

Allocates a new iASString that is identical to the current substring of the passed-in iASString.  


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.


Table 2.15

Method

Description

equals( )  

Compares this iASString to the specified parameter.  

makeSubstring( )  

Modifies this iASString to point to a substring of shadow.  

setValue( )  

Resets the value of this iASString to shadow the specified String.  


equals( )

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:

    • a String object that represents the same sequence of characters as this object

    • an iASString that shadows a substring of a String representing 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 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
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.


Return Value
Returns true if the previous conditions are met; otherwise, returns false.


makeSubstring( )

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.


setValue( )

Resets the value of this iASString to shadow the specified String.


Syntax
public void setValue(
   String val)

val. The String to shadow.


Usage
Use setValue( ) to reset the value of this iASString to shadow the specified String.



iASStringBuffer class

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:


Table 0.9

Constructor

Type of iASStringBuffer Created

public iASStringBuffer()  

Contains the empty string.  

public iASStringBuffer
(String aString)
 

Contains the characters in aString. The buffer is copied, not referenced.  

public iASStringBuffer(
String aString,
int start,
int end)
 

Contains the range of characters in aString from the index start to end, with end excluded.  

public iASStringBuffer(
char aChar)
 

Contains the character aChar.  

public iASStringBuffer(
int size)
 

Has the given length.  

public iASStringBuffer
(iASStringBuffer nsb)
 

Contains another iASStringBuffer's contents. The buffer is copied, not referenced.  

public iASStringBuffer
(char buff[])
 

Contains the specified character array. The buffer is copied, not referenced.  


Methods


Table 2.16

Method

Description

append( )  

Appends a character or string to the iASStringBuffer.  

charArray( )  

Returns the iASStringBuffer's character array.  

charAt( )  

Returns the character at the specified index.  

ensureCapacity( )  

Makes sure that the StringBuffer has enough space to contain "newCapacity" characters.  

equals( )  

Compares the contents of this iASStringBuffer with the contents of another iASStringBuffer.  

getChars( )  

Copies characters from the iASStringBuffer to the specified destination array.  

indexOf( )  

Returns the index of the first occurrence of the specified character in the iASStringBuffer.  

insert( )  

Inserts a character or string into the iASStringBuffer.  

length( )  

Returns the number of characters in the iASStringBuffer.  

moveChars( )  

Moves the tail of the string, by removing characters.  

removeCharAt( )  

Removes the character at the specified index.  

replace( )  

Replaces the given range with a string, or removes the given range.  

setCharAt( )  

Sets the value of a character at the specified index.  

setLength( )  

Truncates the iASStringBuffer to the specified number of characters.  

setStringValue( )  

Sets the contents of the iASStringBuffer to the characters in the specified string.  

tabOrSpaceAt( )  

Determines whether a tab or space exists at the specified index.  

toString( )  

Returns the String for the iASStringBuffer's contents.  

trimToSize( )  

Truncates the internal character array to match the size of the contained string.  

truncateToLength( )  

Same as the trimToSize( ) method.  


append( )

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.


charArray( )

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.


charAt( )

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.


ensureCapacity( )

Makes sure that the StringBuffer has enough space to contain "newCapacity" characters.


Syntax
public void ensureCapacity(
   int newCapacity)


Usage
Called internally.


equals( )

Compares the contents of this iASStringBuffer with the contents of another iASStringBuffer.


Syntax
public boolean equals(
   iASStringBuffer value)


Usage
Specify a value to compare.


getChars( )

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.


indexOf( )

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:

indexOf(aChar, 0);


insert( )

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.


length( )

Returns the number of characters in the iASStringBuffer.


Syntax
public int length()


moveChars( )

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.


removeCharAt( )

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.


replace( )

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.


setCharAt( )

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.


setLength( )

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.


setStringValue( )

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.


tabOrSpaceAt( )

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.


toString( )

Returns the String for the iASStringBuffer's contents.


Syntax
public String toString()


Usage
This method overrides toString( ) in the Object class.


trimToSize( )

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.


truncateToLength( )

Same as the trimToSize( ) method.


Syntax
public void truncateToLength(
   int aLength)



Session2 class (deprecated)

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.



GXSession2 class

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:


    ISession2 s = super.createSession(flags, timeout, appname, sessionid, idgen);

    if (s!= null)
       sess = new MySession(s);

    return s;


    HRESULT hr;
    IGXSession2 *pSession = Null;
    hr = GXAgent::GetSession(dwFlags, pAppName, pIDGen, &pSession);

    if (hr == GXE_SUCCESS)
    {
       m_pSession = new MySession(pSession);
       if (!m_pSession)
        hr = GXE_ALLOC_FAILED;
       pSession->Release();
    }
    return hr;

  • Pass in the ISession2IGXSession2 interface in the subclass constructor, as shown in the following example: public class MySession extends Session2

    {

       public MySession(ISession2 sess)

    class MySession : public GXSession2

    {

       public:

        MySession(IGXSession2 *pSess);

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.


Package Include File

com.kivasoft.session gxapplogic.h


Related Topics

ISession2 Interface (deprecated)IGXSession2 interface



"Using Custom Sessions"SqlUtil class"> "Using Custom Sessions"SqlUtil class

The SqlUtil class contains helper methods for two main purposes:

  • to load queries from query files (.gxq files)

  • to create or initialize JDBC classes for database access.
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.


Package

com.kivasoft.util


Variables


Table 0.10

Variable

Description

minLocChar  

Lower end set of characters that are considered part of a variable name, in addition to a-zA-Z0-9.  

maxLocChar  

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:

public SqlUtil()


Methods


Table 0.11

Method

Description

loadQuery( )  

Loads a query.  


Examples


Example 1
The following code shows how you might use a SELECT query:


{
   int colIndex;
   int x;
   long y;
   iASRowSet rowSet = new com.iplanet.server.jdbc.iASRowSet();

   // Initialize connection info
   rowSet.setDataSourceName("jdbc/nsample");
   
   // permanent parameter substitutions in the SQL statement.
   IValList param = GX.CreateValList();
   param.setValString("REGION", "WEST");
   param.setValInt("POPULATION", 100000);

   SqlUtil.loadQuery(rowSet, "state.gxq", "STATES_select1", param);

   // temporary parameter substitutions.
   rowSet.setString(param.getValInt("STATE"), "CA");
   rowSet.execute();

   // get the return values.
   colIndex = 1;
   x = rowSet.getInt(colIndex++);
   y = rowSet.getLong(colIndex++);

   rowSet.clearParameters();
   // temporary parameter substitutions.
   rowSet.setString(param.getValInt("STATE"), "TX");
   rowSet.execute();
   
   // get the return values.
   colIndex = 1;
   x = rowSet.getInt(colIndex++);
   y = rowSet.getLong(colIndex++);
   
   rowSet.close();
}
catch (SQLException err)
{
}


Example 2
The following code shows how you might use an UPDATE query:


try
{
   String url = "jdbc:iplanet:ODBC:nsample"
   java.util.Properties props = new java.util.Properties();
   props.put("DRIVER", "ODBC");
   props.put("DSN", "nsample");
   props.put("DB", "nsample");
   props.put("user", "iplanet");
   props.put("password", "iplanet");
   Connection conn = DriverManager.getDriver(url).connect(url, props);

   // permanent parameter substitutions in the SQL statement.
   IValList param = GX.CreateValList();
   param.setValString("REGION", "WEST");
   param.setValInt("POPULATION", 100000);

   PreparedStatement prestate =
      SqlUtil.loadQuery(conn, "state.gxq", "STATES_update1", param);
   
   // temporary parameter substitutions.
   prestate.setString(param.getValInt("STATE"), "CA");
   prestate.setInt(param.getValInt("NEW_POP"), 10000);
   prestate.execute();

    prestate.clearParameters();
   // temporary parameter substitutions.
   prestate.setString(param.getValInt("STATE"), "TX");
   prestate.setInt(param.getValInt("NEW_POP"), 10000);
   prestate.execute();

   conn.close();
}
catch (SQLException err)
{
}


Related Topics

com.iplanet.server.jdbc.iAS6.0RowSet class,
java.sql.Connection interface,
java.sql.PreparedStatement interface,
javax.sql.RowSet interface


loadQuery( )

Loads a query.


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.



GXTemplateDataBasic class

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.

  • For a hierarchical data structure, proceed in the following sequence:

    1. Create the parent TemplateDataBasic( )GXTemplateDataBasic( ) instance.

    2. Create the child TemplateDataBasic( )GXTemplateDataBasic( ) instance.

    3. Add one or more rows to the child data structure using rowAppend( )RowAppend( ) on the child instance.

    4. Define the start of a new parent row by using rowAppend( )RowAppend( ) on the parent instance.

    5. Join the child data structure to the parent data structure using the parent's groupAppend( )GroupAppend( ).

    6. Repeat steps 2 through 5 for each subsequent group of data.
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( ).

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


Methods


Table 2.17

Method

Description

groupAppend( )GroupAppend( )  

Links the specified child group to the current parent group.  

rowAppend( )RowAppend( )  

Appends a new row of data to the current template data object or group.  

TemplateDataBasic( )GXTemplateDataBasic( )  

Creates an empty template data object with the specified name.  


Implements

ITemplateData Interface (deprecated)IGXTemplateData interface


Example 1


// Construct a flat result set
/* Create Data Object */
tdbSalesRev = new TemplateDataBasic("salesOffices");
/* Create records of data */
tdbSalesRev.rowAppend("office=New York;revenue=150M");
tdbSalesRev.rowAppend("office=Hong Kong;revenue=130M");
tdbSalesRev.rowAppend("office=Singapore;revenue=105M");


Example 2


// Construct a hierarchical result set with two child
// levels of data: Asia and Europe.

/* Create the hierarchical data object */
tdbContinents = new TemplateDataBasic("continents");

/* Create the Asia group */
tdbAsia = new TemplateDataBasic("countries");
/* Create child records for Asia group */
tdbAsia.rowAppend("country=China;currency=yuan");
tdbAsia.rowAppend("country=Japan;currency=yen");
tdbAsia.rowAppend("country=South Korea;currency=won");
tdbContinents.rowAppend("name=Asia");
/* Link child records to group */
tdbContinents.groupAppend(tdbAsia);

/* Create the Europe group in the same manner */
tdbEurope = new TemplateDataBasic("countries");
tdbEurope.rowAppend("country=France;currency=franc");
tdbEurope.rowAppend("country=Germany;currency=deutsche mark");
tdbEurope.rowAppend("country=Italy;currency=lire");
tdbContinents.rowAppend("name=Europe");
tdbContinents.groupAppend(tdbEurope);


Related Topics

evalTemplate( )EvalTemplate( ) and evalOutput( )EvalOutput( ) in the AppLogic class (deprecated)GXAppLogic class

ITemplateData Interface (deprecated)IGXTemplateData interface

"Constructing a Hierarchical Result Set with GXTemplateDataBasic"


groupAppend( )


GroupAppend( )

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.


Rules


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.


Example


// Construct a hierarchical result set with two child
// levels of data: Asia and Europe.

/* Create the hierarchical data object */
tdbContinents = new TemplateDataBasic("continents");

/* Create the Asia group */
tdbAsia = new TemplateDataBasic("countries");
/* Create child records for Asia group */
tdbAsia.rowAppend("country=China;currency=yuan");
tdbAsia.rowAppend("country=Japan;currency=yen");
tdbAsia.rowAppend("country=South Korea;currency=won");
tdbContinents.rowAppend("name=Asia");
/* Link child records to group */
tdbContinents.groupAppend(tdbAsia);

/* Create the Europe group in the same manner */
tdbEurope = new TemplateDataBasic("countries");
tdbEurope.rowAppend("country=France;currency=franc");
tdbEurope.rowAppend("country=Germany;currency=deutsche mark");
tdbEurope.rowAppend("country=Italy;currency=lire");
tdbContinents.rowAppend("name=Europe");
tdbContinents.groupAppend(tdbEurope);


Related Topics
evalTemplate( )EvalTemplate( ) and evalOutput( )EvalOutput( ) in the AppLogic class (deprecated)GXAppLogic class

ITemplateData Interface (deprecated)IGXTemplateData interface

"Constructing a Hierarchical Result Set with GXTemplateDataBasic"


rowAppend( )


RowAppend( )

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.


Example


// Construct a hierarchical result set with two child
// levels of data: Asia and Europe.

/* Create the hierarchical data object */
tdbContinents = new TemplateDataBasic("continents");

/* Create the Asia group */
tdbAsia = new TemplateDataBasic("countries");
/* Create child records for Asia group */
tdbAsia.rowAppend("country=China;currency=yuan");
tdbAsia.rowAppend("country=Japan;currency=yen");
tdbAsia.rowAppend("country=South Korea;currency=won");
tdbContinents.rowAppend("name=Asia");
/* Link child records to group */
tdbContinents.groupAppend(tdbAsia);

/* Create the Europe group in the same manner */
tdbEurope = new TemplateDataBasic("countries");
tdbEurope.rowAppend("country=France;currency=franc");
tdbEurope.rowAppend("country=Germany;currency=deutsche mark");
tdbEurope.rowAppend("country=Italy;currency=lire");
tdbContinents.rowAppend("name=Europe");
tdbContinents.groupAppend(tdbEurope);


Related Topics
evalTemplate( )EvalTemplate( ) and evalOutput( )EvalOutput( ) in the AppLogic class (deprecated)GXAppLogic class

ITemplateData Interface (deprecated)IGXTemplateData interface

"Constructing a Hierarchical Result Set with GXTemplateDataBasic"


TemplateDataBasic( )


GXTemplateDataBasic( )

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.


Tips

  • 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.


Example


// Construct a hierarchical result set with two child
// levels of data: Asia and Europe.

/* Create the hierarchical data object */
tdbContinents = new TemplateDataBasic("continents");

/* Create the Asia group */
tdbAsia = new TemplateDataBasic("countries");
/* Create child records for Asia group */
tdbAsia.rowAppend("country=China;currency=yuan");
tdbAsia.rowAppend("country=Japan;currency=yen");
tdbAsia.rowAppend("country=South Korea;currency=won");
tdbContinents.rowAppend("name=Asia");
/* Link child records to group */
tdbContinents.groupAppend(tdbAsia);

/* Create the Europe group in the same manner */
tdbEurope = new TemplateDataBasic("countries");
tdbEurope.rowAppend("country=France;currency=franc");
tdbEurope.rowAppend("country=Germany;currency=deutsche mark");
tdbEurope.rowAppend("country=Italy;currency=lire");
tdbContinents.rowAppend("name=Europe");
tdbContinents.groupAppend(tdbEurope);


Related Topics
evalTemplate( )EvalTemplate( ) and evalOutput( )EvalOutput( ) in the AppLogic class (deprecated)GXAppLogic class

ITemplateData Interface (deprecated)IGXTemplateData interface

"Constructing a Hierarchical Result Set with GXTemplateDataBasic"



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.



GXTemplateMapBasic class

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


Methods


Table 2.18

Put( )  

Adds a mapping to the template map.  





Method

Description

getString( )  

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.  

put( )  

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.  

putString( )  

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


// Create template map
TemplateMapBasic map = new TemplateMapBasic();
[... create a query ...]   
// map columns in table to tags in template
map.putString("ParentsSelect", selStr);
map.putString("NAME", myName);
map.putString("CATEGORY", catStr);
// Evaluate the return template using the column mappings
if(evalTemplate(HTML, (ITemplateData) null, map)==0)
return result("");
else
return result("Failed to Generate HTML");


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"


getString( )

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).

pData. Specify null.

pMark. Specify null.


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:


import com.kivasoft.*;
class myTMB extends TemplateMapBasic {
   public String getString(String key, data, mark)
   {
      if (key.equals("CURTIME"))
         return new Date().toString();
      return super.getString(key, data, mark);
   }
}


put( )


Put( )

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 <