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:

• Name
• Condition
• Priority
• Enabled

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:

• The keywords are followed by an operator and a single argument. The basic expressions for evaluating a key-value pair are: Key = Value and Key ~ Value. The '~' operator is a case-insensitive comparison. The value can be the special value '%null%' which means that the given key should be ignored.
• The keywords can be arbitrarily grouped into clauses by using parenthesis, i.e. "(" and ")".
• Groups or clauses can be preceded by a "!" symbol to form a boolean negation.
• The boolean operators "&" and "|" operators can be used between clauses.
• Arguments to the keywords can contain preceding and/or trailing asterisks ("*"). The "*" acts as a wild card match. Note: A "*" may not be embedded within an argument.
• Two special boolean values, %true% and %false%, can also be used. For example, a condition that is always true is "%true%".

Example conditions are:

• host=www.ibm.com
• content-type = text/html & host=*.ibm.com
• %true%
• path~*cNn* | !(path~*EsPn*)
• (method~post & path=/) | (method~get & !path=/) | !(method~head)

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:

• content-type
• method
• protocol
• server
• host
• path
• url
• port
• query
• responseCode
• user-agent

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:

• Meg.UNDEFINED
• Meg.REQUEST_EDITOR
• Meg.GENERATOR
• Meg.MONITOR

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