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.tapestry.spec;
016    
017    import java.util.List;
018    import java.util.Map;
019    
020    import org.apache.hivemind.LocationHolder;
021    import org.apache.hivemind.Resource;
022    import org.apache.tapestry.util.IPropertyHolder;
023    
024    /**
025     * Interface for the Specification for a library.
026     * {@link org.apache.tapestry.spec.ApplicationSpecification}is a specialized
027     * kind of library.
028     * 
029     * @author Geoffrey Longman
030     * @since 2.2
031     */
032    
033    public interface ILibrarySpecification extends IPropertyHolder, LocationHolder
034    {
035    
036        /**
037         * Returns the specification path (within the classpath) for an embedded
038         * library, or null if no such library has been defined.
039         */
040    
041        String getLibrarySpecificationPath(String id);
042    
043        /**
044         * Sets the specification path for an embedded library.
045         * 
046         * @throws IllegalArgumentException
047         *             if a library with the given id already exists
048         */
049    
050        void setLibrarySpecificationPath(String id, String path);
051    
052        /**
053         * Returns a sorted list of library ids (or the empty list, but not null).
054         */
055    
056        List getLibraryIds();
057    
058        String getPageSpecificationPath(String name);
059    
060        void setPageSpecificationPath(String name, String path);
061    
062        /**
063         * Returns a sorted list of page names explicitly defined by this library,
064         * or an empty list (but not null).
065         */
066    
067        List getPageNames();
068    
069        void setComponentSpecificationPath(String type, String path);
070    
071        String getComponentSpecificationPath(String type);
072    
073        /**
074         * Returns the simple types of all components defined in this library.
075         * Returns a list of strings in sorted order, or an empty list (but not
076         * null).
077         * 
078         * @since 3.0
079         */
080    
081        List getComponentTypes();
082    
083        /**
084         * Returns the documentation for this library..
085         */
086    
087        String getDescription();
088    
089        /**
090         * Sets the documentation for this library.
091         */
092    
093        void setDescription(String description);
094    
095        /**
096         * Returns a Map of extensions; key is extension name, value is
097         * {@link org.apache.tapestry.spec.IExtensionSpecification}. May return
098         * null. The returned Map is immutable.
099         */
100    
101        Map getExtensionSpecifications();
102    
103        /**
104         * Adds another extension specification.
105         */
106    
107        void addExtensionSpecification(String name,
108                IExtensionSpecification extension);
109    
110        /**
111         * Returns a sorted List of the names of all extensions. May return the
112         * empty list, but won't return null.
113         */
114    
115        List getExtensionNames();
116    
117        /**
118         * Returns the named IExtensionSpecification, or null if it doesn't exist.
119         */
120    
121        IExtensionSpecification getExtensionSpecification(String name);
122    
123        /**
124         * Returns an instantiated extension. Extensions are created as needed and
125         * cached for later use.
126         * 
127         * @throws IllegalArgumentException
128         *             if no extension specification exists for the given name.
129         */
130    
131        Object getExtension(String name);
132    
133        /**
134         * Returns an instantiated extension, performing a check to ensure that the
135         * extension is a subtype of the given class (or extends the given
136         * interface).
137         * 
138         * @throws IllegalArgumentException
139         *             if no extension specification exists for the given name, or
140         *             if the extension fails the type check.
141         * @since 3.0
142         */
143    
144        Object getExtension(String name, Class typeConstraint);
145    
146        /**
147         * Returns true if the named extension exists (or can be instantiated),
148         * returns false if the named extension has no specification.
149         */
150    
151        boolean checkExtension(String name);
152    
153        /**
154         * Invoked after the entire specification has been constructed to
155         * instantiate any extensions marked immediate.
156         */
157    
158        void instantiateImmediateExtensions();
159    
160        String getPublicId();
161    
162        void setPublicId(String value);
163    
164        /**
165         * Returns the location from which the specification was read.
166         * 
167         * @since 3.0
168         */
169    
170        Resource getSpecificationLocation();
171    
172        /** @since 3.0 * */
173    
174        void setSpecificationLocation(Resource specificationLocation);
175    }