blob: 23c92fe6906eb8203f11e0ea936bac6493dcb1bc [file] [log] [blame]
kpricead5e1e92008-04-24 00:02:23 +00001<?xml version="1.0" encoding="utf-8"?>
2<!--Arbortext, Inc., 1988-2006, v.4002-->
3<!DOCTYPE task PUBLIC "-//OASIS//DTD DITA Task//EN"
4 "task.dtd">
5<task id="twfltwiz" xml:lang="en-us">
6<title>Creating Filters</title>
7<shortdesc>The filters wizard helps you to create <tm tmclass="special" tmowner="Sun Microsystems, Inc."
kprice96ee3b52008-05-15 00:05:07 +00008tmtype="tm" trademark="Java">Java</tm> servlet filters by walking you through
9the creation process and by providing you with output files that you can use
10or that you can modify for use with your Web application. The filters can
11run on Java EE-compliant Web servers.</shortdesc>
kpricead5e1e92008-04-24 00:02:23 +000012<prolog><metadata>
13<keywords><indexterm>servlets<indexterm>creating</indexterm></indexterm></keywords>
14</metadata></prolog>
15<taskbody>
16<context> <p>To create a filter, complete the following steps: </p></context>
kprice96ee3b52008-05-15 00:05:07 +000017<steps>
kpricead5e1e92008-04-24 00:02:23 +000018<step><cmd>In the Java EE perspective, expand your <xref href="ccwebprj.dita"
kprice96ee3b52008-05-15 00:05:07 +000019scope="peer"><desc></desc>dynamic project</xref> in the Project Explorer view.</cmd>
20</step>
kpricead5e1e92008-04-24 00:02:23 +000021<step><cmd>Right click on the <b>Filter</b> icon, and select <menucascade>
22<uicontrol>New</uicontrol><uicontrol>Filter</uicontrol></menucascade> from
kprice96ee3b52008-05-15 00:05:07 +000023the pop-up menu.</cmd><stepresult> The <uicontrol>Create Filter</uicontrol> wizard
kpricead5e1e92008-04-24 00:02:23 +000024appears.</stepresult></step>
25<step><cmd>Follow the project wizard prompts.</cmd></step>
26</steps>
27<postreq><p><b>General Information</b></p><dl><dlentry>
kprice96ee3b52008-05-15 00:05:07 +000028<dt>Modifiers</dt>
29<dd>The <cite>Sun Microsystems <tm tmclass="special" tmowner="Sun Microsystems, Inc."
30tmtype="tm" trademark="Java">Java</tm> Servlet 2.3 Specification</cite> states
31that a Servlet class must be <b>public</b> and not <b>abstract</b>. Therefore,
32you cannot change these modifiers. The only one available for change is the <b>final</b> modifier.</dd>
kpricead5e1e92008-04-24 00:02:23 +000033</dlentry><dlentry>
kprice96ee3b52008-05-15 00:05:07 +000034<dt>Interfaces</dt>
35<dd>There is one obligatory interface that filter classes must implement: <b>javax.servlet.Filter</b>.
36This interface is provided by javax.servlet package and is used to represent
37the life-cycle of the filter. This interface has three methods: init, doFilter
38and destroy. <ul>
39<li>The <b>init</b> method is called by the servlet container only once, when
40it finishes instantiating the filter.</li>
41<li>The<b>doFilter</b> method is where the filtering is performed and is called
42every time a user requests a resource, such as a servlet, to which the filter
43is mapped.</li>
44<li>The <b>destroy</b> method is called by the servlet container to tell the
45filter that it will be taken out of service.</li>
46</ul> Although, that the javax.servlet.Filter interface is provided in the <b>Interfaces</b> field
47by default, you can add additional interfaces to implement by using the <b>Add</b> button.</dd>
kpricead5e1e92008-04-24 00:02:23 +000048</dlentry><dlentry>
kprice96ee3b52008-05-15 00:05:07 +000049<dt>Interface selection dialog</dt>
50<dd>This dialog appears if you select to add an interface to your filter.
51As you type the name of the interface that you are adding, a list of available
52interfaces listed in the <b>Matching items</b> list box updates dynamically
53to display only the interfaces that match the pattern. Choose an interface
54to see the qualifier, and then click <b>OK</b> when finished.</dd>
kpricead5e1e92008-04-24 00:02:23 +000055</dlentry><dlentry>
kprice96ee3b52008-05-15 00:05:07 +000056<dt>Filter Mappings</dt>
57<dd>For a filter to intercept a request to a servlet, you must: <ol>
58<li>declare the filter with a <b>&lt;filter&gt;</b> element in the deployment
59descriptor</li>
60<li>map the filter to the servlet using the <b>&lt;filter-mapping&gt;</b>
61element.</li>
62</ol> Sometimes you want a filter to work on multiple servlets. You can do
63this by mapping a filter to a URL pattern so that any request that matches
64that URL pattern will be filtered. All this is made automatically if you use
65the <b>Filter Mappings</b> field.</dd>
kpricead5e1e92008-04-24 00:02:23 +000066</dlentry><dlentry>
kprice96ee3b52008-05-15 00:05:07 +000067<dt>Method stubs</dt>
68<dd>Because each filter must implement the javax.servlet.Filter interface,
69the <b>Inherited abstract methods</b> option is always checked and cannot
70be changed.</dd>
kpricead5e1e92008-04-24 00:02:23 +000071</dlentry></dl></postreq>
72</taskbody>
73</task>