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
015package org.apache.hivemind.internal;
016
017import java.util.List;
018import java.util.Map;
019
020import org.apache.hivemind.ApplicationRuntimeException;
021import 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 */
028public 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}