/* ====================================================================
The Jicarilla Software License
Copyright (c) 2003 Leo Simons.
All rights reserved.
Permission is hereby granted, free of charge, to any person obtaining
a copy of this software and associated documentation files (the
"Software"), to deal in the Software without restriction, including
without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Software, and to
permit persons to whom the Software is furnished to do so, subject to
the following conditions:
The above copyright notice and this permission notice shall be
included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
==================================================================== */
package org.jicarilla.container;
import org.jicarilla.lang.Selector;
/**
* A variant on the {@link Container} interface that passes on criterions
* passed to the {@link Resolver resolver} it
* {@link ResolverProvider#getResolver() provides} to the adapters that are
* registered with it.
*
* <p>Other than this minor difference, the {@link Container same underlying
* concepts and the same contracts} that apply to <code>Containers</code> apply
* to <code>KeyRelayingContainers</code> as well.</p>
*
* @see org.jicarilla.container.builder.DefaultBuilder for a helper class
* that makes it easier to create and populate container instances
* @author <a href="mail at leosimons dot com">Leo Simons</a>
* @version $Id: KeyRelayingContainer.java,v 1.6 2004/03/23 13:37:51 lsimons Exp $
*/
public interface KeyRelayingContainer extends ResolverProvider
{
/**
* Add a new {@link KeyAwareAdapter} to this container.
*
* @param selector the {@link Selector} that will be used to test
* whether the provided adapter can be used to provide an instance
* for a key requested from the {@link Resolver} returned from
* this container its {@link ResolverProvider#getResolver()}
* method.
* @param adapter a {@link KeyAwareAdapter} that will be used to help this
* container fulfill its {@link ResolverProvider} contract.
*
* @return this container.
*
* @throws IllegalSelectorException if the provided selector is not
* supported by this container (if it is null, for example, or
* if it is not a
* {@link org.jicarilla.lang.CriterionExposingSelector} and
* the container requires it to be).
* @throws IllegalAdapterException if the provided adapter is not
* supported by this container (if it is null, for example, or
* if it is not of some subtype that this container requires).
* @throws KeyAlreadyRegisteredException if the criterion exposed by a
* provided selector or a provided key itself is already registered and
* the container does not support duplicate keys.
* @throws JicarillaException if a miscellaneous exception occurs (an
* internal container error or an assertion failure, for example).
*/
KeyRelayingContainer registerAdapter( Selector selector,
KeyAwareAdapter adapter )
throws IllegalSelectorException, IllegalAdapterException,
KeyAlreadyRegisteredException, JicarillaException;
/**
* Add a new {@link KeyAwareAdapter} to this container.
*
* @param key the criterion that will be used to test whether the
* provided adapter can be used to provide an instance
* for a requested key.
* @param adapter a {@link KeyAwareAdapter} that will be used to help this
* container fulfill its {@link ResolverProvider} contract.
*
* @return this container.
*
* @throws IllegalAdapterException if the provided adapter is not
* supported by this container (if it is null, for example, or
* if it is not of some subtype that this container requires).
* @throws KeyAlreadyRegisteredException if the criterion exposed by a
* provided selector or a provided key itself is already registered and
* the container does not support duplicate keys.
* @throws JicarillaException if a miscellaneous exception occurs (an
* internal container error or an assertion failure, for example).
*/
KeyRelayingContainer registerAdapter( Object key,
KeyAwareAdapter adapter )
throws IllegalAdapterException,
KeyAlreadyRegisteredException, JicarillaException;
}
|