Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## com.novell.nds.dirxml.shimhost
Class ShimHost

    java.lang.Object
      com.novell.nds.dirxml.shimhost.ShimHost

    public class ShimHost

extends Object

`ShimHost` is a class that will load and communicate with a DirXML application shim. It is designed to be a building block for applications that use DirXML application shims outside of the DirXML Engine.

`ShimHost` supplies some default behavior that can be used to simplify what needs to be done to run an application shim:

- Handling for events submitted by the publisher shim: The default behavior is to simply return a "success" status to the publisher shim for each event found in the event document.
- Handling for queries submitted by the subscriber shim during the processing of commands. The default behavior is to return a "success" status as the result of the query.

The default behaviors can be overridden by supplying handlers for the cases listed. See `setPublisherEventHandler()` and `execute()`.

There are a number of classes in the `com.novell.nds.dirxml.shimhost` package designed to help with assembling and formatting the data necessary to run a shim. However, the most important is the `ShimConfig` class which is used to load and save the configuration information for a shim to and from an XML document. The ShimConfig class also provides methods for constructing the initialization documents needed by the shim `init()` methods from the shim configuration data.

The minimum steps required to load and run a shim are:

1. Construct a `ShimHost` instance, supplying a class name.
2. Construct initialization documents for the shim's `init()` methods.
3. Call `start()` to construct the shim object and cause the shim's initialization methods to be called
4. Call `shutdown()` to cause the shim's `DriverShim.shutdown()` method to be called and the shim object to be made available for garbage collection.

A more realistic scenario is:

1. Load shim configuration information from an XML document using an instance of the `ShimConfig` class.
2. Call `ShimConfig.createInitDocs()` to get the initialization documents needed for the call to `ShimHost.start()`.
3. Register an implementation of `com.novell.nds.dirxml.driver.TraceInterface` (e.g., `ConsoleTraceImpl` or `FileTraceImpl`).
4. Construct an instance of the `com.novell.nds.dirxml.driver.Trace` class.
5. Construct a `ShimHost` instance, supplying the shim's class name from the `ShimConfig` instance, and supplying the constructed `Trace` instance.
6. Call `setPublisherEventHandler()` to register a handler for published documents from the shim.
7. Call `start()` to construct and initialize the application shim.
8. Call `execute()` to submit commands to the Subscriber shim.
9. Call `shutdown()` to shut down the shim and clean up resources.

Remote Loader Support

`ShimHost` has two Publisher-channel behaviors to facilitate using the Remote Loader:

1. If the only element under <input> in the Publisher-submitted document is a <query> command that reads the driver object's Public Key attribute then the `ShimHost` instance will return a fabricated <instance> element containing a Public Key value.
2. If the only element under <input> in the Publisher-submitted document is a &check-password> command then the `ShimHost` instance will call any `DriverPasswordCheck` implementation that has been set via `setDriverPasswordCheck()` and return the result in a <status> element.

Note that the above behaviors preclude sending the two commands to any `XmlCommandProcessor` implementation that has been set via `setPublisherEventHandler()`.

See Also:
  `ShimConfig`, `ConsoleTraceImpl`, `FileTraceImpl`

Nested Class Summary
`static interface` | `ShimHost.DriverPasswordCheck` Interface to handle <check-password> commands received on the Publisher channel.
`class` | `ShimHost.MethodException` Extension of `ShimException`, used to encapsulate a `Throwable` that is thrown by a shim method.
`static interface` | `ShimHost.PublisherFatalErrorListener`
`static interface` | `ShimHost.RunningStateChangeListener` Interface through which notification of changes to the shim's running state are made.
`static interface` | `ShimHost.StateListener` Interface to receive notification of shim state elements when state elements appear in documents from the shim.

