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 */
011package com.thoughtworks.proxy.toys.multicast;
012
013import 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 */
023public 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}