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:
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.
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:
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:
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
Tips
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)
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.
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
)
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.
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
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)
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.
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.
Rules
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
)
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.
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
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
)
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.
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
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)
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.
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
)
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.
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)
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.
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)
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.
dwFlags.
Specify one of the following flags or zero to use the default settings.
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)
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.
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:
Example
if (IsAuthorized(m_Context, "MonthlyForecast", "READ") !=
GXACLPERMSTATUS.GXACL_ALLOWED)
return result("<html><body>sorry no access</body><html>);
else
// run monthly forecast report
LoadHierQuery( )
Creates a hierarchical query by loading a query file containing one or more query names and associated data connections.
Syntax
public static IHierQuery LoadHierQuery(
IContext context,
String pFileName,
IDataConnSet pDataConnSet,
int flags,
IValList pParams)
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.
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:
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.
IValList of query file parameters, or null. A collection of place holders for the WHERE clause. A place holder may be a name or a number. It is prefixed by a colon (:) character. The place holders can be replaced by specifying replacement values in the ValList parameter.
Usage
Use LoadHierQuery( ) to create a hierarchical query object. An extension 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 Netscape Application Builder query editor window or an ASCII text editor, ANSI 89 standard SQL SELECT statements, and specialized Netscape Application Server syntax. A query file can define both flat and hierarchical queries.
To use a query file, the 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 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.
IDataConnSet provides a method for adding query name / data connection pairs to the collection. In this way, the extension can use standardized queries and assign data connections dynamically at runtime. Finally, the extension calls LoadHierQuery( ) to create the hierarchical query object.
Rules
Return Value
IHierQuery object representing a hierarchical query, or null for failure (such as query file not found). The 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
The following example shows a query (GXQ) file and a section of an extension 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'
Extension code snippet:
IDataConnSet connSet;
connSet = CreateDataConnSet(m_Context, 0);
// Create database connections
IDataConn conn_detailDB = CreateDataConn(m_Context, 0,
GX_DA_DAD_DRIVERS.GX_DA_DRIVER_DEFAULT, "kdetails", "", "kuser",
"kpassword");
IDataConn conn_statesDB = CreateDataConn(m_Context, 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(m_Context, "state.gxq", connSet, 0,
param);
// Run the report
evalTemplate("state.html", hqry);
Related Topics
CreateDataConnSet( )
LoadQuery( )
Creates a flat query by loading a query file.
Syntax
public static IQuery LoadQuery(
IContext context,
String pFileName,
String pQueryName,
int flags,
IValList pParams)
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.
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:
pQueryName.
Name of the query in the query file.
flags.
Specify 0 (zero). Internal use only.
pParams.
IValList of query file parameters, or null. A collection of place holders for the WHERE clause. A place holder may be a name or a number. It is prefixed by a colon (:) character. The place holders can be replaced by specifying replacement values in the IValList parameter.
Usage
Use LoadQuery( ) to create a flat query object by loading a query (.GXQ) file. An extension 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 Netscape Application Builder or an ASCII text editor, ANSI 89 standard SQL SELECT statements, and special Netscape Application Server syntax.
To run the flat query, call executeQuery( ) in the IDataConn interface.
Return Value
IQuery object, or null for failure (such as query file not found).
Example
The following example shows a query (GXQ) file and a section of an extension 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
Extension code snippet:
// Create database connection
IDataConn conn = CreateDataConn(m_Context, 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(m_Context, "state.gxq", "STATES", 0, param);
// Execute the query
IResultSet rs = conn.executeQuery(
GX_DA_EXECUTEQUERY_FLAGS.GX_DA_RS_BUFFERING, qry, null, null);
Log( )
Writes a log message to an output device.
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 Netscape Application Server services. Specify m_Context if accessing this helper static method from a manager class; otherwise, use m_Module.m_Context.
msg.
Message text to log.
type.
Message type. Use one of the following variables:
category.
User-defined message category. Do not use the range of values reserved for the Netscape systems, which is 0 to 65535, inclusive.
Usage
Use Log( ) for displaying or storing simple messages or for debugging. The output can be directed to the console, to a text file, or to a database table. To direct output, use the Netscape Application Server Administrator. For more information, see the Administration Guide.
Return Value
GXE.SUCCESS if the method succeeds.
Example
// Log messages that include String variables
Log(m_Context, firstName+lastName+password+"
"+String.valueOf(cusId));
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 Netscape Application Server services. Specify m_Context if accessing this helper static method from a manager class; otherwise, use m_Module.m_Context.
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 Netscape Application Server where the AppLogic is to be executed. Specify 0 to execute the AppLogic locally.
port.
Internet port of the Netscape 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 extension passes to the Netscape Application Server the GUID or name of the AppLogic to execute and, optionally, any input and output parameters.
Netscape 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 extension.
The AppLogic that NewRequest( ) invokes can do one of the following tasks:
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
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);
Example 2
// Use DisplayBasket AppLogic to display the contents
if(NewRequest(m_Context, "DisplayBasket",
valIn, valOut)==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 Netscape Application Server services. Specify m_Context if accessing this helper static method from a manager class; otherwise, use m_Module.m_Context.
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 Netscape Application Server where the AppLogic is to be executed. Specify 0 to execute the AppLogic locally.
port.
Internet port of the Netscape 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 an extension calls NewRequestAsync( ), it passes to the Netscape Application Server the GUID of the AppLogic module to execute and, optionally, any input and output parameters.
The Netscape 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:
Rules
Tips
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);
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, "Failed to invoke async AppLogic\n");
}
|