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