com.sun.portal.providers.context
Class PropertiesFilter

java.lang.Object
  extended bycom.sun.portal.providers.context.PropertiesFilter
Direct Known Subclasses:
ClientPropertiesFilter, LocalePropertiesFilter

public abstract class PropertiesFilter
extends java.lang.Object

This class is an abstract PropertiesFilter class. Every PropertiesFilter implementation must extend this class.

A PropertiesFilter is used to describe an arbitrary filter which is used to selectively look up properties with certain criteria as well as when storing properties that are specific to certain setting. The PropertiesFilter itself does not compare any actual property values. Rather, it determines if the qualifiers ('condition' and 'value') associated with the property match the filter criteria supplied in the PropertiesFilter.

PropertiesFilters are instantiated using methods provided in PropertiesFilterFactory and are not to be constructed directly. In addition, PropertiesFilter objects are meant to be immutable and stateless. Once a PropertiesFilter is initialized, the value cannot be modified.

Nevertheless, in some cases, having an access to stateful objects such as ProviderContext within the PropertiesFilter, especially in the match() method may become necessary. This can be achieved by extending the PropertierFilter in such a way that the stateful object(s) can be passed in the constructor and stored as a member variable. Instantiating such a PropertiesFilter is done by directly constructing the PropertiesFilter, bypassing the PropertiesFilterFactory.
Here is an example:

public class LoggingPropertiesFilter extends PropertiesFilter {
private ProviderContext pc = null;
public LoggingPropertiesFilter(ProviderContext pc, String value, boolean required) {
super();
this.pc = pc;
try {
init(value, required);
} catch (PropertiesFilterException pfe) {
pc.debugError("LoggingPropertiesFilter(): Failed to init." , pfe);
}
}
public String getCondition() {
return "loggingEnabled";
}
public boolean match(String condition, String value) throws PropertiesFilterException {
if (!condition.equals("loggingEnabled")) {
return false;
}
if (getValue().equals(value)) {
pc.debugMessage("LoggingPropertiesFilter(): matched loggingEnabled property. value=" value);
}
return true;
}
}

List pflist = new ArrayList();
pflist.add(new LoggingPropertiesFilter(getProviderContext(), "foo", true);
Note that bypassing PropertiesFilterFactory may have a performance impact. Also, PropertiesContext has a life-span of one session and should not be s

Properties are looked up using different types of get/set*Property() methods which are available in ProviderContext.

See Also:
ProviderContext, PropertiesFilterFactory

Constructor Summary
PropertiesFilter()
          Constructor.
 
Method Summary
abstract  java.lang.String getCondition()
          Get the condition of the filter, such as "locale" and "client".
 java.lang.String getValue()
          Get the value of the filter that is associated with the condition of the filter.
protected  void init(java.lang.String value, boolean required)
          Initialize PropertiesFilter with given values.
 boolean isRequired()
          Is filter required? A conditional property lookup involves one or more property filters.
abstract  boolean match(java.lang.String condition, java.lang.String value)
          Does the given condition and value match the filter?
 java.lang.String toString()
          Return a string representation of the PropertiesFilter.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

PropertiesFilter

public PropertiesFilter()
Constructor. In most cases, PropertiesFilters should not be constructed directly. Instead, use PropertiesFilterFactory.get().

See Also:
PropertiesFilterFactory.get(String, String, boolean)
Method Detail

init

protected void init(java.lang.String value,
                    boolean required)
             throws PropertiesFilterException
Initialize PropertiesFilter with given values. PropertiesFilters are immutable. You cannot re-initialize an already initialized PropertiesFilter with new values. Doing so will results in no-op.

Parameters:
value - The value that gets associated with the filter.
required - Flag indicating whether this filter criteria is required or optional.
Throws:
PropertiesFilterException - there was an error while initializing values

getCondition

public abstract java.lang.String getCondition()
                                       throws PropertiesFilterException
Get the condition of the filter, such as "locale" and "client". Filter condition is an unmodifiable constant value.

Returns:
filter condition
Throws:
PropertiesFilterException - if there is an error in getting the condition of the filter.

getValue

public java.lang.String getValue()
Get the value of the filter that is associated with the condition of the filter.

Returns:
filter value that was used to instantiate this PropertiesFilter.

isRequired

public boolean isRequired()
Is filter required? A conditional property lookup involves one or more property filters. If a filter in the filter list is required, then it must match for the overall conditional lookup to succeed. If a filter is not required, then it can fail to match without causing the overall lookup to fail. A chain of non-required filters can be used to implement a progressively less-specific filter lookup, similar to the semantics of Java resource bundle lookup.

For instance, an optional filter would be useful in a case where a locale lookup is followed by a date lookup. Given the filter {locale=en, locale=US, date=03/03/2003}, you can get it to successfully match a property with the qualifier {locale=en; date=03/03/2003} even though it does not exactly match the filter specification. This done by setting the locale filter to be optional.

Returns:
boolean indicating whether this filter is required or optional.

match

public abstract boolean match(java.lang.String condition,
                              java.lang.String value)
                       throws PropertiesFilterException
Does the given condition and value match the filter?

Parameters:
condition - the condition to be matched against the filter condition
value - the value to be matched against the filter value
Throws:
PropertiesFilterException - if there is an error in processing properties to be matched.

toString

public java.lang.String toString()
Return a string representation of the PropertiesFilter. Useful for debugging.

Returns:
a String representation of the PropertiesFilter.