Annotation 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:
  • Required Element Summary

    Required Elements
    Modifier and Type
    Required Element
    Description
    The name of the C++ adapter class.
  • Optional Element Summary

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

    • value

      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