Package org.apache.shiro.web.filter.mgt
Interface FilterChainManager
-
- All Known Implementing Classes:
DefaultFilterChainManager
public interface FilterChainManager
AFilterChainManager
manages the creation and modification ofFilter
chains from an available pool ofFilter
instances.- Since:
- 1.0
-
-
Method Summary
All Methods Instance Methods Abstract Methods Modifier and Type Method Description void
addFilter(String name, Filter filter)
Adds a filter to the 'pool' of available filters that can be used whencreating filter chains
.void
addFilter(String name, Filter filter, boolean init)
Adds a filter to the 'pool' of available filters that can be used whencreating filter chains
.void
addToChain(String chainName, String filterName)
Adds (appends) a filter to the filter chain identified by the givenchainName
.void
addToChain(String chainName, String filterName, String chainSpecificFilterConfig)
Adds (appends) a filter to the filter chain identified by the givenchainName
.void
createChain(String chainName, String chainDefinition)
Creates a filter chain for the givenchainName
with the specifiedchainDefinition
String.void
createDefaultChain(String chainName)
Creates a chain that should match any non-matched request paths, typically/**
assuming anAntPathMatcher
I used.NamedFilterList
getChain(String chainName)
Returns the filter chain identified by the specifiedchainName
ornull
if there is no chain with that name.Set<String>
getChainNames()
Returns the names of all configured chains or an emptySet
if no chains have been configured.Map<String,Filter>
getFilters()
Returns the pool of availableFilter
s managed by this manager, keyed byname
.boolean
hasChains()
Returnstrue
if one or more configured chains are available,false
if none are configured.FilterChain
proxy(FilterChain original, String chainName)
Proxies the specifiedoriginal
FilterChain with the named chain.void
setGlobalFilters(List<String> globalFilterNames)
Configures the set of named filters that will match all paths.
-
-
-
Method Detail
-
getFilters
Map<String,Filter> getFilters()
Returns the pool of availableFilter
s managed by this manager, keyed byname
.- Returns:
- the pool of available
Filter
s managed by this manager, keyed byname
.
-
getChain
NamedFilterList getChain(String chainName)
Returns the filter chain identified by the specifiedchainName
ornull
if there is no chain with that name.- Parameters:
chainName
- the name identifying the filter chain.- Returns:
- the filter chain identified by the specified
chainName
ornull
if there is no chain with that name.
-
hasChains
boolean hasChains()
Returnstrue
if one or more configured chains are available,false
if none are configured.- Returns:
true
if one or more configured chains are available,false
if none are configured.
-
getChainNames
Set<String> getChainNames()
Returns the names of all configured chains or an emptySet
if no chains have been configured.- Returns:
- the names of all configured chains or an empty
Set
if no chains have been configured.
-
proxy
FilterChain proxy(FilterChain original, String chainName)
Proxies the specifiedoriginal
FilterChain with the named chain. The returnedFilterChain
instance will first execute the configured named chain and then lastly invoke the givenoriginal
chain.- Parameters:
original
- the original FilterChain to proxychainName
- the name of the internal configured filter chain that should 'sit in front' of the specified original chain.- Returns:
- a
FilterChain
instance that will execute the named chain and then finally the specifiedoriginal
FilterChain instance. - Throws:
IllegalArgumentException
- if there is no configured chain with the givenchainName
.
-
addFilter
void addFilter(String name, Filter filter)
Adds a filter to the 'pool' of available filters that can be used whencreating filter chains
. Calling this method is effectively the same as callingaddFilter
(name, filter, false);- Parameters:
name
- the name to assign to the filter, used to reference the filter in chain definitionsfilter
- the filter to initialize and then add to the pool of available filters that can be used
-
addFilter
void addFilter(String name, Filter filter, boolean init)
Adds a filter to the 'pool' of available filters that can be used whencreating filter chains
.- Parameters:
name
- the name to assign to the filter, used to reference the filter in chain definitionsfilter
- the filter to assign to the filter poolinit
- whether or not theFilter
should beinitialized
first before being added to the pool.
-
createChain
void createChain(String chainName, String chainDefinition)
Creates a filter chain for the givenchainName
with the specifiedchainDefinition
String.Conventional Use
Because theFilterChainManager
interface does not impose any restrictions on filter chain names, (it expects only Strings), a convenient convention is to make the chain name an actual URL path expression (such as anAnt path expression
). For example:createChain(path_expression, path_specific_filter_chain_definition);
This convention can be used by aFilterChainResolver
to inspect request URL paths against the chain name (path) and, if a match is found, return the corresponding chain for runtime filtering.Chain Definition Format
ThechainDefinition
method argument is expected to conform to the following format:filter1[optional_config1], filter2[optional_config2], ..., filterN[optional_configN]
wherefilterN
is the name of a filter previouslyregistered
with the manager, and[optional_configN]
is an optional bracketed string that has meaning for that particular filter for this particular chain
filterN[]
just becomesfilterN
. And because this method does create a chain, remember that order matters! The comma-delimited filter tokens in thechainDefinition
specify the chain's execution order.Examples
/account/** = authcBasic
This example says "Create a filter named '/account/**
' consisting of only the 'authcBasic
' filter". Also because theauthcBasic
filter does not need any path-specific config, it doesn't have any config brackets[]
./remoting/** = authcBasic, roles[b2bClient], perms["remote:invoke:wan,lan"]
This example by contrast uses the 'roles' and 'perms' filters which do use bracket notation. This definition says: Construct a filter chain named '/remoting/**
' which- ensures the user is first authenticated (
authcBasic
) then - ensures that user has the
b2bClient
role, and then finally - ensures that they have the
remote:invoke:lan,wan
permission.
- authcBasic
- roles[b2bclient]
- perms[remote:invoke:lan
- wan]
- Parameters:
chainName
- the name to associate with the chain, conventionally a URL path pattern.chainDefinition
- the string-formatted chain definition used to construct an actualNamedFilterList
chain instance.- See Also:
FilterChainResolver
,AntPathMatcher
-
createDefaultChain
void createDefaultChain(String chainName)
Creates a chain that should match any non-matched request paths, typically/**
assuming anAntPathMatcher
I used.- Parameters:
chainName
- The name of the chain to create, likely/**
.- Since:
- 1.6
- See Also:
AntPathMatcher
-
addToChain
void addToChain(String chainName, String filterName)
Adds (appends) a filter to the filter chain identified by the givenchainName
. If there is no chain with the given name, a new one is created and the filter will be the first in the chain.- Parameters:
chainName
- the name of the chain where the filter will be appended.filterName
- the name of theregistered
filter to add to the chain.- Throws:
IllegalArgumentException
- if there is not aregistered
filter under the givenfilterName
-
addToChain
void addToChain(String chainName, String filterName, String chainSpecificFilterConfig) throws ConfigurationException
Adds (appends) a filter to the filter chain identified by the givenchainName
. If there is no chain with the given name, a new one is created and the filter will be the first in the chain. Note that the final argument expects the associated filter to be an instance of aPathConfigProcessor
to accept per-chain configuration. If it is not, aIllegalArgumentException
will be thrown.- Parameters:
chainName
- the name of the chain where the filter will be appended.filterName
- the name of theregistered
filter to add to the chain.chainSpecificFilterConfig
- the filter-specific configuration that should be applied for only the specified filter chain.- Throws:
IllegalArgumentException
- if there is not aregistered
filter under the givenfilterName
ConfigurationException
- if the filter is not capable of acceptingchainSpecificFilterConfig
(usually such filters implement thePathConfigProcessor
interface).
-
setGlobalFilters
void setGlobalFilters(List<String> globalFilterNames) throws ConfigurationException
Configures the set of named filters that will match all paths. These filters will match BEFORE explicitly configured filter chains i.e. by callingcreateChain(String, String)
,addToChain(String, String)
, etc.
Filters configured in this list wll apply to ALL requests.- Parameters:
globalFilterNames
- the list of filter names to match ALL paths.- Throws:
ConfigurationException
- if one of the filter names is invalid and cannot be loaded from the set of configured filtersgetFilters()
}.- Since:
- 1.6
-
-