## 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().