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 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 manage this
proxy server, if it is not already started.
About this task
A filter provides an optional, secondary function control, that is
beyond the control that is provided through typical product settings. For
example, an application 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
class.
- 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 life cycle
functionality.
- Write a new doFilter method, that uses the HttpProxyServiceContext
interface.
This new doFilter method can be written to:
- Change any artifacts that are associated with the request or the response,
such as the response itself, the response code, or the headers.
- Change any artifacts that are associated with both the request and the
response.
- Obtain information about either the request or the response.
- Obtain 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, is displayed.
- 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="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.