Accessing the Underlying Servlet Context

With ColdFusion MX 7, each of your CFML pages is being converted to a Java servlet on-the-fly. It's natural that you should be able to access the various objects and methods exposed by the Java Servlet API defined by Sun. In other words, if you feel like using the same methods and interfaces that Java developers use when writing servlets by hand, you are free to do so.

ColdFusion MX 7 uses the GetPageContext() function that gives you access to the underlying page context, which is a servlet term that refers to the current page request. The GetPageContext() function doesn't take any parameters; it just returns the current page context object. The returned object will be a descendant of the abstract javax.servlet.jsp.PageContext class, which just means that the object will have all the methods exposed by PageContext, plus any additional methods supplied by the J2EE server that is actually running ColdFusion.

Table 29.5 shows some of the interesting methods exposed by PageContext. A complete listing is beyond the scope of this book; the intention here is mainly to give you an idea of the kinds of methods available to you via the page context metaphor. Complete references for all the items listed in Table 29.5 (and much more) can be found in the Java 2 Enterprise Edition documentation, which was freely available from http://java.sun.com at the time of this writing.

Table 29.5. Some Interesting PageContext Methods

ATTRIBUTE	DESCRIPTION
forward(relative_url)	Similar conceptually to CFML's <CFLOCATION> tag, except that the redirection occurs on the server rather than on the client. You can use forward() to pass processing of the current page request to a JSP page running on the same server.
include(relative_url)	Similar conceptually to <CFINCLUDE> in CFML. You can use include() to include JSP pages running on the same server.
getOut()	Returns a page writer object that descends from java.io.writer. This object basically represents the page output stream; when you use <cfoutput> to generate dynamic output, the text eventually makes its way to this object's print() or similar methods.
getrequest()	Returns the underlying PageRequest object for the page, which in turn can be used to access all the methods exposed by the HttpServletRequest interface. In turn, the interface supports methods such as isUserInRole() and getHeaders(), which return data similar to that from CFML's own isUserInRole() and getHttpRequestData() methods. You might also want to check out the isSecure() and getAuthType() methods. The getAttribute() and setAttribute() methods are also of interest and will be discussed in the next section, "Integrating with Java Servlets and JSP Pages."
getresponse()	Returns the underlying PageResponse for the page, which exposes all methods of the HttpServletResponse interface. In turn, the interface supports methods such as addCookie() and setHeader(), which correspond to <CFCOOKIE> and <CFHEADER> in CFML.

NOTE

Page context functionality is probably most useful and interesting to developers who have worked with Java servlets or Java Server Pages (JSP). In general, most of the methods exposed by the page context have direct counterparts in CFML, so you might as well use the direct CFML representations of the functionality exposed by the page context and its members. That said, there may be special situations where the items in Table 29.5 will provide functionality that you can't get from CFML alone; we'll explore some of those situations throughout the remainder of this chapter.

The following quick example includes a JSP page. As will be discussed in the next section, the JSP page will be able to access the various CFML variables that may have been set in previous lines of ColdFusion code:

 <cfset getPageContext().include("myPage.jsp")> 

Or, to execute certain code only if a secure connection is being used between the browser and the server:

 <cfif getPageContext().getRequest().isSecure()>  ... </cfif> 

NOTE

There are other ways to implement the <cfif> test shown here, such as testing the value of CGI.SERVER_PORT. Using isSecure() might be considered preferable, however, especially since CGI variables tend to vary a bit among Web servers.