001//  Copyright 2008, 2009, 2013 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.tapestry5.ioc;
016
017import java.io.IOException;
018
019/**
020 * Used to track some set of operations in such a way that a failure (a thrown RuntimeException) will be logged along
021 * with a trace of the stack of operations.
022 */
023public interface OperationTracker
024{
025    /**
026     * Executes the operation.  If the operation throws a {@link RuntimeException} it will be logged and rethrown
027     * wrapped as a {@link org.apache.tapestry5.ioc.internal.OperationException}.
028     *
029     * @param description
030     *         used if there is an exception
031     * @param operation
032     *         to execute
033     */
034    void run(String description, Runnable operation);
035
036    /**
037     * As with {@link #run(String, Runnable)}, but the operation may return a value.
038     *
039     * @param description
040     *         used if there is an exception
041     * @param operation
042     *         to invoke
043     * @return result of operation
044     */
045    <T> T invoke(String description, Invokable<T> operation);
046
047    /**
048     * As with {@link #invoke(String, Invokable)}, but the operation may throw an {@link java.io.IOException}.
049     *
050     * @param description
051     *         used if there is an exception (outside of IOException)
052     * @param operation
053     *         to perform
054     * @return result of operation
055     * @since 5.4
056     */
057    <T> T perform(String description, IOOperation<T> operation) throws IOException;
058}