Request interface



public abstract interface Request

Interface to a request made to a CustomTag. The interface includes methods for retrieving attributes passed to the tag (including queries) and reading global tag settings.

Methods

Returns

Syntax

Description

boolean

attributeExists(String name)

Checks whether the attribute was passed to this tag.

boolean

debug()

Checks whether the tag contains the debug attribute.

String

getAttribute(String name)

Retrieves the value of the passed attribute.

String[]

getAttributeList()

Retrieves a list of attributes passed to the tag.

int

getIntAttribute(String name)

Retrieves the value of the passed attribute as an integer.

int

getIntAttribute(String name, int def)

Retrieves the value of the passed attribute as an integer (returns default if the attribute does not exist or is not a valid number).

Query

getQuery()

Retrieves the query that was passed to this tag.

     

attributeExists

Description

Checks whether the attribute was passed to this tag.

Returns True if the attribute is available; otherwise returns False.

Syntax

public boolean attributeExists(String name)

Parameters

Parameter

Description

name

Name of the attribute to check (case-insensitive)

Example

The following example checks whether the user passed an attribute named DESTINATION to the tag; if not, it throws an exception:

if ( ! request.attributeExists("DESTINATION") ) 
{ 
    throw new Exception(  
    "Missing DESTINATION parameter", 
    "You must pass a DESTINATION parameter in " 
    "order for this tag to work correctly." ) ; 
} ;

debug

Description

Checks whether the tag contains the debug attribute. Use this method to determine whether to write debug information for this request. For more information, see writeDebug.

Returns True if the tag contains the debug attribute; False, otherwise.

Syntax

public boolean debug()

See also

writeDebug

Example

The following example checks whether the debug attribute is present, and if so, it writes a brief debug message:

if ( request.debug() ) 
{ 
    response.writeDebug( "debug info" ) ; 
} 

getAttribute

Description

Retrieves the value of a passed attribute. Returns an empty string if the attribute does not exist (use attributeExists to test whether an attribute was passed to the tag). Use getAttribute(String,String) to return a default value rather than an empty string.

Returns the value of the attribute passed to the tag. If no attribute of that name was passed to the tag, an empty string is returned.

Syntax

public String getAttribute(String name)

Parameters

Parameter

Description

name

The attribute to retrieve (case-insensitive)

Example

The following example retrieves an attribute named DESTINATION and writes its value back to the user:

String strDestination = request.getAttribute("DESTINATION") ; 
response.write( "The destination is: " + strDestination ) ; 

getAttributeList

Description

Retrieves a list of attributes passed to the tag. To retrieve the value of one attribute, use the getAttribute method.

Returns an array of strings containing the names of the attributes passed to the tag.

Syntax

public String[] getAttributeList()

Example

The following example retrieves the list of attributes, then iterates over the list, writing each attribute and its value back to the user:

String[] attribs = request.getAttributeList() ; 
int nNumAttribs = attribs.length ;                     
 
for( int i = 0; i < nNumAttribs; i++ ) 
{ 
    String strName = attribs[i] ; 
    String strValue = request.getAttribute( strName ) ; 
    response.write( strName + "=" + strValue + "<BR>" ) ; 
} 

getIntAttribute

Description

Retrieves the value of the passed attribute as an integer. Returns -1 if the attribute does not exist. Use attributeExists to test whether an attribute was passed to the tag. Use getIntAttribute(String,int) to return a default value rather than throwing an exception or returning -1.

Returns the value of the attribute passed to the tag. If no attribute of that name was passed to the tag, -1 is returned.

Syntax

public int getIntAttribute(String name)

Throws

NumberFormatException if the attribute is not a valid number.

Parameters

Parameter

Description

name

The attribute to retrieve (case-insensitive)

Example

The following example retrieves an attribute named PORT and writes its value back to the user:

int nPort = request.getIntAttribute("PORT") ; 
if ( nPort != -1 ) 
    response.write( "The port is: " + String.valueOf(nPort) ) ; 

getQuery

Description

Retrieves the query that was passed to this tag.

To pass a query to a custom tag, you use the query attribute. It should be set to the name of a query (created using the cfquery tag). The query attribute is optional and should be used only by tags that process an existing dataset.

Returns the Query that was passed to the tag. If no query was passed, returns null.

Syntax

public Query getQuery()

Example

The following example retrieves a query that was passed to a tag. If no query was passed, an exception is thrown:

Query query = request.getQuery() ; 
if ( query == null ) 
{ 
    throw new Exception( 
    "Missing QUERY parameter. " + 
    "You must pass a QUERY parameter in " 
    "order for this tag to work correctly." ) ;  
} 

getSetting

Description

Retrieves the value of a global custom tag setting. Custom tag settings are stored in the CustomTags section of the ColdFusion Registry key.

Returns the value of the custom tag setting. If no setting of that name exists, an empty string is returned.

Syntax

public String getSetting(String name)

Parameters

Parameter

Description

name

The name of the setting to retrieve (case-insensitive)

Usage

All custom tags implemented in Java share a registry key for storing settings. To avoid name conflicts, preface the names of settings with the name of your custom tag class. For example, the code below retrieves the value of a setting named VerifyAddress for a custom tag class named MyCustomTag:

String strVerify = request.getSetting("MyCustomTag.VerifyAddress") ; 
if ( Boolean.valueOf(strVerify) ) 
{ 
    // Do address verification... 
}