org.apache.commons.chain.generic
Class LookupCommand

java.lang.Object
  extended by org.apache.commons.chain.generic.LookupCommand
All Implemented Interfaces:
Command, Filter
Direct Known Subclasses:
DispatchLookupCommand, PathInfoMapper, RequestParameterMapper, ServletPathMapper

public class LookupCommand
extends Object
implements Filter

Look up a specified Command (which could also be a Chain) in a Catalog, and delegate execution to it. If the delegated-to Command is also a Filter, its postprocess() method will also be invoked at the appropriate time.

The name of the Command can be specified either directly (via the name property) or indirectly (via the nameKey property). Exactly one of these must be set.

If the optional property is set to true, failure to find the specified command in the specified catalog will be silently ignored. Otherwise, a lookup failure will trigger an IllegalArgumentException.

Version:
$Revision: 532951 $ $Date: 2007-04-27 04:59:00 +0100 (Fri, 27 Apr 2007) $
Author:
Craig R. McClanahan

Field Summary
 
Fields inherited from interface org.apache.commons.chain.Command
CONTINUE_PROCESSING, PROCESSING_COMPLETE
 
Constructor Summary
LookupCommand()
          Create an instance, setting its catalogFactory property to the value of CatalogFactory.getInstance().
LookupCommand(CatalogFactory factory)
          Create an instance and initialize the catalogFactory property to given factory/
 
Method Summary
 boolean execute(Context context)
          Look up the specified command, and (if found) execute it.
protected  Catalog getCatalog(Context context)
          Return the Catalog to look up the Command in.
 CatalogFactory getCatalogFactory()
          Return the CatalogFactory from which lookups will be performed.
 String getCatalogName()
          Return the name of the Catalog to be searched, or null to search the default Catalog.
protected  Command getCommand(Context context)
          Return the Command instance to be delegated to.
protected  String getCommandName(Context context)
          Return the name of the Command instance to be delegated to.
 String getName()
          Return the name of the Command that we will look up and delegate execution to.
 String getNameKey()
          Return the context attribute key under which the Command name is stored.
 boolean isIgnoreExecuteResult()
          Return true if this command should ignore the return value from executing the looked-up command.
 boolean isIgnorePostprocessResult()
          Return true if this command is a Filter and should ignore the return value from executing the looked-up Filter's postprocess() method.
 boolean isOptional()
          Return true if locating the specified command is optional.
 boolean postprocess(Context context, Exception exception)
          If the executed command was itself a Filter, call the postprocess() method of that Filter as well.
 void setCatalogFactory(CatalogFactory catalogFactory)
          Set the CatalogFactory from which lookups will be performed.
 void setCatalogName(String catalogName)
          Set the name of the Catalog to be searched, or null to search the default Catalog.
 void setIgnoreExecuteResult(boolean ignoreReturn)
          Set the rules for whether or not this class will ignore or pass through the value returned from executing the looked up command.
 void setIgnorePostprocessResult(boolean ignorePostprocessResult)
          Set the rules for whether or not this class will ignore or pass through the value returned from executing the looked up Filter's postprocess() method.
 void setName(String name)
          Set the name of the Command that we will look up and delegate execution to.
 void setNameKey(String nameKey)
          Set the context attribute key under which the Command name is stored.
 void setOptional(boolean optional)
          Set the optional flag for finding the specified command.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

LookupCommand

public LookupCommand()
Create an instance, setting its catalogFactory property to the value of CatalogFactory.getInstance().

Since:
Chain 1.1

LookupCommand

public LookupCommand(CatalogFactory factory)
Create an instance and initialize the catalogFactory property to given factory/

Parameters:
factory - The Catalog Factory.
Since:
Chain 1.1
Method Detail

setCatalogFactory

public void setCatalogFactory(CatalogFactory catalogFactory)

Set the CatalogFactory from which lookups will be performed.

Parameters:
catalogFactory - The Catalog Factory.
Since:
Chain 1.1

getCatalogFactory

public CatalogFactory getCatalogFactory()
Return the CatalogFactory from which lookups will be performed.

Returns:
The Catalog factory.
Since:
Chain 1.1

getCatalogName

public String getCatalogName()

Return the name of the Catalog to be searched, or null to search the default Catalog.

Returns:
The Catalog name.

