com.rbnb.plugins
Class PlugInTemplate

java.lang.Object
  com.rbnb.plugins.PlugInTemplate

public abstract class PlugInTemplate
extends Object

An abstract base class that simplifies PlugIn development.

Most plug-in implementations will only need to overload the processRequest(ChannelMap, PlugInChannelMap ) method in order to have a fully functional plug-in.

Other overloadable functions:

• createForwardMap(PlugInChannelMap) -- create the ChannelMap used to forward requests for data to process,
• getForwardData(Sink, ChannelMap, PlugInChannelMap) -- makes the forwarded request using the given sink and map.
• processRegistrationRequest(ChannelMap, PlugInChannelMap) -- handles registration requests in case channel names or mime types need to be changed, or server XML meta-data needs to be generated.

Constructor Summary

protected	PlugInTemplate() Create a FilterPlugIn with default parameters.
protected	PlugInTemplate(String host, String name) Create a FilterPlugIn specifying the RBNB host and the client name.

Method Summary

void	addChannelToRegister(String channel) Add a channel to be registered with the server for this PlugIn.
protected static String[]	argHelper(String[] args, PlugInTemplate pit) Helper function to parse PlugInTemplate specific command-line options.
protected ChannelMap	createForwardMap(PlugInChannelMap picm) Callback to create a ChannelMap to be used to request data from the server to match an incoming request.
protected ChannelMap	getForwardData(Sink sink, ChannelMap mappedChannels, PlugInChannelMap picm) Callback to make the request to the server for matching data.
boolean	getForwardRequestData() If true, the data from incoming requests is forwarded to the sink to get matching data for processing.
boolean	getForwardRequests() If true, incoming requests are automatically forwarded to the sink to get matching data for processing.
String	getHost() The RBNB hostname:port.
String	getName() The client name used for this PlugIn in the RBNB.
String	getPassword() Password used in connecting to the RBNB.
Properties	getRequestOptions() Gives a Properties object, which represents the options set by the Sink for this PlugIn when the request was made.
Sink	getRequestSink() For sinks where the default request forwarding approach is inappropriate, this method may be used to get a handle to a Sink to make requests.
long	getTimeout() Timeout (in ms) used in calls to Fetch().
boolean	getUseOneSink() If true, one sink is used to get all forwarding data.
String	getUser() Username used in connecting to the RBNB.
Class	getUserRequestClass() Returns the class whose instances are created to help answer requests.
Object	getUserRequestObject() If the user request class has been set, and we are inside a callback such as processRequest(ChannelMap, PlugInChannelMap), then this method returns an instance of the user request class.
boolean	isRunning() Returns true if this PlugIn is currently answering requests.
protected void	processRegistrationRequest(ChannelMap fwdReg, PlugInChannelMap out) Callback to handle requests for dynamic registration.
protected abstract void	processRequest(ChannelMap fwdData, PlugInChannelMap out) Override this callback to perform the plug-in processing.
void	setForwardRequestData(boolean forwardRequestData)
void	setForwardRequests(boolean forwardRequests)
void	setHost(String host)
void	setName(String name)
void	setPassword(String pass)
void	setTimeout(long timeout)
void	setUseOneSink(boolean oneSink)
void	setUser(String user)
void	setUserRequestClass(Class userClass) Set the class used to help answer requests.
protected static void	showHelper() A helper routine which displays the options supported by argHelper.
void	start() Starts the PlugIn in another thread, returning execution to the current thread.
void	stop() Stops the PlugIn thread.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

PlugInTemplate

protected PlugInTemplate()

Create a FilterPlugIn with default parameters.

PlugInTemplate

protected PlugInTemplate(String host,
                         String name)

Create a FilterPlugIn specifying the RBNB host and the client name.

Method Detail

start

public final void start()
                 throws SAPIException

Starts the PlugIn in another thread, returning execution to the current thread. Any threads waiting on this are notified.

Throws:

SAPIException - if a connection error occurs.

stop

public final void stop()

Stops the PlugIn thread.

Any threads waiting on this are notified.

isRunning

public final boolean isRunning()

Returns true if this PlugIn is currently answering requests.

getHost

public final String getHost()

The RBNB hostname:port. The default is "localhost:3333".

setHost

public final void setHost(String host)

getName

public final String getName()

The client name used for this PlugIn in the RBNB. The default is getClass().getName().

See Also:

Class.getName()

setName

public final void setName(String name)

getUser

public final String getUser()

Username used in connecting to the RBNB. Default is null.

setUser

public final void setUser(String user)

getPassword

public final String getPassword()

Password used in connecting to the RBNB. Default is null.

setPassword

public final void setPassword(String pass)

addChannelToRegister

public final void addChannelToRegister(String channel)

Add a channel to be registered with the server for this PlugIn. If never called, no channels are registered. This allows for dynamic registration.

Throws:

