The Transfer Handler

Developer API documentation: TransferHandler<T>

The report transfer handler is responsible for defining the transfer types supported by associated report entry objects as well as supplier objects that can provide meaningful data of each transfer type based on report entry objects. This transfer data may be used during drag-and-drop operations.

Intended target components of report entry drag-and-drop operations (e.g. an FS_BUTTON) should be configured to accept and operate on at least one of the transfer types supplied by the report's transfer handler class. Thus, in the case of an FS_BUTTON, its form definition should include at least one <MIME> or <TYPE> tag (see Input components: FS_BUTTON) in its <DROPTYPES> block matching a transfer type supplied by the transfer handler, and the script or executable called upon a drop action should be able to work on data of this same transfer type. Upon a drag-and-drop operation, the script or executable used to process drop data may work on these transfer types as described in the chapter Using FirstSpirit APIs: Drag-and-Drop.

Structural Notes

Report transfer handler classes implement several interfaces:

• TransferHandler<T>
  Associates a transfer type with a Supplier which provides data of a matching commodity type.
• TransferHandler.SupplierHost.Supplier<T, A>
  Transforms a report entry object of type T into one or more objects of commodity type A and returns these objects as a list.

Though SupplierHost is a sub-interface of TransferHandler, it is not necessary to implement this interface in a report plug-in. A valid SupplierHost object is provided as a parameter in TransferHandler#registerSupplier() calls.

TransferHandler

This class defines one or several transfer data suppliers, which are then registered with a matching transfer type.

The example code shown here references implementations of TransferHandler.SupplierHost.Supplier<T>, which are defined in the code example in the section Supplier.

public class ExampleTransferHandler implements TransferHandler<ExampleReportObject> {

    // BaseContext object for internal persistence in this class.
    private BaseContext _context;

    ExampleTransferHandler(final BaseContext context) {
        _context = context;
    }

    public void registerSuppliers(final SupplierHost<ExampleReportObject> host) {
        final TransferAgent transferAgent = _context.requireSpecialist(TransferAgent.TYPE);

        final TransferType<String> plainTextTransferType = transferAgent.getPlainTextType();
        final Supplier<ExampleReportObject, String> plainTextSupplier = new ExamplePlainTextSupplier();
        host.registerSupplier(plainTextTransferType, plainTextSupplier);

        final TransferType<String> htmlTextTransferType = transferAgent.getHtmlTextType();
        final Supplier<ExampleReportObject, String> htmlTextSupplier = new ExampleHtmlTextSupplier();
        host.registerSupplier(htmlTextTransferType, htmlTextSupplier);
    }

}

registerSuppliers()

This method should create one or several transfer data suppliers and register each of these suppliers with the SupplierHost object provided as a parameter. During this registration, each supplier is associated with a suitable TransferType.

Supplier

A Supplier implementation provides a list of one or more objects of a commodity type. These objects are generated based upon a single report entry object.

public class ExamplePlainTextSupplier implements TransferHandler.SupplierHost.Supplier<String, String> {

    public List<String> supply(final String object) {
        final List<String> result = new ArrayList<String>();
        result.add(object);
        return result;
    }

}

public class ExampleHtmlSupplier implements TransferHandler.SupplierHost.Supplier<String, String> {

    public List<String> supply(final String object) {
        final List<String> result = new ArrayList<String>();
        result.add("<b>" + object + "</b>");
        return result;
    }

}

supply()

This method supplies a list of objects in a specific commodity type. The commodity type is defined by parameterization of each class implementation of the Supplier interface.