Aspekt: TransferHandling

Aspect: TransferHandling

Package: de.espirit.firstspirit.ui.gadgets.aspects.transfer

Abhängig von der SwingGadget-Implementierung kann eine grafische Eingabekomponente (d.h. die Komponente muss java.awt.Component implementieren) einen generischen Zugriff auf die Inhalte anderer Quellen erhalten, um Objekte eines bestimmten Typs (Transfer-Typ) per „Drop“ in die Eingabekomponente zu übernehmen. Dabei unterscheidet man zwei Aspekte, das Liefern und das Empfangen eines Objekts. Der Aspekt TransferHandling ist für das Empfangen eines Objekts per „Drop“ verantwortlich.

Dieser Aspekt kann der SwingGadget-Implementierung über die Implements-Bedingung und den Aufruf von addAspect(…) im öffentlichen Konstruktor der SwingGadget-Implementierung hinzugefügt werden:

public class mySwingGadget implements TransferHandling {

    ...

    public mySwingGadget(final SwingGadgetContext<myGomForm> context) {
        super(context);
        addAspect(TransferHandling.TYPE, this);
    }

    ...

}

Mithilfe der Methode void registerHandlers(@NotNull HandlerHost host) muss die Komponente (oder ein Teil der Komponente, beispielsweise ein Eingabefeld) zunächst als Empfänger (Handler) für die zu transferierenden Objekte registriert werden. Dazu werden vorab ein (oder mehrere) neue Handler-Objekte erzeugt. Das Interface Handler stellt die Methode void handle(@NotNull CommodityContainer commodities, final Point location) für die Tansferbehandlung zur Verfügung. Dieser Methode wird eine Instanz vom Typ CommodityContainer übergeben, die einen typsicheren Zugriff auf die zu übertragenden Objekte ermöglicht. Über den Aufruf der Methode <A> List<A> get(TransferType<A> type) auf der Instanz vom Typ CommodityContainer kann hier der gewünschte Transfer-Typ übergeben werden (siehe Beispiel unten). Dabei kann ein CommodityContainer mehrere, unterschiedliche Transfer-Typen aufnehmen. Die dort übergebenen Transfer-Typen werden typisiert, d. h. der zu verwaltende Wertetyp (beispielsweise PICTURE) wird über die (Java 5) Generics-Funktionalität innerhalb der Implementierung festgelegt.

public void registerHandlers(@NotNull final HandlerHost host) {

    final HandlerHost.Handler imageHandler = new HandlerHost.Handler() {
        public void handle(@NotNull final CommodityContainer commodities,
                final Point location) throws TransferException {
            final TransferAgent transferAgent =
                    _context.getBroker().requireSpecialist(TransferAgent.TYPE);

            final List<Media> media =
                    commodities.get(transferAgent.getMediaType(Picture.class));
            ...
        }
    };

    final TransferAgent transferAgent =
            _context.getBroker().requireSpecialist(TransferAgent.TYPE);

    final TransferType<Media> picType =
            transferAgent.getMediaType(Picture.class));

    host.registerHandler(_preview, imageHandler, picType);
    host.registerHandler(_referenceField, imageHandler, picType);

    final HandlerHost.Handler commentHandler = new HandlerHost.Handler() {
        public void handle(@NotNull final CommodityContainer commodities,
                final Point location) {
            final TransferAgent transferAgent =
                    _context.getBroker().requireSpecialist(TransferAgent.TYPE);

            finalList<String> texts =
                    commodities.get(transferAgent.getType(
                            "text/plain", String.class));
            ...
        }
    };

    host.registerHandler(_commentField, commentHandler,
            transferAgent.getAllTextsType());

    ...

}

Im Beispiel werden zwei Handler-Objekte erzeugt, die unterschiedliche Transfer-Typen behandeln. Die Handler-Instanz imageHandler ist für Medien-Objekte vom Typ Picture zuständig, während die Handler-Instanz commentHandler Texte bzw. Objekte vom Typ String behandelt.

Ein Transfer-Typ wird über einen TransferAgent erzeugt. Über den SwingGadgetContext (siehe SwingGadgetContext) kann eine Instanz vom Typ SpecialistsBroker (siehe Das Interface SpecialistsBroker) angefordert werden. Ein SpecialistsBroker bietet über unterschiedliche „Spezialisten“ Zugriff auf bestimmte Dienste oder Informationen. Für das Erzeugen von Transfer-Typen, wird ein Spezialist vom Typ TransferAgent benötigt. Dieser kann auf dem SpecialistsBroker mithilfe der Methode <S> S requireSpecialist (SpecialistType<S> type) angefordert werden.

Der Methode void registerHandlers(@NotNull HandlerHost host) wird ein Objekt vom Typ HandlerHost übergeben, auf dem die erzeugten Handler anschließend registriert werden müssen. Dazu muss das Ziel der Drop-Aktion, die Menge der Transfer-Typen und der entsprechende Handler übergeben werden.

Im Beispiel werden drei Ziele, zwei Eingabefelder (_referenceField und _commentField) und ein Vorschaubereich (_preview) innerhalb der Eingabekomponente sowie die Transfer-Typen PICTURE und STRING registriert. Damit können Medien (ausschließlich vom Typ Picture und nicht vom Typ File) in das Eingabefeld oder den Vorschaubereich der Eingabekomponente gezogen und dort fallengelassen werden („Drop“). Desweiteren kann das zweite Eingabefeld (_commentField) einfache Texte bzw. Objekte vom Typ String aufnehmen.

Die Drag- & Drop-Funktionalität einer Eingabekomponente kann ausschließlich über die Aspekte TransferHandling und TransferSupplying behandelt werden. Dazu müssen lediglich die dafür vorgesehenen Lieferanten und Empfänger registriert werden. Das umliegende FirstSpirit-Gadget-Framework behandelt dann alle weiteren Funktionen, beispielsweise das Drop-Handling. Beide Aspekte sind eigenständig, können also getrennt voneinander implementiert werden.