Enhydra 5.1 API

org.enhydra.servlet.connectionMethods
Interface ConnectionMethod

All Superinterfaces:
java.io.Serializable
All Known Implementing Classes:
StandardConnectionMethod

public interface ConnectionMethod
extends java.io.Serializable

A ConnectionMethod is how requests get into the server from the outside world. This interface defines the API an object must implement in order to be administered by the server.

Each ConnectionMethod must maintain an ordered list of "channels". Each channel has an ID (a String), used to identify and refer to the channel. See addChannel(), below.

Each channel can be enabled or disabled. When disabled, connections must be refused, and not passed on to any servlets. When enabled, connections are allowed through to the destination servlet.

Each channel also contains an ordered list of TransactionFilters, which can be used for debugging and logging.

When a ConnectionMethod is being used as part of a server, the initialize() method will be called before any other methods. The servlet IDs in the channels are only valid in the ServletManager object provided to initialize(). Filter IDs are only valid in the FilterManager passed in to initialize().

The destroy() method will be called when the ConnectionMethod should shut down. Any external network exposure should be eliminated, for example any ServerSockets should be closed, or any WAI registrations should be unregistered. After destroy() is called, no further calls will be made to the object.

HTTP, WAI and RMI are implementations of this interface. See StandardConnectionMethod for a sample implementation which mananges the channels, but does not actually recieve or generate requests. If you are implementing a ConnectionMethod, it is recommended that you extend StandardConnectionMethod. Connection methods must contain a running non-daemon thread. The thread must be started either in the constructor or (perfered) the initialize() method, and stopped in the destroy() method.

Author:
Andy John
See Also:
ChannelStatus, ServletManager, org.enhydra.servlet.filter.TransactionFilter, StandardConnectionMethod

Field Summary
static java.lang.String disabledChannelHtml
          Return this HTML when an incomming request matches a channel, but that channel is disabled.
static java.lang.String errorHtml
          Return this HTML if an unexpected exception is thrown.
static java.lang.String noChannelHtml
          Return this HTML when an incomming request does not match any of the channels.
 
Method Summary
 void addChannel(java.lang.String channelID, java.lang.String URLPrefix, java.lang.String servletID)
          Add a new channel.
 void addTransactionFilter(java.lang.String channelID, java.lang.String filterID)
          Add a new TransactionFilter to the specified channel.
 boolean channelURLIsValid(java.lang.String channelID)
          Is the string returned from getChannelURL() a valid url?
 void deleteChannel(java.lang.String channelID)
          Delete a channel.
 void destroy()
          Shut down the connection method.
 void disableChannel(java.lang.String channelID)
          Turn off the channel.
 void enableChannel(java.lang.String channelID)
          Turn on the channel.
 boolean equivalent(ConnectionMethod compareObject)
          Compares the connection specific attributes for equivalency
 java.lang.String[] getChannelIDs()
          Returns the identifier names of all the channels currently in the ConnectionMethod.
 ChannelStatus getChannelStatus(java.lang.String channelID)
          Get the current status of a channel.
 java.lang.String getChannelURL(java.lang.String channelID)
          Returns the URL that a user would use to connect to this channel.
 int getPort()
           
 java.lang.String[] getTransactionFilterIDs(java.lang.String channelID)
          Get an array of all the current filter names for a given channel.
 java.lang.String getType()
           
 java.lang.String getUniqueChannelName()
          This returns a channel name that is not currently in use.
 void initialize(Config connectionConfig, java.lang.String id, ServletManager servletManager, FilterManager filterManager)
          Initialize the ConnectionMethod.
 void initialize(java.lang.String id, ServletManager servletManager, FilterManager filterManager)
          Initialize the ConnectionMethod.
 void removeTransactionFilter(java.lang.String channelID, java.lang.String filterID)
          Remove the given TransactionFilter from the specified channel.
 void resetRequestCount(java.lang.String channelID)
          Reset the specified channel's request count to zero.
 void writeToConfig(Config connectionConfig, java.lang.String base)
          Write out self into config fie
 

Field Detail

noChannelHtml

