001    // Copyright 2006, 2007, 2008, 2010 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    import org.apache.tapestry5.ioc.Invokable;
018    
019    /**
020     * Manages per-thread data, and provides a way for listeners to know when such data should be cleaned up. Typically,
021     * data is cleaned up at the end of the request (in a web application). Tapestry IoC has any number of objects that need
022     * to know when this event occurs, so that they can clean up any per-thread/per-request state.
023     * <p/>
024     * Due to <a href="https://issues.apache.org/jira/browse/TAPESTRY-2141">TAPESTRY-2141<a> (and the underlying JDK 1.5 bug
025     * <a href="http://bugs.sun.com/bugdatabase/view_bug.do?bug_id=5025230">5025230</a>), this service has expanded to
026     * manage per-thread data (not just end-of-request listeners).
027     */
028    public interface PerthreadManager
029    {
030        /**
031         * Adds a listener to the hub. All listeners are discarded at the {@link #cleanup()}.
032         * 
033         * @param listener
034         *            to add
035         */
036        void addThreadCleanupListener(ThreadCleanupListener listener);
037    
038        /**
039         * Immediately performs a cleanup of the thread, notifying all listeners then discarding the thread locale and the
040         * map it stores.
041         */
042        void cleanup();
043    
044        /**
045         * Returns an object stored in the per-thread map. When the object is a string, the expected name is <em>service
046         * id</em>.<em>subkey</em>. Unlike most of Tapestry, such keys <em>will</em> be case sensitive.
047         * 
048         * @param key
049         *            key used to retrieve object
050         * @return corresponding per-thread object, or null
051         * @deprecated use {@link PerthreadManager#createValue()} instead
052         */
053        Object get(Object key);
054    
055        /**
056         * Stores a value into the per-thread map.
057         * 
058         * @deprecated use {@link PerthreadManager#createValue()} instead
059         */
060        void put(Object key, Object value);
061    
062        /**
063         * Creates a value using a unique internal key.
064         * 
065         * @since 5.2.0
066         */
067        <T> PerThreadValue<T> createValue();
068    
069        /**
070         * Invokes {@link Runnable#run()}, providing a try...finally to {@linkplain #cleanup() cleanup} after.
071         * 
072         * @since 5.2.0
073         */
074        void run(Runnable runnable);
075    
076        /**
077         * Returns the result from the invocation, providing a try...finally to {@linkplain #cleanup() cleanup} after.
078         */
079        <T> T invoke(Invokable<T> invokable);
080    }