com.github.dm.jrt.object.builder.ObjectRoutineBuilder Maven / Gradle / Ivy
Show all versions of jroutine-object Show documentation
/*
* Copyright 2016 Davide Maestroni
*
* 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.github.dm.jrt.object.builder;
import com.github.dm.jrt.core.config.InvocationConfigurable;
import com.github.dm.jrt.core.routine.Routine;
import com.github.dm.jrt.core.util.ClassToken;
import com.github.dm.jrt.object.config.ObjectConfigurable;
import org.jetbrains.annotations.NotNull;
import java.lang.reflect.Method;
/**
* Interface defining a builder of routines wrapping object methods.
*
* Created by davide-maestroni on 03/07/2015.
*/
public interface ObjectRoutineBuilder
extends InvocationConfigurable, ObjectConfigurable {
/**
* Returns a proxy object enabling asynchronous call of the target instance methods.
*
* The routines used for calling the methods will honor the attributes specified in any optional
* {@code com.github.dm.jrt.object.annotation.*} annotations.
*
* Note that such annotations will override any configuration set through the builder.
*
* In case the wrapped object does not implement the specified interface, the alias annotation
* value will be used to bind the interface method with the instance ones. If no annotation is
* present, the method name will be used instead.
*
* The interface will be interpreted as a proxy of the target object methods, and the optional
* {@link com.github.dm.jrt.object.annotation.AsyncInput AsyncInput},
* {@link com.github.dm.jrt.object.annotation.AsyncMethod AsyncMethod},
* {@link com.github.dm.jrt.object.annotation.AsyncOutput AsyncOutput} and
* {@link com.github.dm.jrt.object.annotation.Invoke Invoke} annotations will be honored.
*
* @param itf the interface implemented by the returned object.
* @param the interface type.
* @return the proxy object.
* @throws java.lang.IllegalArgumentException if the specified class does not represent an
* interface.
* @see
* Annotations
*/
@NotNull
TYPE buildProxy(@NotNull Class itf);
/**
* Returns a proxy object enabling asynchronous call of the target instance methods.
*
* The routines used for calling the methods will honor the attributes specified in any optional
* {@code com.github.dm.jrt.object.annotation.*} annotations.
*
* Note that such annotations will override any configuration set through the builder.
*
* In case the wrapped object does not implement the specified interface, the alias annotation
* value will be used to bind the interface method with the instance ones. If no annotation is
* present, the method name will be used instead.
*
* The interface will be interpreted as a proxy of the target object methods, and the optional
* {@link com.github.dm.jrt.object.annotation.AsyncInput AsyncInput},
* {@link com.github.dm.jrt.object.annotation.AsyncMethod AsyncMethod},
* {@link com.github.dm.jrt.object.annotation.AsyncOutput AsyncOutput} and
* {@link com.github.dm.jrt.object.annotation.Invoke Invoke} annotations will be honored.
*
* @param itf the token of the interface implemented by the returned object.
* @param the interface type.
* @return the proxy object.
* @throws java.lang.IllegalArgumentException if the specified class token does not represent an
* interface.
* @see
* Annotations
*/
@NotNull
TYPE buildProxy(@NotNull ClassToken itf);
/**
* Returns a routine used to call the method whose identifying name is specified in a
* {@link com.github.dm.jrt.object.annotation.Alias Alias} annotation.
*
* If no method with the specified alias is found, this method will behave like
* {@link #method(String, Class[])} with no parameter.
*
* Optional {@code com.github.dm.jrt.object.annotation.*} method annotations will be
* honored as well.
*
* Note that such annotations will override any configuration set through the builder.
*
* Note that it is up to the caller to ensure that the input data are passed to the routine in
* the correct order.
*
* @param name the name specified in the annotation.
* @param the input data type.
* @param the output data type.
* @return the routine.
* @throws java.lang.IllegalArgumentException if the specified method is not found or its
* annotations are invalid.
* @see
* Annotations
*/
@NotNull
Routine method(@NotNull String name);
/**
* Returns a routine used to call the specified method.
*
* The method is searched via reflection ignoring a name specified in a
* {@link com.github.dm.jrt.object.annotation.Alias Alias} annotation. Though, optional
* {@code com.github.dm.jrt.object.annotation.*} method annotations will be honored.
*
* Note that such annotations will override any configuration set through the builder.
*
* Note that it is up to the caller to ensure that the input data are passed to the routine in
* the correct order.
*
* @param name the method name.
* @param parameterTypes the method parameter types.
* @param the input data type.
* @param the output data type.
* @return the routine.
* @throws java.lang.IllegalArgumentException if no matching method is found or its annotations
* are invalid.
* @see
* Annotations
*/
@NotNull
Routine method(@NotNull String name, @NotNull Class... parameterTypes);
/**
* Returns a routine used to call the specified method.
*
* The method is invoked ignoring a name specified in a
* {@link com.github.dm.jrt.object.annotation.Alias Alias} annotation. Though, optional
* {@code com.github.dm.jrt.object.annotation.*} method annotations will be honored.
*
* Note that such annotations will override any configuration set through the builder.
*
* Note that it is up to the caller to ensure that the input data are passed to the routine in
* the correct order.
*
* @param method the method instance.
* @param the input data type.
* @param the output data type.
* @return the routine.
* @throws java.lang.IllegalArgumentException the method annotations are invalid.
* @see
* Annotations
*/
@NotNull
Routine method(@NotNull Method method);
}