forked from paultuckey/urlrewritefilter
-
Notifications
You must be signed in to change notification settings - Fork 0
/
index.html
1493 lines (1272 loc) · 57.2 KB
/
index.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<!DOCTYPE html>
<html lang="en">
<head>
<title>UrlRewriteFilter - Manual</title>
<style type="text/css">
@import url( "doc.css" );
</style>
<script type="text/javascript">
var _gaq = _gaq || [];
_gaq.push(['_setAccount', 'UA-93014-4']);
_gaq.push(['_trackPageview']);
(function() {
var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
})();
</script>
</head>
<body>
<div class="container">
<div id="masthead" class="top">
<h1><a href="http://www.tuckey.org/urlrewrite/">
<img id="logo" src="urf-100.png" border="0" alt="Tuckey Logo" /></a>
UrlRewriteFilter <!--@ver-->4.0.3<!--/@ver--></h1>
</div>
<div class="row">
<div id="menu" class="span3">
<div class="well">
<ul>
<li><a href="http://www.tuckey.org/urlrewrite/">Home</a></li>
<li><a href="http://www.tuckey.org/urlrewrite/#download">Download</a></li>
<li><a href="https://github.com/paultuckey/urlrewritefilter">GitHub Project</a></li>
<li><a href="http://stackoverflow.com/search?q=urlrewritefilter">StackOverflow Search</a></li>
<li><a href="http://stackoverflow.com/questions/tagged/tuckey-urlrewrite-filter">UrlRewrite on StackOverflow</a><br/> </li>
<li><a href="introduction.html">Background</a>
<ul>
<li><a href="introduction.html#license">License</a></li>
<li><a href="introduction.html#changelog">Changelog</a></li>
</ul>
</li>
<li><b>Configuration</b>
<ul>
<li><a href="#install">Install</a></li>
<li><a href="#tips">Tips</a></li>
<li><a href="#filterparams">Filter Parameters</a></li>
<li><a href="#configuration">Configuration File</a></li>
<li><a href="#anttask">Ant Task</a></li>
<li><a href="index.html#mod_rewrite_conf">mod_rewrite Style</a></li>
</ul>
</li>
<li><a href="annotation.html">Annotations</a></li>
<li><a href="guide.html">Examples</a>
<ul>
<li><a href="guide.html#method">Method Invocation</a></li>
<li><a href="guide.html#urlabs">URL Abstraction</a></li>
<li><a href="guide.html#mod_re">mod_rewrite vs UrlRewriteFilter</a></li>
<li><a href="guide.html#extending">Extending UrlRewriteFilter</a></li>
</ul>
</li>
</ul>
</div>
</div>
<div id="main" class="span9">
<h1>Manual</h1>
<p>Community support is available at <a href="http://stackoverflow.com/questions/tagged/tuckey-urlrewrite-filter">UrlRewrite on StackOverflow</a>.</p>
<p>Read <b><a href="guide.html">examples of usage</a></b> and a
<a href="urlrewrite-conf-overview-sample.html">sample</a> of the <a href="#anttask">ant task</a> report.
If you have any suggestions/examples for this manual, please post them to the
<a href="http://groups.google.com/group/urlrewrite">group</a>.</p>
<a name="install"> </a>
<h2>Install</h2>
<ol>
<li>Add Maven dependency below or add
<a href="http://central.maven.org/maven2/org/tuckey/urlrewritefilter/4.0.3/urlrewritefilter-4.0.3.jar">urlrewritefilter-<!--@ver-->4.0.3<!--/@ver-->.jar</a>
directly into your <b>WEB-INF/lib</b> directory.
<pre><code><dependency>
<groupId>org.tuckey</groupId>
<artifactId>urlrewritefilter</artifactId>
<version><!--@ver-->4.0.3<!--/@ver--></version>
</dependency></code></pre></li>
<li>Add the following to your WEB-INF/web.xml (add it near the top above your
servlet mappings (if you have any)): (see <a href="#filterparams">filter
parameters</a> for more options)
<pre><code><filter>
<filter-name>UrlRewriteFilter</filter-name>
<filter-class>org.tuckey.web.filters.urlrewrite.UrlRewriteFilter</filter-class>
</filter>
<filter-mapping>
<filter-name>UrlRewriteFilter</filter-name>
<url-pattern>/*</url-pattern>
<dispatcher>REQUEST</dispatcher>
<dispatcher>FORWARD</dispatcher>
</filter-mapping></code></pre></li>
<li>Add <b><a href="https://tuckey.org/urlrewrite/manual/4.0/urlrewrite.xml">urlrewrite.xml</a></b>
into your WEB-INF directory. (src/main/webapp/WEB-INF/ for Maven users)</li>
<li>Restart the context.</li>
</ol>
<p>You can visit <a href="http://127.0.0.1:8080/rewrite-status">http://127.0.0.1:8080/rewrite-status</a>
(or whatever the address of your local webapp and context)
to see the output (note: this page is only viewable from localhost).</p>
<a name="filterparams"> </a>
<h2>Filter Parameters</h2>
<p>There are a few advanced filter parameters for enabling conf file reloading etc. There are self-explanatory.</p>
<pre>
<filter>
<filter-name>UrlRewriteFilter</filter-name>
<filter-class>org.tuckey.web.filters.urlrewrite.UrlRewriteFilter</filter-class>
<!-- set the amount of seconds the conf file will be checked for reload
can be a valid integer (0 denotes check every time,
-1 denotes no reload check, default -1) -->
<init-param>
<param-name><b>confReloadCheckInterval</b></param-name>
<param-value>60</param-value>
</init-param>
<!-- if you need to the conf file path can be changed
it is specified as a path relative to the root of your context
(default /WEB-INF/urlrewrite.xml) -->
<init-param>
<param-name><b>confPath</b></param-name>
<param-value>/WEB-INF/urlrewrite.xml</param-value>
</init-param>
<!-- sets up log level (will be logged to context log)
can be: slf4j, TRACE, DEBUG, INFO (default), WARN, ERROR, FATAL,
sysout:{level} (ie, sysout:DEBUG)
if you are having trouble using normal levels use sysout:DEBUG
(default WARN) -->
<init-param>
<param-name><b>logLevel</b></param-name>
<param-value>DEBUG</param-value>
</init-param>
<!-- you can change status path so that it does not
conflict with your installed apps (note, defaults
to /rewrite-status) note, must start with / -->
<init-param>
<param-name><b>statusPath</b></param-name>
<param-value>/status</param-value>
</init-param>
<!-- you can disable status page if desired
can be: true, false (default true) -->
<init-param>
<param-name><b>statusEnabled</b></param-name>
<param-value>true</param-value>
</init-param>
<!-- you may want to allow more hosts to look at the status page
statusEnabledOnHosts is a comma delimited list of hosts, * can
be used as a wildcard (defaults to "localhost, local, 127.0.0.1") -->
<init-param>
<param-name><b>statusEnabledOnHosts</b></param-name>
<param-value>localhost, dev.*.myco.com, *.uat.mycom.com</param-value>
</init-param>
<!-- you may want to allow more hosts to look at the status page
statusEnabledOnHosts is a comma delimited list of hosts, * can
be used as a wildcard (defaults to "localhost, local, 127.0.0.1") -->
<init-param>
<param-name><b>statusEnabledOnHosts</b></param-name>
<param-value>localhost, dev.*.myco.com, *.uat.mycom.com</param-value>
</init-param>
<!-- defaults to false. use mod_rewrite style configuration file (if this is true and confPath
is not specified confPath will be set to /WEB-INF/.htaccess) -->
<init-param>
<param-name><b>modRewriteConf</b></param-name>
<param-value>false</param-value>
</init-param>
<!-- load mod_rewrite style configuration from this parameter's value.
note, Setting this parameter will mean that all other conf parameters are ignored.
<init-param>
<param-name><b>modRewriteConfText</b></param-name>
<param-value>
RewriteRule ^/~([^/]+)/?(.*) /u/$1/$2 [R]
RewriteRule ^/([uge])/([^/]+)$ /$1/$2/ [R]
</param-value>
</init-param>
-->
<!-- defaults to false. allow conf file to be set by calling /rewrite-status/?conf=/WEB-INF/urlrewrite2.xml
designed to be used for testing only
<init-param>
<param-name><b>allowConfSwapViaHttp</b></param-name>
<param-value>false</param-value>
</init-param>
-->
</filter>
<filter-mapping>
<filter-name>UrlRewriteFilter</filter-name>
<url-pattern>/*</url-pattern>
<dispatcher>REQUEST</dispatcher>
<dispatcher>FORWARD</dispatcher>
</filter-mapping>
</pre>
<p>Note, setting <code>logLevel</code> to <code>slf4j</code> will cause the built-in logging to
call <a href="http://www.slf4j.org/">slf4j</a> as if it was the logging framework;
obviously, you will need to have the jar for slf4j in your classpath.</p>
<a name="configuration"> </a>
<h2>Configuration File WEB-INF/urlrewrite.xml</h2>
<table align="right">
<tr>
<td>
<small>
<a href="#urlrewrite"><urlrewrite></a>
<a href="#rule"><rule></a>
<a href="#outbound-rule"><outbound-rule></a>
<a href="#class-rule"><class-rule></a>
<br/>
<a href="#name"><name></a>
<a href="#note"><note></a>
<a href="#condition"><condition></a>
<a href="#from"><from></a>
<a href="#to"><to></a>
<a href="#set"><set></a>
<a href="#run"><run></a>
<br/>
<a href="#backreferences">Back References</a>
<a href="#variables">Variables</a>
<a href="#functions">Functions</a>
</small>
</td>
</tr>
</table>
<br clear="all"/>
<p>Configuration is done via a simple XML file that lives in your <code>WEB-INF</code> folder. It should be named
urlrewrite.xml.
It may be helpful to read the <a href="http://www.tuckey.org/res/dtds/urlrewrite4.0.dtd">UrlRewriteFilter DTD
(Document Type Definition)</a>. Please also make sure you look at the <a href="guide.html">examples</a>. A simple
configuration file looks like this:</p>
<pre>
<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE urlrewrite
PUBLIC "-//tuckey.org//DTD UrlRewrite 4.0//EN"
"http://www.tuckey.org/res/dtds/urlrewrite4.0.dtd">
<urlrewrite>
<rule>
<from>^/some/olddir/(.*)$</from>
<to type="redirect">/very/newdir/$1</to>
</rule>
<rule match-type="wildcard">
<from>/blog/archive/**</from>
<to type="redirect">/roller/history/$1</to>
</rule>
</urlrewrite>
</pre>
<p>The urlrewrite.xml file must have a root element called "urlrewrite" and contain
at least one "rule" element.</p>
<p>A "rule" must contain a "from" and a "to" and can have zero or more "condition" elements and zero or more and/or
"set" elements.</p>
<p>When a "rule" is processed against an incoming request, all the "condition" elements must be met, then
the "from" will be applied to the request URL and the final URL generated by applying the
"to" to the "from" pattern. So long as a rule has matched, then the "set" will be run.</p>
<p>When executing a rule the filter will (very simplified) loop over all rules and for each do something like this psuedo code:</p>
<pre>
Pattern.compile(<from> element);
pattern.matcher(request url);
matcher.replaceAll(<to> element);
if ( <condition> elements match && matcher.find() ) {
handle <set> elements (if any)
execute <run> elements (if any)
perform <to> element (if any)
}
</pre>
<a name="urlrewrite"> </a>
<h3><urlrewrite> element</h3>
<p>The top-level element.</p>
<table class="table table-bordered">
<tr>
<th>Attribute</th>
<th>Possible Value</th>
<th>Explanation</th>
</tr>
<tr>
<td rowspan="2">default-match-type <br/><small>(optional)</small></td>
<td><b>regex</b> (default)</td>
<td>All rules and conditions will be processed using the Java Regular Expression engine (unless
<code>match-type</code> is specified on a rule).</td>
</tr>
<tr>
<td>wildcard</td>
<td>All rules and conditions will be processed using the <a href="#wildcard">Wildcard Expression
engine</a>
(unless <code>match-type</code> is specified on a rule).</td>
</tr>
<tr>
<td rowspan="5">decode-using <br/><small>(optional)</small></td>
<td><b>header,utf8</b> (default)</td>
<td>When URL is decoded request.getCharacterEncoding() will be used, if that is empty UTF-8 will be used.
</td>
</tr>
<tr>
<td>null</td>
<td>Do not decode at all. (note, this means the literal string null e.g. decode-using="null") </td>
</tr>
<tr>
<td>header</td>
<td>Only use request.getCharacterEncoding() to decode.</td>
</tr>
<tr>
<td>[encoding]</td>
<td>Only use a specific character encoding, e.g., ISO-8859-1.
See <a href="http://java.sun.com/j2se/1.4.2/docs/api/java/nio/charset/Charset.html">Java Charset Object</a>
for all character encodings.
</td>
</tr>
<tr>
<td>header,[encoding]</td>
<td>
When URL is decoded request.getCharacterEncoding() will be used, if that is empty a specific character
encoding, e.g., ISO-8859-1.
See <a href="http://java.sun.com/j2se/1.4.2/docs/api/java/nio/charset/Charset.html">Java Charset Object</a>
for all character encodings.
</td>
</tr>
<tr>
<td rowspan="2">use-query-string <br/><small>(optional)</small></td>
<td><b>false</b> (default)</td>
<td>The query string will <em>not</em> be appended to the URL that the "from" element matches against.</td>
</tr>
<tr>
<td>true</td>
<td>The query string will be appended to the URL that the "from" element matches against.</td>
</tr>
<tr>
<td rowspan="2">use-context <br/><small>(optional)</small></td>
<td><b>false</b> (default)</td>
<td>The context path will <em>not</em> be added to the URL that the "from" element matches against.</td>
</tr>
<tr>
<td>true</td>
<td>The context path will be added to the URL that the "from" element matches against.</td>
</tr>
</table>
<a name="rule"> </a>
<h3><rule> element</h3>
<p>Zero or more. The basis of a rule.</p>
<table class="table table-bordered">
<tr>
<th>Attribute</th>
<th>Possible Value</th>
<th>Explanation</th>
</tr>
<tr>
<td rowspan="2">enabled <br/><small>(optional)</small></td>
<td><b>true</b> (default)</td>
<td>Enable this rule.</td>
</tr>
<tr>
<td><b>false</b></td>
<td>Disable this rule.</td>
</tr>
<tr>
<td rowspan="36">match-type <br/><small>(optional)</small></td>
<td><b>regex</b> (default)</td>
<td>This rule and its conditions will be processed using the Java Regular Expression engine.</td>
</tr>
<tr>
<td><b>wildcard</b></td>
<td>This rule and its conditions will be processed using the <a href="#wildcard">Wildcard Expression engine</a>.
</td>
</tr>
</table>
<p>In the following example requests for <code>/world/usa/nyc</code> will be transparently forwarded to
<code>/world.jsp</code></p>
<pre>
<rule match-type="regex">
<from>^/world/([a-z]+)/([a-z]+)$</from>
<to>/world.jsp</to>
</rule>
</pre>
<pre>
<rule match-type="wildcard">
<from>/world/*/*</from>
<to>/world.jsp</to>
</rule>
</pre>
<a name="outbound-rule"> </a>
<h3><outbound-rule> element</h3>
<p>Zero or more. This is very similar to a standard rule, but it is used for rewriting URLs that go through
<code>response.encodeURL()</code>.</p>
<table class="table table-bordered">
<tr>
<th>Attribute</th>
<th>Possible Value</th>
<th>Explanation</th>
</tr>
<tr>
<td rowspan="2">enabled <br/><small>(optional)</small></td>
<td><b>true</b> (default)</td>
<td>Enable this rule.</td>
</tr>
<tr>
<td>false</td>
<td>Disable this rule.</td>
</tr>
<tr>
<td rowspan="2">encodefirst <br/><small>(optional)</small></td>
<td><b>false</b> (default)</td>
<td>Run encodeURL() <b>after</b> running this outbound-rule.</td>
</tr>
<tr>
<td>true</td>
<td>Run encodeURL() <b>before</b> running this outbound-rule.</td>
</tr>
</table>
<p>May contain "run", "from", "to" and "set" element(s) also. Example:</p>
<pre>
<outbound-rule>
<from>^/world.jsp?country=([a-z]+)&amp;city=([a-z]+)$</from>
<to>/world/$1/$2</to>
</outbound-rule>
</pre>
<p>Using the example above JSP's with the code
<br/><code><a href="<%= response.encodeURL("/world.jsp?country=usa&amp;city=nyc")
%>">nyc</a></code>
<br/>will output
<br/><code><a href="/world/usa/nyc">nyc</a></code>
</p>
<p>Or JSTL
<br/><code><a href="<c:url value="/world.jsp?country=${country}&amp;city=${city}"
/>">nyc</a></code>
<br/>will output
<br/><code><a href="/world/usa/nyc">nyc</a></code>
</p>
<p>Note, If you are using JSTL (ie, <c:url), this will work also.</p>
<a name="name"> </a>
<h3><name> element</h3>
<p>An optional element used for documenting the name of the rule. This can be used with rule and outbound-rule.
See <a href="#anttask">ant task</a>.</p>
<pre>
<rule>
<b><name>World Rule</name></b>
<from>^/world/([a-z]+)/([a-z]+)$</from>
<to>/world.jsp?country=$1&amp;city=$2</to>
</rule>
</pre>
<a name="note"> </a>
<h3><note> element</h3>
<p>A simple optional element used for documentation of the rule. This can be used with rule and outbound-rule.
See <a href="#anttask">ant task</a>.</p>
<pre>
<rule>
<name>World Rule</name>
<b><note>
Cleanly redirect world requests to JSP,
a country and city must be specified.
</note></b>
<from>^/world/([a-z]+)/([a-z]+)$</from>
<to>/world.jsp</to>
</rule>
</pre>
<a name="condition"> </a>
<h3><condition> element</h3>
<p>An element that lets you choose conditions for the rule. Note, all conditions must be met for the rule to be run
(unless "next" is set to "or" obviously).</p>
<p>Value can be any <a href="http://java.sun.com/j2se/1.4.2/docs/api/java/util/regex/Pattern.html">Regular Expression</a>.</p>
<table class="table table-bordered"ble-bordered">
<tr>
<th>Attribute</th>
<th>Possible Value</th>
<th>Explanation</th>
</tr>
<tr>
<td rowspan="39">type <br/><small>(optional)</small></td>
<td><b>header</b> (default)</td><td>If used, the header name must be specified in the "name" attribute.</td></tr>
<tr><td>method</td><td>The method of the request. GET, POST, HEAD, etc.</td></tr>
<tr><td>port</td><td>The port that the web application server is running on.</td></tr>
<tr><td>time</td><td>
Current time at the server (this will be the number of seconds since 00:00:00 1970-01-01 UTC, otherwise known as Unix
time).
<br/>i.e. <code>(new Date()).getTime()</code>
<br/>This can be used for making sure content goes live only at a time you set.
</td></tr>
<tr><td>year</td><td>
Current year at the server.
<br/>i.e. <code>(Calendar.getInstance()).get(Calendar.<a
href="http://java.sun.com/j2se/1.4.2/docs/api/java/util/Calendar.html#YEAR">YEAR</a>)</code>
</td></tr>
<tr><td>month</td><td>
Month at the server. January is 0
<br/>i.e. <code>(Calendar.getInstance()).get(Calendar.<a
href="http://java.sun.com/j2se/1.4.2/docs/api/java/util/Calendar.html#MONTH">MONTH</a>)</code>
</td></tr>
<tr><td>dayofmonth</td><td>
Day of the month at the server. March first is 1
<br/>i.e. <code>(Calendar.getInstance()).get(Calendar.<a
href="http://java.sun.com/j2se/1.4.2/docs/api/java/util/Calendar.html#DAY_OF_MONTH">DAY_OF_MONTH</a>)</code>
</td></tr>
<tr><td>dayofweek</td><td>
Day of the week at the server. Saturday is 1, Sunday is 7
<br/>i.e. <code>(Calendar.getInstance()).get(Calendar.<a
href="http://java.sun.com/j2se/1.4.2/docs/api/java/util/Calendar.html#DAY_OF_WEEK">DAY_OF_WEEK</a>)</code>
</td></tr>
<tr><td>ampm</td><td>
AM or PM time at the server.
<br/>i.e. <code>(Calendar.getInstance()).get(Calendar.<a
href="http://java.sun.com/j2se/1.4.2/docs/api/java/util/Calendar.html#AM_PM">AM_PM</a>)</code>
</td></tr>
<tr><td>hourofday</td><td>
The hour of the day (24 hour clock) at the server. 10pm is 22
<br/>i.e. <code>(Calendar.getInstance()).get(Calendar.<a
href="http://java.sun.com/j2se/1.4.2/docs/api/java/util/Calendar.html#HOUR_OF_DAY">HOUR_OF_DAY</a>)</code>
</td></tr>
<tr><td>minute</td><td>
The minute field of the current time at the server.
<br/>i.e. <code>(Calendar.getInstance()).get(Calendar.<a
href="http://java.sun.com/j2se/1.4.2/docs/api/java/util/Calendar.html#MINUTE">MINUTE</a>)</code>
</td></tr>
<tr><td>second</td><td>
The second field of the current time at the server.
<br/>i.e. <code>(Calendar.getInstance()).get(Calendar.<a
href="http://java.sun.com/j2se/1.4.2/docs/api/java/util/Calendar.html#SECOND">SECOND</a>)</code>
</td></tr>
<tr><td>millisecond</td><td>
The millisecond field of the current time at the server.
<br/>i.e. <code>(Calendar.getInstance()).get(Calendar.<a
href="http://java.sun.com/j2se/1.4.2/docs/api/java/util/Calendar.html#MILLISECOND">MILLISECOND</a>)</code>
</td></tr>
<tr><td>attribute</td><td>
Will check the value of a request attribute (don't confuse this with parameter!), <code>name</code> must be set when
using this type.
<br/>i.e. <code>request.<a
href="http://java.sun.com/j2ee/1.4/docs/api/javax/servlet/ServletRequest.html#getAttribute(java.lang.String)">getAttribute</a>([name])
</code>
</td></tr>
<tr><td>auth-type</td><td>
Will check the value of a request attribute (don't confuse this with parameter!)
<br/>i.e. <code>request.<a
href="http://java.sun.com/j2ee/1.4/docs/api/javax/servlet/http/HttpServletRequest.html#getAuthType()">getAuthType</a>()
</code>
</td></tr>
<tr><td>character-encoding</td><td>
The character encoding of the imcoming request.
<br/>i.e. <code>request.<a
href="http://java.sun.com/j2ee/1.4/docs/api/javax/servlet/ServletRequest.html#getCharacterEncoding()">getCharacterEncoding</a>()
</code>
</td></tr>
<tr><td>content-length</td><td>
The length of the imcoming request (can be useful if you want to deny large requests).
<br/>i.e. <code>request.<a
href="http://java.sun.com/j2ee/1.4/docs/api/javax/servlet/ServletRequest.html#getContentLength()">getContentLength</a>()
</code>
</td></tr>
<tr><td>content-type</td><td>
The type of the imcoming request. (this is probably not that useful)
<br/>i.e. <code>request.<a
href="http://java.sun.com/j2ee/1.4/docs/api/javax/servlet/ServletRequest.html#getContentType()">getContentType</a>()
</code>
</td></tr>
<tr><td>context-path</td><td>
The context path of the imcoming request.
<br/>i.e. <code>request.<a
href="http://java.sun.com/j2ee/1.4/docs/api/javax/servlet/http/HttpServletRequest.html#getContextPath()">getContextPath</a>()
</code>
</td></tr>
<tr><td>cookie</td><td>
The value of a cookie, note, <code>name</code> must be specified to use this
<br/>i.e. <code>request.<a
href="http://java.sun.com/j2ee/1.4/docs/api/javax/servlet/http/HttpServletRequest.html#getCookies()">getCookies</a>()
</code> the find we the one with [name] specified and check the value.
</td></tr>
<tr><td>parameter</td><td>
A tidier way of checking request parameters than looking for them in the query string. This will check for the
parameter in GET or POST, note, <code>name</code> must be specified.
<br/>i.e. <code>request.<a
href="http://java.sun.com/j2ee/1.4/docs/api/javax/servlet/ServletRequest.html#getParameter(java.lang.String)">getParameter</a>([name])
</code>
</td></tr>
<tr><td>path-info</td><td>
i.e. <code>request.<a
href="http://java.sun.com/j2ee/1.4/docs/api/javax/servlet/http/HttpServletRequest.html#getPathInfo()">getPathInfo</a>()
</code>
</td></tr>
<tr><td>path-translated</td><td>
i.e. <code>request.<a
href="http://java.sun.com/j2ee/1.4/docs/api/javax/servlet/http/HttpServletRequest.html#getPathTranslated()">getPathTranslated</a>()
</code>
</td></tr>
<tr><td>protocol</td><td>The protocol used to make the request, e.g. HTTP/1.1
<br/>i.e. <code>request.<a
href="http://java.sun.com/j2ee/1.4/docs/api/javax/servlet/ServletRequest.html#getProtocol()">getProtocol</a>()
</code>
</td></tr>
<tr><td>query-string</td><td>The query string used to make the request (if any), e.g. id=2345&name=bob
<br/>i.e. <code>request.<a
href="http://java.sun.com/j2ee/1.4/docs/api/javax/servlet/http/HttpServletRequest.html#getQueryString()">getQueryString</a>()
</code>
</td></tr>
<tr><td>remote-addr</td><td>The IP address of the host making the request, e.g. 123.123.123.12
<br/>i.e. <code>request.<a
href="http://java.sun.com/j2ee/1.4/docs/api/javax/servlet/ServletRequest.html#getRemoteAddr()">getRemoteAddr</a>()
</code>
</td></tr>
<tr><td>remote-host</td><td>The host name of the host making the request, e.g. 123qw-dsl.att.com (note,
this will only work if your app server is configured to lookup host names, most aren't).
<br/>i.e. <code>request.<a
href="http://java.sun.com/j2ee/1.4/docs/api/javax/servlet/ServletRequest.html#getRemoteHost()">getRemoteHost</a>()
</code>
</td></tr>
<tr><td>remote-user</td><td>The login of the user making this request, if the user has been authenticated, e.g. bobt
<br/>i.e. <code>request.<a
href="http://java.sun.com/j2ee/1.4/docs/api/javax/servlet/http/HttpServletRequest.html#getRemoteUser()">getRemoteUser</a>()
</code>
</td></tr>
<tr><td>requested-session-id</td><td>Returns the session ID specified by the client, e.g. 2344asd234sada4
<br/>i.e. <code>request.<a
href="http://java.sun.com/j2ee/1.4/docs/api/javax/servlet/http/HttpServletRequest.html#getRequestedSessionId()">getRequestedSessionId</a>()
</code>
</td></tr>
<tr><td>requested-session-id-from-cookie</td><td>Whether the requested session ID is from a cookie or not
<br/>i.e. <code>request.<a
href="http://java.sun.com/j2ee/1.4/docs/api/javax/servlet/http/HttpServletRequest.html#isRequestedSessionIdFromCookie()">isRequestedSessionIdFromCookie</a>()
</code>
</td></tr>
<tr><td>requested-session-id-from-url</td><td>Whether the requested session ID is from the URL or not
<br/>i.e. <code>request.<a
href="http://java.sun.com/j2ee/1.4/docs/api/javax/servlet/http/HttpServletRequest.html#isRequestedSessionIdFromURL()">isRequestedSessionIdFromURL</a>()
</code>
</td></tr>
<tr><td>requested-session-id-valid</td><td>Whether the requested session ID is valid or not
<br/>i.e. <code>request.<a
href="http://java.sun.com/j2ee/1.4/docs/api/javax/servlet/http/HttpServletRequest.html#isRequestedSessionIdValid()">isRequestedSessionIdValid</a>()
</code>
</td></tr>
<tr><td>request-uri</td><td>Returns the part of this request's URL from the protocol name up to the query
string in the first line of the HTTP request
<br/>i.e. <code>request.<a
href="http://java.sun.com/j2ee/1.4/docs/api/javax/servlet/http/HttpServletRequest.html#getRequestURI()">getRequestURI()</a>
</code>
</td></tr>
<tr><td>request-url</td><td>Reconstructs the URL the client used to make the request. The returned URL
contains a protocol, server name, port number, and server path, but it does not include query string parameters.
<br/>i.e. <code>request.<a
href="http://java.sun.com/j2ee/1.4/docs/api/javax/servlet/http/HttpServletRequest.html#getRequestURL()">getRequestURL()</a>
</code>
</td></tr>
<tr><td>session-attribute</td><td>
(note, name must be set)
<br/>i.e. <code>session.<a
href="http://java.sun.com/j2ee/1.4/docs/api/javax/servlet/http/HttpSession.html#getAttribute(java.lang.String)">getAttribute([name])</a>
</code>
</td></tr>
<tr><td>session-isnew</td><td>
Weather the session is new or not.
<br/>i.e. <code>session.<a href="http://java.sun.com/j2ee/1.4/docs/api/javax/servlet/http/HttpSession.html#isNew()">isNew()</a>
</code>
</td></tr>
<tr><td>server-name</td><td>
The host name of the server to which the request was sent (from the host header not the machine name).
<br/>i.e. <code>request.<a
href="http://java.sun.com/j2ee/1.4/docs/api/javax/servlet/ServletRequest.html#getServerName()">getServerName()</a>
</code>
</td></tr>
<tr><td>scheme</td><td>
The scheme used for the request, e.g. http or https
<br/>i.e. <code>request.<a
href="http://java.sun.com/j2ee/1.4/docs/api/javax/servlet/ServletRequest.html#getScheme()">getScheme()</a>
</code>
</td></tr>
<tr><td>user-in-role</td><td>
(Note, the value for this cannot be a regular expression)
<br/>i.e. <code>request.<a
href="http://java.sun.com/j2ee/1.4/docs/api/javax/servlet/http/HttpServletRequest.html#isUserInRole(java.lang.String)">isUserInRole([value])</a>
</code>
</td></tr>
<tr>
<td>name <br/><small>(optional)</small></td>
<td>(can be anything)</td>
<td>If the type is a header, this specifies the name of the HTTP header used to run the value
against.</td>
</tr>
<tr>
<td rowspan="2">next <br/><small>(optional)</small></td>
<td><b>and</b> (default)</td><td>The next "rule" <b>and</b> this "rule" must match.</td></tr>
<tr><td>or</td><td>The next "rule" <b>or</b> this "condition" may match.</td></tr>
<tr>
<td rowspan="6">operator <br/><small>(optional)</small></td>
<td><b>equal</b> (default)</td>
<td>Equals. The operator is to be used when the condition is run, the regular expression matches, or the values are
equal.</td></tr>
<tr><td>notequal</td><td>Not equal to. (i.e. request value != condition value).</td></tr>
<tr><td>greater</td><td>Greater than. (i.e. request value > condition value). Note, this operator only works with
numeric
rule types.</td></tr>
<tr><td>less</td><td>Less than. (i.e. request value < condition value). Note, this operator only works with numeric
rule types.</td></tr>
<tr><td>greaterorequal</td><td>Greater to or equal to. (i.e. request value >= condition value). Note, this operator
only
works with numeric rule types.</td></tr>
<tr><td>lessorequal</td><td>Less than or equal to. (i.e. request value <= condition value). Note, this operator only
works with numeric rule types.</td></tr>
</table>
<p>Examples:</p>
<pre>
<condition name="user-agent" operator="notequal">Mozilla/[1-4]</condition>
<condition type="user-in-role" operator="notequal">bigboss</condition>
<condition name="host" operator="notequal">www.example.com</condition>
<condition type="method" next="or">PROPFIND</condition>
<condition type="method">PUT</condition>
</pre>
<a name="from"> </a>
<h3><from> element</h3>
<p>You must always have exactly one for each rule or outbound-rule. Value can be a regular expression in the
Perl5 style. Note, "from" URLs are relative to the context.</p>
<table class="table table-bordered">
<tr>
<th>Attribute</th>
<th>Possible Value</th>
<th>Explanation</th>
</tr>
<tr>
<td rowspan="2">casesensitive <br/><small>(optional)</small></td>
<td>false (default)</td>
<td>This value will be matched using a case insentitive match. Ie, "/WellingtoN" will match "/wellington".
</td>
</tr>
<tr>
<td>true</td>
<td>This value will be matched using a case sensitive match. ie, "/aAa" will NOT match "/aaa".
</td>
</tr>
</table>
<p>Example:</p>
<pre>
<from>^/world/([a-z]+)$</from>
</pre>
<a name="to"> </a>
<h3><to> element</h3>
<p>Value can be a regular replacement expression in the Perl5 style.</p>
<table class="table table-bordered">
<tr>
<th>Attribute</th>
<th>Possible Value</th>
<th>Explanation</th>
</tr>
<tr>
<td rowspan="8">type <br/><small>(optional)</small></td>
<td>forward (default)</td>
<td>Requests matching the "conditions" for this "rule", and the URL in the "from" element will be internally
forwarded
to the URL specified in the "to" element. Note: In this case the "to" URL must be in the same context as
UrlRewriteFilter. This is the same as doing:
<br/><code>RequestDispatcher rq = request.getRequestDispatcher([to value]);
<br/>rq.forward(request, response);</code>
</td>
</tr>
<tr>
<td>passthrough</td>
<td>Identical to "forward".</td>
</tr>
<tr>
<td>redirect</td>
<td>Requests matching the "conditions" and the "from" for this rule will be HTTP redirected.
This is the same a doing:
<br/><code>HttpServletResponse.sendRedirect([to value]))</code></td>
</tr>
<tr>
<td>permanent-redirect</td>
<td>The same as doing:
<br/><code>response.setStatus(HttpServletResponse.SC_MOVED_PERMANENTLY);
<br/>response.setHeader("Location", [to value]);</code>
<br/>(note, SC_MOVED_PERMANENTLY is the HTTP status code 301)</td>
</tr>
<tr>
<td>temporary-redirect</td>
<td>The same as doing:
<br/><code>response.setStatus(HttpServletResponse.SC_MOVED_TEMPORARILY);
<br/>response.setHeader("Location", [to value]);</code>
<br/>(note, SC_MOVED_TEMPORARILY is HTTP status code 302)</td>
</tr>
<tr>
<td>pre-include</td>
<td> </td>
</tr>
<tr>
<td>post-include</td>
<td> </td>
</tr>
<tr>
<td>proxy</td>
<td>The request will be proxied to the full URL specified. commons-http and commons-codec must both be in the
classpath to use this feature.
</td>
</tr>
<tr>
<td rowspan="2">last <br/><small>(optional)</small></td>
<td>false (default)</td>
<td>The rest of the "rules" will be processed if this one succeeds.</td>
</tr>
<tr>
<td>true</td>
<td>No more "rules" will be processed if this one is a match.</td>
</tr>
<tr>
<td rowspan="2">encode <br/><small>(optional)</small></td>
<td>false (default if under rule)</td>
<td>response.<a
href="http://java.sun.com/j2ee/1.4/docs/api/javax/servlet/http/HttpServletResponse.html#encodeURL(java.lang.String)">encodeURL</a>([to])
will be run on the to url before performing the rewrite.</td>
</tr>
<tr>
<td>true (default if under outbound-rule)</td>
<td>response.<a
href="http://java.sun.com/j2ee/1.4/docs/api/javax/servlet/http/HttpServletResponse.html#encodeURL(java.lang.String)">encodeURL</a>([to])
will NOT be called.</td>
</tr>
<tr>
<td>context <br/><small>(optional)</small></td>
<td> </td>
<td>If your application server is configured to allow "cross-context" communication, then this attribute can be used
to forward (and only forward, not redirect or other "to" types) requests to a named servlet context.
<br/>
<br/>On Tomcat, for instance, the application contexts in the server configuration (server.xml or
context.xml) need the option crossContext="true". For instance, the two applications mentioned before
("app" and "forum") have to be defined as:
<br/>
<br/><code><Context docBase="app" path="/app" reloadable="true" crossContext="true"/></code>
<br/><code><Context docBase="forum" path="/forum" reloadable="true" crossContext="true"/></code>
</td>
</tr>
<tr>
<td rowspan="2">qsappend <br/><small>(optional)</small></td>
<td>false (default)</td>
<td></td>
</tr>
<tr>
<td>true</td>
<td>Append the query string to the to url when redirecting or forwarding.</td>
</tr>
</table>
<p>Note, "to" can be null, i.e., <code><to>null</to></code>; this will mean that the request will go no
further if the rule is matched (i.e., this filter will not call <code>chain.doFilter</code>).</p>
<p>If "to" is set to -, no substitution will take place, and the request will go on like nothing happened (i.e., this filter will call <code>chain.doFilter</code>).</p>
<pre>
<to>/world.jsp?country=$1</to>
</pre>
<p>To elements can contain backreferences and variables.</p>
<a name="backreferences"> </a>
<h4>Backreferences</h4>
<pre>
%N
</pre>
<p>Provides access to the grouped parts (parentheses) of the pattern from the last matched <a href="#condition">Condition</a>
in the current rule.
N must be less than 10 and greater than 0 (i.e. %1, %2, %3 etc).</p>
<a name="variables"> </a>
<h4>Variables</h4>
<pre>
%{VARIABLE-NAME}
</pre>
<p>Any valid condition type can be used as a variable name. ie,
'<code>%{port}</code>' will be translated to '<code>80</code>',
'<code>%{year}</code>' to '<code>2005</code>',
'<code>%{cookie:myCookie}</code>' would be translated to
'<code>myCookieValue</code>' (assuming the user had a cookie named myCookie with the value myCookieValue).</p>