Welcome!

You will be redirected in 30 seconds or close now.

ColdFusion Authors: Yakov Fain, Jeremy Geelan, Maureen O'Gara, Nancy Y. Nee, Tad Anderson

Related Topics: ColdFusion

ColdFusion: Article

Fun with Filters in CFMX

Fun with Filters in CFMX

There are a lot of powerful new integration points between CFMX and Java, but one that might benefit a lot of people - even those who don't know how to program in Java - is the ability to leverage servlet filters in CFMX.

A filter is a Java program that can be used to execute before and/or after your CF template. More than just running some code in advance, a filter can also manipulate the request (the HTTP stream) that is calling your template, and can change how, or even if, your template is run, or cause some other template or code to run first. It can also manipulate the output (the HTTP response) that your template generates.

ColdFusion MX can run servlet filters. You don't need to write them because some have already been written for servlet and JSP developers. Because ColdFusion MX runs atop a J2EE server, we can leverage these or even write our own filters if we want to.

In this article, I'll show you where to find some example filters and how to implement them in CFMX. You don't need to understand Java to use them. By the way, they work in both the Enterprise and Pro (as well as developer and trial) editions of CFMX, and also with the built-in Web server in CFMX and external Web servers like IIS and Apache.

How Do Filters Compare to Application.cfm?
Filters may sound very similar to the way Application.cfm (and OnRequestEnd.cfm) work. But a filter has many added benefits and is really quite different from those two traditional mechanisms in CF. Before getting into the details of filters, it may help to first contrast them to those more traditional approaches.

Most will know that Application.cfm and OnRequestEnd.cfm are templates that run before (and after, in the case of OnRequestEnd.cfm) a ColdFusion template is executed. They provide a means to effect some kind of pre-or post-processing in order to augment your template.

Some use them to add a test (such as security) before a template runs, or to create some data structure (perhaps persisted in the application scope) to be shared by many templates. Some even use them for creating headers (and footers), though that may get complicated if you have a template that should run without the headers or footers.

Some Challenges with Application.cfm/OnRequestEnd.cfm
One problem with the traditional CF approach is that there's no way to stop these two files from running for any one template, as might be desired when trying to use them for headers and footers. (Of course, using them for headers and footers may be an arguable approach, but it does point up a limitation with them.) Any time you run a CF template, CF looks to run any existing Application.cfm in the current or a parent directory, whichever it finds first. And if there's an OnRequestEnd.cfm in the same directory as the Application.cfm that's run, that will be executed at the conclusion of the named template.

