com.gh.bmd.jrt.processor.annotation.Proxy Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of jroutine-processor Show documentation
Parallel programming on the go
There is a newer version: 6.0.0
/*
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package com.gh.bmd.jrt.processor.annotation;

import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

/**
 * This annotation is used to indicate interfaces used as templates to generate proxy classes
 * enabling asynchronous calls to the target instance methods.
 * 
 * The target class is specified in the annotation attribute. A proxy class implementing the
 * annotated interface will be generated within the interface package and its name will be obtained
 * by appending "{@value #CLASS_NAME_SUFFIX}" to the interface simple name. In case the specific
 * interface is not a top class, the simple name of the outer classes will be prepended to the
 * interface one.

 * The routines used for calling the methods will honor the attributes specified in any optional
 * {@link com.gh.bmd.jrt.annotation.Bind}, {@link com.gh.bmd.jrt.annotation.Timeout},
 * {@link com.gh.bmd.jrt.annotation.TimeoutAction} and {@link com.gh.bmd.jrt.annotation.Pass}
 * annotations defined for each interface method.
 * 

 * Special care must be taken when dealing with proxies of generic classes. First of all, the
 * proxy interface must declare the same generic types as the wrapped class or interface.
 * Additionally, the generic parameters must be declared as Object in order for the
 * proxy interface methods to match the target ones.

 * Be also aware that it is responsibility of the caller to ensure that the same instance is not
 * wrapped around two different generic interfaces.

 * For example, a class of the type:
 * 
 *     
 *
 *             public class MyList<TYPE> {
 *
 *                 private final ArrayList<TYPE> mList = new ArrayList<TYPE>();
 *
 *                 public void add(final TYPE element) {
 *
 *                     mList.add(element);
 *                 }
 *
 *                 public TYPE get(final int i) {
 *
 *                     return mList.get(i);
 *                 }
 *             }
 *     
 * 
 * can be correctly wrapped by an interface of the type:
 *  *     
 *
 *             @Proxy(MyList.class)
 *             public interface MyListAsync<TYPE> {
 *
 *                 void add(Object element);
 *
 *                 TYPE get(int i);
 *
 *                 @Bind("get")
 *                 @Pass(Object.class)
 *                 OutputChannel<TYPE> getAsync(int i);
 *
 *                 @Bind("get")
 *                 @Pass(Object.class)
 *                 List<TYPE> getList(int i);
 *             }
 *     
 * 
 * 
 * Note that, you'll need to enable annotation pre-processing by adding the "jroutine-processor"
 * artifact or module to the specific project dependencies. Be sure also to include a proper rule in
 * your Proguard file, so to keep the name of all the classes implementing the specific mirror
 * interface, like, for example:
 * 
 *     
 *
 *         -keep public class * extends my.mirror.Interface {
 *              public <init>;
 *         }
 *     
 * 
 * 
 * Created by davide on 11/3/14.
 */
@Target(ElementType.TYPE)
@Retention(RetentionPolicy.SOURCE)
public @interface Proxy {

    /**
     * Constant indicating the generated class name suffix.
     */
    String CLASS_NAME_SUFFIX = "_Proxy";

    /**
     * The wrapped class.
     *
     * @return the class.
     */
    Class value();
}