001    /**
002     * <copyright>
003     *
004     * Copyright (c) 2002-2004 IBM Corporation and others.
005     * All rights reserved.   This program and the accompanying materials
006     * are made available under the terms of the Eclipse Public License v1.0
007     * which accompanies this distribution, and is available at
008     * http://www.eclipse.org/legal/epl-v10.html
009     * 
010     * Contributors: 
011     *   IBM - Initial API and implementation
012     *
013     * </copyright>
014     *
015     * $Id: AdapterFactory.java,v 1.4 2009/01/07 12:29:50 emerks Exp $
016     */
017    package org.eclipse.emf.common.notify;
018    
019    
020    
021    /**
022     * A factory for creating adapters and associating them with notifiers.
023     * An implementation may choose to associate one adapter with multiple notifiers.
024     */
025    public interface AdapterFactory
026    {
027      /**
028       * Returns whether this factory supports adapters for the given type.
029       * @param type the key indicating the type of adapter in question.
030       * @return whether this factory supports adapters for the given type.
031       * @see Adapter#isAdapterForType
032       */
033      boolean isFactoryForType(Object type);
034    
035      /**
036       * Returns either an associated adapter for the object, or the object itself,
037       * depending on whether the object is a notifier that supports an adapter of the given type.
038       * This is essentially just a convenience method 
039       * that allows a factory to act as a filter for converting objects to adapters.
040       * If the type isn't supported or the specific object can't be adapted to it,
041       * <code>null</code> will typically be returned.
042       * @param object arbitrary object to adapt.
043       * @param type the key indicating the type of adapter required.
044       * @return either an associated adapter, the object itself, or <code>null</code> if the type isn't supported or the object cannot be adapted to it.
045       */
046      Object adapt(Object object, Object type);
047    
048      /**
049       * Returns either a previously associated adapter or a newly associated adapter, as appropriate.
050       * It will check if the right type of adapter is already associated with the target 
051       * and will return it in that case;
052       * otherwise, it will {@link #adaptNew create} a new adapter if possible.
053       * @param target the notifier to adapt.
054       * @param type the key indicating the type of adapter required.
055       * @return a previously existing associated adapter, a new associated adapter if possible, or <code>null</code> otherwise.
056       * @see Adapter#setTarget
057       * @see #adaptNew
058       */
059      Adapter adapt(Notifier target, Object type);
060    
061      /**
062       * Creates a new associated adapter of the given type;
063       * it may optionally call {@link Adapter#setTarget setTarget} on the adapter, 
064       * and it may optionally add the adapter to the {@link Notifier#eAdapters target.eAdapters()}. 
065       * This is typically not called directly by clients.
066       * @param target the notifier to adapt.
067       * @param type the key indicating the type of adapter required.
068       * @return a new associated adapter if possible, or <code>null</code> otherwise.
069       * @see Adapter#setTarget
070       * @see Notifier#eAdapters
071       */
072      Adapter adaptNew(Notifier target, Object type);
073    
074      /**
075       * Creates a new associated adapter of each type of adapter supported by this factory, as necessary.
076       * This is typically used to adapt newly created objects.
077       * @param notifier notifier to adapt.
078       * @see #adaptNew
079       */
080      void adaptAllNew(Notifier notifier);
081    }