Field Summary
`static int` | `DRIVER_INIT_DOC` Array index of initialization document for `DriverShim.init()` in `start()` method's `initDocs` parameter.
`static int` | `DRIVER_INIT_RETURN` Array index of return document from `DriverShim.init()` in return from `start()` method.
`static int` | `DRIVER_SHUTDOWN_RETURN` Array index of return document from `DriverShim.shutdown()` in return from `shutdown()` method.
`static int` | `DRIVER_STATE` Array index of <driver-state> element in `stateElements` array passed to `StateListener.notifyShimState()` method.
`static int` | `PUBLISHER_INIT_DOC` Array index of initialization document for `PublicationShim.init()` in `start()` method's `initDocs` parameter.
`static int` | `PUBLISHER_INIT_RETURN` Array index of return document from `PublicationShim.init()` in return from `start()` method.
`static int` | `PUBLISHER_START_RETURN` Array index of return document from `PublicationShim.start()` in return from `shutdown()` method.
`static int` | `PUBLISHER_STATE` Array index of <publisher-state> element in `stateElements` array passed to `StateListener.notifyShimState()` method.
`static String` | `REMOTE_SHIM_CLASS_NAME` Name of the Remote Interface Shim class.
`static int` | `STATE_FLAG_DRIVER_INITIALIZED` Bit flag for `getRunningState()` value indicating that `DriverShim.init()` has been called and returned from.
`static int` | `STATE_FLAG_IN_PUBLISHER_START` Bit flag for `getRunningState()` value indicating that `PublicationShim.start()` has been called.
`static int` | `STATE_FLAG_PUBLISHER_INITIALIZED` Bit flag for `getRunningState()` value indicating that `PublicationShim.init()` has been called and returned from.
`static int` | `STATE_FLAG_SUBSCRIBER_INITIALIZED` Bit flag for `getRunningState()` value indicating that `SubscriptionShim.init()` has been called and returned from.
`static int` | `STATE_RUNNING` Value returned by `getRunningState()` indicating that the shim is fully initialized and running.
`static int` | `STATE_STOPPED` Value returned by `getRunningState()` indicating that the shim is not running.
`static int` | `SUBSCRIBER_INIT_DOC` Array index of initialization document for `SubscriptionShim.init()` in `start()` method's `initDocs` parameter.
`static int` | `SUBSCRIBER_INIT_RETURN` Array index of return document from `SubscriptionShim.init()` in return from `start()` method.
`static int` | `SUBSCRIBER_STATE` Array index of <subscriber-state> element in `stateElements` array passed to `StateListener.notifyShimState()` method.

Constructor Summary
`ShimHost(String className)` Construct a `ShimHost` instance for the passed class name.
`ShimHost(String className, Trace tracer)` Construct a `ShimHost` instance for the passed class name using the passed `Trace` facility.

Method Summary
`static void` | `checkForFatalError(Document returnDoc)` Examine a shim document for any <status> element with level="fatal".
`static void` | `checkForFatalError(XmlDocument doc)` Examine a shim document for any <status> element with level="fatal".
`static void` | `cleanup()` Perform static class cleanup().
`Document` | `execute(Document commandDocument, XmlQueryProcessor queryProcessor)` Cause the Subscriber thread to submit the passed command document to the shim's `SubscriptionShim.execute()` method.
`String` | `getClassName()` Return the class name associationed with this instance.
`int` | `getRunningState()` Return the current state of this instance
`Document` | `getSchema(Document initDoc)` Call the shim's `DriverShim.getSchema()` method.
`Trace` | `getTracer()` Get the `Trace` object that is used by this instance for outputting trace messages.
`static void` | `initialize()` Perform static class initialization.
`static void` | `initialize(ClassLoader cl)` Perform static class initialization.
`void` | `load()` Construct the instance of the `DriverShim` implementation class to be used.
`void` | `setDriverPasswordCheck(ShimHost.DriverPasswordCheck checker)` Method to set a `DriverPasswordCheck` implementation to check a string against the driver object password.
`void` | `setPublisherEventHandler(XmlCommandProcessor cmdProcessor)` Set an `XmlCommandProcessor` instance to receive event documents from the shim's Publisher.
`void` | `setRunningStateChangeListener(ShimHost.RunningStateChangeListener listener)` Method to set a RunningStateChangeListener implementation to be notified when the shim starts or stops.
`void` | `setStateListener(ShimHost.StateListener listener)` Method to set a `StateListener` implementation to be notified of shim state changes when reported by the shim in a shim document.
`Document[]` | `shutdown(Document reasonDoc)` Cause the Subscriber thread to call the shim's `DriverShim.shutdown()` method.
`Document[]` | `start(Document[] initDocs)` Cause the Subscriber thread to initialize the shim and start the publisher.
`void` | `validateClass()` Validate that the class name with which this instance was created can be found.

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Field Detail

