GXContext class
GXContext is a utility class that enables developers to access NAS 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 Netscape Extension Builder, a separately available product.
In rare situations, EJB and servlet developers may want to call the methods of GXContext, thereby allowing NAS 4.0 applications to include additional NAS 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 NAS features in other ways. Servlet developers can use the methods of two NAS-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.netscape.server.IServerContext sc;
// legal cast within NAS
sc = (com.netscape.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 NAS
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.netscape.server.IServerContext sc;
// legal cast within NAS
sc = (com.netscape.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
Related Topics
com.kivasoft.applogic.AppLogic class (deprecated),
com.netscape.server.ICallerContext interface,
com.kivasoft.IContext interface,
com.netscape.server.IServerContext interface,
com.netscape.server.servlet.extension.HttpSession2 interface,
com.netscape.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 Netscape 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.
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.
Note
In a future release of NAS, 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 Netscape 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 Netscape 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 Netscape 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
Taking Advantage of NAS Features
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. 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 Netscape 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 NAS cluster.
Syntax
public static int GetSessionCount(
IContext context,
int dwFlags,
String appName)
context.
An IContext object, which provides access to Netscape 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.
Related Topics
Taking Advantage of NAS Features
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. For information on obtaining a context, see "Examples."
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,
"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 Netscape Application Server services. For information on obtaining a context, see "Examples."
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.
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 Netscape Application Server Administrator. For more information, see the Administration 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 Netscape 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 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 caller passes to NAS 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. NAS 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:
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,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 Netscape 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 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 NewRequestAsync( ) is called, the caller passes to NAS 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, 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");
}
|
Previous