setCatalogName

public void setCatalogName(String catalogName)

Set the name of the Catalog to be searched, or null to search the default Catalog.

Parameters:
catalogName - The new Catalog name or null

getName

public String getName()

Return the name of the Command that we will look up and delegate execution to.

Returns:
The name of the Command.

setName

public void setName(String name)

Set the name of the Command that we will look up and delegate execution to.

Parameters:
name - The new command name

getNameKey

public String getNameKey()

Return the context attribute key under which the Command name is stored.

Returns:
The context key of the Command.

setNameKey

public void setNameKey(String nameKey)

Set the context attribute key under which the Command name is stored.

Parameters:
nameKey - The new context attribute key

isOptional

public boolean isOptional()

Return true if locating the specified command is optional.

Returns:
true if the Command is optional.

setOptional

public void setOptional(boolean optional)

Set the optional flag for finding the specified command.

Parameters:
optional - The new optional flag

isIgnoreExecuteResult

public boolean isIgnoreExecuteResult()

Return true if this command should ignore the return value from executing the looked-up command. Defaults to false, which means that the return result of executing this lookup will be whatever is returned from that command.

Returns:
true if result of the looked up Command should be ignored.
Since:
Chain 1.1

setIgnoreExecuteResult

public void setIgnoreExecuteResult(boolean ignoreReturn)

Set the rules for whether or not this class will ignore or pass through the value returned from executing the looked up command.

If you are looking up a chain which may be "aborted" and you do not want this class to stop chain processing, then this value should be set to true

Parameters:
ignoreReturn - true if result of the looked up Command should be ignored.
Since:
Chain 1.1

isIgnorePostprocessResult

public boolean isIgnorePostprocessResult()

Return true if this command is a Filter and should ignore the return value from executing the looked-up Filter's postprocess() method. Defaults to false, which means that the return result of executing this lookup will be whatever is returned from that Filter.

Returns:
true if result of the looked up Filter's postprocess() method should be ignored.
Since:
Chain 1.1

setIgnorePostprocessResult

public void setIgnorePostprocessResult(boolean ignorePostprocessResult)

Set the rules for whether or not this class will ignore or pass through the value returned from executing the looked up Filter's postprocess() method.

If you are looking up a Filter which may be "aborted" and you do not want this class to stop chain processing, then this value should be set to true

Parameters:
ignorePostprocessResult - true if result of the looked up Filter's postprocess() method should be ignored.
Since:
Chain 1.1

execute

public boolean execute(Context context)
                throws Exception

Look up the specified command, and (if found) execute it. Unless ignoreExecuteResult is set to true, return the result of executing the found command. If no command is found, return false, unless the optional property is false, in which case an IllegalArgumentException will be thrown.

Specified by:
execute in interface Command
Parameters:
context - The context for this request
Returns:
the result of executing the looked-up command, or false if no command is found or if the command is found but the ignoreExecuteResult property of this instance is true
Throws:
IllegalArgumentException - if no such Command can be found and the optional property is set to false
Exception - if and error occurs in the looked-up Command.

postprocess

public boolean postprocess(Context context,
                           Exception exception)

If the executed command was itself a Filter, call the postprocess() method of that Filter as well.

Specified by:
postprocess in interface Filter
Parameters:
context - The context for this request
exception - Any Exception thrown by command execution
Returns:
the result of executing the postprocess method of the looked-up command, unless ignorePostprocessResult is true. If no command is found, return false, unless the optional property is false, in which case IllegalArgumentException will be thrown.

getCatalog

protected Catalog getCatalog(Context context)

Return the Catalog to look up the Command in.

Parameters:
context - Context for this request
Returns:
The catalog.
Throws:
IllegalArgumentException - if no Catalog can be found
Since:
Chain 1.2

getCommand

protected Command getCommand(Context context)

Return the Command instance to be delegated to.

Parameters:
context - Context for this request
Returns:
The looked-up Command.
Throws:
IllegalArgumentException - if no such Command can be found and the optional property is set to false

getCommandName

protected String getCommandName(Context context)

Return the name of the Command instance to be delegated to.

Parameters:
context - Context for this request
Returns:
The name of the Command instance
Since:
Chain 1.2


Copyright 2003-2008 The Apache Software Foundation. All Rights Reserved.