IllegalArgumentException - if the channel is invalid.

getTimeout

public final long getTimeout()

Timeout (in ms) used in calls to Fetch(). The default is -1 (forever).

See Also:

PlugIn.Fetch(long), Sink.Fetch(long)

setTimeout

public final void setTimeout(long timeout)

getUseOneSink

public final boolean getUseOneSink()

If true, one sink is used to get all forwarding data. Otherwise, one sink is used per thread created to handle an incoming request.

The default is false.

setUseOneSink

public final void setUseOneSink(boolean oneSink)

getForwardRequests

public final boolean getForwardRequests()

If true, incoming requests are automatically forwarded to the sink to get matching data for processing. This is the typical usage for filter plug-ins that process data already in the RBNB to produce new data.

Other plug-ins generate their own data internally, or want to handle forwarding themselves; they should set this field to false.

The default is true.

setForwardRequests

public final void setForwardRequests(boolean forwardRequests)

getForwardRequestData

public final boolean getForwardRequestData()

If true, the data from incoming requests is forwarded to the sink to get matching data for processing. Otherwise, the forwarded request contains only the channel names.

The default is true.

setForwardRequestData

public final void setForwardRequestData(boolean forwardRequestData)

getUserRequestClass

public final Class getUserRequestClass()

Returns the class whose instances are created to help answer requests. The default is null.

See Also:

setUserRequestClass(Class)

setUserRequestClass

public final void setUserRequestClass(Class userClass)

Set the class used to help answer requests. One instance of this class will be created each time a thread is created to handle an incoming PlugIn request. This instance can be recovered from inside these threads using getUserRequestObject().

The class should have either a single argument constructor which takes an instance of PlugInTemplate, or failing that a no-argument constructor.

This object is typically used to store references to objects which are expensive to create and non-reentrant, to give a performance improvement over creating them each time processRequest(ChannelMap, PlugInChannelMap) is called.

getUserRequestObject

public final Object getUserRequestObject()

If the user request class has been set, and we are inside a callback such as processRequest(ChannelMap, PlugInChannelMap), then this method returns an instance of the user request class.

Returns:

The user request object instance of the current thread, or null.

getRequestSink

public final Sink getRequestSink()
                          throws SAPIException

For sinks where the default request forwarding approach is inappropriate, this method may be used to get a handle to a Sink to make requests. These calls must be made inside one of the callback methods of this class.

NOTE: If the useOneSink property is true, you should synchronize on the Sink object returned by this method.

Returns:

The Sink instance for the current thread,

Throws:

SAPIException - if the sink is new and needs to be connected, but failed.

getRequestOptions

public final Properties getRequestOptions()

Gives a Properties object, which represents the options set by the Sink for this PlugIn when the request was made. Note that calls to this function must be made inside one of the callback methods of this class.

createForwardMap

protected ChannelMap createForwardMap(PlugInChannelMap picm)
                               throws SAPIException

Callback to create a ChannelMap to be used to request data from the server to match an incoming request.

Override this method to provide an alternative mapping between channel names. It must be reentrant. The default simply copies the names over, with some special processing for registration requests.

Developers overriding this method are encouraged to respect the value of the forwardRequestData field.

Note this method will never be called if getForwardRequests() is false.

Throws:

SAPIException

processRequest

protected abstract void processRequest(ChannelMap fwdData,
                                       PlugInChannelMap out)
                                throws SAPIException

Override this callback to perform the plug-in processing.

Parameters:

fwdData - Matching data from the server, if forwardRequests is true; otherwise an empty ChannelMap which may be used as desired.

out - PlugIn output.

Throws:

SAPIException

See Also:

setForwardRequests(boolean), getUserRequestClass(), getRequestSink()

processRegistrationRequest

protected void processRegistrationRequest(ChannelMap fwdReg,
                                          PlugInChannelMap out)
                                   throws SAPIException

Callback to handle requests for dynamic registration. The default simply forwards the request from the filtered channel; override to provide other functionality.

Throws:

SAPIException

getForwardData

protected ChannelMap getForwardData(Sink sink,
                                    ChannelMap mappedChannels,
                                    PlugInChannelMap picm)
                             throws SAPIException

Callback to make the request to the server for matching data. Override if you wish to alter the way the request is made.

Note that this method is not called if the getForwardRequests() property is false.

Returns:

either the mappedChannels map, or a new map; filled with data.

Throws:

SAPIException

showHelper

protected static void showHelper()

A helper routine which displays the options supported by argHelper. The format is a tab, followed by the option and its format, padded to 24 characters; followed by a description, then newline.

argHelper

protected static String[] argHelper(String[] args,
                                    PlugInTemplate pit)

Helper function to parse PlugInTemplate specific command-line options.

Returns:

the remaining arguments.

Throws:

IllegalArgumentException - if the arguments supported do not follow the conventions specified in showHelper().