public static final java.lang.String noChannelHtml
Return this HTML when an incomming request does not match any of the channels. Suggested use: response.sendError(HttpServletResponse.SC_NOT_FOUND, ConnectionMethod.noChannelHtml);

See Also:
Constant Field Values

disabledChannelHtml

public static final java.lang.String disabledChannelHtml
Return this HTML when an incomming request matches a channel, but that channel is disabled. Suggested use: response.sendError(HttpServletResponse.SC_MOVED_TEMPORARILY, ConnectionMethod.disabledChannelHtml);

See Also:
Constant Field Values

errorHtml

public static final java.lang.String errorHtml
Return this HTML if an unexpected exception is thrown. Suggested use: response.sendError(HttpServletResponse.SC_SERVER_ERROR, ConnectionMethod.errorHtml);

See Also:
Constant Field Values
Method Detail

initialize

public void initialize(Config connectionConfig,
                       java.lang.String id,
                       ServletManager servletManager,
                       FilterManager filterManager)
                throws ConnectionMethodException
Initialize the ConnectionMethod. The ServletManager to use is passed in. This ServletManager is used to look up Servlets based on their String servlet IDs.

This will be called before any other method in this interface.

Parameters:
connectionConfig - The portion of the config file relevant to this connection method
id - The id associated with this connection method
servletManager - The ServletManager to use to obtain servlets. Servlet ID strings given in addChannel() are valid only in this ServletManager.
filterManager - The FilterManager to use to get filters. Filter ID strings given in addTransactionFilter() are valid only in this FilterManager.
Throws:
ConnectionMethodException - If an error occurs.

initialize

public void initialize(java.lang.String id,
                       ServletManager servletManager,
                       FilterManager filterManager)
                throws ConnectionMethodException
Initialize the ConnectionMethod. The ServletManager to use is passed in. This ServletManager is used to look up Servlets based on their String servlet IDs.

Parameters:
id - The id associated with this connection method
servletManager - The ServletManager to use to obtain servlets. Servlet ID strings given in addChannel() are valid only in this ServletManager.
filterManager - The FilterManager to use to get filters. Filter ID strings given in addTransactionFilter() are valid only in this FilterManager.
Throws:
ConnectionMethodException - If an error occurs.

writeToConfig

public void writeToConfig(Config connectionConfig,
                          java.lang.String base)
                   throws ConfigException,
                          KeywordValueException
Write out self into config fie

Parameters:
base - The base key string
ConfigException
KeywordValueException

addChannel

public void addChannel(java.lang.String channelID,
                       java.lang.String URLPrefix,
                       java.lang.String servletID)
                throws ConnectionMethodException
Add a new channel. The new channel is not enabled, and has no TransactionFilters. The Servlet ID is only valid in the ServletManager passed in to initialize(). When the Servlet ID is used to fetch the actual Servlet, the reference should only be kept in the ConnectionMethod for the duration of the request. After the request is finished, the ConnectionMehtod should eliminate all pointers to the Servlet. This will allow the ServletManager to destroy the Servlet and cause it to get garbage collected. The ServletManager's get() method should be called for every request.

Parameters:
channelID - The symbolic name to use for this channel.
URLPrefix - If a request's URL starts with this string, it should be sent to the servlet identified by servletID. To obtain the servlet, use the ServletManager's get() method.
servletID - The servlet to send requests to. Use the ServletManager's get() method to get the servlet. Call get() for each request, do not save a reference to the servlet.
Throws:
ConnectionMethodException - If an error occurs.

deleteChannel

public void deleteChannel(java.lang.String channelID)
                   throws ConnectionMethodException
Delete a channel.

Parameters:
channelID - Which channel to remove.
Throws:
ConnectionMethodException - If an error occurs.

getChannelStatus

public ChannelStatus getChannelStatus(java.lang.String channelID)
Get the current status of a channel.

Parameters:
channelID - Which channel.
Returns:
The status of the channel, stored in a ChannelStatus object. Null is returned if the given channelID cannot be found.
See Also:
ChannelStatus

getChannelIDs

public java.lang.String[] getChannelIDs()
Returns the identifier names of all the channels currently in the ConnectionMethod.