### DRIVER_INIT_DOC

    public static final int DRIVER_INIT_DOC

  Array index of initialization document for `DriverShim.init()` in `start()` method's `initDocs` parameter.

  See Also:
    `start(org.w3c.dom.Document[])`, Constant Field Values

### SUBSCRIBER_INIT_DOC

    public static final int SUBSCRIBER_INIT_DOC

  Array index of initialization document for `SubscriptionShim.init()` in `start()` method's `initDocs` parameter.

  See Also:
    `start(org.w3c.dom.Document[])`, Constant Field Values

### PUBLISHER_INIT_DOC

    public static final int PUBLISHER_INIT_DOC

  Array index of initialization document for `PublicationShim.init()` in `start()` method's `initDocs` parameter.

  See Also:
    `start(org.w3c.dom.Document[])`, Constant Field Values

### DRIVER_INIT_RETURN

    public static final int DRIVER_INIT_RETURN

  Array index of return document from `DriverShim.init()` in return from `start()` method.

  See Also:
    `start(org.w3c.dom.Document[])`, Constant Field Values

### SUBSCRIBER_INIT_RETURN

    public static final int SUBSCRIBER_INIT_RETURN

  Array index of return document from `SubscriptionShim.init()` in return from `start()` method.

  See Also:
    `start(org.w3c.dom.Document[])`, Constant Field Values

### PUBLISHER_INIT_RETURN

    public static final int PUBLISHER_INIT_RETURN

  Array index of return document from `PublicationShim.init()` in return from `start()` method.

  See Also:
    `start(org.w3c.dom.Document[])`, Constant Field Values

### DRIVER_SHUTDOWN_RETURN

    public static final int DRIVER_SHUTDOWN_RETURN

  Array index of return document from `DriverShim.shutdown()` in return from `shutdown()` method.

  See Also:
    `shutdown(org.w3c.dom.Document)`, Constant Field Values

### PUBLISHER_START_RETURN

    public static final int PUBLISHER_START_RETURN

  Array index of return document from `PublicationShim.start()` in return from `shutdown()` method.

  See Also:
    `shutdown(org.w3c.dom.Document)`, Constant Field Values

### DRIVER_STATE

    public static final int DRIVER_STATE

  Array index of <driver-state> element in `stateElements` array passed to `StateListener.notifyShimState()` method.

  See Also:
    `ShimHost.StateListener`, Constant Field Values

### SUBSCRIBER_STATE

    public static final int SUBSCRIBER_STATE

  Array index of <subscriber-state> element in `stateElements` array passed to `StateListener.notifyShimState()` method.

  See Also:
    `ShimHost.StateListener`, Constant Field Values

### PUBLISHER_STATE

    public static final int PUBLISHER_STATE

  Array index of <publisher-state> element in `stateElements` array passed to `StateListener.notifyShimState()` method.

  See Also:
    `ShimHost.StateListener`, Constant Field Values

### STATE_FLAG_DRIVER_INITIALIZED

    public static final int STATE_FLAG_DRIVER_INITIALIZED

  Bit flag for `getRunningState()` value indicating that `DriverShim.init()` has been called and returned from.

  See Also:
    `getRunningState()`, Constant Field Values

### STATE_FLAG_SUBSCRIBER_INITIALIZED

    public static final int STATE_FLAG_SUBSCRIBER_INITIALIZED

  Bit flag for `getRunningState()` value indicating that `SubscriptionShim.init()` has been called and returned from.

  See Also:
    `getRunningState()`, Constant Field Values

