com.ibm.wbi
Class Proxy

com.ibm.wbi.Proxy

All Implemented Interfaces:

java.util.EventListener, java.beans.PropertyChangeListener

public class Proxy

implements java.beans.PropertyChangeListener

The main component of the pluggable transforming proxy framework. This component connects and manages all components and Sublayers.

Field Summary

static java.lang.String	COPYRIGHT The IBM copyright information.
static int	ERROR Indicates an error return code.
static java.lang.String	HOME_PROPERTY
static int	NOERROR Indicates a no error return code.
static java.lang.String	PRODUCT
static java.lang.String	RELEASE
protected static com.ibm.wbi.TransactionTracingHandler	tracingHandler Reference to the transaction tracing handler.
static java.lang.String	VERSION

Constructor Summary

Proxy()
Construct a new pluggable transforming proxy.

Method Summary

void	abort() Abort abruptly shuts down the proxy without gracefully cleaning up.
void	addPlugin(Plugin plugin, java.util.Properties attributes, boolean enabled) Transiently adds a Plugin to this instance of the Proxy (this does not install the Plugin into the configuration store).
void	deregisterAllSublayers() Deregister all registered sublayers (and all their associated components).
void	deregisterSublayer(com.ibm.wbi.Sublayer sublayer) Deregister a Sublayer (and all it's associated components).
static java.lang.String	getInstallPath() Get the system install path.
static java.util.Enumeration	getInstances() Determine the list of running Proxies in the current virtual machine.
static java.lang.String	getNativePath() Get the path for the native code.
static Proxy	getNewestInstance() Determine the newest instance of Proxy that has been created.
Plugin	getPlugin(java.lang.String installname) Get the plugin by its install name
Plugin[]	getPlugins() Get an array of Plugins currently registered in the Proxy.
com.ibm.wbi.RequestDescriptor[]	getRequests() Get an array of descriptors that can be used to inquire about the requests currently being serviced by the Proxy.
com.ibm.wbi.Sublayer	getSublayer(java.lang.Integer identity) Get the Sublayer that produces the the specified identity.
java.lang.Integer[]	getSublayerIdentities() Get an array of all registered Sublayer identities.
com.ibm.wbi.Sublayer[]	getSublayers() Get an array of registered Sublayers.
static SystemContext	getSystemContext() Get the SystemContext.
static com.ibm.wbi.TransactionTracingHandler	getTransactionTracingHandler() Get a reference to the tracing handler.
boolean	initialize(SystemContext context) Initialize the proxy loading the Sublayers and registered Plugins.
boolean	initialize(SystemContext context, boolean loadSublayers, boolean loadPlugins) Initialize the proxy for receiving requests.
void	installPlugin(com.ibm.wbi.PluginDescriptor pd) Install a Plugin as specified by the descriptor
void	installPluginFromRegistryFile(java.lang.String registryFile) Install a Plugin as specified in the Registry File.
protected void	loadSublayersFromConfigurationStore() Loads the sublayers that are specified in the configuration store.
void	propertyChange(java.beans.PropertyChangeEvent e)
void	registerSublayer(com.ibm.wbi.Sublayer sublayer) Register the specified Sublayer (and all it's associate components).
void	reloadPlugins() Reload the plugins, this re-builds the condition trees on the MEGs.
void	removePlugin(Plugin plugin) Transiently removes a Plugin from this instance of the Proxy (this does not uninstall the Plugin from the configuration store).
boolean	restart() Restart the transproxy without waiting for pending requests.
boolean	restart(int timeout) Restart the transproxy waiting for pending requests for the specified time.
boolean	restart(int timeout, boolean loadSublayers, boolean loadPlugins) Restart the transproxy waiting for pending requests for the specified time.
void	resume() Resume the registered Sublayers to accepting requests.
protected void	startSublayers()
void	suspend() Suspend the registered Sublayers from accepting any more requests after this call.
boolean	terminate() Terminate attempts to gracefully take each component of the proxy down and remove all reference links without waiting for pending requests.
boolean	terminate(int wait) Terminate attempts to gracefully take each component of the proxy down and remove all reference links.
static void	throttle() This method blocks until the Proxy is "unthrottled".
void	uninstallAllPlugins() Uninstall all the Plugins.
void	uninstallPlugin(java.lang.String fullyQualifiedClassName) Uninstall the Plugin with the specified class name.

Field Detail

PRODUCT

public static java.lang.String PRODUCT

RELEASE

public static java.lang.String RELEASE

VERSION

public static java.lang.String VERSION

HOME_PROPERTY

public static final java.lang.String HOME_PROPERTY

COPYRIGHT

public static final java.lang.String COPYRIGHT

The IBM copyright information.

NOERROR

public static final int NOERROR

Indicates a no error return code.

ERROR

public static final int ERROR

Indicates an error return code.

tracingHandler

protected static com.ibm.wbi.TransactionTracingHandler tracingHandler

Reference to the transaction tracing handler.

Constructor Detail

Proxy

public Proxy()

Construct a new pluggable transforming proxy.

Method Detail

getNewestInstance

public static Proxy getNewestInstance()

Determine the newest instance of Proxy that has been created.

Returns:

the newest instance of Proxy that has been created. Beware of global variables like this one! Returns null if no instances have been created in the current virtual machine.

getInstances

public static java.util.Enumeration getInstances()

Determine the list of running Proxies in the current virtual machine.

Returns:

An Enumeration of all Proxy instances that are currently initialized.

getInstallPath

public static java.lang.String getInstallPath()

Get the system install path.

Returns:

The system install path.

getNativePath

public static java.lang.String getNativePath()

Get the path for the native code. WBI can be combined with native code. This method determines the path of the directory that contains the native code. The result of this method depends on the operating system and architecture the current Java process is running on.

In general the directories for native code are located in the bin directory under the WBI root (install) directory. The name of such a directory is based on the name of the operating system and its underlying architecture.

Examples:

• Assume you are running the operating system Linux on a standard PC. The name of the directory will then be

  x86_Linux

  and is located in <WBI_rootdirectory>/bin. White spaces in the operating system name are replaced with underscores "_".

• Note: If the operating system is Windows 95/98/NT/2000 and the underlying architecture is a standard PC, the native directory is

  x86_win32

  instead of x86_Windows* due to the fact that these operating systems share the same architecture.

This method should be called by each plugin that uses native code in order to determine the right native directory. Using this method maintains platform independency.
You simply load a native library by using the following statements:

       String dllName = ...
       File dllFile = new File( Proxy.getNativePath(), dllName );
       System.load( dllFile.getAbsolutePath() );
 

This allows you Java code for a WBI plugin to be platform independent. Make sure that your plugin handles the situation if there is not native library for a particular platform, e.g. do not use the functionality of the native library or disable the respective plugin.

Returns:

The path that contains native code or null if an error occurred.

getSystemContext

public static SystemContext getSystemContext()

Get the SystemContext.

Returns:

The system context.

reloadPlugins

public void reloadPlugins()

Reload the plugins, this re-builds the condition trees on the MEGs. This may be necessary if new sublayers are introduced.

initialize

public boolean initialize(SystemContext context)

Initialize the proxy loading the Sublayers and registered Plugins.

Parameters:

context - The SystemContext that contains all the initialized resources for the transproxy.

Returns:

true if successfully initialized; else false.

initialize

public boolean initialize(SystemContext context,
                          boolean loadSublayers,
                          boolean loadPlugins)

Initialize the proxy for receiving requests.

Parameters:

context - The SystemContext that contains all the initialized resources for the transproxy.

loadSublayers - true if Sublayers should be loaded from configuration store; else false.

loadPlugins - true if Plugins should be loaded from configuration store; else false.

Returns:

true if proxy loaded without any errors.

abort

public void abort()

Abort abruptly shuts down the proxy without gracefully cleaning up.

terminate

public boolean terminate()

Terminate attempts to gracefully take each component of the proxy down and remove all reference links without waiting for pending requests.

Returns:

true if terminated with all requests serviced; false if pending requests left when terminated.

terminate

public boolean terminate(int wait)

Terminate attempts to gracefully take each component of the proxy down and remove all reference links.

Parameters:

wait - The amount of time to wait for pending requests.

Returns:

true if terminated with all requests serviced; false if pending requests left when terminated.

restart

public boolean restart()

Restart the transproxy without waiting for pending requests.

Returns:

true if terminated with all requests serviced; false if pending requests left when terminated.

restart

public boolean restart(int timeout)

Restart the transproxy waiting for pending requests for the specified time.

Parameters:

wait - The amount of time to wait for pending requests.

Returns:

true if terminated with all requests serviced; false if pending requests left when terminated.

restart

public boolean restart(int timeout,
                       boolean loadSublayers,
                       boolean loadPlugins)

Restart the transproxy waiting for pending requests for the specified time.

Parameters:

wait - The amount of time to wait for pending requests.

loadSublayers - true if Sublayers should be loaded from configuration store; else false.

loadPlugins - true if Plugins should be loaded from configuration store; else false.

Returns:

true if terminated with all requests serviced; false if pending requests left when terminated.

suspend

public void suspend()

Suspend the registered Sublayers from accepting any more requests after this call. All pending request from Sublayer will still be processed.

resume

public void resume()

Resume the registered Sublayers to accepting requests.

throttle

public static void throttle()

This method blocks until the Proxy is "unthrottled".

getRequests

public com.ibm.wbi.RequestDescriptor[] getRequests()

Get an array of descriptors that can be used to inquire about the requests currently being serviced by the Proxy.

Returns:

An array of RequestDescriptors.

getPlugins

public Plugin[] getPlugins()

Get an array of Plugins currently registered in the Proxy.

Returns:

An array of Plugins.

getPlugin

public Plugin getPlugin(java.lang.String installname)

Get the plugin by its install name

Parameters:

installname - Full name of plugin (e.g., "ibm/test")

Returns:

The named Plugin

addPlugin

public void addPlugin(Plugin plugin,
                      java.util.Properties attributes,
                      boolean enabled)
               throws com.ibm.wbi.PluginException

Transiently adds a Plugin to this instance of the Proxy (this does not install the Plugin into the configuration store). These attributes must be specified.

• DescriptiveName
• Description
• MajorVersion
• MinorVersion

Parameters:

plugin - The Plugin to register.

attributes - The Plugin attributes.

enabled - true if enabled, else false.

Throws:

com.ibm.wbi.PluginException - If an error occurs.

removePlugin

public void removePlugin(Plugin plugin)
                  throws com.ibm.wbi.PluginException

Transiently removes a Plugin from this instance of the Proxy (this does not uninstall the Plugin from the configuration store).

Parameters:

plugin - The Plugin to remove.

Throws:

com.ibm.wbi.PluginException - If an error occurs.

installPluginFromRegistryFile

public void installPluginFromRegistryFile(java.lang.String registryFile)
                                   throws com.ibm.wbi.PluginInstallException,
                                          java.io.IOException

Install a Plugin as specified in the Registry File.

Parameters:

registryFile - The Plugin Registry File.

Throws:

com.ibm.wbi.PluginInstallException - If an error occurs.

java.io.IOException - If problems while reading registry file (e.g. FileNotFoundException)

installPlugin

public void installPlugin(com.ibm.wbi.PluginDescriptor pd)
                   throws com.ibm.wbi.PluginInstallException

Install a Plugin as specified by the descriptor

Parameters:

pd - The Plugin Descriptor

Throws:

com.ibm.wbi.PluginInstallException - If an error occurs.

uninstallPlugin

public void uninstallPlugin(java.lang.String fullyQualifiedClassName)
                     throws com.ibm.wbi.PluginInstallException

Uninstall the Plugin with the specified class name.

Parameters:

fullyQualifiedClassName - The class name.

Throws:

com.ibm.wbi.PluginInstallException - If an error occurs.

uninstallAllPlugins

public void uninstallAllPlugins()
                         throws com.ibm.wbi.PluginInstallException

Uninstall all the Plugins.

Throws:

com.ibm.wbi.PluginInstallException - If an error occurs.

registerSublayer

public void registerSublayer(com.ibm.wbi.Sublayer sublayer)
                      throws com.ibm.wbi.SublayerException,
                             java.lang.Exception

Register the specified Sublayer (and all it's associate components). This will call the start() method on the Sublayer to begin processing requests.

Parameters:

sublayer - The Sublayer to register.

Throws:

com.ibm.wbi.SublayerException - If an error occurs registering the Sublayer.

java.lang.Exception - If problems while starting the sublayer

deregisterSublayer

public void deregisterSublayer(com.ibm.wbi.Sublayer sublayer)
                        throws com.ibm.wbi.SublayerException,
                               java.lang.Exception

Deregister a Sublayer (and all it's associated components). This will call the stop() method on the Sublayer to stop processing requests. The method will block for maximum of 30 seconds to service all requests associated with the Sublayer.

Parameters:

sublayer - The Sublayer to deregister.

Throws:

com.ibm.wbi.SublayerException - If an error occurs deregistering the Sublayer.

java.lang.Exception - If problems while stopping the sublayer. Note that it is removed from the registry regardless.

deregisterAllSublayers

public void deregisterAllSublayers()
                            throws java.lang.Exception

Deregister all registered sublayers (and all their associated components). This will call the stop() method on the Sublayer to stop processing requests.

Throws:

java.lang.Exception - If problems while stopping any sublayer. Note that they are removed from the registry regardless.

getSublayerIdentities

public java.lang.Integer[] getSublayerIdentities()

Get an array of all registered Sublayer identities.

Returns:

An array of Sublayer identities.

getSublayers

public com.ibm.wbi.Sublayer[] getSublayers()

Get an array of registered Sublayers.

Returns:

Sublayer array.

getSublayer

public com.ibm.wbi.Sublayer getSublayer(java.lang.Integer identity)
                                 throws com.ibm.wbi.SublayerException

Get the Sublayer that produces the the specified identity.

Parameters:

identity - The Sublayer identity.

Returns:

The Sublayer associated with the identity.

Throws:

com.ibm.wbi.SublayerException - If the Sublayer does not exist.

propertyChange

public void propertyChange(java.beans.PropertyChangeEvent e)

Specified by:

propertyChange in interface java.beans.PropertyChangeListener

loadSublayersFromConfigurationStore

protected void loadSublayersFromConfigurationStore()

Loads the sublayers that are specified in the configuration store.

startSublayers

protected void startSublayers()
                       throws java.lang.Exception

getTransactionTracingHandler

public static com.ibm.wbi.TransactionTracingHandler getTransactionTracingHandler()

Get a reference to the tracing handler.

Returns:

The reference to the tracing handler or null if not set.