Package org.bytedeco.javacpp.annotation

Annotation Type Adapter

  • @Documented
@Retention(RUNTIME)
@Target({METHOD,PARAMETER,ANNOTATION_TYPE})
public @interface Adapter
    Specifies a C++ class to act as an adapter between a target type and one or more adaptee type(s). Instances of the adapter class are short-living and last only for the duration of a JNI call.

    Six such C++ classes are made available by Generator to bridge a few differences, for instance, between std::string and String, between std::vector, Java arrays of primitive types, Buffer, and Pointer, or between xyz::shared_ptr and Pointer:
    Adapter classTarget typeAdaptee typesHelper annotation
    VectorAdapter<P,T,A> std::vector<T,A> P StdVector
    StringAdapter<T> std::basic_string<T> char
    signed char
    unsigned char
    wchar_t
    unsigned short
    signed int    		 StdString
    SharedPtrAdapter<T> SHARED_PTR_NAMESPACE::shared_ptr<T> T SharedPtr
    UniquePtrAdapter<T,D> UNIQUE_PTR_NAMESPACE::unique_ptr<T,D> T UniquePtr
    MoveAdapter<T,D> T T StdMove
    OptionalAdapter<T> OPTIONAL_NAMESPACE::optional<T> T Optional
    The helper annotations are shortcuts that infer the template type(s) of the adapter class from the Java class they annotate.

    When an argument of a method is annotated, an instance of the adapter class is created from the Java object passed as argument, and this instance is passed to the C++ function, thus triggering an implicit cast to the type expected by the function (usually a reference or pointer to the target type). If the argument is also annotated with Cast, the adapter instance is cast to the type(s) specified by the Cast annotation before being passed to the function.

    When a method is annotated, an instance of the adapter is created from the value (usually a pointer or reference to the target type) returned by the C++ function or by new if the method is an allocator. If the method is also annotated with Cast, the value returned by the C++ function is cast by value 3 of the Cast annotation, if any, before instantiation of the adapter. Then a Java object is created from the adapter to be returned by the method.

    Adapter classes must at least define the following public members:
    • For each adaptee type, a constructor accepting 3 arguments (or more if argc() > 1): a pointer to a const value of the adaptee, a size, and the owner pointer
    • Another constructor that accepts a reference to the target type
    • A static void deallocate(owner) function
    • Overloaded cast operators to both the target type and the adaptee types, for references and pointers
    • void assign(pointer, size, owner) functions with the same signature than the constructors accepting 3 arguments
    • A size member variable for arrays accessed via pointer
    To reduce further the amount of coding, this annotation can also be used on other annotations, such as with StdString, StdVector, and SharedPtr.
    See Also:
    Generator

    • Required Element Summary

      Required Elements 
      Modifier and Type Required Element Description
      java.lang.String value
      The name of the C++ adapter class.

    • Optional Element Summary

      Optional Elements 
      Modifier and Type Optional Element Description
      int argc
      The number of arguments that Generator takes from the method as arguments to the adapter constructor.

    • Element Detail

      • value

        java.lang.String value
        The name of the C++ adapter class.

      • argc

        int argc
        The number of arguments that Generator takes from the method as arguments to the adapter constructor.
        Default:
        1