001// Copyright 2004, 2005 The Apache Software Foundation
002//
003// Licensed under the Apache License, Version 2.0 (the "License");
004// you may not use this file except in compliance with the License.
005// You may obtain a copy of the License at
006//
007//     http://www.apache.org/licenses/LICENSE-2.0
008//
009// Unless required by applicable law or agreed to in writing, software
010// distributed under the License is distributed on an "AS IS" BASIS,
011// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
012// See the License for the specific language governing permissions and
013// limitations under the License.
014
015package org.apache.hivemind.service;
016
017/**
018 * Service which acts as a dispatch hub for events about the lifecycle of the current thread.
019 * <p>
020 * Note: prior to release 1.1.1, the ThreadEventNotifier implementation would retain the listeners
021 * after {@link #fireThreadCleanup()}, which could allow certain threads to retain a reference to a
022 * listener, and thus that listener's class loader, even after the an application redeployment,
023 * resulting in a massive memory leak. Starting with release 1.1.1, all listeners are discarded by
024 * {@link #fireThreadCleanup()}.
025 * 
026 * @author Howard Lewis Ship
027 */
028public interface ThreadEventNotifier
029{
030    /**
031     * Adds the listener. The notifier retains the listener until {@link #fireThreadCleanup()} is
032     * invoked, at which point is discarded.
033     */
034    public void addThreadCleanupListener(ThreadCleanupListener listener);
035
036    /**
037     * Removes the listener, if it has been previously added. If the listener has been added
038     * multiple times, only one instance is removed. Note that this method is rarely used, because
039     * all listeners are automatically removed by {@link #fireThreadCleanup()}.
040     */
041    public void removeThreadCleanupListener(ThreadCleanupListener listener);
042
043    /**
044     * Invokes {@link ThreadCleanupListener#threadDidCleanup()} on all listeners, and discards the
045     * list of listeners.
046     */
047    public void fireThreadCleanup();
048}