Updated HierarchyEventListener interface

[mw...@apache.org]

Working on the PluginRegistry class, it became apparent that when a
LoggerRepository/Hierarchy is shutdown, the PluginRegistry should be
informed so that it can cleanly shutdown and remove any plugins associated
with that Repository/Hierarchy.  After looking at the problem, it was
confirmed that the best way to achieve this would be for the PluginRegistry
to register a HierarchyEventListener interface with each
LoggerRepository/Hierarchy it contains plugins for.  Unfortunately, the
existing HierarchyEventListener interface only contains 2 methods, related
to appenders being added/removed.

So, I have taken a crack at extending the interface to be more generic and
support current and future expansion without affecting the method signature
of the interface.  However, I don't know what the best course of action is
regarding the currently defined methods.  They should be deprecated...but
the calling code in Hierarchy is going to need to be intelligent enough to
look for the deprecated methods and call those over the handleHierarchyEvent
method?  Advice on this point would be appreciated.

Here is the proposed interface:

package org.apache.log4j.spi;

import java.util.Map;
import org.apache.log4j.*;

/**
   Listen to events occuring within a {@link
   org.apache.log4j.Hierarchy Hierarchy}.

   @author Ceki Gülcü
   @author Mark Womack
   @since 1.2

 */
public interface HierarchyEventListener {
  // defined event types
  /** Hierarchy startup. Event data is empty. */
  public static final int EVENT_HIERARCHY_STARTUP   = 0;

  /** Hierarchy shutdown. Event data is empty. */
  public static final int EVENT_HIERARCHY_SHUTDOWN  = 1;

  /** Appender added to hierarchy. Event data contains APPENDER and
  LOGGER. */
  public static final int EVENT_APPENDER_ADDED      = 2;

  /** Appender removed from hierarchy. Event data contains APPENDER
  and LOGGER. */
  public static final int EVENT_APPENDER_REMOVED    = 3;

  // defined data keys for events
  public static final String DATA_APPENDER = "appender";
  public static final String DATA_LOGGER   = "logger";

  /**
  @deprecated
  Called when an appender is added a category.
  Use handleHierarchyEvent instead as of v1.3. */
  public void addAppenderEvent(Category cat, Appender appender);

  /**
  @deprecated
  Called when an appender is removed from a category.
  Use handleHierarchyEvent instead as of v1.3. */
  public void removeAppenderEvent(Category cat, Appender appender);

  /**
  Called when events occur in the hierarchy. See the EVENT_* constants for
  a list of supported hierarchy event type. Each event type documents the
  set of event data sent for that event.  Depending on the event type, the
  set of event data varies. */
  public void handleHierarchyEvent(int eventType, Hierarchy hierarchy,
    Map eventData);
}

I chose to break out the event info (type, hierarchy, data) into parameters
to avoid creating an event object, but we could encapsulate the info into a
HierarchyEvent if desired.  I want to get this squared away so that I can
continue with the plugin work.

-Mark


--
To unsubscribe, e-mail:   <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>

Re: Updated HierarchyEventListener interface

[Ceki Gülcü <ce...@qos.ch>]

Although the handleHierarchyEvent(int eventType, ...) method can
handle many types of events isn't it a bit too C like? Aren't we
better off defining a new interface or new interfaces? We could have
an interface to handle Logger related events (appender additions,
appender deletions, level changes) and hierarchy wide events
(threshold change, start, stop, etc).

I thinking along the lines of

public interface HierarchyEventListener {
   public void hierarchyStartEvent(Hierarchy h);
   public void hierarchyStopEvent(Hierarchy h);
}


public interface LoggerEventListener {
    // Note that the logger knows the repository it is attached to. Assuming
    // we add a new method getLoggerRepository() to the Logger class,
    // management software can get a handle on the repository where the
    // logger (generating the event) is attached to.

    public void addAppenderEvent(Logger logger, Appender appender);
    public void removeAppenderEvent(Logger logger, Appender appender);
    public void removeAllAppendersEvent(Logger logger);
    public void levelChangedEvent(Logger logger);
}


However, if you need to make progress quickly in other fronts, then go
ahead as long as we keep in mind that we can review/modify/rollback things
later.

ps: I am glad to see you forging ahead with this.


At 21:31 11.11.2002 -0800, you wrote:
>Working on the PluginRegistry class, it became apparent that when a
>LoggerRepository/Hierarchy is shutdown, the PluginRegistry should be
>informed so that it can cleanly shutdown and remove any plugins associated
>with that Repository/Hierarchy.  After looking at the problem, it was
>confirmed that the best way to achieve this would be for the PluginRegistry
>to register a HierarchyEventListener interface with each
>LoggerRepository/Hierarchy it contains plugins for.  Unfortunately, the
>existing HierarchyEventListener interface only contains 2 methods, related
>to appenders being added/removed.
>
>So, I have taken a crack at extending the interface to be more generic and
>support current and future expansion without affecting the method signature
>of the interface.  However, I don't know what the best course of action is
>regarding the currently defined methods.  They should be deprecated...but
>the calling code in Hierarchy is going to need to be intelligent enough to
>look for the deprecated methods and call those over the handleHierarchyEvent
>method?  Advice on this point would be appreciated.
>
>Here is the proposed interface:
>
>package org.apache.log4j.spi;
>
>import java.util.Map;
>import org.apache.log4j.*;
>
>/**
>    Listen to events occuring within a {@link
>    org.apache.log4j.Hierarchy Hierarchy}.
>
>    @author Ceki Gülcü
>    @author Mark Womack
>    @since 1.2
>
>  */
>public interface HierarchyEventListener {
>   // defined event types
>   /** Hierarchy startup. Event data is empty. */
>   public static final int EVENT_HIERARCHY_STARTUP   = 0;
>
>   /** Hierarchy shutdown. Event data is empty. */
>   public static final int EVENT_HIERARCHY_SHUTDOWN  = 1;
>
>   /** Appender added to hierarchy. Event data contains APPENDER and
>   LOGGER. */
>   public static final int EVENT_APPENDER_ADDED      = 2;
>
>   /** Appender removed from hierarchy. Event data contains APPENDER
>   and LOGGER. */
>   public static final int EVENT_APPENDER_REMOVED    = 3;
>
>   // defined data keys for events
>   public static final String DATA_APPENDER = "appender";
>   public static final String DATA_LOGGER   = "logger";
>
>   /**
>   @deprecated
>   Called when an appender is added a category.
>   Use handleHierarchyEvent instead as of v1.3. */
>   public void addAppenderEvent(Category cat, Appender appender);
>
>   /**
>   @deprecated
>   Called when an appender is removed from a category.
>   Use handleHierarchyEvent instead as of v1.3. */
>   public void removeAppenderEvent(Category cat, Appender appender);
>
>   /**
>   Called when events occur in the hierarchy. See the EVENT_* constants for
>   a list of supported hierarchy event type. Each event type documents the
>   set of event data sent for that event.  Depending on the event type, the
>   set of event data varies. */
>   public void handleHierarchyEvent(int eventType, Hierarchy hierarchy,
>     Map eventData);
>}
>
>I chose to break out the event info (type, hierarchy, data) into parameters
>to avoid creating an event object, but we could encapsulate the info into a
>HierarchyEvent if desired.  I want to get this squared away so that I can
>continue with the plugin work.
>
>-Mark
>
>
>--
>To unsubscribe, e-mail:   <ma...@jakarta.apache.org>
>For additional commands, e-mail: <ma...@jakarta.apache.org>

--
Ceki

TCP implementations will follow a general principle of robustness: be
conservative in what you do, be liberal in what you accept from
others. -- Jon Postel, RFC 793



--
To unsubscribe, e-mail:   <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>