    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}