### STATE_FLAG_PUBLISHER_INITIALIZED

    public static final int STATE_FLAG_PUBLISHER_INITIALIZED

  Bit flag for `getRunningState()` value indicating that `PublicationShim.init()` has been called and returned from.

  See Also:
    `getRunningState()`, Constant Field Values

### STATE_FLAG_IN_PUBLISHER_START

    public static final int STATE_FLAG_IN_PUBLISHER_START

  Bit flag for `getRunningState()` value indicating that `PublicationShim.start()` has been called.

  See Also:
    `getRunningState()`, Constant Field Values

### STATE_STOPPED

    public static final int STATE_STOPPED

  Value returned by `getRunningState()` indicating that the shim is not running.

  See Also:
    `getRunningState()`, Constant Field Values

### STATE_RUNNING

    public static final int STATE_RUNNING

  Value returned by `getRunningState()` indicating that the shim is fully initialized and running.

  See Also:
    `getRunningState()`, Constant Field Values

### REMOTE_SHIM_CLASS_NAME

    public static final String REMOTE_SHIM_CLASS_NAME

  Name of the Remote Interface Shim class.

  See Also:
    Constant Field Values

Constructor Detail

### ShimHost

    public ShimHost(String className)
             throws IllegalArgumentException,
                    ClassNotFoundException,
                    ShimException

  Construct a `ShimHost` instance for the passed class name. This overload will set up `com.novell.nds.dirxml.shimhost.ConsoleTraceImpl` as the trace facility for the constructed instance, meaning that all trace messages will be delivered to System.out.

  Parameters:
    `className` - the name of the application shim's `DriverShim` implementation class
  Throws:
    `IllegalArgumentException` - if `className` is `null`
    `ClassNotFoundException` - if the specified class can't be loaded
    `ShimException` - if the specified class's default constructor throws a `Throwable` during construction

### ShimHost

    public ShimHost(String className,
                    Trace tracer)
             throws IllegalArgumentException,
                    ClassNotFoundException,
                    ShimException

  Construct a `ShimHost` instance for the passed class name using the passed `Trace` facility.

  Parameters:
    `className` - the name of the application shim's `DriverShim` implementation class
    `tracer` - an instance of `Trace` to use for outputting trace messages
  Throws:
    `IllegalArgumentException` - if `className` is null
    `ClassNotFoundException` - if the specified class can't be loaded
    `ShimException` - if the specified class's default constructor throws a `Throwable` during construction

Method Detail

### initialize

    public static void initialize()

  Perform static class initialization.

### initialize

    public static void initialize(ClassLoader cl)

  Perform static class initialization.

  Parameters:
    `cl` - ClassLoader instance to use for loading shim classes.

### cleanup

    public static void cleanup()

  Perform static class cleanup().

### validateClass

    public void validateClass()
                       throws ClassNotFoundException

  Validate that the class name with which this instance was created can be found.

  Throws:
    `ClassNotFoundException`

### getClassName

    public String getClassName()

  Return the class name associationed with this instance.

  Returns:
    class name

### getRunningState

    public int getRunningState()

  Return the current state of this instance

  Returns:
    state
  See Also:
    `STATE_STOPPED`, `STATE_RUNNING`, `STATE_FLAG_DRIVER_INITIALIZED`, `STATE_FLAG_SUBSCRIBER_INITIALIZED`, `STATE_FLAG_PUBLISHER_INITIALIZED`, `STATE_FLAG_IN_PUBLISHER_START`

### getTracer

    public Trace getTracer()

  Get the `Trace` object that is used by this instance for outputting trace messages.

  Returns:
    `Trace` instance

### setPublisherEventHandler

    public void setPublisherEventHandler(XmlCommandProcessor cmdProcessor)

  Set an `XmlCommandProcessor` instance to receive event documents from the shim's Publisher. Note that the `XmlCommandProcessor.execute()` will be called on the Publisher thread.

  Parameters:
    `cmdProcessor` - `XmlCommandProcessor` instance, or `null`
  See Also:
    `XmlCommandProcessor`

