001 /*
002 * jDTAUS - DTAUS fileformat.
003 * Copyright (c) 2005 Christian Schulte <cs@schulte.it>
004 *
005 * This library is free software; you can redistribute it and/or
006 * modify it under the terms of the GNU Lesser General Public
007 * License as published by the Free Software Foundation; either
008 * version 2.1 of the License, or any later version.
009 *
010 * This library is distributed in the hope that it will be useful,
011 * but WITHOUT ANY WARRANTY; without even the implied warranty of
012 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
013 * Lesser General Public License for more details.
014 *
015 * You should have received a copy of the GNU Lesser General Public
016 * License along with this library; if not, write to the Free Software
017 * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
018 *
019 */
020 package org.jdtaus.core.container;
021
022 /**
023 * Implementation container.
024 * <p>The container is responsible for creating and maintaining instances of
025 * implementations of specifications. It is driven by a model defining the
026 * relationships between specifications and implementations. Its main use is to
027 * decouple compiletime classpaths from runtime classpaths. Implementations need
028 * not be visible during compiletime. Applications can be written against a
029 * stable API with no implementation dependent knowledge. The implementations
030 * building the runtime can then be exchanged independently during application
031 * assembly.</p>
032 * <p>Example: Getting an instance of an implementation of a specification<br/>
033 * <pre>
034 * Specification spec = (Specification) ContainerFactory.getContainer().
035 * getImplementation(Specification.class, "jDTAUS Implementation");
036 * </pre></p>
037 * <p>Example: Getting an instance of an implementation of a dependency<br/>
038 * <pre>
039 * public class Implementation {
040 *
041 * private transient Specification _dependency0;
042 *
043 * private Specification getSpecification() {
044 * Specification ret = null;
045 * if(this._dependency0 != null) {
046 * ret = this._dependency0;
047 * } else {
048 * ret = (Specification) ContainerFactory.getContainer().
049 * getDependency(Implementation.class, "Specification");
050 *
051 * if(ModelFactory.getModel().getModules().
052 * getImplementation(Implementation.class.getName()).
053 * getDependencies().getDependency("Specification").isBound()) {
054 *
055 * this._dependency0 = ret;
056 * }
057 * }
058 *
059 * return ret;
060 * }
061 *
062 * }
063 * </pre></p>
064 *
065 * @author <a href="mailto:cs@schulte.it">Christian Schulte</a>
066 * @version $Id: Container.java 1914 2007-03-01 02:20:44Z schulte2005 $
067 *
068 * @see ContainerFactory
069 */
070 public interface Container
071 {
072
073 //--Container---------------------------------------------------------------
074
075 /**
076 * Gets an instance of an implementation of some specification.
077 *
078 * @param specification the class of the specification to return an
079 * instance of an implementation for.
080 * @param implementationName the name of the implementation to return.
081 *
082 * @return an instance of the implementation named
083 * {@code implementationName} implementing {@code specification}.
084 *
085 * @throws NullPointerException if either {@code specification} or
086 * {@code implementationName} is {@code null}.
087 * @throws org.jdtaus.core.container.InstantiationException if creating
088 * an instance of the implementation fails.
089 */
090 Object getImplementation(Class specification, String implementationName);
091
092 /**
093 * Gets an instance of an implementation of some dependency.
094 *
095 * @param implementation the class of the implementation to return an
096 * instance of a dependency for.
097 * @param dependencyName the logical name of the dependency to return.
098 *
099 * @return an instance of the implementation of the dependency named
100 * {@code dependencyName} for {@code implementation}.
101 *
102 * @throws NullPointerException if either {@code implementation} or
103 * {@code dependencyName} is {@code null}.
104 * @throws org.jdtaus.core.container.InstantiationException if creating
105 * an instance of the dependency fails.
106 */
107 Object getDependency(Class implementation, String dependencyName);
108
109 //---------------------------------------------------------------Container--
110
111 }