You can't tell CF to not run these files if they exist. Some of the other challenges are:

  • You can't apply them selectively to only some templates in a directory
  • You can't run more than one. As soon as CF finds the closest one (in the current or an ancestor directory), it runs that one and looks for no more
  • You can't have just an OnRequestEnd.cfm. It only runs if there is a corresponding Application.cfm in the same directory
  • If you do a CFABORT, any OnRequestEnd.cfm is not executed
  • They apply only to CF templates, not to HTML pages or indeed to JSPs or servlets running alongside your CF templates (which is now possible in CFMX, though JSPs can run in CFMX Enterprise only) Now, many developers haven't worried too much about these limitations. Heck, some never even knew about OnRequestEnd.cfm. It came out in 4.01 with little fanfare. See my February 2000 article, "Hidden Gems in 4.0.1 - What You Might Have Missed," at www.sys-con.com/coldfusion/article.cfm?id=81 for more such surprises.

    So why should they get excited about servlet filters? What do they really add?

    Where Filters Augment Traditional CF Approaches
    Filters work differently from the traditional approach of automatically running Application.cfm and OnRequestEnd.cfm. For one thing, you have much greater control of when a filter is run. Through some configuration files built into CFMX, which we will see later, you map filters to a given URL pattern, so that they can be made to apply to:

    • A single template
    • All templates in a given directory and subdirectories
    • All templates of a given file type
    • All templates on the entire server
    Try that with Application.cfm! They can also apply not just to requests for CF templates but also even HTML or image files, for instance.

    More important, because these are added declaratively through configuration files (rather than controlled by code in the template directories) you can also:

    • Designate multiple URL patterns for a given filter
    • Designate multiple filters to a given pattern
    • Add/remove/modify filters without the templates knowing about it
    • Apply changes to a filter across several applications
    Remember that filters can either process the incoming request or the outgoing response (HTML result, typically) of a CF template (or servlet or JSP if running under CFMX). What kinds of things could a request (input) filter do? To name a few:
  • Log and audit visits
  • Block execution of a page for a given time period (perhaps during a maintenance period)
  • Block visitors from given domains
  • Trigger events when a resource is accessed
  • Cache/reuse a page's results
  • Modify the input request before processing by CF
  • Test for/handle cross-browser scripting attempts
  • Modify request character encoding

    It's true that CF developers can do some of these things themselves in Application.cfm processing, but remember that they may already be written as servlet filters, thus saving you the development effort. Also, remember the greater flexibility in mapping filters to URLs.

    What could a response (output) filter do? Again, this is just a short list of creative solutions that do exist or could be created to process the output of a template before returning it to the user:

    • Log page execution time
    • Localization (targeting output to a locale)
    • Image conversion
    • XML transformations of XML output
    • Encryption
    • Data compression (gzip)
    I mentioned that filters have been written and used by JSP and servlet developers for some time. There are public repositories of them that address all sorts of useful programming solutions, some of which are just as valuable to CF developers.

    Where Can I Find Them?
    As for where you can find these already written, there are a few places including jsptags.com and servletsuite.com. There are surely more, but the latter has quite a few that might interest CFers, including:

    Cache filter
    www.servletsuite.com/servlets/cacheflt.htm
    Billing filter
    www.servletsuite.com/servlets/billflt.htm
    Profiler filter (track execution times)
    www.servletsuite.com/servlets/profflt.htm
    IP filter (access restriction, load balancing)
    www.servletsuite.com/servlets/ipflt.htm
    Zip/Compression filter
    www.servletsuite.com/servlets/gzipflt.htm

    The Power of a Compression Filter
    That last item in the list, a compression filter, may be the most compelling one for many and, I'll give a specific example of one as a demonstration of how all this works. A compression filter, also often called a Zip or gzip filter, is a tool that compresses the output of a Web page so that it generally takes up far less space when being sent from the server to the browser. The browser can then decompress the page and render it as usual to the end user.

    CF pages are notorious for having excessive white space, so a compression filter can be a big win for us. The good news is that most browsers, even relatively old ones, can support decompression. A compression filter will determine if a browser can support compression by checking the HTTP header called accept-encoding (or in CF, you could test it with cgi.http_accept_encoding) before trying to compress the page. A smart one might also balance the size of the page being processed before trying to compress it, since compression does cost some CPU cycles on both the server (to compress) and the client (to decompress) page.

    Still, for all but the most trivial page, compression is generally a good thing, and it's rather easily tested to confirm the savings. In some testing I did, it resulted in a 4:1 reduction in bandwidth (size of pages downloaded to the browser). For sites that pay for their bandwidth utilization (someone is always paying for it), or just for the speed improvement of sending "lighter" pages to the browser, compression is valuable.

    (It's worth noting that both Apache and IIS offer their own forms of compression that, if implemented properly, will generally suffice to provide the benefits that compression can bring. But if they're not set up, or not set up properly, then a filter in CFMX may be a good way to go. In fact, I wonder if in the future Macromedia may build one in and make it more simply enabled via an Administrator setting. Until then, it's a good example of a filter.)

    How to Implement a Filter in Three Easy Steps
    It's incredibly easy to implement a filter. If you visit any of the pages mentioned here, you'll find explanations of the filters, the downloadable files, how to configure them, and maybe an example that might be written as a JSP page. Most don't even show that, because there's nothing necessarily specific about using a filter with either CF or a JSP page, for instance. You just associate the filter with a given URL, and the filter doesn't care what kind of page it's processing before or after.

    The only clue that the filter is written in Java is that the downloadable files will likely refer to a JAR (Java Archive). But all you need to know is where to put that file and how to set up CFMX to map the filter to a URL. That's really all there is to it. Indeed, the explanations on the page will often be very similar if not identical to what you need in CFMX. There are just three simple steps. I'll walk you through implementing that gzip/compression filter.

  • Step 1: Download the filter (JAR file):
    Upon visiting the page that holds the filter, such as the last one for the gzip filter mentioned above at www.servletsuite.com/servlets/ipflt.htm, you'll find a link to the JAR file that needs to be downloaded and placed into the cfusionmx\wwwroot\WEB-INF\lib directory. It doesn't matter if you use another Web server or store your CF templates somewhere other than the cfusionmx\wwwroot. That directory will still exist, and under it you will find the WEB-INF\lib subdirectory. Place the file there. This is the location in which J2EE servers (like that underlying CFMX) expect to find Java programs like filters, when they are packaged as JAR files. (If you happened to get a filter or servlet that was just a "class" file, rather than a JAR, it would be placed in the cfusionmx\wwwroot\WEB-INF\classes directory.)

  • Step 2: Implement the filter mapping (XML configuration):
    As the page showing the downloadable filter may also indicate, the next step is to modify the web.xml file to define a pointer and map to the filter. Again, this file does exist in CFMX, specifically in the cfusionmx\wwwroot\WEB-INF. The directions will likely indicate just the XML that you need to add to the web.xml file. In the case of the compression filter, it would be:

    <filter>
    <filter-name>GZIPFilter</filter-name>
    <filter-class>com.cj.gzipflt.GzipFilter</filter-class>
    </filter>

    <filter-mapping>
    <filter-name>GZIPFilter</filter-name>
    <url-pattern>*.cfm</url-pattern>
    </filter-mapping>

    Note that in the next to last line, we're indicating that this filter should apply against all files of type "cfm", and since we don't say otherwise, it means all such files in all directories that are run under CFMX. You could create additional filter-mapping entries to list other URL mappings. To just control files in a "test" directory under your webroot, the pattern could be "/test/*.cfm" or simply "/test/*".

    Of course, as when modifying any of the XML files in the CFMX configuration, be very careful. It may even be wise to save a backup of the file before editing it so that you can recover in case the server fails to start, etc.

  • Step 3: Restart the CFMX server:
    The last step is to restart the server. CF will not detect the filter unless the server is restarted. It may not seem obvious that this should be so, but it actually looks for and preprocesses any filters at startup.

    Conclusion
    This has been a pretty quick introduction to servlet filters. You'll notice we didn't look at a single line of Java code. We're not interested here in creating filters, just in using them. There are plenty of resources for learning more about creating them - though there's not too much more you need to know about using them. We've run out of room to cover any further details, but if you're interested in more on this subject, including a few other tips that may help you as you explore them, take a look at the slides from my one-hour user group presentation, "Augmenting Application.cfm with Filters," available at my site at www.systemanage.com/presentations.

  • More Stories By Charlie Arehart

    A veteran ColdFusion developer since 1997, Charlie Arehart is a long-time contributor to the community and a recognized Adobe Community Expert. He's a certified Advanced CF Developer and Instructor for CF 4/5/6/7 and served as tech editor of CFDJ until 2003. Now an independent contractor (carehart.org) living in Alpharetta, GA, Charlie provides high-level troubleshooting/tuning assistance and training/mentoring for CF teams. He helps run the Online ColdFusion Meetup (coldfusionmeetup.com, an online CF user group), is a contributor to the CF8 WACK books by Ben Forta, and is frequently invited to speak at developer conferences and user groups worldwide.

    Comments (0)

    Share your thoughts on this story.

    Add your comment
    You must be signed in to add a comment. Sign-in | Register

    In accordance with our Comment Policy, we encourage comments that are on topic, relevant and to-the-point. We will remove comments that include profanity, personal attacks, racial slurs, threats of violence, or other inappropriate material that violates our Terms and Conditions, and will block users who make repeated violations. We ask all readers to expect diversity of opinion and to treat one another with dignity and respect.


    IoT & Smart Cities Stories
    The deluge of IoT sensor data collected from connected devices and the powerful AI required to make that data actionable are giving rise to a hybrid ecosystem in which cloud, on-prem and edge processes become interweaved. Attendees will learn how emerging composable infrastructure solutions deliver the adaptive architecture needed to manage this new data reality. Machine learning algorithms can better anticipate data storms and automate resources to support surges, including fully scalable GPU-c...
    A valuable conference experience generates new contacts, sales leads, potential strategic partners and potential investors; helps gather competitive intelligence and even provides inspiration for new products and services. Conference Guru works with conference organizers to pass great deals to great conferences, helping you discover new conferences and increase your return on investment.
    Poor data quality and analytics drive down business value. In fact, Gartner estimated that the average financial impact of poor data quality on organizations is $9.7 million per year. But bad data is much more than a cost center. By eroding trust in information, analytics and the business decisions based on these, it is a serious impediment to digital transformation.
    SYS-CON Events announced today that Silicon India has been named “Media Sponsor” of SYS-CON's 21st International Cloud Expo, which will take place on Oct 31 – Nov 2, 2017, at the Santa Clara Convention Center in Santa Clara, CA. Published in Silicon Valley, Silicon India magazine is the premiere platform for CIOs to discuss their innovative enterprise solutions and allows IT vendors to learn about new solutions that can help grow their business.
    We are seeing a major migration of enterprises applications to the cloud. As cloud and business use of real time applications accelerate, legacy networks are no longer able to architecturally support cloud adoption and deliver the performance and security required by highly distributed enterprises. These outdated solutions have become more costly and complicated to implement, install, manage, and maintain.SD-WAN offers unlimited capabilities for accessing the benefits of the cloud and Internet. ...
    Founded in 2000, Chetu Inc. is a global provider of customized software development solutions and IT staff augmentation services for software technology providers. By providing clients with unparalleled niche technology expertise and industry experience, Chetu has become the premiere long-term, back-end software development partner for start-ups, SMBs, and Fortune 500 companies. Chetu is headquartered in Plantation, Florida, with thirteen offices throughout the U.S. and abroad.
    SYS-CON Events announced today that CrowdReviews.com has been named “Media Sponsor” of SYS-CON's 22nd International Cloud Expo, which will take place on June 5–7, 2018, at the Javits Center in New York City, NY. CrowdReviews.com is a transparent online platform for determining which products and services are the best based on the opinion of the crowd. The crowd consists of Internet users that have experienced products and services first-hand and have an interest in letting other potential buye...
    Business professionals no longer wonder if they'll migrate to the cloud; it's now a matter of when. The cloud environment has proved to be a major force in transitioning to an agile business model that enables quick decisions and fast implementation that solidify customer relationships. And when the cloud is combined with the power of cognitive computing, it drives innovation and transformation that achieves astounding competitive advantage.
    DXWorldEXPO LLC announced today that "IoT Now" was named media sponsor of CloudEXPO | DXWorldEXPO 2018 New York, which will take place on November 11-13, 2018 in New York City, NY. IoT Now explores the evolving opportunities and challenges facing CSPs, and it passes on some lessons learned from those who have taken the first steps in next-gen IoT services.
    Cloud-enabled transformation has evolved from cost saving measure to business innovation strategy -- one that combines the cloud with cognitive capabilities to drive market disruption. Learn how you can achieve the insight and agility you need to gain a competitive advantage. Industry-acclaimed CTO and cloud expert, Shankar Kalyana presents. Only the most exceptional IBMers are appointed with the rare distinction of IBM Fellow, the highest technical honor in the company. Shankar has also receive...