| /******************************************************************************* |
| * Copyright (c) 2010-present Sonatype, Inc. |
| * All rights reserved. This program and the accompanying materials |
| * are made available under the terms of the Eclipse Public License v1.0 |
| * which accompanies this distribution, and is available at |
| * http://www.eclipse.org/legal/epl-v10.html |
| * |
| * Contributors: |
| * Stuart McCulloch (Sonatype, Inc.) - initial API and implementation |
| *******************************************************************************/ |
| package org.eclipse.sisu; |
| |
| import java.lang.annotation.Annotation; |
| |
| /** |
| * {@link W}atches for {@link Q}ualified bean implementations of {@link T}:<br> |
| * <br> |
| * |
| * <pre> |
| * // add @Named for automatic registration |
| * public class MyMediator |
| * implements Mediator<Named, MyType, MyWatcher> |
| * { |
| * public void add( BeanEntry<Named, MyType> entry, MyWatcher watcher ) |
| * throws Exception |
| * { |
| * // translate event to whatever the watcher expects |
| * } |
| * |
| * public void remove( BeanEntry<Named, MyType> entry, MyWatcher watcher ) |
| * throws Exception |
| * { |
| * // translate event to whatever the watcher expects |
| * } |
| * } |
| * </pre> |
| * |
| * Mediator implementations must have a public no-arg constructor; they are neither injected nor injectable, acting |
| * instead as stateless translators. |
| * <p> |
| * <p> |
| * IMPORTANT: mediation occurs when bindings change and there is at least <b>one</b> live watcher. If no-one requests or |
| * injects an instance of the watcher type then the mediator will <b>not</b> be called. |
| * <p> |
| * <p> |
| * In the following example as soon as MyTabbedPane is injected, Sisu will use the SwingTabMediator to deliver all known |
| * JPanels annotated with @Tab to the watching MyTabbedPane. Sisu will continue to send updates, which add or remove |
| * tabs as appropriate, until the MyTabbedPane instance becomes unreachable. MyTabbedPane doesn't need to know anything |
| * about Sisu APIs and vice-versa because SwingTabMediator takes care of the necessary translation. |
| * |
| * <pre> |
| * @Named |
| * public class MyTabbedPane |
| * extends JTabbedPane |
| * { |
| * // watcher |
| * } |
| * |
| * @Qualifier |
| * @Retention( RetentionPolicy.RUNTIME ) |
| * public @interface Tab |
| * { |
| * String title(); |
| * } |
| * |
| * @Tab( title = "Summary" ) |
| * public class SummaryTab |
| * extends JPanel |
| * { |
| * // qualified bean |
| * } |
| * |
| * @Tab( title = "Notes" ) |
| * public class NotesTab |
| * extends JPanel |
| * { |
| * // qualified bean |
| * } |
| * |
| * @Named |
| * public class SwingTabMediator |
| * implements Mediator<Tab, JPanel, MyTabbedPane> |
| * { |
| * public void add( BeanEntry<Tab, JPanel> entry, final MyTabbedPane watcher ) |
| * throws Exception |
| * { |
| * final Tab tab = entry.getKey(); |
| * final JPanel panel = entry.getValue(); |
| * |
| * SwingUtilities.invokeLater( new Runnable() |
| * { |
| * public void run() |
| * { |
| * watcher.addTab( tab.title(), panel ); |
| * } |
| * } ); |
| * } |
| * |
| * public void remove( BeanEntry<Tab, JPanel> entry, final MyTabbedPane watcher ) |
| * throws Exception |
| * { |
| * final Tab tab = entry.getKey(); |
| * |
| * SwingUtilities.invokeLater( new Runnable() |
| * { |
| * public void run() |
| * { |
| * watcher.removeTabAt( watcher.indexOfTab( tab.title() ) ); |
| * } |
| * } ); |
| * } |
| * } |
| * </pre> |
| * |
| * @see org.eclipse.sisu.inject.BeanLocator |
| */ |
| public interface Mediator<Q extends Annotation, T, W> |
| { |
| /** |
| * Processes the added {@link BeanEntry} and sends the necessary updates to the watcher. |
| * |
| * @param entry The added bean entry |
| * @param watcher The watching object |
| */ |
| void add( BeanEntry<Q, T> entry, W watcher ) |
| throws Exception; |
| |
| /** |
| * Processes the removed {@link BeanEntry} and sends the necessary updates to the watcher. |
| * |
| * @param entry The removed bean entry |
| * @param watcher The watching object |
| */ |
| void remove( BeanEntry<Q, T> entry, W watcher ) |
| throws Exception; |
| } |