"Developer's Guide": Java Helper Static Methods

Complete Contents
Introduction
Chapter 1 About Netscape Application Server Extensions
Chapter 2 About the Netscape Extension Builder
Chapter 3 Introduction to Netscape's Interface Definition Language
Chapter 4 Designing a Netscape Extension
Chapter 5 Generating Output Files
Chapter 6 Completing Method Stubs
Chapter 7 Using Template Streaming
Chapter 8 Managing State and Session Information
Chapter 9 Using Object Pools
Chapter 10 Compiling the Extension Source Code
Chapter 11 Deploying and Managing a Netscape Extension
Chapter 12 Example Extension: HelloWorld
Appendix A C++ Helper Functions
Appendix B Java Helper Static Methods
Appendix C Java Class Decorations
Appendix D Reserved Words
Appendix E The ConnManager.cpp File
Glossary

Contents

Index

Java Helper Static Methods

The GXContext class is a utility class that enables Java extension writers to access core Netscape Application Server functionality. The GXContext class provides a suite of helper static methods that can be used anywhere in an extension's method stubs.

You call the methods in the GXContext class by using the following convention: GXContext.<method>

The following Java helper static methods are described in this appendix:


GXContext.CreateDataConn( )	GXContext.GetObject( )
GXContext.CreateDataConnSet( )	GXContext.GetStateTreeRoot( )
GXContext.CreateHierQuery( )	GXContext.IsAuthorized( )
GXContext.CreateMailbox( )	GXContext.LoadHierQuery( )
GXContext.CreateQuery( )	GXContext.LoadQuery( )
GXContext.CreateTrans( )	GXContext.Log( )
GXContext.DestroySession( )	GXContext.NewRequest( )
GXContext.GetAppEvent( )	GXContext.NewRequestAsync( )

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

Syntax 1
Use this version for most database drivers.

public static IDataConn CreateDataConn(
IContext context,
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 static IDataConn CreateDataConn(
IContext context,
int flags,
int driver,
IValList prop)

context. An IContext object, which provides access to Netscape Application Server services. Specify m_Context if accessing this helper static method from a manager class; otherwise, use m_Module.m_Context.

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 caller 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 Netscape 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 Netscape 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. IValList 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.

Usage
A data connection is a communication link or session with a database or other data source. Before interacting with a data source, an extension 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 IDataConn interface.

Use CreateDataConn( ) to set up a separate connection for each database or data source you want to access. Extension objects refer to the data connection object in their methods that perform subsequent operations on the database.

Rules

Call 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 extension 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 extension 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 extension 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 extension can also explicitly close data connections using closeConn( ) in the IDataConn 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.

Return Value
IDataConn object representing the specified data connection, or null if a failure occurred. An extension uses the data connection object to uniquely identify this data connection in subsequent operations, such as queries and record insert, update, and delete operations.

Example
// Method to open a connection to a database

protected com.kivasoft.IDataConn getOBDataConn()

{

String username = "kdemo";

String password = "kdemo";

IDataConn newDataConn = CreateDataConn(m_Context, 0,

GX_DA_DAD_DRIVERS.GX_DA_DRIVER_ODBC,

/* Datasource name. */ "ksample",

/* Database name. */ "",

/* userName. */ username,

/* password. */ password);

if (newDataConn == null)

{

Log(m_Context, "ERROR: Could not create database connection");

}

return newDataConn;

}

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

Syntax
public static IDataConnSet CreateDataConnSet(
IContext context,
int flags)

flags. Specify 0. Internal use only.

Usage
Use CreateDataConnSet( ) only if you are loading a query file using LoadHierQuery( ). To use a query file, an extension first establishes a data connection with each database on which any queries will be run.

Next, the extension calls CreateDataConnSet( ) to create an IDataConnSet 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, the extension can use standardized queries and select and assign data connections dynamically at runtime.

Finally, the extension calls 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).

Example
IDataConnSet connSet;