Returns:
An array of Strings, the names of all the channels in the ConnectionMethod.

enableChannel

public void enableChannel(java.lang.String channelID)
                   throws ConnectionMethodException
Turn on the channel. Allows requests to be sent to the servlet.

Parameters:
channelID - Which channel to enable.
Throws:
ConnectionMethodException - If an error occurs.

disableChannel

public void disableChannel(java.lang.String channelID)
                    throws ConnectionMethodException
Turn off the channel. Incomming requests should be refused. No requests should be allowd through to the servlet.

Parameters:
channelID - Which channel to disable.
Throws:
ConnectionMethodException - If an error occurs.

resetRequestCount

public void resetRequestCount(java.lang.String channelID)
                       throws ConnectionMethodException
Reset the specified channel's request count to zero. The counter measures the number of requests processed by this channel.

Parameters:
channelID - Which channel.
Throws:
ConnectionMethodException - If an error occurs.

addTransactionFilter

public void addTransactionFilter(java.lang.String channelID,
                                 java.lang.String filterID)
                          throws ConnectionMethodException
Add a new TransactionFilter to the specified channel. Use this ID to refer to the filter in removeTransactionFilter(). The filter will be fetched from the filter manager when a request comes in.

Parameters:
channelID - Which channel to add a TransactionFilter to.
filterID - The TransactionFilter to add. The filter is fetched from the FilterManager passed in to initialize() each time a request comes in.
Throws:
ConnectionMethodException - If an error occurs.
See Also:
org.enhydra.servlet.filter.TransactionFilter

removeTransactionFilter

public void removeTransactionFilter(java.lang.String channelID,
                                    java.lang.String filterID)
                             throws ConnectionMethodException
Remove the given TransactionFilter from the specified channel.

Parameters:
channelID - Which channel to remove a TransactionFilter from.
Throws:
ConnectionMethodException - If an error occurs.
See Also:
org.enhydra.servlet.filter.TransactionFilter

getTransactionFilterIDs

public java.lang.String[] getTransactionFilterIDs(java.lang.String channelID)
                                           throws ConnectionMethodException
Get an array of all the current filter names for a given channel. If there are no filters, this will return a zero-length array.

Returns:
An array of filter names. You can pass these to removeTransactionFilter().
Throws:
ConnectionMethodException - If an error occurs, for example if the channel does not exist.

getUniqueChannelName

public java.lang.String getUniqueChannelName()
This returns a channel name that is not currently in use. Use this when you want to programatically create a channel, and you don't care what it's name is. The name returned will not be in the list of current channels, and will not be returned on any other calls to this function.

Returns:
A name that can be used with addChannel().

getChannelURL

public java.lang.String getChannelURL(java.lang.String channelID)
                               throws ConnectionMethodException
Returns the URL that a user would use to connect to this channel. For example, with an HTTP method on port 2000 on a machine called enhydra.lutris.com, and a url prefix of /abalone/, the returned string would be "http://enhydra.lutris.com:2000/abalone/".

Note: it is not always possible for a connection method to know the exact URL a user should use, so the returned string may be an approximation. For example, the RMI connection method may be accessed from any host that has access to it.

Returns:
A URL string.
Throws:
ConnectionMethodException - If an error occurs, for example if the channel does not exist.

channelURLIsValid

public boolean channelURLIsValid(java.lang.String channelID)
                          throws ConnectionMethodException
Is the string returned from getChannelURL() a valid url?

Returns:
True if the url returned from getChannelURL() is a valid url that users could sucessfully enter into their browsers.
Throws:
ConnectionMethodException - If an error occurs, for example if the channel does not exist.

destroy

public void destroy()
             throws ConnectionMethodException
Shut down the connection method. Any threads created in initialize() or any other mehtod must be terminated.

After this call, none of these methods will be called again.

Throws:
ConnectionMethodException - If an error occurs.

equivalent

public boolean equivalent(ConnectionMethod compareObject)
Compares the connection specific attributes for equivalency

Parameters:
compareObject - The object to compare this to
Throws:
ConnectionMethodException - If an error occurs.

getType

public java.lang.String getType()

getPort

public int getPort()

Enhydra 5.1 API