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.proxy.filter.http.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 run on both the request
and the response. The filter point determines where the filter is
run. In this example, the filter runs 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="https://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 run 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 it 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.