org.ocap.application
Class AppFilter

java.lang.Object
  extended by org.dvb.application.AppsDatabaseFilter
      extended by org.ocap.application.AppFilter

public class AppFilter
extends AppsDatabaseFilter

AppFilter provides a means of filtering AppIDs. As a subclass of AppsDatabaseFilter, the method accept(org.dvb.application.AppID) makes a true/false decision based on an AppID.

An AppFilter contains a list of zero or more AppPatterns. Each AppPattern has the attributes: pattern, action, and priority. pattern specifies a group of AppIDs with a pair of ranges for organization ID and application ID. action specifies an action assigned to the AppID group; either AppPattern.ALLOW, AppPattern.DENY, or AppPattern.ASK. priority specifies this AppPattern's position in the search order: the biggest number comes first. Applications can insert an AppPattern anywhere in the search order by using the priority attribute effectively (AppFilter.add). When two or more AppPatterns in an AppFilter have the same priority, the search order among them is undefined. It is not recommendable to use AppPatterns that have the same priority but different actions.

When accept is called, the given AppID is compared to the AppID group of each AppPattern in the search order until a match is found. Then, it returns true or false if the action of matching AppPattern is ALLOW or DENY respectively. If no match is found, accept returns true.

If the action of matching AppPattern is ASK, then AppFilter calls AppFilterHandler.accept for the final decision; the matching AppPattern is handed over to this method. Applications can specify the AppFilterHandler with AppFilter.setAskHandler. If no AppFilterHandler is set, AppFilter returns true.

AppPatterns can have an expiration time and MSO-private information (expirationTime and info). accept and getAppPatterns methods ignore AppPatterns that have expired. The implementation may delete expired AppPatterns from AppFilter.

Example:

 import org.ocap.application.*;
 import org.dvb.application.AppID;

 AppManagerProxy am = ...;
 AppPattern[] patterns = {
     /* note that search order is dictated by "priority" */
     new AppPattern("10-5f:1-ff", AppPattern.ALLOW, 40),     // #3
     new AppPattern("30:2c-34", AppPattern.ALLOW, 100),      // #1
     new AppPattern("20-40", AppPattern.DENY, 80),           // #2
 };
 AppFilter af = new AppFilter(patterns);
 
 /* false - matches "20-40" */
 boolean badOne = af.accept(new AppID(0x30, 0x10));

 /* true - matches "30:2c-34" */
 boolean goodOne = af.accept(new AppID(0x30, 0x30));

 /* will be the second entry: priority between 100 and 80 */
 af.add(new AppPattern("40-4f:1000-1fff", DENY, 90));

 /* register af with the system */
 am.setAppFilter(af);
 

See Also:
AppPattern, AppFilterHandler, AppManagerProxy, AppID, AppsDatabaseFilter

Constructor Summary
AppFilter()
          Constructs an empty AppFilter.
AppFilter(AppPattern[] patterns)
          Constructs an AppFilter with initial AppPatterns.
 
Method Summary
 boolean accept(AppID appID)
          Returns whether this AppFilter accepts the given AppID.
 void add(AppPattern pattern)
          Adds an AppPattern to this AppFilter.
 java.util.Enumeration getAppPatterns()
          Returns the AppPatterns in this AppFilter.
 boolean remove(AppPattern pattern)
          Removes an AppPattern that equals to pattern in this AppFilter.
 void setAskHandler(AppFilterHandler handler)
          Sets the handler to call when accept hits an AppPatterns with action AppPattern.ASK.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

AppFilter

public AppFilter()
Constructs an empty AppFilter.


AppFilter

public AppFilter(AppPattern[] patterns)
Constructs an AppFilter with initial AppPatterns.

Parameters:
patterns - AppPatterns to constitute an AppFilter.
Method Detail

getAppPatterns

public java.util.Enumeration getAppPatterns()
Returns the AppPatterns in this AppFilter.

Returns:
the enumeration of AppPatterns. When this AppFilter has no AppPattern, this method returns an empty Enumeration, not null.

accept

public boolean accept(AppID appID)
Returns whether this AppFilter accepts the given AppID.

Specified by:
accept in class AppsDatabaseFilter
Parameters:
appID - an AppID to test.
Returns:
true if appID passes this filter.

add

public void add(AppPattern pattern)
Adds an AppPattern to this AppFilter.

Parameters:
pattern - the AppPattern to add

remove

public boolean remove(AppPattern pattern)
Removes an AppPattern that equals to pattern in this AppFilter. If this AppFilter does not contain pattern, it is unchanged.

Parameters:
pattern - the AppPattern to remove.
Returns:
true if the AppFilter contained the specified AppPattern.
See Also:
AppPattern.equals(java.lang.Object)

setAskHandler

public void setAskHandler(AppFilterHandler handler)
Sets the handler to call when accept hits an AppPatterns with action AppPattern.ASK.

If a handler is already registered with this AppFilter, the new handler replaces it.

Parameters:
handler - the handler to set.