001    // SECTION-START[License Header]
002    // <editor-fold defaultstate="collapsed" desc=" Generated License ">
003    /*
004     *   Copyright (c) 2009 The JOMC Project
005     *   Copyright (c) 2005 Christian Schulte <cs@jomc.org>
006     *   All rights reserved.
007     *
008     *   Redistribution and use in source and binary forms, with or without
009     *   modification, are permitted provided that the following conditions
010     *   are met:
011     *
012     *     o Redistributions of source code must retain the above copyright
013     *       notice, this list of conditions and the following disclaimer.
014     *
015     *     o Redistributions in binary form must reproduce the above copyright
016     *       notice, this list of conditions and the following disclaimer in
017     *       the documentation and/or other materials provided with the
018     *       distribution.
019     *
020     *   THIS SOFTWARE IS PROVIDED BY THE JOMC PROJECT AND CONTRIBUTORS "AS IS"
021     *   AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
022     *   THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
023     *   PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE JOMC PROJECT OR
024     *   CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
025     *   EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
026     *   PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
027     *   OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
028     *   WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
029     *   OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
030     *   ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
031     *
032     *   $Id: Invoker.java 1102 2009-12-07 03:01:58Z schulte2005 $
033     *
034     */
035    // </editor-fold>
036    // SECTION-END
037    package org.jomc.spi;
038    
039    // SECTION-START[Documentation]
040    // <editor-fold defaultstate="collapsed" desc=" Generated Documentation ">
041    /**
042     * Invokes objects.
043     * <p>This specification declares a multiplicity of {@code One}.
044     * An application assembler is required to provide no more than one implementation of this specification (including none).
045     * Use of class {@link org.jomc.ObjectManager ObjectManager} is supported for getting that implementation.<pre>
046     * Invoker object = (Invoker) ObjectManagerFactory.getObjectManager( getClassLoader() ).getObject( Invoker.class );
047     * </pre>
048     * </p>
049     *
050     * <p>This specification does not apply to any scope. A new object is returned whenever requested.</p>
051     *
052     * @author <a href="mailto:cs@jomc.org">Christian Schulte</a> 1.0
053     * @version $Id: Invoker.java 1102 2009-12-07 03:01:58Z schulte2005 $
054     */
055    // </editor-fold>
056    // SECTION-END
057    // SECTION-START[Annotations]
058    // <editor-fold defaultstate="collapsed" desc=" Generated Annotations ">
059    @javax.annotation.Generated( value = "org.jomc.tools.JavaSources",
060                                 comments = "See http://jomc.sourceforge.net/jomc/1.0-alpha-11/jomc-tools" )
061    // </editor-fold>
062    // SECTION-END
063    public interface Invoker
064    {
065        // SECTION-START[InvocationHandler]
066    
067        /**
068         * Performs a method invocation on an object.
069         *
070         * @param invocation The invocation to perform.
071         *
072         * @return The return value of the invocation. If the declared return type of the method of the invocation is a
073         * primitive type, then the value returned by this method must be an instance of the corresponding primitive wrapper
074         * class; otherwise, it must be a type assignable to the declared return type of the method of the invocation.
075         * If the value returned by this method is {@code null} and the declared return type of the method of the invocation
076         * is primitive, then a {@code NullPointerException} will be thrown. If the value returned by this method is
077         * otherwise not compatible to the declared return type of the method of the invocation, a
078         * {@code ClassCastException} will be thrown.
079         *
080         * @throws Throwable The exception thrown from the method invocation. The exception's type must be assignable
081         * either to any of the exception types declared in the {@code throws} clause of the method of the invocation or to
082         * the unchecked exception types {@code java.lang.RuntimeException} or {@code java.lang.Error}.
083         * If a checked exception is thrown by this method that is not assignable to any of the exception types declared in
084         * the {@code throws} clause of the method of the invocation, then an {@code UndeclaredThrowableException}
085         * containing the exception that was thrown by this method will be thrown.
086         *
087         * @see java.lang.reflect.UndeclaredThrowableException
088         */
089        Object invoke( Invocation invocation ) throws Throwable;
090    
091        // SECTION-END
092    }