001    /*
002     * (c) 2005, 2009, 2010 ThoughtWorks Ltd
003     * All rights reserved.
004     *
005     * The software in this package is published under the terms of the BSD
006     * style license a copy of which has been included with this distribution in
007     * the LICENSE.txt file.
008     * 
009     * Created on 28-Jul-2005
010     */
011    package com.thoughtworks.proxy.toys.multicast;
012    
013    import java.lang.reflect.Method;
014    
015    
016    /**
017     * Interface that is implemented by all multicasting proxies. Cast the proxy to access the proxied elements again or to
018     * call a method on them independent of the type of the proxy.
019     *
020     * @author Jörg Schaible
021     * @since 0.2
022     */
023    public interface Multicast {
024    
025        /**
026         * Multicast a matching method call, that is not available with the types implemented by the proxy.
027         * <p>
028         * Use this possibility to operate on objects, that can typically not be proxied e.g. if the class type of the
029         * target object is final like it is for a lot of basic classes of <tt>java.lang</tt>. The result of the call
030         * follow the normal rules for multicast invocations.
031         * </p>
032         * <p>
033         * Note that the implementation of this function must search the best fitting method. It is much more efficient to
034         * call the overloaded version of this function with the appropriate method object.
035         * </p>
036         *
037         * @param type   the type that has a method with the given name and matching arguments
038         * @param method the method name
039         * @param args   the arguments of the invocation
040         * @return the result of the multicast
041         * @throws NoSuchMethodException if the type has no matching method
042         * @throws SecurityException     if the security manager prevents the method access by reflection
043         * @since 0.2
044         */
045        <T> T multicastTargets(Class<T> type, String method, Object[] args) throws NoSuchMethodException;
046    
047        /**
048         * Multicast a direct method call, that is not available with the types implemented by the proxy.
049         * <p>
050         * Use this possibility to operate on objects, that can typically not be proxied e.g. if the class type of the
051         * target object is final like it is for a lot of basic classes of <tt>java.lang</tt>. The result of the call
052         * follow the normal rules for multicast invocations.
053         * </p>
054         *
055         * @param method the method to call
056         * @param args   the arguments of the invocation
057         * @return the result of the multicast
058         * @since 0.2
059         */
060        Object multicastTargets(Method method, Object[] args);
061    
062        /**
063         * Access the targets of the proxy in a typed array.
064         *
065         * @param type the type of an array element
066         * @return the typed array of proxy targets
067         * @since 0.2
068         */
069        <T> T[] getTargetsInArray(Class<T> type);
070    
071        /**
072         * Access the targets of the proxy in an array.
073         *
074         * @return the array of proxy targets
075         * @since 0.2
076         */
077        Object[] getTargetsInArray();
078    }