connSet = CreateDataConnSet(m_Context, 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(m_Context, "employeeReport.gxq",

connSet, 0, null);

// Run the report

evalTemplate("employeeReport.html", hqry);

Related Topics
LoadHierQuery( )

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

Syntax
public static IHierQuery CreateHierQuery(
IContext context
)

Usage
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( ) instead for simple, flat queries requiring tabular, non-nested output that is merged with HTML templates.

To use a hierarchical query, an extension first creates each individual flat query and defines its selection criteria. Next, it creates the IHierQuery object with CreateHierQuery( ), then calls addQuery( ) repeatedly to add a child query to a parent query for each level of detail in the hierarchical query.

Alternatively, an extension can create a hierarchical query by loading a query file using LoadHierQuery( ). With this technique, the Netscape 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 extension 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.

Example 1
// Create the flat query

IQuery qry = CreateQuery(m_Context);

qry.setTables("CTLusers");

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

qry.setOrderBy("LoginName);

// Create the hierarchical query used for template processing

IHierQuery hqry = CreateHierQuery(m_Context);

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

qry.setTables("CTLusers");

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

qry.setWhere("UserId > 100");

// Create the hierarchical query

IHierQuery hqry = CreateHierQuery(m_Context);

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)

. . .

Related Topics
CreateDataConn( )

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)

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.

Return Value
IMailbox object representing a mailbox, or null for failure (such as an invalid parameter).

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

Syntax
public static IQuery CreateQuery(
IContext context
)

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 extension can also use CreateQuery( ) to create a query object to perform SELECT, INSERT, DELETE, or UPDATE operations on a database.

Tips

To query a database, the extension first uses CreateQuery( ) to create the query object, then constructs the query selection criteria using methods in the IQuery interface, and finally runs the query on a database server. The extension can process results using methods in the IResultSet interface.

Alternatively, the extension can pass a SQL SELECT statement directly to the database server using setSQL( ) in the IQuery interface.

To retrieve data with nested levels of information, use CreateHierQuery( ) instead.

Return Value
IQuery object representing a query, or null for failure. An extension 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.

Example
// Create the flat query object

IQuery qry = CreateQuery(m_Context);

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

Related Topics
CreateDataConn( ),

CreateQuery( )

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

Syntax
public static ITrans CreateTrans(
IContext context
)

Usage
Transaction processing allows the extension 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 extension can roll back, or abandon, any proposed changes to the target table(s).

If your application requires transaction processing, use CreateTrans( ) to create a transaction object. Pass this transaction object to subsequent methods, such as addRow( ) or executeQuery( ), that make up a transaction.

Tips

Use this method in conjunction with addRow( ),updateRow( ), and deleteRow( ) methods in the ITable interface and executeQuery( )in the IDataConn interface.

To manage transaction processing operations, use CreateTrans( ) to create an instance of the ITrans interface, then use begin( ), commit( ), and rollback( ) in the ITrans interface to begin, commit, and rollback the transaction, respectively.

Return Value
ITrans object representing a transaction, or null for failure. The extension uses this object to uniquely identify this transaction in subsequent transaction processing operations, such as beginning, committing, or rolling back a transaction.

Example
// Create and begin a transaction

ITrans trx = CreateTrans(m_Context);

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

DestroySession( )
Deletes a user session.

Syntax
public static int DestroySession(
IContext context,
String pAppName
String pSessionID
ISessionIDGen pIDGen)

pAppName. Name of the application associated with the session. The application name enables the Netscape Application Server to determine which extensions have 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. An extension typically calls DestroySession( ) when the user logs out of an application.

Tip
If the extension 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( )

GetAppEvent( )
Retrieves the application event object.

Syntax
public static IAppEvent GetAppEvent(
IContext context
)

Usage
Use GetAppEvent( )to retrieve an IAppEvent object. Through the IAppEvent interface, you can create and manage application events. An extension 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.

GetObject( )
Retrieves an object from the context.

Syntax
public static Object GetObject(
IContext context,
String contextName)

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 (from another extension, for example), in order to access the services of another loaded extension.

Return Value
The returned object, or null for failure.

Example
IModuleData modData=GXContext.GetObject(context,

"com.kivasoft.IModuleData");

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)

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.

GXSTATE.GXSTATE_PERSISTENT to write the data to a persistent store that survives server crashes.

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|GXSTATE.GXSTATE_PERSISTENT,

"Grammy");

if (tree!=null)

{

IState2 child = tree.getStateChild("Best Female Vocal");

if (child == null)

{

child = tree.createStateChild("Best Female Vocal", 0,

GXSTATE.GXSTATE_DISTRIB|GXSTATE.GXSTATE_PERSISTENT);

IsAuthorized( )
Checks a user's permission level to a specified action.

Syntax 1
Use in most cases.

public static int IsAuthorized(
IContext context,
String pTarget,
String pPermission)

Syntax 2
Contains several parameters that are place holders for future functionality.

public static int IsAuthorized(
IContext context,
String pDomain,
String pTarget,
String pPermission,
int method,
int flags,
ICred pCred,
IObject pEnv)

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

pEnv. Specify null.

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

Return Value
One of the following:


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.