/*******************************************************************************
* 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;
}