IValList interface (deprecated)
IValList is deprecated and is provided for backward compatibility only. New Java applications should use the standard servlet-JSP programming model.
For information about replacing IValList functionality in existing applications, see the Migration Guide.
An IValList represents a collection of GXVAL objects. This collection is not a sequential list, but an unordered set of GXVAL objects with no implied sequence or progression.
For Netscape Application Server-enabled AppLogics, input arguments and output value(s) are stored in IValList objects. Every request to an AppLogic passes a list of input arguments, and every result from an AppLogic returns a list of output values. The AppLogic class (deprecated) defines two member variables, valIn and valOut, to contain the input arguments and output values, respectively, of AppLogic execution.
In an IValList, values and objects are mapped to keys. The key name is the name of a GXVAL object. AppLogic code refers to GXVAL object in the IValList by its key name. Key names are unique within each IValList object.
The IValList interface provides methods for adding, retrieving, removing, and counting GXVAL objects in the IValList instance. Using methods in the IValList interface, the AppLogic can test for input arguments and modify their contents for output values.
Keys may be passed to the AppLogic as a request from an HTML document or from another AppLogic module. In an HTML form, keys are often the field names defined in the form. In this way, the AppLogic can easily identify expected, common, or "well-known" keys, and the AppLogic can ignore irrelevant parameters.
For example, an AppLogic named getLogin might prompt users for their username and login, then pass this information, identified as "username" and "password", to other AppLogics for processing. An AppLogic named validateLogin could retrieve the input parameters, find the values associated with the well-known keys "username" and "password", then take action based on the data that the user entered (testing for its existence, performing a range or length check, looking up the combination in a password table, and so on).
To create an instance of the IValList interface, use the GX.CreateValList( ) method.
Package
com.kivasoft
Methods
Related Topics
valIn and valOut in the AppLogic class (deprecated)
execute( ) in the AppLogic class (deprecated)
count( )
Returns the number of GXVAL objects in the IValList .
Syntax
public int count()
Usage
When the contents of an IValList are unknown, an AppLogic can iterate through each GXVAL object to test, retrieve, and update information. Use count( ) to determine the maximum number of iterations needed to go completely through the IValList.
Rule
Do not add or remove GXVAL objects to or from the IValList when iterating through the IValList.
Tips
Return Value
An int value representing the number of GXVal objects in the IValList, or zero for failure (such as the IValList is empty).
Example
// Obtain the contents of the shopping basket
IValList basket=session.getBasketContents();
// Determine whether basket is empty
if(basket.count()==0)
{
// If basket contains items, process template to show
if(evalTemplate(EMPTY_HTML, (ITemplateData) null, (ITemplateMap)
null) ==0)
return result("");
else
// If basket is empty, just return message
return result("Failed to Generate HTML");
}
Related Topics
getNextKey( )
resetPosition( )
valIn and valOut in the AppLogic class (deprecated)
execute( ) in the AppLogic class (deprecated)
getNextKey( )
Retrieves the key name of the next GXVAL object in the IValList.
Syntax
public String getNextKey()
Usage
When the contents of a IValList are unknown, the AppLogic can iterate through each GXVAL object and retrieve its key name. The AppLogic can then take action based on this information, or use the key name in operations that retrieve, update, or remove GXVAL objects in the IValList list.
Rule
Do not add or remove GXVAL objects to or from the IValList when iterating through the IValList.
Tip
Use getNextKey( ) in conjunction with count( ) and resetPosition( ) to iterate through the IValList.
Return Value
String representing the next retrieved key in the IValList, or null for failure (such as if no other keys exist).
Example
// Returns the contents of the shopping basket
public synchronized IValList getBasketContents()
{
IValList list = getValList();
IValList ret = GX.CreateValList();
// Iterate through the contents of the shopping basket
list.resetPosition();
String key;
while((key=list.getNextKey())!=null)
{
// Is this a desired key?
if(key.startsWith(PROD))
{
// Obtain the product number from the item
String prod = key.substring(PROD.length(),
key.length());
// Set the return IValList appropriately
ret.setVal(prod, list.getVal(key));
}
}
ret.resetPosition();
return ret;
Related Topics
count( )
resetPosition( )
execute( ) in the AppLogic class (deprecated)
getVal( )
Copies the specified GXVAL object from the IValList.
Syntax
public GXVAL getVal(
String pKey)
pKey.
Key name of the GXVAL object to copy from the IValList.
Usage
Use getVal( ) if the data type of the GXVAL object is not known. Use getValString( ) instead for string objects, getValInt( ) for integer objects, and getValBLOB( ) for BLOB objects.
Rule
The specified key name must currently exist in the IValList.
Return Value
New GXVAL object representing a copy of the GXVAL object specified by pKey, or null for failure (such as invalid keyname).
Example
// Returns the contents of the shopping basket
public synchronized IValList getBasketContents()
{
IValList list = getValList();
IValList ret = GX.CreateValList();
// Iterate through the contents of the shopping basket
list.resetPosition();
String key;
while((key=list.getNextKey())!=null)
{
// Is this a desired key?
if(key.startsWith(PROD))
{
// Obtain the product number from the item
String prod=key.substring(PROD.length(),key.length());
// Set the return IValList appropriately
ret.setVal(prod, list.getVal(key));
}
}
ret.resetPosition();
return ret;
}
Related Topics
getValBLOB( ), getValInt( ), and getValString( ) in the IValList interface (deprecated)
valIn and valOut in the AppLogic class (deprecated)
execute( ) in the AppLogic class (deprecated)
getValBLOB( )
Returns a specified BLOB object from the IValList.
Syntax
public byte[] getValBLOB(
String pKey)
pKey.
Key name of the GXVAL object that contains the BLOB value to retrieve.
Usage
Use getValBLOB( ) when the type of a GXVAL object is a BLOB, but its value is not known and needed for subsequent operations. Use getValString( ) instead for string objects and getValInt( ) for integer objects. If the type of the GXVAL object is not known, use getVal( ).
Rule
The data type must be TEXT, BINARY, VARBINARY, or database equivalent.
Return Value
A byte array for success, or null for failure.
Related Topics
getValBLOBSize( ) and setValBLOB( ) in the IValList interface (deprecated)
getValBLOBSize( )
Returns the size of a specified BLOB object in the IValList.
Syntax
public int getValBLOBSize(
String pKey)
pKey.
Key name of the GXVAL object that contains the BLOB.
Usage
BLOB objects can be large. If you want to determine the size of a BLOB object before retrieving it, use getValBLOBSize( ).
Rule
The data type must be TEXT, BINARY, VARBINARY, or database equivalent.
Return Value
An integer value for success, or zero for failure (such as datatype mismatch).
Related Topics
getValBLOB( )
getValByRef( )
Gets the specified GXVAL object from the IValList.
Syntax
public GXVAL getValByRef(
string pKey)
pKey.
Key name of the GXVAL object to get from the IValList.
Usage
Use getValByRef( ) if the data type of the GXVAL object is not known, or if iterating through an IValList to get each GXVAL object. Use getValString( ) instead for string objects, getValInt( ) for integer objects, and getValBLOB( ) for BLOB objects.
Return Value
New GXVAL object representing a copy of the GXVAL object specified by pKey, or null for failure (such as invalid keyname).
Related Topics
getValBLOB( ), getValInt( ), and getValString( ) in the IValList interface (deprecated)
valIn and valOut in the AppLogic class (deprecated)
execute( ) in the AppLogic class (deprecated)
getValInt( )
Retrieves an integer value from the specified GXVAL object in the IValList.
Syntax
public int getValInt(
String pKey)
pKey.
Key name of the GXVAL object from which to retrieve the integer value.
Usage
Use getValInt( ) if the data type of the GXVAL object is known to be an integer. Otherwise, use getValString( ) instead for string objects, getValBLOB( ) for BLOB objects, or getVal( ) for objects of other types.
Rules
Return Value
An int value representing the value of the specified GXVAL object, or null for failure (such as invalid key name or data type mismatch).
Example
// Obtains the User ID from the Session's IValList
public int getUserId()
{
return getValList().getValInt("UserId");
}
Related Topics
valIn and valOut in the AppLogic class (deprecated)
execute( ) in the AppLogic class (deprecated)
getValString( )
Retrieves a string value from the specified GXVAL object in the IValList.
Syntax
public String getValString(
String pKey)
pKey.
Key name of the GXVAL object from which to retrieve the string value.
Usage
Use getValString( ) when the data type of the GXVAL object is known to be a string. Otherwise, use getValInt( ) instead for integer objects, getValBLOB( ) for BLOB objects, or getVal( ) for objects of other types.
Rules
Tips
Return Value
A String representing the value of the GXVAL object, or null for failure (such as invalid key name or data type mismatch).
Example
// Obtain security information from the valIn IValList
String nameParm = valIn.getValString("username");
String passwordParm = valIn.getValString("password");
String aclStr = valIn.getValString("accessControlLevel");
// Obtain the credit card info from the form
String cardStr=valIn.getValString("CreditCard");
String number=valIn.getValString("CreditCardNumber");
String month=valIn.getValString("ExpireMonth");
String year=valIn.getValString("ExpireYear");
Related Topics
valIn and valOut in the AppLogic class (deprecated)
execute( ) in the AppLogic class (deprecated)
removeVal( )
Removes the specified GXVAL object from the IValList.
Syntax
public int removeVal(
String pKey)
pKey.
Key name of the GXVAL object to remove from the IValList.
Usage
Use removeVal( ) to delete a GXVAL object that is no longer needed in the IValList . For example, if the AppLogic contains overloaded methods, you might want to remove a GXVAL object to ensure that the proper method is executed.
Rules
Return Value
GXE.SUCCESS if the method succeeds.
Example
// Empties the contents of the shopping basket
public synchronized void emptyBasket(Agent agent)
{
IValList list = getValList();
while(true)
{
// Iterate over the contents
list.resetPosition();
String key;
boolean repeat=false;
while((key=list.getNextKey())!=null)
{
// Is this a desired key?
if(key.startsWith(PROD))
{
// Remove the Val object from the shopping cart
list.removeVal(key); repeat=true; break;
}
}
if(!repeat) break;
}
Related Topics
setVal( ) and resetPosition( ) in the IValList interface (deprecated)
valIn and valOut in the AppLogic class (deprecated)
execute( ) in the AppLogic class (deprecated)
resetPosition( )
Resets the iterator position to the "first" GXVAL object in the IValList.
Syntax
public int resetPosition()
Usage
When the contents of an IValList are unknown, the AppLogic can iterate through each GXVAL object and retrieve its key name. Before iterating through the IValList , the AppLogic needs to call resetPosition( ) once to ensure that iteration begins at the "first" GXVAL object in the IValList .
Rule
Do not add or remove GXVAL objects to or from the IValList when iterating through the IValList.
Tips
Return Value
GXE.SUCCESS if the method succeeds.
Example
// Returns the contents of the shopping basket
public synchronized IValList getBasketContents()
{
IValList list=getValList();
IValList ret = GX.CreateValList();
// Iterate through the contents of the shopping basket
list.resetPosition();
String key;
while((key=list.getNextKey())!=null)
{
// Is this a desired key?
if(key.startsWith(PROD))
{
// Obtain the product number from the item
String prod = key.substring(PROD.length(),
key.length());
// Set the return IValList appropriately
ret.setVal(prod, list.getVal(key));
}
}
ret.resetPosition();
return ret;
}
Related Topics
count( ) and getNextKey( ) in the IValList interface (deprecated)
valIn and valOut in the AppLogic class (deprecated)
execute( ) in the AppLogic class (deprecated)
setVal( )
Copies a GXVAL object to the IValList .
Syntax
public int setVal(
String pKey,
GXVAL pVal)
pKey.
Key name of the GXVAL object to add to the IValList.
pVal.
The GXVAL object, identified by pKey, to add to the IValList.
Usage
Use setVal( ) to add an existing GXVAL object to the IValList. If a GXVAL object with the same key name already exists, setVal( ) overwrites it with the new one.
Rule
Do not add new GXVAL objects to the IValList when iterating through the IValList.
Tip
To add a new GXVAL object of type integer, string, or BLOB to the IValList, use setValInt( ), setValString( ), or setValBLOB( ), respectively.
Return Value
GXE.SUCCESS if the method succeeds.
Example
// Returns the contents of the shopping basket
public synchronized IValList getBasketContents()
{
IValList list=getValList();
IValList ret = GX.CreateValList();
// Iterate through the contents of the shopping basket
list.resetPosition();
String key;
while((key=list.getNextKey())!=null)
{
// Is this a desired key?
if(key.startsWith(PROD))
{
// Obtain the product number from the item
String prod = key.substring(PROD.length(),
key.length());
// Set the return IValList appropriately
ret.setVal(prod, list.getVal(key));
}
}
ret.resetPosition();
return ret;
}
Related Topics
valIn and valOut in the AppLogic class (deprecated)
execute( ) in the AppLogic class (deprecated)
setValBLOB( )
Adds a BLOB object to the IValList
Syntax
public int setValBLOB(
String pKey,
byte[] pBuff,
int nBuffLen)
pKey.
Key name of the GXVAL object to add to the IValList.
pBuff.
The value of the BLOB object to add to the IValList.
nBuffLen.
Number of bytes to set for the byte array. The first nBuffLen bytes in the array pBuff hold the value.
Usage
Use setValBLOB( ) to add a GXVAL object that contains a BLOB value to the IValList. If a GXVAL object with the same key name already exists, setValBLOB( ) overwrites it with the new one.
Return Value
GXE.SUCCESS if the method succeeds.
Related Topics
getValBLOB( )
getValBLOBSize( )
setValByRef( )
Copies a GXVAL object to the IValList .
Syntax
public int setValByRef(
String pKey,
GXVAL pVal)
pKey.
Key name of the GXVAL object to add to the IValList.
pVal.
The GXVAL object, identified by pKey, to add to the IValList.
Usage
Use setValByRef( ) to add an existing GXVAL object to the IGXValList. If a GXVAL object with the same key name already exists, setValByRef( ) overwrites it with the new one.
Rule
Do not add new GXVAL objects to the IValList when iterating through the IValList.
Tip
To add a new GXVAL object of type integer, string, or BLOB to the IValList, use setValInt( ), setValString( ), or setValBLOB( ), respectively.
Return Value
GXE.SUCCESS if the method succeeds.
Related Topics
valIn and valOut in the AppLogic class (deprecated)
execute( ) in the AppLogic class (deprecated)
setValInt( )
Adds a GXVAL object of type integer to the IValList.
Syntax
public int setValInt(
String pKey,
int nVal)
pKey.
Key name of the GXVAL object to create or overwrite.
nVal.
The integer value to assign to the GXVAL object identified by pKey.
Usage
Use setValInt( ) to add a GXVAL object of type integer to the IValList. If a GXVAL object with the same key name already exists, setValInt( ) overwrites it with the new one.
Rules
When iterating through existing GXVAL objects in the IValList, do not add new GXVAL objects to the IValList.
Tips
To add a new GXVAL object of type string or BLOB to the IValList, use setValString( ) or setValBLOB( ), respectively.
Return Value
GXE.SUCCESS if the method succeeds.
Example
// Specifies the User ID for the Session's IValList
public void setUserId(int uid, Agent agent)
{
getValList().setValInt("UserId", uid);
agent.saveSession();
}
Related Topics
valIn and valOut in the AppLogic class (deprecated)
execute( ) in the AppLogic class (deprecated)
setValString( )
Adds a GXVAL object of type string to the IValList.
Syntax
public int SetValString(
String pKey,
String val)
pKey.
Key name of the GXVAL object to create or overwrite.
val.
The string value to assign to the GXVAL object identified by pKey.
Usage
Use setValString( ) to add a GXVAL object of type string to the IValList. If a GXVAL object with the same key name already exists, setValString( ) overwrites it with the new one.
Rules
When iterating through existing GXVAL objects in the IValList, do not add new GXVAL objects to the IValList.
Tips
To add a new GXVAL object of type integer or BLOB to the IValList, use setValInt( ) or setValBLOB( ), respectively.
Return Value
GXE.SUCCESS if the method succeeds.
Example
// Create and IValList and set string values
IValList custValList = GX.CreateValList();
custValList.setValString(":ssn", ssn);
custValList.setValString(":userName", userName);
Related Topics
valIn and valOut in the AppLogic class (deprecated)
execute( ) in the AppLogic class (deprecated)
|
Previous
