001: /* ====================================================================
002: The Jicarilla Software License
003:
004: Copyright (c) 2003 Leo Simons.
005: All rights reserved.
006:
007: Permission is hereby granted, free of charge, to any person obtaining
008: a copy of this software and associated documentation files (the
009: "Software"), to deal in the Software without restriction, including
010: without limitation the rights to use, copy, modify, merge, publish,
011: distribute, sublicense, and/or sell copies of the Software, and to
012: permit persons to whom the Software is furnished to do so, subject to
013: the following conditions:
014:
015: The above copyright notice and this permission notice shall be
016: included in all copies or substantial portions of the Software.
017:
018: THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
019: EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
020: MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
021: IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
022: CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
023: TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
024: SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
025: ==================================================================== */
026: package org.jicarilla.container;
027:
028: import org.jicarilla.lang.Selector;
029:
030: /**
031: * A variant on the {@link Container} interface that passes on criterions
032: * passed to the {@link Resolver resolver} it
033: * {@link ResolverProvider#getResolver() provides} to the adapters that are
034: * registered with it.
035: *
036: * <p>Other than this minor difference, the {@link Container same underlying
037: * concepts and the same contracts} that apply to <code>Containers</code> apply
038: * to <code>KeyRelayingContainers</code> as well.</p>
039: *
040: * @see org.jicarilla.container.builder.DefaultBuilder for a helper class
041: * that makes it easier to create and populate container instances
042: * @author <a href="mail at leosimons dot com">Leo Simons</a>
043: * @version $Id: KeyRelayingContainer.java,v 1.6 2004/03/23 13:37:51 lsimons Exp $
044: */
045: public interface KeyRelayingContainer extends ResolverProvider {
046: /**
047: * Add a new {@link KeyAwareAdapter} to this container.
048: *
049: * @param selector the {@link Selector} that will be used to test
050: * whether the provided adapter can be used to provide an instance
051: * for a key requested from the {@link Resolver} returned from
052: * this container its {@link ResolverProvider#getResolver()}
053: * method.
054: * @param adapter a {@link KeyAwareAdapter} that will be used to help this
055: * container fulfill its {@link ResolverProvider} contract.
056: *
057: * @return this container.
058: *
059: * @throws IllegalSelectorException if the provided selector is not
060: * supported by this container (if it is null, for example, or
061: * if it is not a
062: * {@link org.jicarilla.lang.CriterionExposingSelector} and
063: * the container requires it to be).
064: * @throws IllegalAdapterException if the provided adapter is not
065: * supported by this container (if it is null, for example, or
066: * if it is not of some subtype that this container requires).
067: * @throws KeyAlreadyRegisteredException if the criterion exposed by a
068: * provided selector or a provided key itself is already registered and
069: * the container does not support duplicate keys.
070: * @throws JicarillaException if a miscellaneous exception occurs (an
071: * internal container error or an assertion failure, for example).
072: */
073: KeyRelayingContainer registerAdapter(Selector selector,
074: KeyAwareAdapter adapter) throws IllegalSelectorException,
075: IllegalAdapterException, KeyAlreadyRegisteredException,
076: JicarillaException;
077:
078: /**
079: * Add a new {@link KeyAwareAdapter} to this container.
080: *
081: * @param key the criterion that will be used to test whether the
082: * provided adapter can be used to provide an instance
083: * for a requested key.
084: * @param adapter a {@link KeyAwareAdapter} that will be used to help this
085: * container fulfill its {@link ResolverProvider} contract.
086: *
087: * @return this container.
088: *
089: * @throws IllegalAdapterException if the provided adapter is not
090: * supported by this container (if it is null, for example, or
091: * if it is not of some subtype that this container requires).
092: * @throws KeyAlreadyRegisteredException if the criterion exposed by a
093: * provided selector or a provided key itself is already registered and
094: * the container does not support duplicate keys.
095: * @throws JicarillaException if a miscellaneous exception occurs (an
096: * internal container error or an assertion failure, for example).
097: */
098: KeyRelayingContainer registerAdapter(Object key,
099: KeyAwareAdapter adapter) throws IllegalAdapterException,
100: KeyAlreadyRegisteredException, JicarillaException;
101:
102: }
|