### setStateListener

    public void setStateListener(ShimHost.StateListener listener)

  Method to set a `StateListener` implementation to be notified of shim state changes when reported by the shim in a shim document. The `StateListener.notifyShimState()` method may be called on either the Publisher or the Subscriber thread.

  Parameters:
    `listener` - `StateListener` implementation
  See Also:
    `ShimHost.StateListener`

### setRunningStateChangeListener

    public void setRunningStateChangeListener(ShimHost.RunningStateChangeListener listener)

  Method to set a RunningStateChangeListener implementation to be notified when the shim starts or stops. The listener will be notified only when the shim transitions from stopped to running and vice versa.

  Parameters:
    `listener` - object to be notified
  See Also:
    `ShimHost.RunningStateChangeListener`

### setDriverPasswordCheck

    public void setDriverPasswordCheck(ShimHost.DriverPasswordCheck checker)

  Method to set a `DriverPasswordCheck` implementation to check a string against the driver object password.

  Parameters:
    `checker` - `DriverPasswordCheck` implementation
  See Also:
    `ShimHost.DriverPasswordCheck`

### load

    public void load()
              throws ClassNotFoundException,
                     ShimException

  Construct the instance of the `DriverShim` implementation class to be used. Calling this method is not strictly necessary as it will be called when needed by the `getSchema()` and `start()` methods. It is provided for testing and completeness.

  This method causes the Subscriber thread to actually construct the `DriverShim` instance. This method will not return until the Subscriber thread has completed the construction.

  Throws:
    `ShimException` - if the `DriverShim` constructor throws a `Throwable`
    `ClassNotFoundException`
  See Also:
    `DriverShim`

### getSchema

    public Document getSchema(Document initDoc)
                       throws IllegalStateException,
                              IllegalArgumentException,
                              ShimException,
                              ClassNotFoundException

  Call the shim's `DriverShim.getSchema()` method.

  This method causes the Subscriber thread to call `DriverShim.getSchema()`. This method will not return until the Subscriber thread has completed the call and returned the resulting document to the calling thread.

  Parameters:
    `initDoc` - `Document` to pass to `DriverShim.getSchema()`
  Returns:
    `Document` returned from `DriverShim.getSchema()`
  Throws:
    `IllegalStateException` - if `getRunningState()` returns other than `STATE_STOPPED`
    `IllegalArgumentException` - if `initDoc` parameter is `null`
    `ShimException` - if `DriverShim.getSchema()` throws a `Throwable`
    `ClassNotFoundException` - if `load()` has not yet been called, and a `ClassNotFoundException` is thrown during the attempt to load the shim
  See Also:
    `getRunningState()`, `load()`, `DriverShim.getSchema(com.novell.nds.dirxml.driver.XmlDocument)`

### start

    public Document[] start(Document[] initDocs)
                     throws IllegalStateException,
                            IllegalArgumentException,
                            ShimException,
                            ClassNotFoundException

  Cause the Subscriber thread to initialize the shim and start the publisher.

  This method will cause the following actions on the Subscriber thread:
  1. If `load()` has not yet been called, `load()` is called to create the `DriverShim` implementation.
  2. `DriverShim.init()` is called.
  3. `SubscriptionShim.init()` is called.
  4. The Publisher thread is started
  5. `PublicationShim.init()` is called.
  6. `PublicationShim.start()` is called.
  If an error occurs in any of the above steps the start process is aborted and the shim is shut down by calling `shutdown()`.

  Parameters:
    `initDocs` - array of 3 initialization `Document`s to pass to `DriverShim.init()`, `SubscriptionShim.init()`, and `PublicationShim.init()`
  Returns:
    array of 3 return Documents from `DriverShim.init()`, `SubscriptionShim.init()`, and `PublicationShim.init()`
  Throws:
    `IllegalStateException` - if `getRunningState()` returns other than `STATE_STOPPED`
    `IllegalArgumentException` - if the `initDocs` parameter is `null`, or one of the array elements is `null`
    `ShimException` - if one of the shim methods throws a `Throwable`, or if one of the shim methods returns a "fatal" status
    `ClassNotFoundException` - if `load()` has not yet been called, and a `ClassNotFoundException` is thrown during the attempt to load the shim
  See Also:
    `getRunningState()`, `load()`, `DriverShim.init(com.novell.nds.dirxml.driver.XmlDocument)`, `SubscriptionShim.init(com.novell.nds.dirxml.driver.XmlDocument)`, `PublicationShim.init(com.novell.nds.dirxml.driver.XmlDocument)`, `PublicationShim.start(com.novell.nds.dirxml.driver.XmlCommandProcessor)`, `DRIVER_INIT_DOC`, `SUBSCRIBER_INIT_DOC`, `PUBLISHER_INIT_DOC`, `DRIVER_INIT_RETURN`, `SUBSCRIBER_INIT_RETURN`, `PUBLISHER_INIT_RETURN`

