com.ibm.wbi
Class Meg

com.ibm.wbi.Meg
Direct Known Subclasses:
Editor, Generator, Monitor, RequestEditor

public abstract class Meg

A Meg is a self-contained content tailoring entity. It receives a call to handleRequest() to tailor a particular type of "Request" specified by the provided RequestEvent. The meg must be thread safe since multiple threads (for different requests) may be calling the handleRequest() method.


Field Summary
static java.lang.String COPYRIGHT
          IBM copyright information.
static int EDITOR
          An Editor meg.
static int GENERATOR
          A Generator meg.
static int MONITOR
          A Monitor meg.
static int REQUEST_EDITOR
          A Request Editor meg.
static int UNDEFINED
          An undefined meg type.
 
Method Summary
 void forwardRequest(Meg meg, RequestEvent event)
          Forward this request directly to another Meg for handling.
 java.lang.String getCondition()
          Get the condition of the Meg.
 boolean getEnabled()
          Get the enabled state of the Meg.
 java.lang.String getMegProperty(java.lang.String key)
          Returns the property which is mapped to the given key name.
 java.lang.String getMegProperty(java.lang.String key, java.lang.String defaultValue)
          Returns the property which is mapped to the given key name or a default value if no value was found in the database.
 java.util.Enumeration getMegPropertyKeys()
          Returns an enumeration of all the Meg property keys set by this Meg.
 java.lang.String getName()
          Get the name of the Meg.
 Plugin getPlugin()
          Get the Plugin of the Meg.
 int getPriority()
          Get the priority of the Meg in the range of 100 to 1.
 SystemContext getSystemContext()
          Get the SystemContext object passed in with the initialize method.
abstract  int getType()
          Get the Meg type.
abstract  void handleRequest(RequestEvent event)
          The method called to handle a request that satisfies the Meg's condition.
 void initialize()
          Called when the Meg is initialized.
 void initialize(SystemContext systemContext)
          Deprecated. Override initialize() instead and use getSystemContext()
 boolean isEnabled()
          Determine if this Meg is enabled.
 boolean isMegApplicable(RequestInfo ri)
          Determines if this meg satisfies a request by its RequestInfo object using the built condition tree (does not consider if it is enabled or not).
protected  void loadMegResources(Section section)
          Retains a reference to the database section for this Meg's properties which is used for getMegResource and setMegResource methods.
protected  void run(java.lang.Object argument)
           
 void setCondition(java.lang.String condition)
          Set the condition of the Meg.
 void setEnabled(boolean enabled)
          Set the enabled state of the Meg.
 void setMegProperty(java.lang.String key, java.lang.String value)
          Sets the property which is mapped to the given Meg property key name.
 void setName(java.lang.String name)
          Set the name of the Meg used to provide a description.
 void setPriority(int priority)
          Set the priority of the Meg.
 void setSystemContext(SystemContext systemContext)
          Set the SystemContext object for this Meg.
 void setup(java.lang.String propertyName)
          Load the attributes for the Meg from a property file.
 void setup(java.lang.String name, java.lang.String condition)
          Setup the Meg with the given attributes.
 void setup(java.lang.String name, java.lang.String condition, int priority)
          Setup the Meg with the given attributes and is enabled.
 void setup(java.lang.String name, java.lang.String condition, int priority, boolean enabled)
          Setup the Meg with the given attributes.
 

Field Detail

COPYRIGHT

public static final java.lang.String COPYRIGHT
IBM copyright information.

UNDEFINED

public static final int UNDEFINED
An undefined meg type.

REQUEST_EDITOR

public static final int REQUEST_EDITOR
A Request Editor meg.

GENERATOR

public static final int GENERATOR
A Generator meg.

EDITOR

public static final int EDITOR
An Editor meg.

MONITOR

public static final int MONITOR
A Monitor meg.
Method Detail

setup

public void setup(java.lang.String propertyName)
Load the attributes for the Meg from a property file. Any or all of the following attributes can be set:
Parameters:
propertyName - The property file to load the meg attributes from.

setup

public void setup(java.lang.String name,
                  java.lang.String condition)
Setup the Meg with the given attributes. The priority defaults to 1 and the Meg is enabled.
Parameters:
name - The name of the meg.
condition - The condition under which this meg should be invoked.

setup

public void setup(java.lang.String name,
                  java.lang.String condition,
                  int priority)
Setup the Meg with the given attributes and is enabled.
Parameters:
name - The name of the meg.
condition - The condition under which this meg should be invoked.
priority - The priority of the meg incase of a condition tie.

setup

public void setup(java.lang.String name,
                  java.lang.String condition,
                  int priority,
                  boolean enabled)
Setup the Meg with the given attributes.
Parameters:
name - The name of the meg.
condition - The condition under which this meg should be invoked.
priority - The priority of the meg incase of a condition tie.
enabled - true if enabled.
See Also:
setCondition(java.lang.String)

initialize

public void initialize()
                throws MegException

Called when the Meg is initialized. Meg subclasses should override this method and do any Meg- specific initialization that needs to be done. The SystemContext variable is available through getSystemContext().

See Also:
getSystemContext()

initialize

public void initialize(SystemContext systemContext)
Deprecated. Override initialize() instead and use getSystemContext()

See Also:
initialize(), getSystemContext()

setSystemContext

public void setSystemContext(SystemContext systemContext)
Set the SystemContext object for this Meg. This method should only be called by the object administrating the plugins.
Parameters:
systemContext - Holds "static" information that pertains to the engine that the Meg is running under. Implementations are encouraged to not store this object put instead obtain it from the getSystemContext() method.

getSystemContext

public SystemContext getSystemContext()
Get the SystemContext object passed in with the initialize method.
Returns:
The system context.

handleRequest

public abstract void handleRequest(RequestEvent event)
                            throws RequestRejectedException,
                                   java.io.IOException
The method called to handle a request that satisfies the Meg's condition.
Parameters:
event - The request event used to modify the request/response.
Throws:
RequestRejectedException - Thrown if the request is rejected. This must be thrown before anything is written to the event's output stream otherwise the meg forfeits it's opportunity.
java.io.IOException - Can be thrown if an exception was generated by the meg while processing the MegInput/OutputStreams

forwardRequest

public void forwardRequest(Meg meg,
                           RequestEvent event)
                    throws RequestRejectedException,
                           java.io.IOException
Forward this request directly to another Meg for handling. The other Meg must be of the same type as the caller, otherwise the results are undefined (e.g., a RequestEditor can only forward a request to another RequestEditor).
Parameters:
meg - The Meg to handle the request.
event - The RequestEvent being forwarded.
Throws:
RequestRejectedException - Thrown if meg rejects the request.
java.io.IOException - Thrown if an exception was generated while meg was processing the MegInput/OutputStreams

setName

public void setName(java.lang.String name)
Set the name of the Meg used to provide a description.
Parameters:
name - The name of the Meg.

getName

public java.lang.String getName()
Get the name of the Meg.
Returns:
The name of the Meg.

setCondition

public void setCondition(java.lang.String condition)
Set the condition of the Meg. The condition property is used to determine whether the meg should be invoked for a transaction. The condition property is specified according to a grammar for Monitors, Editors, RequestEditors and Generators . The basic concept of the meg condition grammar is the use of one or more key-value pairs. A key-value pair consists of a keyword (predefined or application-specific) and an argument.

The basic expressions for evaluating an attribute-value pair are: AttributeName = Value and AttributeName ~ Value. The '~' operator is a case-insensitive comparison. The Value can be the special value '%null%' which means that the given AttributeName should not be defined.

The following rules apply for specifying conditions:

Example conditions are:

Note: The following condition information is specific to the HTTP/1.0 protocol

WBI offers two different kinds of keywords: predefined and application-specific.

Predefined Keywords

The following predefined keywords can be used:

For example, if you wanted to register a response editor that was triggered when a response was issued from hosts that ended with the letters 'ibm.com' and were of type HTML, the following syntax would be used:

     myMeg.setCondition("host~*ibm.com & content-type~*htm*");
   
If you wished to register a generator that fired when the following request was issued:
     http://_myPlugin/generator/One
   
You would use the following when registering your generator:
     myMeg.setCondition("protocol=http & host~_myPlugin & path=/generator/One");
   

Application-Specific Keywords

The second kind of keywords are application-specific. These keywords are very useful if the plugin itself wants to control whether a particular meg should be invoked during a transaction or not. An application-specific keyword can be any string that complies with the following syntax:
     AppKeyword := '$'( [a-zA-Z0-9] | '-' | '_' )*
   
The constraints on arguments to application-specific keywords are the same as for the predefined keywords.

Examples:
A simple application-specific keyword would be:

     myMeg.setCondition("$myApp=invokeMyMeg");
   
Application-specific keywords can be combined with any predefined keyword, such as:
     myMeg.setCondition("$myApp=invokeMyMeg & host~www.yahoo.com");
   
Note:The rules for combining application-specific keywords with any other keyword (application-specific or predefined) are the same as for combinations of predefined keywords only.

A meg that was setup with application-specific keyword(s) will only be invoked during a transaction if another meg sets these keywords correctly. Application-specific keywords are referred to as extra rule keys within WBI. These extra rule keys can be set during a transaction by any meg that is invoked during the transaction. Extra rule keys are set by calling the

       setExtraRuleKey( String key, String value )
     
method of class RequestInfo.
Parameters:
condition - A string holding the condition under which this meg gets invoked.
See Also:
RequestInfo, DocumentInfo


getCondition

public java.lang.String getCondition()
Get the condition of the Meg.
Returns:
The condition of the meg as a String containing rules which are used to determine when a meg gets invoked.
See Also:
Meg.setCondition(...)

setEnabled

public void setEnabled(boolean enabled)
Set the enabled state of the Meg.
Parameters:
enabled - true if enabled.

getEnabled

public boolean getEnabled()
Get the enabled state of the Meg.
Returns:
true if enabled.

isEnabled

public boolean isEnabled()
Determine if this Meg is enabled.
Returns:
true if enabled.

setPriority

public void setPriority(int priority)
Set the priority of the Meg. The allowable range for a Meg priority is between 100 and 1 with 100 being the highest priority and 1 being the lowest. The priority is only used in dispatching a Meg if multiple Megs have conditions that match the request. The conflict is resolved by which Meg has the highest priority.
Parameters:
priority - The priority of the Meg (100 to 1).

getPriority

public int getPriority()
Get the priority of the Meg in the range of 100 to 1.
Returns:
The priority of the Meg (100 to 1).

getPlugin

public final Plugin getPlugin()
Get the Plugin of the Meg.
Returns:
null if none; else the Plugin.

getMegPropertyKeys

public java.util.Enumeration getMegPropertyKeys()
Returns an enumeration of all the Meg property keys set by this Meg.
Returns:
An enumeration of key names.

setMegProperty

public void setMegProperty(java.lang.String key,
                           java.lang.String value)
Sets the property which is mapped to the given Meg property key name.
Parameters:
key - The key name used to reference the object.
value - The property.

getMegProperty

public java.lang.String getMegProperty(java.lang.String key)
Returns the property which is mapped to the given key name.
Parameters:
key - The key name used to reference the object.
Returns:
The property

getMegProperty

public java.lang.String getMegProperty(java.lang.String key,
                                       java.lang.String defaultValue)
Returns the property which is mapped to the given key name or a default value if no value was found in the database.
Parameters:
key - The key name used to reference the object.
defaultValue - The default value for the resource.
Returns:
The property

getType

public abstract int getType()
Get the Meg type. One of:
Returns:
Meg type.

isMegApplicable

public final boolean isMegApplicable(RequestInfo ri)
Determines if this meg satisfies a request by its RequestInfo object using the built condition tree (does not consider if it is enabled or not).
Parameters:
ri - The RequestInfo object.
Returns:
true if meg satisfies the condition; else false.

loadMegResources

protected void loadMegResources(Section section)
Retains a reference to the database section for this Meg's properties which is used for getMegResource and setMegResource methods.
Parameters:
section - The DatabaseSection representing the properties for the meg.

run

protected final void run(java.lang.Object argument)
                  throws java.lang.Exception