001    // Copyright 2004, 2005 The Apache Software Foundation
002    //
003    // Licensed under the Apache License, Version 2.0 (the "License");
004    // you may not use this file except in compliance with the License.
005    // You may obtain a copy of the License at
006    //
007    //     http://www.apache.org/licenses/LICENSE-2.0
008    //
009    // Unless required by applicable law or agreed to in writing, software
010    // distributed under the License is distributed on an "AS IS" BASIS,
011    // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
012    // See the License for the specific language governing permissions and
013    // limitations under the License.
014    
015    package org.apache.hivemind.internal;
016    
017    import java.util.List;
018    import java.util.Map;
019    
020    import org.apache.hivemind.ApplicationRuntimeException;
021    import org.apache.hivemind.schema.Schema;
022    
023    /**
024     * An extension point that provides configuration data in the form of a list of elements.
025     * 
026     * @author Howard Lewis Ship
027     */
028    public interface ConfigurationPoint extends ExtensionPoint
029    {
030        /**
031         * Returns the constructed extensions as a list of elements assembled from the various
032         * contributions. The List is unmodifiable. May return an empty list, but won't return null. May
033         * return a proxy to the actual data (which is constructed only as needed), but user code
034         * shouldn't care about that.
035         */
036        public List getElements();
037    
038        /**
039         * Returns true if the elements contributed to this configuration point can be
040         * {@link #getElementsAsMap() retrieved as a Map}. The contributions in the map are keyed on
041         * an attribute as specified by the contributions schema. Thus, as a requirement, this
042         * configuration point must have a defined schema, which in turn must support
043         * {@link Schema#canInstancesBeKeyed() keying} of all valid instances.
044         * 
045         * @since 1.1
046         */
047        public boolean areElementsMappable();
048    
049        /**
050         * Returns the constructed extensions as a Map of elements assembled from the various
051         * contributions. The returned Map is unmodifiable and is keyed on the contribution elements'
052         * {@link org.apache.hivemind.schema.ElementModel#getKeyAttribute() key attribute}. Just as
053         * {@link #getElements()} this method may also return a proxy.
054         * <p>
055         * If there is no key attribute defined for this configuration's contribution elements an
056         * {@link org.apache.hivemind.ApplicationRuntimeException} is thrown.
057         * 
058         * @since 1.1
059         */
060        public Map getElementsAsMap() throws ApplicationRuntimeException;
061    
062        /**
063         * Returns the Schema for contributions to the configuration point (which may be null if the
064         * point does not define a schema for contributions).
065         */
066        public Schema getContributionsSchema();
067    }