You can create a custom filter for your proxy server if
you need to have the proxy server perform a function, such as customized
logging, that is not provided through normal product settings.
Before you begin
- Determine where you are going to store the artifact that contains
the filter you create. You can import this artifact from either a
local or remote file system.
- You must know the name of the proxy server on which you want to
install the custom filter.
- You must start the administrative console that is used to control
this proxy server, it is not already started.
About this task
A filter provides an optional, secondary control over a function,
that is beyond the control that is normally provided through typical
product settings. For example, an applications might use a logging
filter mechanism to suppress all of the events that have a particular
message key.
Procedure
- Create a custom filter.
- Create a class that extends com.ibm.wsspi.HttpDefaultFilter.
- Override the abstract doFilter method, and, optionally,
the init and destroy methods. If you override the init and destroy
methods, you must call the super versions of these methods to preserve
filter lifecycle functionality.
- Write a new doFilter method, that uses the HttpProxyServiceContext
interface.
This new doFilter method can be written such
that it:
- Changes any artifacts that are associated with the request or
the response, such as the response itself, the response code, or the
headers.
- Changes any artifacts that are associated with both the request
and the response.
- Obtains information about either the request or the response.
- Obtains information about both the request and the response.
- Use the proxy server filter managed bean (MBean), proxyFilterMbean,
to determine the correct ordinal for the filter.
proxyFilterMbean = AdminControl.queryNames('type=ProxyServerFilterBean,*')
AdminControl.invoke(proxyFilterMbean, 'viewAllFilters')
The order, in which all of the filters on the
proxy server are processed, displays.
- Create the filter descriptor file, filter-context.xml
This file is used to define all of the filters that have
this descriptor. The following example illustrates a basic version
of a filter-context.xml file.
In this example. the descriptor
determines where and when the given filter is executed on both the
request and the response. The filter point determines where the filter
is executed. In this example, the filter executes after the request
is received. The ordinal determines when the filter gets processed
relative to other filters at the same filter point. The higher the
ordinal, the higher the filter is in the processing queue.
<?xml version="1.0" encoding="UTF-8>
<filter-context xmlns="http://www.ibm.com/2003/FilterContextSchema">
<description>Proxy Filter Sample descriptor</description>
<display-name>Proxy Sample Filter</display-name>
<filter>
<filter-name>HttpRequestFilter</filter-name
<filter-class>com.ibm.ws.proxy.sample.HttpRequestFilter</filter-class>
<description>HTTP sample filter to execute at REQUEST filter point</description>
<display-name>HTTP Request Sample</display-name>
<protocol-name>HTTP</protocol-name>
<filter-point>RequestReceived</filter-point>
<ordinal>1000</ordinal>
</filter>
</filter-context>
- Bundle the compiled .class files for the filter, and
the filter descriptor into a JAR file.
- Import the artifact (JAR file) that contains the custom
filter.
- In the administrative console, click .
- Select either Local file system or Remote file system to indicate where the
JAR file is located.
- Specify the fully qualified name of the JAR file.
The fully qualified name of the JAR file includes the directory
path to where the file is located, and the file name. If you do not
know the fully qualified name of the JAR file, you can use the browse
function to locate the file.
- Create a business level application (BLA) that includes
this artifact.
- In the administrative console, click .
- In the Name field, specify a
name for the new application that you are creating.
You can also specify a description of the application in the Description field.
- Click Apply.
- Create a BLA composition unit (CU) from the artifact.
- In the Deployed assets table,
click Add > Add asset.
- Select the name of the artifact that you imported in
the first step, and then click Continue.
- Change the composition unit settings as needed, and
then click Modify target.
- Select the proxy server on which you want to deploy
this CU from the list of available deployment targets, and then click OK.
When you click OK the product maps the composition unit to the selected proxy server.
- Specify the relationship options for this composition
unit.
- Click Finish.
To verify that the product successfully added the CU,
click application_name. If
the product successfully adds the CU, the name of the CU is shown
in the list of deployed assets for this BLA.
- Start the proxy server.
- Start the BLA that contains the filter.
Results
The filter is running on the proxy server.
What to do next
Use the proxy server filter MBean, proxyFilterMbean, to verify
that the filter is installed on the proxy server and that is is being
processed in the correct order relative to the other filters that
are deployed on the proxy server. If you need to change the order
in which this filter is processed, run the modifyOrdinal command against
the proxyFilterMbean MBean.