TherewritevalveimplementsURLrewritefunctionalityinawaythatisverysimilartomod_rewritefromApacheHTTPServer.
Therewritevalveisconfiguredasavalveusingtheorg.apache.catalina.valves.rewrite.RewriteValveclassname.
Itcanalsobeinthecontext.xmlofawebapp.Thevalvewillthenusearewrite.configfilecontainingtherewritedirectives,itmustbeplacedintheWEB-INFfolderofthewebapplication
Therewrite.configfilecontainsalistofdirectiveswhichcloselyresemblethedirectivesusedbymod_rewrite,inparticularthecentralRewriteRuleandRewriteConddirectives.Linesthatstartwitha#characteraretreatedascommentsandwillbeignored.
Syntax:RewriteCondTestStringCondPattern
TheRewriteConddirectivedefinesarulecondition.OneormoreRewriteCondcanprecedeaRewriteRuledirective.ThefollowingruleisthenonlyusedifboththecurrentstateoftheURImatchesitspattern,andiftheseconditionsaremet.
TestStringisastringwhichcancontainthefollowingexpandedconstructsinadditiontoplaintext:
ThesevariablesallcorrespondtothesimilarlynamedHTTPMIME-headersandServletAPImethods.MostaredocumentedelsewhereintheManualorintheCGIspecification.Thosethatarespecialtotherewritevalveincludethosebelow.
Otherthingsyoushouldbeawareof:
CondPatternistheconditionpattern,aregularexpressionwhichisappliedtothecurrentinstanceoftheTestString.TestStringisfirstevaluated,beforebeingmatchedagainstCondPattern.
Remember:CondPatternisaperlcompatibleregularexpressionwithsomeadditions:
Example:
TorewritetheHomepageofasiteaccordingtothe``User-Agent:''headeroftherequest,youcanusethefollowing:
RewriteCond%{HTTP_USER_AGENT}^Mozilla.*RewriteRule^/$/homepage.max.html[L]RewriteCond%{HTTP_USER_AGENT}^Lynx.*RewriteRule^/$/homepage.min.html[L]RewriteRule^/$/homepage.std.html[L]Explanation:Ifyouuseabrowserwhichidentifiesitselfas'Mozilla'(includingNetscapeNavigator,Mozillaetc),thenyougetthemaxhomepage(whichcouldincludeframes,orotherspecialfeatures).IfyouusetheLynxbrowser(whichisterminal-based),thenyougettheminhomepage(whichcouldbeaversiondesignedforeasy,text-onlybrowsing).Ifneitheroftheseconditionsapply(youuseanyotherbrowser,oryourbrowseridentifiesitselfassomethingnon-standard),yougetthestd(standard)homepage.
Syntax:RewriteMapnamerewriteMapClassNameoptionalParameters
TherewriteMapClassNamevaluealsoallowsspecialvalues:
Themapsareimplementedusinganinterfacethatusersmustimplement.Itsclassnameisorg.apache.catalina.valves.rewrite.RewriteMap,anditscodeis:
packageorg.apache.catalina.valves.rewrite;publicinterfaceRewriteMap{publicStringsetParameters(Stringparams);publicStringlookup(Stringkey);}RewriteRuleSyntax:RewriteRulePatternSubstitution
TheRewriteRuledirectiveistherealrewritingworkhorse.Thedirectivecanoccurmorethanonce,witheachinstancedefiningasinglerewriterule.Theorderinwhichtheserulesaredefinedisimportant-thisistheorderinwhichtheywillbeappliedatrun-time.
Patternisaperlcompatibleregularexpression,whichisappliedtothecurrentURL.``Current''meansthevalueoftheURLwhenthisruleisapplied.ThismaynotbetheoriginallyrequestedURL,whichmayalreadyhavematchedapreviousrule,andhavebeenaltered.
Somehintsonthesyntaxofregularexpressions:
MasteringRegularExpressions,2ndEditionJeffreyE.F.FriedlO'Reilly&Associates,Inc.2002ISBN978-0-596-00289-3
Intherules,theNOTcharacter('!')isalsoavailableasapossiblepatternprefix.Thisenablesyoutonegateapattern;tosay,forinstance:``ifthecurrentURLdoesNOTmatchthispattern''.Thiscanbeusedforexceptionalcases,whereitiseasiertomatchthenegativepattern,orasalastdefaultrule.
Note:WhenusingtheNOTcharactertonegateapattern,youcannotincludegroupedwildcardpartsinthatpattern.Thisisbecause,whenthepatterndoesNOTmatch(i.e.,thenegationmatches),therearenocontentsforthegroups.Thus,ifnegatedpatternsareused,youcannotuse$Ninthesubstitutionstring!
Thesubstitutionofarewriteruleisthestringwhichissubstitutedfor(orreplaces)theoriginalURLwhichPatternmatched.Inadditiontoplaintext,itcaninclude
Back-referencesareidentifiersoftheform$N(N=0..9),whichwillbereplacedbythecontentsoftheNthgroupofthematchedPattern.Theserver-variablesarethesameasfortheTestStringofaRewriteConddirective.Themapping-functionscomefromtheRewriteMapdirectiveandareexplainedthere.Thesethreetypesofvariablesareexpandedintheorderabove.
Asalreadymentioned,allrewriterulesareappliedtotheSubstitution(intheorderinwhichtheyaredefinedintheconfigfile).TheURLiscompletelyreplacedbytheSubstitutionandtherewritingprocesscontinuesuntilallruleshavebeenapplied,oritisexplicitlyterminatedbyaLflag.
Thespecialcharacters$and%canbequotedbyprependingthemwithabackslashcharacter\.
Thereisaspecialsubstitutionstringnamed'-'whichmeans:NOsubstitution!ThisisusefulinprovidingrewritingruleswhichonlymatchURLsbutdonotsubstituteanythingforthem.ItiscommonlyusedinconjunctionwiththeC(chain)flag,inordertoapplymorethanonepatternbeforesubstitutionoccurs.
Unlikenewermod_rewriteversions,theTomcatrewritevalvedoesnotautomaticallysupportabsoluteURLs(thespecificredirectflagmustbeusedtobeabletospecifyanabsoluteURLs,seebelow)ordirectfileserving.
AdditionallyyoucansetspecialflagsforSubstitutionbyappending[flags]asthethirdargumenttotheRewriteRuledirective.Flagsisacomma-separatedlistofanyofthefollowingflags: