001    // Copyright 2006, 2007, 2008 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    
015    package org.apache.tapestry5.ioc.services;
016    
017    /**
018     * Manages per-thread data, and provides a way for listeners to know when such data should be cleaned up.  Typically,
019     * data is cleaned up at the end of the request (in a web application). Tapestry IoC has any number of objects that need
020     * to know when this event occurs, so that they can clean up any per-thread/per-request state.
021     * <p/>
022     * Due to <a href="https://issues.apache.org/jira/browse/TAPESTRY-2141">TAPESTRY-2141<a> (and the underlying JDK 1.5 bug
023     * <a href="http://bugs.sun.com/bugdatabase/view_bug.do?bug_id=5025230">5025230</a>), this service has expanded to
024     * manager per-thread data (not just end-of-request listeners).
025     */
026    public interface PerthreadManager
027    {
028        /**
029         * Adds a listener to the hub.  All listeners are discarded at the {@link #cleanup()}.
030         *
031         * @param listener to add
032         */
033        void addThreadCleanupListener(ThreadCleanupListener listener);
034    
035        /**
036         * Immediately performs a cleanup of the thread, notifying all listeners then discarding the thread locale and the
037         * map it stores.
038         */
039        void cleanup();
040    
041    
042        /**
043         * Returns an object stored in the per-thread map.    When the object is a string, the expected name is <em>service
044         * id</em>.<em>subkey</em>.  Unlike most of Tapestry, such keys <em>will</em> be case sensitive.
045         *
046         * @param key key used to retrieve object
047         * @return corresponding per-thread object, or null
048         */
049        Object get(Object key);
050    
051        /**
052         * Stores a value into the per-thread map.
053         */
054        void put(Object key, Object value);
055    }