001: /*
002: * GeoTools - OpenSource mapping toolkit
003: * http://geotools.org
004: * (C) 2002-2006, GeoTools Project Managment Committee (PMC)
005: *
006: * This library is free software; you can redistribute it and/or
007: * modify it under the terms of the GNU Lesser General Public
008: * License as published by the Free Software Foundation;
009: * version 2.1 of the License.
010: *
011: * This library is distributed in the hope that it will be useful,
012: * but WITHOUT ANY WARRANTY; without even the implied warranty of
013: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
014: * Lesser General Public License for more details.
015: */
016: package org.geotools.xml;
017:
018: import org.picocontainer.MutablePicoContainer;
019:
020: /**
021: * Resonsible for loading bindings into a container.
022: *
023: * <p>
024: * Strategy objects live inside a pico container. This provides the strategy
025: * with the following:
026: * <ul>
027: * <li>Life cycle
028: * <li>Dependency management
029: * </ul>
030: * </p>
031: * <p>
032: * <h3>Life Cycle</h3>
033: *
034: * Strategy components that require notification of life cycle events must
035: * implement the {@link org.picocontainer.Startable}, and
036: * {@link org.picocontainer.Disposable} interfaces.
037: *
038: * </p>
039: *
040: * <p>
041: * <h3>Dependencies</h3>
042: *
043: * Pico Container uses a design pattern known as <b>Inversion of Control (IoC)</b>.This
044: * pattern is very useful when the implementation of a particular dependency can
045: * vary. For a detailed description, see <a href=http://www.picocontainer.org/Inversion+of+Control>
046: * Inversion of Control</a> pattern.
047: * </p>
048: *
049: * <p>
050: * To achieve IoC, Pico Container uses a mechanism known as <b>Contstructor
051: * Injection</b>. In this scheme, a particular component specifies all of its
052: * dependencies in its constructor. The container will ensure that the
053: * dependencies are satisfied when the component is instantiated. For an more
054: * detailed explanation, see <a href=http://www.martinfowler.com/articles/injection.html#ConstructorInjectionWithPicocontainer>
055: * Constructor Injection</a>.
056: * </p>
057: *
058: * <p>
059: * So how does the container know which implementation to supply to the
060: * component when it is instantiated? An implementation of the dependency must
061: * be registered with the container before the component is instantiated. This
062: * is usually done at parser configuration time. See {@link org.geotools.xml.Configuration
063: * for more details}. Consider the following strategy.
064: *
065: * <pre>
066: * <code>
067: * class MyBinding extends SimpleBinding {
068: * List list;
069: *
070: * public MyBinding(List list) {
071: * this.list = list;
072: * }
073: *
074: * public Object parse(InstanceComponent instance, Object value)
075: * throws Exception {
076: *
077: * list.add(value);
078: * return list;
079: * }
080: * }
081: * </code>
082: * </pre>
083: *
084: * In the above example, our component depends on an object of type List. Since
085: * List itself is abstract, at some point an actual concrete implementation of
086: * List must be passed into the constructor of MyStrategy. Consider the
087: * following strategy configuration.
088: *
089: * <pre>
090: * <code>
091: * class MyBindingConfiguration implements BindingConfiguration {
092: *
093: * public void configure(MutablePicoContainer container) {
094: * //first register a concrete implemtnation of list
095: * container.registerComponentImplementation(LinkedList.class);
096: *
097: * //register the actual component
098: * QName qName = new QName("http://geotools/org/", "my");
099: * container.registerComponentImplementation(qName,MyStrategy.class);
100: * }
101: *
102: * }
103: * </code>
104: * </pre>
105: *
106: * With the above container configuration, the concrete type of List will be
107: * LinkedList.
108: * </p>
109: *
110: * @author Justin Deoliveira,Refractions Research Inc.,jdeolive@refractions.net
111: *
112: */
113: public interface BindingConfiguration {
114: /**
115: * Configures the container which houses the bindings.
116: *
117: * <p>
118: * A binding is looked up in the container by its qualified name.
119: * The following code snippet illustrates how to register a strategy with
120: * the container.
121: * </p>
122: *
123: * <pre>
124: * <code>
125: * void configure(MutablePicoContainer container) {
126: * QName qName = FOO.BARTYPE;
127: * Class impl = F00BarBinding.class;
128: * container.registerComponentImplementation(qName,impl);
129: * }
130: * </code>
131: * </pre>
132: */
133: void configure(MutablePicoContainer container);
134: }
|