### execute

    public Document execute(Document commandDocument,
                            XmlQueryProcessor queryProcessor)
                     throws IllegalStateException,
                            ShimException

  Cause the Subscriber thread to submit the passed command document to the shim's `SubscriptionShim.execute()` method.

  If the shim issues a call-back query via the `queryProcessor` parameter, the `XmlQueryProcessor.query()` method will be called on the thread used to call this method.

  Note that the `start()` method must have been previously called, and that the `shutdown()` method must not yet have been called.

  Parameters:
    `commandDocument` - `Document` containing commands for Subscriber shim
    `queryProcessor` - implementation of `XmlQueryProcessor` to handler queries from the Subscriber shim. This parameter may be `null`, in which case the behavior is to return a "success" status as the result of any query.
  Returns:
    result `Document` from the Subscriber shim
  Throws:
    `IllegalStateException` - if `getRunningState()` doesn't return `STATE_RUNNING`
    `ShimException` - if `SubscriptionShim.execute()` throws a `Throwable`
  See Also:
    `getRunningState()`, `SubscriptionShim.execute(com.novell.nds.dirxml.driver.XmlDocument, com.novell.nds.dirxml.driver.XmlQueryProcessor)`, `XmlQueryProcessor.query(com.novell.nds.dirxml.driver.XmlDocument)`

### shutdown

    public Document[] shutdown(Document reasonDoc)
                        throws IllegalStateException,
                               ShimException

  Cause the Subscriber thread to call the shim's `DriverShim.shutdown()` method.

  The `start()` method must have been previously called.

  Parameters:
    `reasonDoc` - a `Document` containing information on the purpose of the shutdown (may be `null`)
  Returns:
    array of 2 `Document`s returned from `DriverShim.shutdown()` and `PublicationShim.start()`
  Throws:
    `IllegalStateException` - if `getRunningState()` returns `STATE_STOPPED`
    `ShimException` - if `DriverShim.shutdown()` throws a `Throwable`
  See Also:
    `DriverShim.shutdown(com.novell.nds.dirxml.driver.XmlDocument)`, `PublicationShim.start(com.novell.nds.dirxml.driver.XmlCommandProcessor)`, `getRunningState()`, `DRIVER_SHUTDOWN_RETURN`, `PUBLISHER_START_RETURN`

### checkForFatalError

    public static void checkForFatalError(XmlDocument doc)
                                   throws FatalShimException

  Examine a shim document for any <status> element with level="fatal".

  This method is used internally by the `ShimHost` class, and is provided for users of the `ShimHost` class as well.

  Parameters:
    `doc` - `XmlDocument` from shim
  Throws:
    `FatalShimException` - if there is one or more <status> element with the level attribute set to "fatal"

### checkForFatalError

    public static void checkForFatalError(Document returnDoc)
                                   throws FatalShimException

  Examine a shim document for any <status> element with level="fatal".

  This method is used internally by the `ShimHost` class, and is provided for users of the `ShimHost` class as well.

  Parameters:
    `returnDoc` - `Document` from shim
  Throws:
    `FatalShimException` - if there is one or more <status> element with the level attribute set to "fatal"

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD